Armature Planner

Armature Planner Loop

The Planner translates objectives and specifications into a well-structured DAG of actionable work. The output is a validated, cited, dependency-resolved set of issues ready for workers to claim.

Prerequisites

• If arm is not found, stop and resolve this before proceeding.
• Do NOT run arm worker-init — the Planner does not require a worker identity. Skip that step entirely.
• Have a source document, spec, or design doc before you start. Every issue you create must be citable. If no source exists yet, write one first or be prepared to use arm sources accept-citation with a clear rationale.

DAG Hygiene Mandate

arm validate and arm doctor must exit clean at all times. This is non-negotiable.

Before releasing any plan to the Coordinator and after every decomposition, run:

arm validate       # zero ERRORs; all issues cited
arm doctor        # zero errors; no broken refs, orphaned ops, or cycles

If either exits non-zero, fix the reported issues before releasing. Treat DAG decay the same way you treat failing tests — it is a blocker, not a warning to ignore.

Warnings from other stories must be resolved, not ignored. If arm doctor reports a D1 (commits referencing non-done issues) or D2 (stale claims) from unrelated work, clean them up before planning your work. DAG health is cumulative.

The Planner Loop

digraph planner_loop {
    "Start: objective/spec" [shape=box];
    "Single task?" [shape=diamond];
    "arm create" [shape=box];
    "Write plan.json" [shape=box];
    "dag apply --dry-run" [shape=box];
    "OK?" [shape=diamond];
    "dag apply --plan plan.json" [shape=box];
    "dag transition" [shape=box];
    "sources add/sync/verify" [shape=box];
    "sources link / sources accept-citation" [shape=box];
    "arm link (deps)" [shape=box];
    "arm validate" [shape=box];
    "arm doctor" [shape=box];
    "Release to Coordinator" [shape=doublecircle];

    "Start: objective/spec" -> "Single task?";
    "Single task?" -> "arm create" [label="yes"];
    "Single task?" -> "Write plan.json" [label="no"];
    "arm create" -> "sources add/sync/verify";
    "Write plan.json" -> "dag apply --dry-run";
    "dag apply --dry-run" -> "OK?" ;
    "OK?" -> "Write plan.json" [label="fix errors"];
    "OK?" -> "dag apply --plan plan.json" [label="yes"];
    "dag apply --plan plan.json" -> "dag transition";
    "dag transition" -> "sources add/sync/verify";
    "sources add/sync/verify" -> "sources link / sources accept-citation";
    "sources link / sources accept-citation" -> "arm link (deps)";
    "arm link (deps)" -> "arm validate";
    "arm validate" -> "arm doctor";
    "arm doctor" -> "Release to Coordinator";
}

Step-by-Step

1. Register Sources First

Register source documents before creating issues. This lets you link issues at creation time rather than doing a remediation pass later.

arm sources add --url path/to/spec.md --title "Feature Spec" --type filesystem
arm sources sync       # fetch and fingerprint all registered sources
arm sources verify     # confirm all show OK (not MISSING)

If arm sources verify shows MISSING entries, re-run arm sources sync until they resolve. Do not proceed with issue creation while sources are MISSING.

2. Create or Decompose

For a single task:

arm create --title "Task title" --type task --parent STORY-ID

Valid types: task, feature, bug, story

For a full decomposition (most common):

See references/decompose-apply.md for the full dag apply workflow.

3. Promote from Draft

After dag apply, all created issues are in draft state. Promote them so workers can see them:

arm dag transition --issue ROOT-ID   # promotes ROOT-ID and all children draft → verified

Workers cannot claim draft issues. Do not skip this step.

4. Link Issues to Sources

Every issue must be cited before arm validate will pass.

# Link each issue to a registered source
arm sources link --issue ISSUE-ID --source-id UUID

# If no source document exists for this issue
arm sources accept-citation --issue ISSUE-ID --rationale "No external spec; requirements captured in issue body" --ci

Do this at creation time — not as a post-hoc remediation pass. Citation debt accumulates silently and blocks validation.

5. Resolve Dependencies

Identify scope overlaps and set blocking dependencies before releasing work.

arm link --source A --dep B    # A is blocked_by B; A runs after B completes
arm validate                   # scope overlap WARNINGs appear here; resolve each one

6. Validate and Release

arm validate --ci   # must exit 0 with no ERRORs; scope overlaps resolved
arm doctor          # repo health check (D1-D6); fix any errors
arm list --group    # final sanity check — all issues visible and in expected states

