# framework-spec
Spec for agentic coding — a concise specification describing the architecture, responsibilities, interfaces and behaviours expected from agentic coding frameworks and components.
## Table of contents
- [Overview](#overview)
- [Principles](#principles)
- [Specification surface](#specification-surface)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)
## Overview
This repository defines a minimal, implementation‑agnostic specification for "agentic coding" systems — systems that use autonomous or semi-autonomous agents to write, review, and modify code. The goal is to provide a stable set of expectations and interfaces so different agent implementations can interoperate and so projects can evaluate or adopt agentic tools with predictable behaviour.
The spec focuses on:
- Agent lifecycle and capabilities
- Communication and messaging formats
- Task and goal representation
- Observability and safety controls
- Integration hooks for repositories and CI systems
## Principles
- Language-agnostic: keep definitions independent of any single programming language.
- Minimal and actionable: specify only what is necessary for interoperability and evaluation.
- Safe-by-default: include guidance for permissions, rate limits, and human-in-the-loop controls.
- Extendable: allow implementors to add features while remaining compatible with the core spec.
## Specification surface
The repository organizes the specification around these core concepts:
- Agent
- Identity, capabilities, authorization scopes
- Lifecycle: propose → plan → act → report → retire
- Task / Goal
- Standardized task structure (title, description, inputs, acceptance criteria, priority)
- Task states and transitions
- Messaging
- Standard message types (request, progress, result, exception)
- Suggested JSON schema for messages and events
- Repositories & Integrations
- Hooks for cloning, patch creation, and PR metadata
- Recommended patterns for CI gating and human approvals
- Observability & Safety
- Event logging model, assertions, and audit trails
- Permissioning and escalation patterns
(For full JSON schemas, message examples and governance guidelines, see the corresponding spec files in this repository.)
## Examples
- Example task message (JSON) and recommended PR metadata are included under the `examples/` directory.
- Example agent lifecycle flows and suggested webhooks are in `docs/flows.md`.
## Contributing
Contributions are welcome. If you'd like to propose a change:
1. Open an issue describing the rationale and proposed change.
2. Submit a PR that updates the relevant spec documents and includes example(s) and tests where applicable.
3. Aim for small, reviewable changes. Include cross-references to other spec parts when changing semantics.
See CONTRIBUTING.md (if present) for more detail.
## License
This project is released under the MIT License. See LICENSE for details.
## Contact
Maintained by Bird-NZ. For questions or discussions, open issues on this repository or reach out via GitHub.