Skip to content
This repository was archived by the owner on Aug 11, 2026. It is now read-only.

Commit c5600c2

Browse files
1broseidonclaudeGemini
committed
Add agent-to-agent contract system documentation
Comprehensive documentation for the contract system that enables structured coordination between PM and worker agents. New Documentation: - docs/guides/contracts.md - Contract system overview and schema - docs/guides/agent-workflows.md - PM and worker agent patterns - docs/cli/contract-commands.md - CLI command reference Schema Updates: - v1/board.json - Add completionColumn property to columns - docs/types/board.md - Document completionColumn field CLI Documentation Updates: - docs/cli/commands.md - Add contract command examples - docs/reference/commands.md - Add contract subcommand reference - docs/tools/cli.md - Add Agent Contracts section - docs/.vitepress/config.ts - Add Guides navigation section Features Documented: - Contract lifecycle (ready → in_progress → delivered → done/failed) - PM agent responsibilities and workflow - Worker agent pickup/deliver/validate flow - Creating contracts via --with-contract flag - Deliverables, validation commands, and constraints - Blocked status for stuck agents - Rework flow with reject/approve Cross-references: - Links to protocol schema (v1/board.json) - Integration with CLI commands - Real-world examples from task-58 and task-59 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Co-Authored-By: Gemini <noreply@google.com>
1 parent 2d887f0 commit c5600c2

9 files changed

Lines changed: 598 additions & 1 deletion

File tree

‎docs/.vitepress/config.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,12 +140,20 @@ export default defineConfig({
140140
{ text: 'Core Library', link: '/tools/core' },
141141
],
142142
},
143+
{
144+
text: 'Guides',
145+
items: [
146+
{ text: 'Agent Contracts', link: '/guides/contracts' },
147+
{ text: 'Agent Workflows', link: '/guides/agent-workflows' },
148+
],
149+
},
143150
{
144151
text: 'Reference',
145152
items: [
146153
{ text: 'Protocol Specification', link: '/reference/protocol' },
147154
{ text: 'API Reference', link: '/reference/api' },
148155
{ text: 'CLI Commands', link: '/reference/commands' },
156+
{ text: 'Contract Commands', link: '/cli/contract-commands' },
149157
{ text: 'Schema Types', link: '/reference/types' },
150158
],
151159
},