Only release to the Coordinator after both commands are clean.

Writing Good Plan JSON

This section is critical. Every issue in the plan MUST have a source (source entry ID) or arm dag apply will refuse the plan. Apply is source-atomic: each create is emitted with its source-link in the same batch. Every task MUST have dod, scope, and acceptance fields or Plan Release (dag transition / confirm) will fail. Validate the plan JSON against the plan schema before submitting; see docs/json-schema-examples.md for worked examples.

The Three Mandatory Fields

dod — Definition of Done

Describes what "complete" looks like. Must be concrete and verifiable by the worker without asking the Planner. Limited to 500 characters (E9 validation error if exceeded). Summarize the outcome in the DoD; place extended requirements in the notes array instead.

• Good: "The parser handles all five token types defined in spec §3.2 and returns typed AST nodes. All existing tests pass and new unit tests cover the added branches."
• Bad: "Done when it works" — vague, not verifiable
• Bad: "Implement the feature" — restates the title, adds no information
• Bad: Long DoD over 500 chars — summarize and move details to notes

scope — Files Affected

Lists the specific files this task modifies. Use the (new) suffix for files that do not yet exist. Use precise paths, not vague descriptions.

• Good: "cmd/parse/main.go, internal/ast/node.go (new), internal/ast/node_test.go (new)"
• Bad: "the parser files" — worker cannot determine what to touch
• Bad: "internal/" — too broad, enables scope collisions

acceptance — Verifiable Criteria

JSON array of specific criteria the worker can verify mechanically. Each entry should name a test, a command output, or an observable behavior.

Spec traceability: Name new tests using Test<Description>_REQ_<RequirementID>, where RequirementID is the story or task ID (e.g. STORY-T1). This makes the test visible to make trace-report and ties it back to the requirement that motivated it. Use this pattern for every acceptance criterion that corresponds to a new test function.

• Good: ["TestParseTokenTypes_REQ_STORY_T1 passes", "make check green", "arm validate exits 0"]
• Bad: ["TestParseTokenTypes passes"] — test name won't appear in make trace-report
• Bad: [] — empty array provides no acceptance signal
• Bad: ["looks good"] — not mechanically verifiable

See docs/conventions.md (test naming and traceability section) in the armature repo for comprehensive documentation of test naming and all other naming conventions.

notes — Optional Free-Text Notes

JSON array of strings ([]string) containing optional extended notes or guidance for the worker. Use notes to provide context that does not fit in dod or acceptance, or to reference external docs. Initialize as [] (empty array) if not needed.

• Good: ["See RFC-2019-auth for security requirements", "Coordinate with infra team on deployment"]
• Good: [] — empty array if no additional notes
• Bad: Using notes to store what should be in dod or acceptance

Complete Well-Formed Task Example

WARNING: The plan JSON must be wrapped in the required { "version": 1, "title": "...", "issues": [...] } top-level structure. Omitting the wrapper or using an unsupported plan version will cause arm dag apply to fail with a validation error.

{
  "version": 1,
  "title": "Example Decomposition Plan",
  "issues": [
    {
      "id": "STORY-001",
      "title": "User authentication story",
      "type": "story",
      "scope": "",
      "priority": "",
      "source": "00000000-0000-0000-0000-000000000001",
      "dod": "Decomposition plan for the story is created, reviewed, and passes arm validate",
      "parent": "",
      "blocked_by": null,
      "notes": [],
      "acceptance": [
        "Decomposition plan created for STORY-001",
        "All child tasks have dod, scope, and acceptance fields",
        "arm validate passes with no errors"
      ]
    },
    {
      "id": "TASK-001",
      "title": "Implement login endpoint",
      "type": "task",
      "scope": "internal/auth/login.go (new)",
      "source": "00000000-0000-0000-0000-000000000001",
      "context_files": [
        "docs/auth-architecture.md"
      ],
      "priority": "high",
      "dod": "Login endpoint returns JWT on valid credentials",
      "parent": "STORY-001",
      "blocked_by": [],
      "notes": [],
      "acceptance": [
        "Implementation complete per dod",
        "TestImplementLoginEndpoint_REQ_TASK_001 passes",
        "make check green"
      ]
    },
    {
      "id": "TASK-002",
      "title": "Write login integration tests",
      "type": "task",
      "scope": "internal/auth/login_test.go (new)",
      "source": "00000000-0000-0000-0000-000000000001",
      "priority": "medium",
      "dod": "Integration tests cover happy path and error cases",
      "parent": "STORY-001",
      "blocked_by": [
        "TASK-001"
      ],
      "notes": [],
      "acceptance": [
        "Implementation complete per dod",
        "TestWriteLoginIntegrationTests_REQ_TASK_002 passes",
        "make check green"
      ]
    }
  ]
}

