path: root/makima/src/daemon/skills/directive.md

---
name: makima-directive
description: Directive commands for makima DAG-based project orchestration. Use these commands to manage long-lived directives with auto-progressing steps.
---

# Makima Directive Skill

You are orchestrating a **directive** — a long-lived project managed through a DAG (directed acyclic graph) of steps. Unlike contracts which are finite and phase-based, directives are **ongoing and continuous**: they stay active as the project evolves, and new features/requirements can be added at any time.

## Key Concepts

- **Directive**: A long-lived top-level entity with a goal, repository info, and a mutable DAG of steps
- **Steps**: Nodes in the DAG. Each step can spawn a task using the mesh infrastructure
- **Auto-progression**: When a step completes, newly-ready steps (whose dependencies are met) automatically become ready
- **Continuous evolution**: The goal can be updated at any time. When all steps complete, the directive goes `idle` (not completed) — waiting for new work
- **Statuses**: `draft` → `active` ↔ `idle` → `archived`. Directives are never "completed" — they go idle and wait

## Commands

### Check Status
```bash
makima directive status
```
Returns the directive with all steps, their statuses, and dependency information.

### Add a Step
```bash
makima directive add-step "Step Name" --description "What this step does" --task-plan "Detailed instructions for the task" --depends-on "uuid1,uuid2" --order-index 1
```

### Remove a Step
```bash
makima directive remove-step <step_id>
```

### Set Dependencies
```bash
makima directive set-deps <step_id> "dep_uuid1,dep_uuid2"
```

### Start the Directive
```bash
makima directive start
```
Sets status to `active` and advances any steps with no dependencies to `ready`.

### Advance the DAG
```bash
makima directive advance
```
Finds newly-ready steps (all dependencies met) and marks them ready. If all steps are in terminal states, sets the directive to `idle`.

### Complete a Step
```bash
makima directive complete-step <step_id>
```

### Fail a Step
```bash
makima directive fail-step <step_id>
```

### Skip a Step
```bash
makima directive skip-step <step_id>
```

### Update the Goal
```bash
makima directive update-goal "New or expanded goal text"
```
Updates the goal and bumps `goalUpdatedAt`. If the directive is `idle`, it reactivates to `active`.

### Pause
```bash
makima directive pause
```

### Update Directive Metadata
```bash
makima directive update --pr-url "<url>" --pr-branch "<branch>"
```
Updates the directive's PR URL and/or PR branch. Used by completion tasks to store the PR URL after creating it.

### Ask User a Question
```bash
makima directive ask "<question>"
```
Asks the user a question and waits for their response. Questions appear on the directive page with a yellow indicator and can be answered inline.

Options:
- `--choices "opt1,opt2,opt3"` - Provide choices for the user to select from
- `--context "<context>"` - Additional context to help the user understand the question
- `--timeout <seconds>` - Wait timeout (default: 3600 = 1 hour)
- `--phaseguard` - Wait indefinitely until the user responds (no timeout). The CLI automatically reconnects via polling every ~5 minutes to avoid HTTP timeout limits. Recommended for critical decisions during planning.
- `--multi-select` - Allow the user to select multiple choices
- `--non-blocking` - Return immediately without waiting for a response
- `--question-type <general|phase_confirmation|contract_complete>` - Question type

**When to use:**
- During planning, when you need clarification on requirements or approach
- When there are multiple valid approaches and user preference matters
- When a decision requires domain knowledge you don't have
- Always use `--phaseguard` for questions that block progress (the reconcile mode on the directive also controls this)

**Example:**
```bash
makima directive ask "Should we use REST or GraphQL for the new API?" --choices "REST,GraphQL" --context "The existing codebase uses REST but the frontend team prefers GraphQL" --phaseguard
```

### Create an Order (Future Work)
```bash
makima directive create-order --title "Order title" --order-type spike
```
Creates an order for future work that is automatically linked to the current directive. Only `spike` and `chore` order types are allowed.

Options:
- `--title "<title>"` - (Required) Title of the order
- `--description "<description>"` - Optional description of the work
- `--priority <critical|high|medium|low|none>` - Priority level (default: medium)
- `--order-type <spike|chore>` - Type of work (default: spike). Only spike and chore are allowed.
- `--labels "label1,label2"` - Optional comma-separated labels

**When to use:**
- When you discover work that is out of scope for the current directive step but should be tracked
- When a spike reveals follow-up tasks that need to be done later
- When you identify technical debt or maintenance work during implementation
- When a chore (e.g., dependency update, config change) is needed but not part of the current goal

