Add new directive mechanism v3

1 files changed, 111 insertions, 0 deletions

diff --git a/makima/src/daemon/skills/directive.md b/makima/src/daemon/skills/directive.md
new file mode 100644
index 0000000..7c55cf8
--- /dev/null
+++ b/makima/src/daemon/skills/directive.md
@@ -0,0 +1,111 @@
+---
+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
+```
+
+## Orchestration Workflow
+
+### Initial Setup
+1. Check the directive status to understand the goal
+2. Decompose the goal into steps with clear dependencies
+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)