Anti-Patterns to Avoid

Note: arm dag apply --example omits acceptance in its output. Always add it manually to every task in your plan JSON.

Source Registration

Every issue must have a citation before arm validate passes. The two paths:

Path A: Source document exists

# 1. Register the source (do this before creating issues)
arm sources add --url docs/design/feature-spec.md --title "Feature Spec" --type filesystem

# 2. Sync to fingerprint it
arm sources sync

# 3. Verify it shows OK
arm sources verify

# 4. Link each issue (get UUID from sources verify output)
arm sources link --issue ISSUE-ID --source-id UUID

Path B: No source document exists

arm sources accept-citation --issue ISSUE-ID --rationale "Requirements captured in issue body; no external spec exists" --ci

To bulk-cite multiple issues at once, pass --issue multiple times:

arm sources accept-citation --issue A --issue B --issue C --rationale "same rationale applies to all" --ci

sources link also accepts multiple issues in one invocation. Use bulk forms to reduce citation debt in large plan loads.

Use a specific rationale — vague rationales like "no docs" are harder to audit later.

Rules

• Register sources before creating issues, not after.
• Do not leave any issue uncited. Check coverage with arm validate.
• If arm validate reports uncited node: ID, either sources link the issue or use sources accept-citation on that issue before releasing to workers.
• If arm validate reports unknown source: UUID, the source UUID is not in the manifest — re-run arm sources sync then arm sources verify.

For dependency linking and overlap resolution, see references/dependency-management.md.

Release Checklist

Run this checklist before handing work off to the Coordinator.

1. arm validate — no ERRORs, citation coverage complete

   arm validate --ci   # exits non-zero on any error
   

   Note: If arm validate reports context_files WARNINGs, treat them as decomposition signals—break large tasks into smaller subtasks or add blocking dependencies to reduce context size. Re-run until no context_files WARNINGs remain.

2. arm doctor — repo health checks D1-D6 pass

   arm doctor          # or arm doctor --strict (warnings as errors)
   

3. All issues promoted from draft

   arm list --group    # no issues should appear in draft state
   

4. All issues cited — arm validate output shows COVERAGE: N/N cited

5. Dependencies correct — no scope overlap WARNINGs in arm validate

6. Priorities set — review arm list --group to confirm priorities reflect intended execution order

7. Spec traceability check — confirm acceptance criteria use _REQ_ naming

   make trace-report   # lists which requirements have tagged tests; gaps mean missing _REQ_ names
   

   If a task's acceptance criterion names a test function, that function should appear in the make trace-report output once the worker delivers it. If it does not, the acceptance criterion name is missing the _REQ_ suffix.

Do not release until all seven checks pass.

Common Failure Modes

Quick Reference

# Single issue creation
arm create --title "X" --type task --parent STORY-ID

# Decomposition
arm dag apply --example                         # inspect schema
arm dag apply --plan plan.json --dry-run        # preview without writing; iterate here
arm dag apply --plan plan.json                  # apply the plan (source-atomic; Introduction check)

# Draft promotion
arm dag transition --issue ROOT-ID                    # promote root + all children

# Source management
arm sources add --url PATH --title "TEXT" --type filesystem
arm sources sync                                      # fetch and fingerprint
arm sources verify                                    # confirm all show OK
arm sources link --issue ID --source-id UUID           # link issue to source
arm sources accept-citation --issue ID --rationale "..." --ci # accept risk (no source)

# Dependency management
arm link --source A --dep B                           # A runs after B
arm unlink --source A --dep B                         # remove dependency

# Validation
arm validate                                          # graph + citation check
arm validate --ci                                     # exit non-zero on errors
arm doctor                                            # repo health check
arm doctor --strict                                   # warnings as errors
arm list --group                                      # grouped by status
arm list --parent STORY-ID                            # tasks under a story

# Scope maintenance (after refactoring renames or deletions)
arm scope-rename OLD-PATH NEW-PATH        # rename path/prefix across all scopes
arm scope-delete PATH                    # remove exact path from all scopes