‎docs/cli/commands.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ brainfile mcp # Start MCP server for AI assistants
3030
| [`hooks`](#hooks) | AI agent hook integration |
3131
| [`auth`](#auth) | Authenticate with GitHub/Linear |
3232
| [`config`](#config) | Manage CLI configuration |
33+
| [`contract`](#contract) | Manage agent-to-agent contracts |
3334
| [`mcp`](#mcp) | MCP server for AI assistants |
3435

3536
---
@@ -76,6 +77,7 @@ brainfile add --title "Implement auth"
7677
brainfile add --title "Fix bug" --priority high --tags "bug,urgent"
7778
brainfile add --title "Review PR" --assignee john --due-date 2025-02-01
7879
brainfile add --title "Fix auth bug" --files "src/auth.ts,src/login.tsx"
80+
brainfile add --title "Implement API" --with-contract --deliverable "src/api.ts"
7981
```
8082

8183
**Options:**
@@ -88,6 +90,10 @@ brainfile add --title "Fix auth bug" --files "src/auth.ts,src/login.tsx"
8890
- `--due-date <date>` - Due date (YYYY-MM-DD)
8991
- `--subtasks <list>` - Comma-separated subtask titles
9092
- `--files <list>` - Comma-separated related file paths
93+
- `--with-contract` - Initialize with an empty contract
94+
- `--deliverable <path:desc>` - Add deliverable (repeatable)
95+
- `--validation <command>` - Add validation command (repeatable)
96+
- `--constraint <text>` - Add constraint (repeatable)
9197

9298
---
9399

@@ -423,6 +429,20 @@ brainfile config path
423429

424430
---
425431

432+
## contract
433+
434+
Manage the lifecycle of agent-to-agent contracts.
435+
436+
```bash
437+
brainfile contract pickup --task task-1
438+
brainfile contract deliver --task task-1
439+
brainfile contract validate --task task-1
440+
```
441+
442+
See the [Contract Commands Reference](./contract-commands) for detailed documentation of all contract subcommands.
443+
444+
---
445+
426446
## mcp
427447

428448
Start an MCP (Model Context Protocol) server for direct AI assistant integration.

‎docs/cli/contract-commands.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
title: CLI Contract Commands
3+
description: Reference for agent-to-agent coordination commands
4+
---
5+
6+
# CLI Contract Commands
7+
8+
Contract commands facilitate the lifecycle of agent-to-agent coordination. Most of these commands are designed to be used by AI agents, but they can also be used by humans managing a team of agents.
9+
10+
## Command Overview
11+
12+
| Command | Role | Description |
13+
|---------|------|-------------|
14+
| [`pickup`](#pickup) | Worker | Claim a task and set status to `in_progress` |
15+
| [`deliver`](#deliver) | Worker | Submit completed work and set status to `delivered` |
16+
| [`validate`](#validate) | PM | Automatically run validation commands |
17+
| [`approve`](#approve) | PM | Manually accept work and set status to `done` |
18+
| [`reject`](#reject) | PM | Reject work and set status to `failed` |
19+
| [`attach`](#attach) | PM | Add a contract to an existing task |
20+
| [`blocked`](#blocked) | Worker | Mark a contract as blocked with a reason |
21+
| [`reset`](#reset) | PM | Reset contract status (e.g., after unblocking) |
22+
23+
---
24+
25+
## pickup
26+
27+
Claim a task for implementation. This sets the contract status to `in_progress` and records the start time.
28+
29+
```bash
30+
brainfile contract pickup --task task-42
31+
```
32+
33+
**Options:**
34+
- `-t, --task <id>` - Task ID (required)
35+
36+
**Side Effects:**
37+
- Sets `contract.status` to `in_progress`.
38+
- Sets `contract.metrics.pickedUpAt` timestamp.
39+
40+
---
41+
42+
## deliver
43+
44+
Submit completed work for review. This validates that all deliverables are present and all subtasks are complete before setting status to `delivered`.
45+
46+
```bash
47+
brainfile contract deliver --task task-42
48+
```
49+
50+
**Options:**
51+
- `-t, --task <id>` - Task ID (required)
52+
53+
**Side Effects:**
54+
- Sets `contract.status` to `delivered`.
55+
- Sets `contract.metrics.deliveredAt` timestamp.
56+
- Calculates `contract.metrics.duration`.
57+
58+
---
59+
60+
## validate
61+
62+
Run the automated validation commands defined in the contract.
63+
64+
```bash
65+
brainfile contract validate --task task-42
66+
```
67+
68+
**Options:**
69+
- `-t, --task <id>` - Task ID (required)
70+
71+
**Outcomes:**
72+
- **Success**: Sets status to `done`, moves task to completion column (if configured).
73+
- **Failure**: Sets status to `failed`, adds command output to `contract.feedback`.
74+
75+
---
76+
77+
## approve
78+
79+
Manually approve a delivered contract, skipping automated validation.
80+
81+
```bash
82+
brainfile contract approve --task task-42
83+
```
84+
85+
**Options:**
86+
- `-t, --task <id>` - Task ID (required)
87+
88+
**Side Effects:**
89+
- Sets `contract.status` to `done`.
90+
- Moves task to completion column.
91+
92+
---
93+
94+
## reject
95+
96+
Reject a delivered contract and provide feedback for rework.
97+
98+
```bash
99+
brainfile contract reject --task task-42 --feedback "Missing unit tests for edge cases."
100+
```
101+
102+
**Options:**
103+
- `-t, --task <id>` - Task ID (required)
104+
- `-f, --feedback <text>` - Explanation of why the work was rejected (required)
105+
106+
**Side Effects:**
107+
- Sets `contract.status` to `failed`.
108+
- Increments `contract.metrics.reworkCount`.
109+
110+
---
111+
112+
## attach
113+
114+
Attach a contract definition to an existing task.
115+
116+
```bash
117+
brainfile contract attach --task task-42 \
118+
--deliverable "src/main.ts" \
119+
--validation "npm test" \
120+
--constraint "Follow style guide"
121+
```
122+
123+
**Options:**
124+
- `-t, --task <id>` - Task ID (required)
125+
- `--deliverable <path:description>` - Add a deliverable (repeatable)
126+
- `--validation <command>` - Add a validation command (repeatable)
127+
- `--constraint <text>` - Add an implementation constraint (repeatable)
128+
- `--out-of-scope <text>` - Add an out-of-scope item (repeatable)
129+
130+
---
131+
132+
## blocked
133+
134+
Mark a contract as blocked due to external dependencies.
135+
136+
```bash
137+
brainfile contract blocked --task task-42 --reason "Upstream API is down"
138+
```
139+
140+
**Options:**
141+
- `-t, --task <id>` - Task ID (required)
142+
- `-r, --reason <text>` - Why the task is blocked (required)
143+
144+
**Side Effects:**
145+
- Sets `contract.status` to `blocked`.
146+
147+
---
148+
149+
## reset
150+
151+
Reset a contract to a specific status. Useful for clearing blocked or failed states.
152+
153+
```bash
154+
brainfile contract reset --task task-42 --status ready
155+
```
156+
157+
**Options:**
158+
- `-t, --task <id>` - Task ID (required)
159+
- `-s, --status <name>` - Target status (default: `ready`)
160+
161+
```

‎docs/guides/agent-workflows.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Agent Workflow Patterns
3+
description: Best practices for PM and worker agent coordination
4+
---
5+
6+
# Agent Workflow Patterns
7+
8+
The contract system enables powerful coordination patterns between different types of agents. This guide outlines the standard roles and workflows for efficient project management.
9+
10+
## Roles
11+
12+
### PM Agent (Project Manager)
13+
The PM agent is responsible for the "What" and "Why". They break down high-level goals into actionable tasks, define contracts, and verify results.
14+
15+
- **Primary tools**: `add`, `patch`, `contract attach`, `contract validate`, `contract approve`, `contract reject`.
16+
- **Key responsibility**: Ensure task descriptions are comprehensive and validation criteria are objective.
17+
18+
### Worker Agent (The Doer)
19+
Worker agents (like `codex`, `cursor`, `gemini`) focus on the "How". They pick up contracts, implement code, and deliver artifacts.
20+
21+
- **Primary tools**: `list`, `contract pickup`, `contract deliver`, `show`.
22+
- **Key responsibility**: Meet the deliverables and constraints defined in the contract.
23+
24+
---
25+
26+
## The Standard Loop
27+
28+
A typical feature implementation follows this cycle:
29+
30+
### 1. Planning (PM)
31+
The PM agent analyzes the requirement and creates a task with a contract.
32+
33+
```bash
34+
brainfile add --title "Add OAuth2 Support" \
35+
--description "Implement Google OAuth2 login flow. See design docs for details." \
36+
--assignee codex \
37+
--with-contract \
38+
--deliverable "src/auth/oauth.ts:Implementation" \
39+
--deliverable "src/auth/__tests__/oauth.test.ts:Tests" \
40+
--validation "npm test -- oauth" \
41+
--constraint "Use official google-auth-library"
42+
```
43+
44+
### 2. Execution (Worker)
45+
The worker agent detects the assignment and begins work.
46+
47+
```bash
48+
# Worker checks for new tasks
49+
brainfile list --contract ready --assignee codex
50+
51+
# Worker claims the task
52+
brainfile contract pickup -t task-105
53+
54+
# Worker reads full details
55+
brainfile show -t task-105
56+
57+
# Worker implements code...
58+
59+
# Worker self-verifies
60+
npm test -- oauth
61+
62+
# Worker delivers
63+
brainfile contract deliver -t task-105
64+
```
65+
66+
### 3. Verification (PM)
67+
The PM agent reviews the work and closes the task.
68+
69+
```bash
70+
# PM sees delivered tasks
71+
brainfile list --contract delivered
72+
73+
# PM runs automated validation
74+
brainfile contract validate -t task-105
75+
76+
# If all good, PM moves task to Done
77+
brainfile move -t task-105 -c Done
78+
```
79+
80+
---
81+
82+
## Handling Rework
83+
84+
If the PM agent finds issues during validation or manual review, the rework flow is triggered.
85+
86+
1. **PM Rejects**: `brainfile contract reject -t task-105 --feedback "Tests are passing, but the redirect URL is hardcoded. It should use the config."`
87+
2. **State Change**: Contract status returns to `failed`.
88+
3. **Worker Re-pickup**: The worker sees the `failed` status, reads the `feedback` field via `brainfile show`, and runs `contract pickup` again.
89+
4. **Fix & Re-deliver**: Worker fixes the issue and runs `contract deliver`.
90+
91+
---
92+
93+
## Blocked Agents
94+
95+
Sometimes a worker agent cannot proceed due to external factors (missing API keys, ambiguous requirements, upstream bugs).
96+
97+
1. **Agent Marks Blocked**: `brainfile contract blocked -t task-105 --reason "Need Google Client ID and Secret to complete tests."`
98+
2. **PM Notification**: The PM sees the `blocked` status in the TUI or via `list`.
99+
3. **Resolution**: The PM provides the missing info or fixes the dependency.
100+
4. **Reset**: The PM runs `brainfile contract reset -t task-105` to return it to `ready` or `in_progress`.
101+
102+
---
103+
104+
## Advanced Patterns
105+
106+
### The Multi-Agent Pipeline
107+
Break a large feature into a sequence of contracts:
108+
1. **Agent A (Architect)**: Produces an interface specification (`docs/api.md`).
109+
2. **Agent B (Backend)**: Implements the API based on the spec.
110+
3. **Agent C (Frontend)**: Consumes the API based on the spec.
111+
112+
### Automated Triage
113+
A specialized `triage` agent can monitor incoming bug reports (tasks without contracts), research the cause, and then `attach` a contract with specific `relatedFiles` and `validation` commands for a `codex` agent to fix.
114+
115+
### Self-Referential Tasks
116+
When implementing new Brainfile features, agents often use the system to build the system. For example, `task-58` was used to implement the very contract creation commands you are using now.
117+
118+
```

0 commit comments

Comments
 (0)