---
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