mission-brief

mission-brief

What this skill does

mission-brief takes a feature description, structures it into a Mission Brief (goal, constraints, success criteria), generates an ordered step list with prompts, and executes those steps — each step dispatched to a subagent whose prompt triggers the installed SDD skills. No YAML workflow files, no per-framework profiles, no profile detection. The step prompts use canonical SDD terminology (specify, plan, implement, converge) that works with any SDD skill set — model-invoked skills auto-trigger, command-based frameworks match by filename, and if neither exists the subagent executes directly.

When to use

• "Build this feature end to end": you give a description, mission-brief composes the pipeline and runs specify → plan → implement ↔ converge.
• You want a converge loop with a circuit breaker and an audit trail.
• You want to resume an interrupted mission across sessions (mission-brief --resume).
• You want to run unattended across sessions (mission-brief --async).

When NOT to use

• A single small edit — just do it; a mission is overhead.
• You already have a spec and tasks and only want to implement one task — invoke the implement skill directly.

Mission Brief template

Before generating steps, the description is structured into:

## Mission Brief

**Goal**: <what to build — one sentence>
**Constraints**: <tech stack, limitations, dependencies, requirements>
**Non-Goals**: <what is explicitly out of scope — e.g., "no database storage, local memory cache only">
**Success Criteria**:
- <measurable outcome 1>
- <measurable outcome 2>
- <measurable outcome 3>

The brief serves two purposes:

1. Forces explicit done-criteria upfront — feeds the converge step's independence check (the checker verifies against these criteria).
2. Carries mission context into every step's delegation prompt so each subagent has full context without re-reading prior steps.

Inputs

$ARGUMENTS

The text in the $ARGUMENTS block above IS your mission description — proceed with it immediately. Do not ask the user what they want to build.

Parse flags from the arguments first, then treat the remaining text as spec_description:

• --async / --sync — execution mode flag (overrides config default).
• --resume — explicit resume from state.
• Everything else — the mission description (spec_description).

