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

1. 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).

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

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

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

1. 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".

1. 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 skillsdirs. For each <skillsdir>/<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).

1. 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:

```markdown ## Workflow Step: <id>

Phase: <phase> (<tier>) ```

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

1. Delegate to a subagent with this prompt verbatim:

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

<LOCALSKILLSLIST>

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 | SPECCORRECTIONNEEDED. - DONE: work is complete and verified. - CONTINUE: more work is needed (tasks remain, review found issues). - SPECCORRECTIONNEEDED: 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>. ```

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

``markdown - 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.localskills is empty, <LOCALSKILLS_LIST> is replaced with: "No custom skills detected in this workspace."

<DISCOVEREDPATHS> is replaced with the discovered directories from state.discovered: - If commandsdirs 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."

1. Wait for the subagent.
2. Update .mission-state.json now — before the next step. Store the

subagent's returned values in state under stepresults.<id>: - Store 1-2 sentence summary as stepresults.<id>.output - Store confidence score as stepresults.<id>.confidence (if provided, otherwise default to HIGH) - Store unresolved details as stepresults.<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 <id> 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.

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

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

1. If the converge subagent returned SPECCORRECTIONNEEDED as its outcome

signal → stop and return speccorrectionneeded 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 stepresults.<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 consecutivetasksappended, check circuit breaker (below), repeat from 1 if under max_iterations.

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

Circuit breaker. Track consecutivetasksappended 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 consecutivescoreregressions in state (initialized to 0). After each converge step that returns a quality score:

• If current score < previous score → increment consecutivescoreregressions
• If current score >= previous score → reset to 0
• If consecutivescoreregressions 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:

speccorrectionneeded (returned by converge subagent as SPECCORRECTIONNEEDED):

1. Read state. If speccorrections >= maxspec_corrections → STOP:

"Spec repeatedly fails evaluation (N/M). Human review of the spec required." Keep state for inspection.

1. 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: maxspeccorrections (default 2), triggered by

SPECCORRECTIONNEEDED 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 SPECCORRECTIONNEEDED 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 (skillsdirs + commandsdirs + localskills), completedsteps (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 <LOCALSKILLSLIST> built from

discovered.local_skills (empty list → "No custom skills detected").

• Gate steps appear only in sync + gated/hybrid runs, never in --async.
• SPECCORRECTIONNEEDED 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