1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
---
name: makima-chain-directive
description: Directive contract tools for orchestrating chains. Use when creating chains from goals, adding contracts to chains, evaluating completions, or managing chain structure.
---
# Chain Directive Contract Tools
Directive contracts are special contracts that research, plan, create, and orchestrate chains. They use formal directives with requirements and acceptance criteria, and evaluate each contract completion before allowing the chain to progress.
## Workflow Overview
1. **Init**: Create a directive contract + empty chain from a goal
2. **Research**: Directive contract explores codebase, understands requirements
3. **Specify**: Write formal directive with requirements (REQ-001, etc.) and acceptance criteria
4. **Plan**: Design chain structure, add contracts, set dependencies
5. **Execute**: Finalize chain, start execution, evaluate completions
6. **Review**: All contracts complete, create final report
## Creating a Chain from a Goal
### Initialize directive-driven chain
```
POST /api/v1/chains/init
{
"goal": "Add OAuth2 authentication support",
"repository_url": "https://github.com/org/repo",
"local_path": "/path/to/repo",
"phase_guard": true
}
```
Returns:
- `chain_id` - The created chain
- `directive_contract_id` - The directive contract orchestrating the chain
- `supervisor_task_id` - Task ID for the directive contract supervisor
## Chain Design Tools (for directive contracts)
These tools are available when working on a directive contract:
### create_chain_from_directive
Create a new chain linked to this directive contract.
```json
{
"name": "oauth-implementation",
"description": "Chain for OAuth2 implementation"
}
```
### add_chain_contract
Add a contract definition to the chain.
```json
{
"name": "auth-backend",
"description": "Implement authentication backend",
"contract_type": "implementation",
"depends_on": ["setup"],
"requirement_ids": ["REQ-001", "REQ-002"]
}
```
### set_chain_dependencies
Update dependency relationships.
```json
{
"contract_name": "integration-tests",
"depends_on": ["auth-backend", "auth-frontend"]
}
```
### modify_chain_contract
Update a contract definition.
```json
{
"name": "auth-backend",
"new_name": "authentication-service",
"description": "Updated description",
"add_requirement_ids": ["REQ-003"],
"remove_requirement_ids": ["REQ-001"]
}
```
### remove_chain_contract
Remove a contract definition (fails if others depend on it).
```json
{
"name": "unused-contract"
}
```
### preview_chain_dag
Generate visual DAG preview of the chain structure.
Returns ASCII diagram and JSON nodes.
### validate_chain_directive
Validate chain structure before finalizing.
Checks for:
- Empty chains
- Missing dependencies
- Circular dependencies
- Uncovered requirements
### finalize_chain_directive
Lock the directive and optionally start chain execution.
```json
{
"auto_start": true
}
```
## Orchestration Tools (during execution)
### get_chain_status
Get current chain progress and contract statuses.
Returns completed/active/pending counts and contract details.
### get_uncovered_requirements
List requirements not mapped to any contract.
Returns uncovered requirement IDs and coverage percentage.
### evaluate_contract_completion
Evaluate a completed contract against the directive.
```json
{
"contract_id": "uuid",
"passed": true,
"feedback": "All acceptance criteria met",
"rework_instructions": null
}
```
### request_rework
Reject completion and request rework.
```json
{
"contract_id": "uuid",
"feedback": "Missing error handling for edge cases"
}
```
## Evaluation Flow
When a contract completes and evaluation is enabled:
1. Contract status changes to `completed`
2. Chain contract marked as `pending_evaluation`
3. Directive contract evaluates using `evaluate_contract_completion`
4. **Pass**: Chain progresses, downstream contracts created
5. **Fail**: Contract marked for rework, retry count incremented
6. After max retries (default 3), escalate to user
## Directive Document Structure
The directive contains:
```json
{
"requirements": [
{
"id": "REQ-001",
"title": "User Authentication",
"description": "Users must be able to log in with email/password",
"priority": "must",
"category": "feature"
}
],
"acceptance_criteria": [
{
"id": "AC-001",
"requirement_ids": ["REQ-001"],
"description": "Login endpoint returns JWT on valid credentials",
"testable": true,
"verification_method": "automated"
}
],
"constraints": [
{
"id": "CON-001",
"type": "technical",
"description": "Must use existing PostgreSQL database"
}
],
"external_dependencies": [
{
"id": "EXT-001",
"name": "OAuth Provider API",
"type": "api",
"required": true
}
]
}
```
## Example Workflow
```bash
# 1. Initialize a directive-driven chain
curl -X POST http://localhost:3000/api/v1/chains/init \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"goal": "Add user profile editing feature"}'
# 2. Directive contract goes through phases:
# - Research: Explores codebase
# - Specify: Writes formal directive
# - Plan: Creates chain contracts using tools
# - Execute: Monitors and evaluates completions
# 3. Monitor chain progress
curl http://localhost:3000/api/v1/chains/$CHAIN_ID \
-H "Authorization: Bearer $TOKEN"
# 4. View directive traceability
curl http://localhost:3000/api/v1/chains/$CHAIN_ID/directive/traceability \
-H "Authorization: Bearer $TOKEN"
```
## Key Concepts
- **Directive Contract**: The orchestrator that creates and manages the chain
- **Formal Directive**: Structured specification with traceable requirements
- **Continuous Evaluation**: LLM evaluates after every contract completion
- **Block & Rework**: Failed evaluations block progress until fixed
- **Dynamic Modification**: Chain structure can be modified during execution
|