If no description and not --resume: derive a best-effort description from the feature name (git branch, or the last state's feature). If --resume and no state: report "No interrupted mission found" and stop.

Feature name derivation: slugify the description to lowercase-hyphenated, drop stop words (a, an, the, new, to, with, for, add, fix, update). Example: "add a new react dashboard with telemetry" → react-dashboard-telemetry. If .adlc/workflow/runs/ already contains a dir with that name, append -2, -3, etc.

Flow

All paths are relative to the current working directory (the project root where the agent operates). Do not look in subdirectories for config or state unless explicitly stated.

Phase 0 — Configuration

1. mkdir -p .adlc/workflow (and .adlc/workflow/tmp, .adlc/workflow/runs).
2. If .adlc/workflow/workflow-config.yml does not exist, copy it from the skill's config-template.yml (located alongside this SKILL.md).
3. Read .adlc/workflow/workflow-config.yml. Defaults if fields are absent:

workflow:
  execution: sync            # sync | async
  supervision: gated         # gated | hybrid | autonomous
  max_iterations: 5
  max_spec_corrections: 2
  circuit_breaker: 3
  quality_threshold: null    # optional 0-100, blocks DONE below threshold
  # models: { strong: "...", fast: "..." }   # optional

Resolve the effective execution mode: --async/--sync flag > config execution > sync. If --async and supervision is gated/hybrid: warn ("async forces ungated; running autonomous") and treat as autonomous for this run.

Phase 1 — Resume check (--resume only)

<FEATURE_DIR> = .adlc/workflow/runs/<feature>/ (defined in Phase 4, but referenced here for the completed-mission check).

If --resume was passed:

1. Read .adlc/workflow/.mission-state.json.
2. If <FEATURE_DIR>/mission-log.json exists → report "Mission already completed for feature X. Audit trail: …" → stop.
3. If state exists with non-empty completed_steps → resume: load the step list from state.steps, skip to Phase 5 (Execute) at the first incomplete step.
4. If no state → report "No interrupted mission found. Run mission-brief \"<desc>\" to start one." → stop.

If --resume was NOT passed and a state file with non-empty completed_steps exists: ask — "An interrupted mission for feature X exists (N/M steps done). Run mission-brief --resume to continue, or confirm to start fresh (this discards the state)." Do not silently clobber.

Phase 2 — Mission Brief

Structure spec_description into the Mission Brief template:

1. Goal: extract the core objective in one sentence.
2. Constraints: infer tech stack, limitations, and requirements from the description and the project context (check package.json, go.mod, language files, existing specs). If unclear, leave a placeholder and mark it for the user to fill.
3. Non-Goals: infer 1–2 reasonable boundaries or features that should be explicitly excluded to keep implementation focused and simple. If none can be inferred, mark as "None".
4. Success Criteria: derive 2-5 measurable outcomes. If the description is vague, generate reasonable defaults based on the feature type and mark them as "suggested — edit if needed".

Present the brief to the user:

• sync + gated/hybrid → show the brief and ask for confirmation or edits before proceeding.
• sync + autonomous → if Success Criteria are "TBD" or empty, STOP: "Autonomous mode requires checkable done-criteria." Otherwise proceed without confirmation.
• --async → proceed without confirmation (autonomous, ungated).

Store the brief in .mission-state.json.brief.

Phase 3 — Route classification & optional phases

Classify into spec / change / quick:

For spec route only, assess optional-phase candidates (hands-off, recorded in state; the user approves each at a runtime gate if supervision is gated/hybrid):

Phase 4 — Command discovery & generate step list

4a. Command/skills discovery

Read references/agent-integrations.md (alongside this SKILL.md). For each agent directory listed in the table, check if it exists in the project root. Record discovered directories in state:

"discovered": {
  "skills_dirs": [".claude/skills"],
  "commands_dirs": [{"dir": ".opencode/commands", "ext": ".md"}]
}

This discovery is done once at generation time and reused on --resume. See the reference file for the full algorithm.

4a.1 Local skills inventory (universal skill routing)

After discovering skills directories (4a), build an inventory of every installed skill across all skills_dirs. For each <skills_dir>/<skill-name>/ subdirectory that contains a SKILL.md:

1. Read the SKILL.md frontmatter (YAML between --- fences).
2. Extract name and description (fall back to the directory name if frontmatter is missing or unparseable).
3. Record an entry in discovered.local_skills:

"discovered": {
  "skills_dirs": [".claude/skills"],
  "commands_dirs": [{"dir": ".opencode/commands", "ext": ".md"}],
  "local_skills": [
    {"name": "tdd", "path": ".claude/skills/tdd", "description": "Test-driven development with red-green-refactor..."},
    {"name": "grill-me", "path": ".claude/skills/grill-me", "description": "Get relentlessly interviewed about a plan..."},
    {"name": "code-review", "path": ".claude/skills/code-review", "description": "Two-axis review of the diff..."}
  ]
}

This inventory is vendor-agnostic — it captures skills from any source (mattpocock/skills, addy osmani/agent-skills, superpowers, custom team skills, or any Agent-Skills-standard repository). The inventory is passed to every subagent at dispatch time (Phase 5) so the LLM decides which skill fits the current step — no hard-coded phase-to-skill mapping tables.

4b. Generate the step list

Generate an ordered list of steps based on the route and optional-phase candidates. Each step is a structured object stored in state.steps:

{
  "id": "specify",
  "phase": "specify",
  "tier": "strong",
  "prompt": "Write a feature specification for the goal below. ...",
  "status": "pending"
}

The step list is the reviewable artifact — present it to the user in gated/hybrid mode before execution:

## Mission Steps

1. [specify]  (strong) Write a feature specification for: react dashboard with telemetry
2. [plan]     (strong) Break down the specification into an implementation plan
3. [tasks]    (fast)   Generate the detailed task list from the plan
4. [implement](strong) Implement the next pending task from the plan
5. [converge] (fast)   Review the implementation against the spec and success criteria
   ↺ loop 4–5 until converged (max 5 iterations, circuit breaker 3)

For quick route: single implement step with the full brief as input.

For change route: specify + implement↺converge loop (no optional phases).

For spec route: full pipeline with optional phases inserted as gated candidates.

Step prompt construction

Each step's prompt is built from three parts:

1. Phase instruction — canonical SDD terminology per phase:

2. Mission Brief context — the goal, constraints, and success criteria from Phase 2 are appended to every prompt.

3. Delegation wrapper — added by the executor at dispatch time (Phase 5). The wrapper includes discovered.local_skills so the subagent can decide which installed skill (if any) to invoke for the current step.

Phase 5 — Execute the step list

Create a todowrite list mirroring state.steps. Mark steps in completed_steps as completed. Update after every step.

Step dispatch

For each step with status: pending:

1. Emit:

   ## Workflow Step: <id>
   
   **Phase**: <phase> (<tier>)
   

2. If the step is a converge step (phase is converge), prepend the independence hint to the delegation prompt:

   You are grading work that another agent produced. Do NOT assume the implementation is correct — verify against the spec independently. Try to make each requirement fail at the primary source (run the test, check the file, grep for the reference). You are the checker, not the maker.

   CRITICAL: Verify that NO features or implementations listed under Non-Goals have been introduced. If any out-of-scope work was built, report CONTINUE as your outcome signal, and list the non-goals violation in your summary.

3. Delegate to a subagent with this prompt verbatim:

   You are being invoked by the `mission-brief` executor.
   
   ## Task
   
   <step.prompt>
   
   ## Mission Brief
   
   **Goal**: <goal>
   **Constraints**: <constraints>
   **Non-Goals**: <non-goals>
   **Success Criteria**: <success criteria>
   
   ## Available Skills in This Workspace
   
   <LOCAL_SKILLS_LIST>
   
   The list above shows skills installed in this workspace from any source
   (ADLC team skills, mattpocock/skills, addy osmani/agent-skills,
   superpowers, or custom). Review each skill's name and description.
   If one matches the goal of your current task, **invoke it** (via the
   skill tool or by reading its SKILL.md inline) and use it to execute
   this step. If multiple skills could apply, pick the best fit. If none
   apply, proceed with direct execution.
   
   ## How to execute
   
   Try these in order:
   
   1. **Skill match**: If an installed skill's description matches this task,
      invoke it (via skill tool or by reading its SKILL.md inline).
   
   2. **Command match**: If a command file for this phase exists, read and
      execute it. <DISCOVERED_PATHS>
      Look for a file whose name matches the phase (e.g., `*specify*`,
      `*implement*`, `*converge*`).
   
   3. **Direct execution**: If neither exists, execute the task directly using
      your available tools.
   
   **Confidence Self-Estimation**:
   Evaluate your confidence (HIGH/MEDIUM/LOW) in this implementation or task. If
   you are missing critical context, have low confidence, or find the requirements
   ambiguous, report `Confidence score: LOW` (or `MEDIUM`) and list the specific
   unresolved details in your return summary.
   
   If you found a skill or command, note its name in your summary.
   
   Do NOT follow handoffs to other skills or commands — return your results to
   the executor when you finish.
   
   Return:
   1. A 1-2 sentence summary (mention which skill/command you used, if any).
   2. Files changed (if any).
   3. Test results (if any).
   4. Outcome signal: DONE | CONTINUE | SPEC_CORRECTION_NEEDED.
      - DONE: work is complete and verified.
      - CONTINUE: more work is needed (tasks remain, review found issues).
      - SPEC_CORRECTION_NEEDED: verification found spec-level issues that
        require re-running specify. Include a `spec_corrections` field with
        the specific issues.
   5. (optional) Quality score: "X/Y (Z%)" — if a verification skill ran
      quality gates, report the score.
   6. (optional) Gate summary: "N passed, M failed" — if quality gates were
      checked, list which passed and which failed.
   7. (optional) Confidence score: HIGH | MEDIUM | LOW. Self-estimated confidence in the correctness of your work.
   8. (optional) Unresolved details: <brief description of what is uncertain or missing context>.
   

   <LOCAL_SKILLS_LIST> is replaced with a formatted list built from discovered.local_skills. Each entry shows the skill name, path, and description:

   - **tdd** (`.claude/skills/tdd`) — Test-driven development with red-green-refactor...
   - **grill-me** (`.claude/skills/grill-me`) — Get relentlessly interviewed about a plan...
   - **code-review** (`.claude/skills/code-review`) — Two-axis review of the diff...
   

   If discovered.local_skills is empty, <LOCAL_SKILLS_LIST> is replaced with: "No custom skills detected in this workspace."

   <DISCOVERED_PATHS> is replaced with the discovered directories from state.discovered:

   • If commands_dirs is non-empty: "Check these locations: .opencode/commands/ (.md), .claude/commands/ (.md), ..."
   • If skills_dirs is non-empty: "Installed skills are in: .claude/skills/, ..."
   • If both empty: "Check your harness's commands/skills directories, or consult references/agent-integrations.md for known locations."

4. Wait for the subagent.

5. Update .mission-state.json now — before the next step. Store the subagent's returned values in state under step_results.<id>:

   • Store 1-2 sentence summary as step_results.<id>.output
   • Store confidence score as step_results.<id>.confidence (if provided, otherwise default to HIGH)
   • Store unresolved details as step_results.<id>.unresolved
   • Append <id> to completed_steps
   • Mark state.steps[N].status = completed
   • Write the state file. Discard the full subagent response.

   Confidence Escalation Gate: If the parsed confidence score is LOW and the active supervision mode is autonomous or hybrid:

   • Auto-escalate supervision to gated for this step's verification.
   • Halt execution and present the subagent's findings and unresolved details to the user:

     "⚠️ Subagent completed step but reported LOW confidence due to: [unresolved details]. Supervision auto-escalated to gated. Review changes and confirm before proceeding? (yes/no)"

   • Wait for explicit user confirmation before continuing the step list. If confirmed, proceed; if denied, pause the mission.

6. If the step was implement, append to <FEATURE_DIR>/iterations.md:

   ## Iteration <N> - <date>
   - Files changed: <list>
   - Summary: <1-2 sentences>
   - Tests: <pass/fail>
   

7. If the converge subagent returned SPEC_CORRECTION_NEEDED as its outcome signal → stop and return spec_correction_needed to Phase 6. Do not continue.

Gate steps (sync, gated/hybrid only)

When supervision is gated or hybrid, the executor inserts gates inline (not as separate steps — as executor behavior):

• After specify (gated + hybrid): ask "Spec created. Review before implementation?" → proceed / revise (re-run specify) / abort.
• After each implement (gated only): ask "Implementation complete. Run convergence?" → proceed / revise (re-run implement) / abort.
• Final sign-off (gated + hybrid): after converge, ask "Convergence passed. Review and approve completion?" → approve / reject (pause).

For --async or autonomous: no gates, no sign-off.

Store gate choices in step_results.<id>_gate.output.choice.

Converge loop (implement ↔ converge)

The implement and converge steps form a do-while loop:

1. Execute implement step (iteration N).
2. Execute converge step.
3. Check the converge subagent's outcome signal:
   • DONE → loop exits, proceed to Phase 6.
   • CONTINUE → increment consecutive_tasks_appended, check circuit breaker (below), repeat from 1 if under max_iterations.

Use iteration-prefixed IDs for tracking: loop_0_implement, loop_1_implement, etc. The step id stays as-is; only the completed_steps entry is prefixed.

Circuit breaker. Track consecutive_tasks_appended in state. After each converge step, if the signal is CONTINUE, increment; if DONE, reset to 0. If the counter reaches circuit_breaker (default 3) → stop the loop and return failed: "Circuit breaker: N consecutive iterations did not converge. Human review needed — the loop is not converging." This counter persists across resume.

Score regression tracking. Track consecutive_score_regressions in state (initialized to 0). After each converge step that returns a quality score:

• If current score < previous score → increment consecutive_score_regressions
• If current score >= previous score → reset to 0
• If consecutive_score_regressions reaches circuit_breaker (default 3) → stop: "Circuit breaker: N consecutive score regressions. Quality is trending downward — human review needed." This counter persists across resume.

Quality threshold enforcement. If quality_threshold is set (non-null) and the converge subagent returns DONE with a quality score below the threshold → treat as CONTINUE instead (the work is not done to the required quality bar).

Context budget awareness

After every step, summarize and discard the full subagent response. After 5+ steps, proactively suggest: "Session is getting long — you can continue, or start a fresh chat and run mission-brief --resume." If responses get repetitive, suggest a fresh chat.

Phase 6 — Completion routing

When all steps complete (or a signal forces a return), act on the signal:

spec_correction_needed (returned by converge subagent as SPEC_CORRECTION_NEEDED):

1. Read state. If spec_corrections >= max_spec_corrections → STOP: "Spec repeatedly fails evaluation (N/M). Human review of the spec required." Keep state for inspection.
2. Otherwise: increment spec_corrections, reset all step statuses to pending (fresh pipeline run), re-execute (Phase 5), repeat Phase 6.

converged or tasks_appended (loop finished):

• sync + gated/hybrid → require human sign-off: display the audit trail from iterations.md; ask "Convergence passed. Review and approve completion?" → approve proceeds; reject pauses ("Mission paused for review. Run mission-brief --resume after addressing issues.").
• sync + autonomous, or --async → skip sign-off.
• Move .mission-state.json → .adlc/workflow/runs/<feature>/mission-log.json (audit trail — not deleted).
• Report:

  ## Mission Complete
  - Feature: <feature>
  - Route: <route>
  - Execution: <sync|async>
  - Supervision: <mode>
  - Signal: <converged|tasks_appended>
  - Spec corrections: <n>/<max>
  - Audit trail: .adlc/workflow/runs/<feature>/mission-log.json
  

failed: report the error; keep state for inspection. User can re-run mission-brief --resume.

Safety mechanisms

• Supervision modes: gated (default) gates inline; autonomous runs freely but requires checkable done-criteria (refuse "TBD"); hybrid gates only at spec review + final sign-off.
• Confidence Escalation: If the subagent reports Confidence score: LOW during execution, the system overrides autonomous/hybrid modes and forces an interactive human gate.
• Non-Goals Enforcement: The Mission Brief includes out-of-scope boundaries. The converge step acts as an independent grader that explicitly checks for and rejects any non-goals violations.
• Async forces ungated: --async + gated/hybrid config → warn + autonomous.
• Inner loop cap: max_iterations (default 5).
• Circuit breaker: stops after N consecutive non-converging iterations (default 3) — prevents infinite spinning; persists across resume.
• Outer loop cap: max_spec_corrections (default 2), triggered by SPEC_CORRECTION_NEEDED signal from converge subagent.
• Score regression detection: if quality scores trend downward for N consecutive iterations (circuit_breaker), stops the loop even if subagent reports CONTINUE.
• Quality threshold: if configured, blocks DONE below threshold — treats as CONTINUE instead.
• Converge independence hint: converge subagent verifies independently.
• Audit trail: iterations.md + mission-log.json — not deleted.
• State persistence: .mission-state.json survives compaction/restarts.
• Resume is explicit: mission-brief --resume; fresh mission-brief asks before clobbering an interrupted state.

Common Rationalizations

Red Flags

• Executing steps without writing .mission-state.json after each one.
• Inserting gates in an --async run.
• Skipping the Mission Brief in autonomous mode when Success Criteria are "TBD".
• Reading the full subagent response into working memory instead of summarizing + discarding.
• Clobbering an interrupted state without asking (fresh mission-brief without --resume).
• Deleting .mission-state.json on completion instead of moving it to mission-log.json.
• Hardcoding a specific agent's commands directory instead of using the discovered paths from state.discovered.
• Ignoring a SPEC_CORRECTION_NEEDED signal from the converge subagent and proceeding as if DONE.
• Ignoring a subagent's LOW confidence report and proceeding without human escalation.
• Allowing non-goals violations to pass through the converge step without reporting CONTINUE.

Verification

• .adlc/workflow/workflow-config.yml exists (copied from template if absent).
• .mission-state.json contains: brief (goal/constraints/success criteria), steps (ordered list with phase/tier/prompt/status), discovered (skills_dirs + commands_dirs + local_skills), completed_steps (grows monotonically).
• iterations.md gains an entry per implement step.
• On completion, mission-log.json exists under .adlc/workflow/runs/<feature>/.
• A --resume with no state reports "No interrupted mission found" and stops.
• A --resume with mission-log.json present reports "already completed".
• The delegation prompt includes discovered paths (not a hardcoded list).
• The delegation prompt includes <LOCAL_SKILLS_LIST> built from discovered.local_skills (empty list → "No custom skills detected").
• Gate steps appear only in sync + gated/hybrid runs, never in --async.
• SPEC_CORRECTION_NEEDED signals from converge are routed to Phase 6 (not treated as DONE or CONTINUE).
• If quality_threshold is set, converge scores below threshold are treated as CONTINUE.
• Confidence score: LOW reports from subagents trigger an automatic supervision override to gated review.
• The Non-Goals section is successfully populated in the brief and passed to every subagent's prompt context.

Configuration

• .adlc/workflow/workflow-config.yml — execution, supervision, budgets, quality threshold, optional models map. See config-template.yml.
• references/agent-integrations.md — full agent→directory mapping table. Update when new agents are added or conventions change. The executor reads it at generation time for command/skills discovery.

Example session

# Start a sync gated mission
mission-brief "add a new react dashboard with telemetry"

# Run unattended across sessions
mission-brief --async "refactor the auth module to use JWT"

# Resume after a session restart or a paused gate
mission-brief --resume