**Example:**
```bash
makima directive create-order --title "Investigate flaky test in auth module" --order-type spike --priority high --description "The auth module tests intermittently fail on CI. Needs investigation." --labels "testing,auth"
makima directive create-order --title "Update deprecated serde API usage" --order-type chore --priority low --labels "tech-debt"
```

## Memory Commands

Directives have an optional key-value memory system that persists across steps and planning cycles. Use memory to share context, decisions, and learned information between steps — so downstream tasks don't need to re-discover what earlier steps already figured out.

### Set a Memory Entry
```bash
makima directive memory-set <key> <value>
```
Stores a key-value pair in the directive's memory. If the key already exists, the value is overwritten. Keys are strings; values are strings (use JSON encoding for structured data).

**Example:**
```bash
makima directive memory-set "db_schema_version" "3"
makima directive memory-set "auth_pattern" "JWT with refresh tokens stored in httpOnly cookies"
makima directive memory-set "api_base_path" "/api/v2"
```

### Get a Memory Entry
```bash
makima directive memory-get <key>
```
Retrieves the value for a specific key. Returns the value if found, or an error if the key does not exist.

**Example:**
```bash
makima directive memory-get "db_schema_version"
```

### List All Memory Entries
```bash
makima directive memory-list
```
Returns all key-value pairs stored in the directive's memory. Useful for understanding what context is available before starting work on a step.

### Delete a Memory Entry
```bash
makima directive memory-delete <key>
```
Removes a single key-value pair from memory.

**Example:**
```bash
makima directive memory-delete "deprecated_config_key"
```

### Clear All Memory
```bash
makima directive memory-clear
```
Removes **all** key-value pairs from the directive's memory. Use with caution — this is irreversible.

### Batch Set Memory Entries
```bash
makima directive memory-batch-set --json '{"key1": "value1", "key2": "value2"}'
```
Sets multiple key-value pairs in a single operation. Existing keys are overwritten; keys not mentioned are left unchanged.

**Example:**
```bash
makima directive memory-batch-set --json '{"framework": "axum", "orm": "sqlx", "test_runner": "cargo test"}'
```

## Using Memory Effectively

### When to Write Memory
- **During planning**: Record architectural decisions, technology choices, and file layout patterns
- **After step completion**: Save discovered information (e.g., generated IDs, API endpoints, schema details)
- **When context matters**: Store anything a downstream step would need to avoid re-exploring the codebase

### When to Read Memory
- **At step start**: Check `memory-list` to see what context previous steps have provided
- **Before making decisions**: Check if an earlier step already made a relevant architectural choice
- **During re-planning**: Read memory to understand what was learned in previous iterations

### Best Practices
- Use descriptive, namespaced keys (e.g., `auth.strategy`, `db.migration_count`, `api.base_url`)
- Store concise but complete values — enough for another task to act on without guessing
- Clean up stale entries when the directive's goal changes significantly
- Use `memory-batch-set` when recording multiple related decisions at once

## Orchestration Workflow

### Initial Setup
1. Check the directive status to understand the goal
2. Decompose the goal into steps with clear dependencies
   - If requirements are unclear, use `makima directive ask` to get clarification before finalizing the plan
3. Add steps using `add-step` with appropriate `--depends-on` flags
4. Start the directive with `start`
5. Steps with no dependencies will become `ready` immediately

### Monitoring and Advancing
1. Periodically check status to see step progress
2. When tasks complete, the DAG auto-advances — newly-ready steps appear
3. Use `advance` to manually trigger DAG progression if needed
4. Mark steps as complete/failed/skipped as appropriate

### Re-planning (When Goal Updates)
When the goal is updated (you'll see a new `goalUpdatedAt` timestamp):
1. Check the current status to see completed and in-progress steps
2. Identify what's new in the updated goal
3. Add new steps that depend on existing completed steps as appropriate
4. The DAG will auto-advance any newly-ready steps

### Idle State
When all steps complete, the directive enters `idle` state. This is normal — it means:
- All current work is done
- The directive is waiting for new requirements
- When the user updates the goal, it reactivates automatically
- You should add new steps based on the updated goal

## Environment Variables
- `MAKIMA_API_URL` - API server URL
- `MAKIMA_API_KEY` - Authentication key
- `MAKIMA_DIRECTIVE_ID` - Current directive ID (set automatically)