mm-build · mirror-mind-ai - Agent Skill

Builder Mode

Activates Builder Mode for a specific journey. Loads identity context and project docs.

Usage

Pi:

/mm-build <journey-slug>

Codex:

$mm-build <journey-slug>

Claude Code:

/mm:build <journey-slug>

Base Builder Mode Behavior

This is the default behavior for every journey, including journeys that have not adopted Ariad or any Builder method.

1. Load Context (DB)

mirror build load <slug>

The command:

Activates ■ Builder Mode in the operating-mode lifecycle
Renders the Mode Transition Surface (■ BUILDER MODE ACTIVE)
Prints identity context (soul + ego + user + journey, persona=engineer)
Prints relevant memories
Starts a new database conversation session
Emits project_path=<path> as the last output line

1.1 Transition Surface

Render the build load transition surface visibly before continuing with project doc loading or substantive Builder work.

For journeys without adopted Ariad, preserve original Builder behavior:

load context;
read project docs;
stop at the Builder Activation Boundary;
ask what work should be done next.

Do not render Ariad surfaces, Ariad lifecycle suggestions, roadmap snapshot, pull candidates, cursor state, or checkpoint language for journeys that have not adopted Ariad.

For Ariad-adopted journeys, see Ariad Runtime Behavior below.

Builder Mode surface should orient the user around:

active journey
journey path/stage, when present
project path, when present
compact briefing/synthesis
boundary: Builder executes commitment.

1.2 Journey Binding

Every build command after build load carries --journey <slug>. The slug is the journey this session's build load activated, and its ■ BUILDER MODE ACTIVE surface names it. For a journey the Navigator names explicitly, pass that slug instead.

The runtime never guesses the journey. Without --journey, a command binds only to a session in Builder Mode named with --session-id or MIRROR_SESSION_ID. An agent shell names none, so the command refuses with requires a journey. A guessed journey once moved other journeys' cursors and wrote files into other projects.

If that refusal appears and this session's slug is no longer in view, ask the Navigator. Do not take the slug from mode status, the status line, or any other database-wide state. They can show another window's journey.

2. Read Project Docs

Parse project_path from the last output line above. If project_path is not set, skip this step and proceed — the journey has no associated project yet.

Use file tools to load project documentation. Prefer the project's actual documentation structure over any fixed scaffold.

Always read when present

<project_path>/README.md — public overview, setup, and usage
<project_path>/REFERENCE.md — detailed operational reference
<project_path>/CLAUDE.md — project-specific operating instructions
<project_path>/docs/index.md — documentation map

Discover available docs

Run:

find <project_path>/docs -maxdepth 3 -type f -name '*.md' | sort

Then read the docs relevant to the current task.

For Mirror Mind, the primary docs are:

<project_path>/docs/getting-started.md
<project_path>/docs/project/briefing.md
<project_path>/docs/project/decisions.md
<project_path>/docs/product/specs/runtime-interface/index.md
<project_path>/docs/project/roadmap/index.md
<project_path>/docs/process/development-guide.md
<project_path>/docs/process/worklog.md
<project_path>/docs/product/principles.md

When working inside a CV/Delivery Story/User Story/Technical Story, also read the relevant:

index.md
plan.md
test-guide.md
refactoring.md, if present

3. Builder Activation Boundary

Activating Builder Mode or loading a journey is context setup only. After loading the context and required docs, stop and ask what work should be done next.

Do not edit files, create tests, run implementation, start TDD, or mutate project state until the user gives an explicit implementation or documentation instruction, such as implement, fix, edit, create, run tests, or names a specific story to execute.

Context activation is not execution consent.

4. Work In Builder Mode

Once the user explicitly authorizes work:

Work from project_path — read, edit, and create project files normally
Keep project docs updated as the code evolves
Commit at the end of each session with a descriptive English commit message

5. Project Docs Maintenance

Follow the project's existing documentation structure. Do not create a generic docs scaffold unless the user explicitly asks for one.

When to update docs:

README.md: public positioning, setup, stack, or usage changes
REFERENCE.md: CLI behavior, configuration, runtime contracts, or operational details change
docs/project/briefing.md: stable architectural premises change
docs/project/decisions.md: an incremental design decision is made
docs/product/specs/runtime-interface/index.md: runtime lifecycle, hooks, skills, or extension contracts change
docs/project/roadmap/: CV/Delivery Story/User Story/Technical Story status, plans, or verification guides change
docs/process/worklog.md: a meaningful milestone is completed
docs/product/principles.md: product, code, testing, or process principles change

6. Configure `project_path`

If the journey does not yet have an associated project:

mirror journey set-path <slug> /path/to/project

7. Finalize Session

When the user says "End the session":

mirror mirror log "SESSION_SUMMARY"

Adopted Method Behavior

A journey may adopt a Builder method. Method-specific behavior applies only when that method has been adopted for the active journey.

Currently implemented method-specific runtime: Ariad.

For journeys without adopted Ariad:

preserve Base Builder Mode behavior;
do not render Ariad surfaces;
do not route roadmap, pull, prepare, template, cursor, or lifecycle requests to Ariad commands;
if the user asks for Ariad behavior, explain that Ariad must be adopted first.

Inspect Builder Method

When the user asks which Builder method governs the active journey, inspect the current Builder method state:

mirror build inspect-method --journey <slug>

Render the command output visibly. If no Builder journey has been loaded in this session, do not run the command: say so plainly and ask the user to activate or name a journey. If the journey has not adopted a Builder method yet, say so plainly. Do not infer that Ariad governs the journey just because Ariad is available.

When the user asks what Ariad is as a Builder method, inspect the built-in method defaults:

mirror build inspect-method ariad

This is read-only inspection.

Adopt Ariad

When the user explicitly asks to adopt Ariad for the active journey, run:

mirror build adopt --journey <slug> --method ariad

Render the adoption report visibly. This mutates Builder method state only. It must not generate templates, create a delivery cursor, execute lifecycle work, change story status, commit, push, or release.

Ariad Runtime Behavior

This section applies only when the active journey has adopted Ariad (adopted_method == ariad).

Deterministic Ariad Surface Transport Protocol

This is a transport invariant for all Ariad commands and lifecycle phases, not a phase-specific instruction. In the Ariad method DSL, surfaces are runtime artifacts with transport=verbatim, marker_protocol=ariad_compact, and interpretation_policy=after_block_only.

Ariad runtime commands emit deterministic surfaces wrapped as:

<<<ARIAD:<SURFACE_ID>>>
...
<<<END:<SURFACE_ID>>>

For any command output that contains one or more Ariad surface blocks, the final assistant response must return every marked block from stdout verbatim before any commentary. This is a hard rendering requirement, not optional tool-output evidence. Do not summarize, translate, reorder, trim, rewrap, re-indent, reformat, or mix prose inside a wrapped surface. Do not replace a surface with a conversational summary, even when the user phrase is short (for example, validated, approved, ok, or continue). If you catch yourself summarizing a marked Ariad surface, stop and re-render the complete marked block before any interpretation.

If multiple Ariad surface blocks are emitted, return all of them in the same order. After the complete surface block(s), add a conversational interpretation for the Navigator. This interpretation should explain what happened, what it means, what is blocked or allowed now, and what the next Ariad step is. It may be complete and helpful, not merely a one-line summary, but it must stay outside the surface block and must not contradict the runtime boundary.

Use this pattern:

<<<ARIAD:<SURFACE_ID>>>
...
<<<END:<SURFACE_ID>>>

What happened:
...

Next step:
...

A refused lifecycle command renders CHECKPOINT_REFUSED. Return it verbatim like any other surface. It shows the stage the cursor actually holds and the true reason, and nothing changed: the refusal comes before any write. Read the reason before acting. An already-complete step needs no rerun, a pending confirmation needs the Navigator's answer, a step not reached needs the step before it, and missing evidence needs the evidence the reason names. A failure that is not a refusal prints a plain Error: line instead and makes no claim about what changed: run build show to see where the cursor stands before trying again.

If a marked block was lost before it reached the Navigator (output filtered, truncated, or never rendered), say which surface was lost and run build show, as described in Show The Active Checkpoint. Return its ACTIVE_CHECKPOINT block verbatim. Never substitute another command's surface, such as check-implementation, as evidence of where the cursor stands.

Paths on Ariad surfaces

A card prints a path inside the project relative to the journey's project_path, from the project_path= line build load prints. Open it by joining the two, never by joining it to the working directory, which can belong to another repository. A card that reports a file written or left in place names its project folder and journey on a project: row. If that row names a project or journey other than the one this session loaded, tell the Navigator before touching the files. Plan prints its files' absolute paths as *_path= lines below its surface. They are not part of the surface: use them as printed, and do not render them.

Statuses on Ariad surfaces

A row that names a roadmap package states its status as the first clause of the package's **Status:** line, links reduced to their labels, cut to fit the row. The rest of the line is in the package the row names; read it there when you need more than the status, such as why a package is Blocked.

Ariad Activation Surfaces

For Ariad-adopted journeys whose delivery cursor has no active item, build load emits:

PROJECT POSITION
■ BUILDER ORIENTATION

For Ariad-adopted journeys with no delivery cursor yet, or with an active item or a pending confirmation, build load emits:

■ BUILDER RESUME

Every position and next pull on these surfaces is the journey's own, derived from its delivery cursor. With an active item, the position is the Capability Value the item belongs to, and any recommended pull is chosen inside it. Without one, the surfaces read no item pulled yet, list project-wide candidates, recommend nothing, and give the literal pull explicitly: command. Never present a candidate from the project-wide list as this journey's recommendation.

These surfaces are mandatory activation output. The final response to the user must include the wrapped Ariad surface blocks verbatim from the command output. If the command output contains <<<ARIAD:BUILDER_RESUME>>>, <<<ARIAD:PROJECT_POSITION>>>, or <<<ARIAD:BUILDER_ORIENTATION>>>, the response is invalid unless the visible reply also contains every complete matching begin/end block in stdout order.

After rendering these surfaces, do not ask a generic question such as "inspeção runtime, planejamento de Delivery, ou exploração?" and do not add a third runtime-inspection option unless the surface itself recommends it. For an Ariad journey with no active item, ask only which item the Navigator wants to pull, from the project-wide list and without ranking it, or whether to inspect the roadmap further, after the verbatim blocks.

For an Ariad journey with an active item, the resume's allowed next actions are the steps the cursor accepts next, the recommended one first; build show prints the same list. Offer the step the list names, and no lifecycle step it does not. Offering is not doing: the Builder Activation Boundary holds, and no step runs before the Navigator says so. Each step routes to a section of this skill, or in Delivery Story flow to its Delivery Story command:

answer_pending_confirmation: ask the Navigator the question the pending confirmation row names. Never answer it.
prepare_active_item: Prepare, build prepare-item.
expand_active_item: Expand was blocked. After the Navigator fixes what EXPAND_BLOCKED named, pull the Delivery Story again.
plan_active_item: Plan Ariad Work.
implement_active_item: the implementation guard, then the approved Plan.
validate_active_item: Validate Ariad Work.
review_active_item_debt: Review Ariad Debt.
check_active_item_coherence: Check Ariad Coherence.
close_active_item: Close Ariad Done.
pull_candidate_if_known: the item is closed, or none is pulled. Pull the item the Navigator chooses, as Pull And Prepare Ariad Work describes.
inspect_roadmap: Inspect Roadmap And Pull Candidates.
inspect_method: Inspect Builder Method.
sync_cursor: Sync Delivery Cursor.
adopt_method: Adopt Ariad.

A list of only inspect_roadmap and inspect_method, on an item that is open, means the cursor holds a position Ariad does not know. Say so, and offer sync-cursor, then Pull. sync-cursor drops the item and any pending question, and returns the cadence to stepwise.

Compose Refinement Work

The Refinement authority

Refinement Work lives in project files, at this exact path beneath the trusted project_path:

docs/project/refinement/index.md

The root index is the sole authority for focus, ordering, and current RS/CR status; linked documents own narrative, plans, evidence, and outcomes. Read the project's own convention from the index before acting.

There is no second store. CV22.DS10.TS4 retired the compatibility-only SQLite Workbench and its twenty commands; the front door answers each of them with its cutoff. If the index does not exist, the project has not started Refinement Work — say so and offer to create the index. Never inspect legacy rows, never fall back to SQLite when a file-first operation is unclear, and never treat an absent index as a different kind of authority.

File-first path

When the Navigator asks to inspect, show, or orient to Refinement Work, read the canonical index and the linked documents needed to explain the current focus. Render one compact, agent-composed Refinement Workbench view with these facts in this order:

canonical project-relative index path;
focused RS and CR, or explicit none values;
every RS with its canonical status;
open CRs in canonical order with ID, RS, title, status, and canonical Driver and Delivery details when assigned;
terminal CR history after open work, preserving canonical Driver and Delivery provenance when present;
the next safe action for the focused item, grounded in its canonical status and linked plan; and
a boundary stating that inspection selected, changed, and executed nothing.

Use ▸ to distinguish focused items. Preserve index ordering exactly. Omit an empty section cleanly or label it none; do not invent content. The root index wins whenever linked narrative disagrees about focus or status. Name the source path visibly and state that SQLite was not consulted. A representative shape is:

Refinement Workbench

source
<canonical project-relative index path>

CURRENT FOCUS
<focused RS or none>
▸ <focused CR or none>

REFINEMENT STORIES
<RS rows in canonical order>

OPEN CHANGE REQUESTS
<non-terminal CR rows in canonical order>
  Driver: <canonical human> · Delivery: <canonical PR or branch>  # only when assigned

TERMINAL HISTORY
<terminal CR rows after open work, or none>
  Driver: <canonical human> · Delivery: <canonical PR or branch>  # only when present

NEXT SAFE ACTION
<one grounded next action>

BOUNDARY
Read-only inspection. No work was selected, changed, or executed.
SQLite was not consulted.

This is a presentation contract for the agent reading project documents, not a runtime-generated deterministic Ariad surface. Do not wrap it in <<<ARIAD:...>>>, add a Markdown parser, or call legacy Workbench commands to produce it. If the canonical index is unreadable or structurally ambiguous, report the practical defect and stop instead of silently falling back to SQLite. Read-only intent stays read-only: recommend a concrete correction, but do not mutate files.

Treat Driver and Delivery as canonical project facts, not runtime discoveries. Show them only when the index row provides values other than its documented empty marker. Never infer assignment from the current Git checkout, branch author, latest committer, active journey, conversation, or SQLite state. Follow the project's collaboration convention when changing status: if it requires Driver and Delivery before in_progress, blocked, or validated, stop for the missing Navigator decision rather than synthesizing either value. Reassignment and stale work disposition are semantic decisions and always remain explicit.

Collaborative file-first lifecycle

Read and follow any collaboration protocol linked by the canonical index. When no more specific project rule exists, use this route:

Inspect before mutation. Read the complete index and relevant linked documents. Confirm focus, existing IDs, target RS, status, Driver, and Delivery.
Capture without selecting. Require a concrete title, problem, expected behavior, and explicit RS target. If the layout has no unassigned CR location, stop rather than inventing one. Allocate the next unused project-wide numeric ID from the complete index, preserve three-digit formatting, create one evolving CR document with Problem, Expected Behavior, Impact, Plan Or Decision, Evidence, and Outcome, append a captured/unassigned row, and preserve Current Focus exactly.
Select explicitly. Update only Current Focus. Selection changes no status and authorizes neither planning nor implementation.
Plan before implementation. Record scope, affected files, acceptance, validation, exclusions, and authority boundaries. Move captured to planned only after Navigator approval.
Assign before starting. Before in_progress, obtain explicit human Driver and branch/PR Delivery decisions, then update status and both fields atomically. Replace a branch reference with the PR link after the PR opens.
Evidence is not validation. Record checks and isolated smoke evidence during implementation, but require an explicit natural Navigator validation route and acceptance before validated.
Review before terminal closure. Record proportionality/debt findings. done requires accepted validation and resolved debt action. blocked, parked, rejected, and promoted require narrative reasons; parked also requires a revisit trigger and promoted a Delivery target. Move terminal CRs below open work, preserve Driver/Delivery provenance, and clear focused CR state without selecting the next item implicitly.
Return a handoff. Report RS/CR, canonical status, Driver, Delivery, changed files, checks, Navigator validation, limitations, unresolved decisions, and the requested next action. A handoff never grants merge, publication, or release.
Let Git expose concurrency. Refresh against the approved base before final handoff. Never overwrite, silently renumber, merge narratives, delete another contributor's work, or use SQLite to resolve ID/index/focus/status conflicts. Stop for semantic conflict resolution.

When the Navigator asks how to create, work on, or collaborate through Refinement Work, answer read-only and explain the complete contributor route. Do not stop the explanation at terminal status: include the return handoff and how ordinary Git conflicts protect concurrent ID, index, focus, status, assignment, and narrative edits. Name the linked project protocol as the durable authority.

Status remains document vocabulary, not an application state machine. Do not add ID reservation, locks, watchers, heartbeats, stale-work automation, Markdown parsing, projection, synchronization, or custom Git commands without repeated operational evidence and separate Navigator approval.

When the Navigator authorizes a mutable operation such as capture, select, continue, update, or implement, that request also authorizes structural repairs needed to complete it without a second confirmation only when every repair is:

necessary for the requested operation;
deterministic from existing project evidence;
local to the involved Refinement documents;
non-destructive and reversible through Git;
meaning-preserving; and
free of unrequested status, priority, focus, identity, SQLite, configuration, commit, push, publication, or release decisions.

After completing the operation, explain in Navigator-facing project language what defect was found, what was repaired, and what was left unchanged. Do not lead with internal Mirror terms such as projection, artifact mismatch, or runtime coherence.

Stop only when repair would choose product meaning, delete content, resolve a concurrent conflict, or expand the original request. In that case, explain the practical consequence, recommend the smallest safe solution, name the files it would change, and ask for the missing decision. Never use legacy SQLite as a recovery path.

Follow the canonical file's status vocabulary and ID convention. Do not invent missing narrative or an RS assignment. Do not treat journey-local UUIDs or legacy display codes as project artifact identity. Git owns history, conflicts, and recovery; ordinary file work must not create an application-level Git protocol.

Prepare Ariad Templates

When the user asks to prepare Ariad templates or make the adopted journey documentation-ready, run:

mirror build prepare-templates --journey <slug> --method ariad

Render the report visibly. The operation may create missing method-declared template files, but must preserve existing files and must not create a delivery cursor, execute lifecycle work, change story status, commit, push, or release.

Sync Delivery Cursor

When the user asks to sync the initial Builder delivery cursor for an Ariad-adopted journey, run:

mirror build sync-cursor --journey <slug> --method ariad

Render the cursor sync report visibly. This persists runtime resume state only. It must not infer an active roadmap item, execute Pull/Prepare/Plan, change story status, commit, push, or release.

Inspect Roadmap And Pull Candidates

When the user asks to see the roadmap, inspect the roadmap, show roadmap candidates, see what can be pulled, choose the next story, or asks "o que posso puxar agora?", run:

mirror build pull-candidates --journey <slug> --method ariad

Render the configured Ariad surfaces visibly, currently ROADMAP SNAPSHOT and ■ Ariad Pull Candidates. With an active item both are scoped to its Capability Value: candidates in <CV>, a count of those outside, and a recommendation inside the CV (or no remaining candidates in <CV>). Without one, the list is project-wide candidates and no pull is recommended. This is read-only: it must not pull an item, update the cursor, execute lifecycle work, change story status, commit, push, or release.

Show The Active Checkpoint

When the user asks where the active item stands or asks to see the current checkpoint again, or when a surface was lost, run:

mirror build show --journey <slug> --method ariad

Return the ACTIVE_CHECKPOINT surface verbatim. It shows the stage, the cursor's position, the cadence, the steps the cursor accepts next, as the resume lists them, and the story package's files: index.md, plan.md, and test-guide.md with their state, and the closure records, each present or missing. It does not replay the original checkpoint surface: that evidence lives in those records, so read the one the Navigator needs, such as plan.md before Plan approval. It is read-only and changes neither the cursor nor any file.

Pull And Prepare Ariad Work

When the user asks to change testing/runtime cadence, use:

mirror build set-cadence --journey <slug> --method ariad --profile <stepwise|checkpoint|accelerated|autonomous>

Use stepwise for detailed dogfooding: Plan stops for approval unless the Navigator naturally asks the Driver to create and execute the active story Plan without another approval turn. Use checkpoint for normal Ariad cadence. Use accelerated when the Navigator trusts the Driver to complete the active story Plan and continue directly into local implementation; the runtime automatically records bounded story Plan authority and still stops at Navigator Validation. Use autonomous only with explicit Navigator limits, for example:

mirror build set-cadence --journey <slug> --method ariad \
  --profile autonomous \
  --limit "stop before push or release" \
  --limit "stop on scope change" \
  --limit "stop on failing checks"

The Builder resume, build show, and the Builder orientation print the cadence profile and, under autonomous, its limits. Read it there before Plan: under accelerated, Plan continues into implementation without a Navigator turn.

Higher-autonomy cadence never grants permission to cross Navigator validation acceptance, debt decisions, unsafe operations, scope changes, push/release, or Done/history boundaries. For an active User Story or Technical Story in story_by_story, accelerated satisfies the Plan approval gate through a complete, structurally matching, single-use receipt instead of pausing for another Navigator turn; Plan completeness and mismatch checks still apply. In current Ariad, Pull is the Navigator signal to Prepare; pulling a Delivery Story also expands it into implementable User/Technical Stories and stops for confirmation of the recommended next story.

When the user asks to continue under the active cadence, use:

mirror build continue-lifecycle --journey <slug> --method ariad \
  --process "<process alignment evidence>" \
  --project "<project/docs/artifacts alignment evidence>" \
  --product "<product behavior alignment evidence>" \
  --history-action "<required to cross Done/history boundary>" \
  --roadmap-update "<required to cross Done/history boundary>" \
  --next-recommendation "<required to cross Done/history boundary>"

continue-lifecycle may emit multiple Ariad surfaces; return every marked block verbatim in order. In stepwise cadence it must refuse automatic continuation. In higher-autonomy cadence it may continue only through bypassable soft stops and must still stop at hard gates when required evidence is missing.

When the user asks to pull a roadmap item into active Ariad work, run the contained Pull command with explicit item metadata:

mirror build pull-item --journey <slug> --method ariad \
  --item-code <code> \
  --item-title "<title>" \
  --item-level <delivery_story|user_story|technical_story> \
  --why-now "<why this level now>"

Render all emitted surfaces visibly. Pull may update runtime cursor active item and automatically run Prepare. If the pulled item is a Delivery Story, Pull also expands it into implementable child stories and recommends the next User/Technical Story to plan. Pull must not create a Plan, approve a checkpoint, implement, validate, review, close, commit, push, or release.

When the Pull card's source reads not in the roadmap, say so to the Navigator before planning: the code may be mistyped, or the roadmap behind.

When the Navigator confirms the recommended child story after an Expand surface, pull that child story explicitly with --item-level user_story or --item-level technical_story using the recommended code/title from the surface. Then plan that implementable story when requested.

When the user asks to prepare the pulled item, run:

mirror build prepare-item --journey <slug> --method ariad

Render the Prepare report visibly. Prepare may update the runtime cursor last delivery event, but must not create a Plan, approve a checkpoint, start implementation, change story status, commit, push, or release.

Delivery Story Candidate Table Authoring Contract

Expand resolves an already-authored Delivery Story package by its index.md heading code, never by folder name or arithmetic on code and title -- an authored package can live under any folder a human chose. Once resolved, Expand reads its ## Candidate Stories table, header-driven. The header must include these four column names (case-insensitive, any order, extra columns such as Outcome or Risk are fine):

| Code | Story | Type | Status |

or the 5-column generated variant:

| Code | Story | Type | Outcome | Status |

When authoring or reviewing a Delivery Story index.md by hand, use this exact grammar (see docs/project/roadmap/templates/delivery-story-index.md). If the Navigator proposes a different shape (for example | Family | Scope | Type | Risk |), flag the mismatch before Pull/Expand runs so the table is Expand-compatible by construction.

A pipe inside a cell is written \|, as GFM writes it, and reads back as |; Ariad escapes the pipes in any title it writes into a cell.

If Expand renders <<<ARIAD:EXPAND_BLOCKED>>> (the resolved package's table does not parse, two packages claim the same code, or a Delivery Story with no package would need a story that an authored package already claims), return the surface verbatim per the transport protocol, then explain what to fix: correct the table header to the canonical grammar, resolve the duplicate heading, or author the Delivery Story's index.md with a canonical candidate table that lists the story already authored. Do not hand-edit the package's materialized children to work around a blocked Expand, and do not re-run Pull/Expand until the Navigator has fixed the authored content.

Delivery Story Release Intent

When the active Ariad item belongs to a Delivery Story and the Navigator explicitly says the DS is expected to create a release boundary, has no release intent, or remains undecided, record only that planning state:

mirror build release-intent --journey <slug> --method ariad \
  --intent <planned|none|undecided>

To inspect without changing state, omit --intent. Return the RELEASE_INTENT surface verbatim.

Map only explicit meaning:

planned — the DS is expected to create a release boundary if completed coherently;
none — the DS is explicitly not expected to create a release boundary;
undecided — the decision is intentionally unresolved and may be revisited.

Do not infer intent from cadence, version changes, completed implementation, existing tags, roadmap position, or a previous DS. Release intent belongs to the Delivery Story ancestor and is not authorization to commit, push, create a tag, promote stable, publish a release, or mutate a remote system. Those remain separate gates.

Delivery Story Navigator Flow

When the active Ariad work is a Delivery Story or the Navigator refers to the current Delivery Story and says a natural-language equivalent of:

quero seguir no nível da DS
seguir no nível da Delivery Story
use Delivery Story flow
não preciso validar cada US
aprove um plano geral da DS e eu valido no fim

run:

mirror build set-flow-unit --journey <slug> --method ariad --unit delivery_story

Return the DELIVERY_STORY_SCOPE_CONFIRMATION surface verbatim. Explain after the surface that child User/Technical Stories remain traceable Driver work packages, and that choosing Delivery Story flow does not approve a Plan, start implementation, validate, push, or release.

The scope confirmation is a Navigator stop. It asks whether the scope is right before any DS Plan exists. The runtime records the stop without enforcing it: the cursor holds navigator_scope_confirmation until the Plan replaces it, and plan-delivery-story does not refuse while it is pending, so the question stays true only if you wait for the answer. End the turn after the surface. Do not run plan-delivery-story in the same turn, even when the Navigator's request also asked for the Plan. Plan only on a later Navigator turn that confirms or corrects the scope. Cadence and Plan preauthorization do not remove this stop.

A Builder resume that shows pending confirmation: navigator_scope_confirmation is this same question, still open. Ask it again, or render it again with the set-flow-unit --unit delivery_story command above, and plan only on the Navigator's answer.

A flow unit is chosen only at the Delivery Story's flow decision, after Prepare or Expand and before its Plan. Anywhere else set-flow-unit --unit refuses with one Error: no flow unit was chosen: ... line and changes nothing. Relay that reason to the Navigator. Do not reset or re-pull to force the choice without their decision.

set-flow-unit without --unit only inspects the current choice and renders NAVIGATOR_FLOW_UNIT.

When the effective flow unit is story_by_story, preserve existing child-story Plan behavior. Do not silently use Delivery Story-level Plan unless the Navigator has selected delivery_story flow or explicitly asks to follow work at Delivery Story level.

Delivery Story Plan Ariad Work

When the active Ariad work is a Delivery Story with navigator_flow_unit=delivery_story and the Navigator says a natural-language equivalent of:

planeje a DS
planeje a Delivery Story
plan the Delivery Story
crie o plano geral da DS

run:

mirror build plan-delivery-story --journey <slug> --method ariad \
  --objective "<aggregate Delivery Story objective>" \
  --child <child-work-item-code>

Pass one --child argument for each known child User/Technical Story work package. If child work packages are already present in the cursor, the command may use them; otherwise include the known roadmap child codes. If the user names a specific journey, pass --journey <slug>.

Return the DELIVERY_STORY_PLAN_CHECKPOINT surface verbatim. Interpret only after the block. Explain that the DS-level Plan is pending approval and that no implementation, validation, push, or release is authorized by planning alone.

Conditional Plan preauthorization

Use conditional preauthorization only when the Navigator explicitly authorizes one active Delivery Story by exact child identity and names the fixed next hard stop at Navigator Validation. Vague continuation, cadence selection, “faça tudo”, “não me pergunte nada”, or generic autonomy language never creates authority. Delivery Story preauthorization applies only to delivery_story flow. Exact User Story and Technical Story preauthorization is handled separately under story_by_story flow below.

For an explicit matching request, include:

mirror build plan-delivery-story --journey <slug> --method ariad \
  --objective "<aggregate Delivery Story objective>" \
  --child <every exact child code> \
  --preauthorize-approval \
  --stop-after navigator_validation

Return DELIVERY_STORY_PLAN_CHECKPOINT, PLAN_PREAUTHORIZATION_RECORDED, and artifact surfaces verbatim. The receipt is not approval: complete the Driver-owned plan.md first. Required sections must exist and contain no empty, Pending, TODO/TBD, or placeholder body. Never replace an existing non-empty Plan with the runtime scaffold.

In the same assistant turn, after completing the Plan, consume the receipt with:

mirror build approve-delivery-story-plan --journey <slug> --method ariad \
  --use-preauthorization

On exact match, return every approval/start surface, implement only local approved work, and stop at Navigator Validation. On PLAN_PREAUTHORIZATION_MISMATCH, return the bounded surface and stop at ordinary Plan approval. Never repair, expand, reinterpret, or recreate authority silently. Child order is presentational, but addition or removal is a mismatch.

Cancel pending authority when the Navigator withdraws it:

mirror build cancel-delivery-story-plan-preauthorization --journey <slug> \
  --method ariad

Cancellation preserves the ordinary Plan approval gate. Preauthorization never crosses validation acceptance, debt, Done/history, commit, push, release, deploy, purchase, or another irreversible boundary.

If the Navigator asks to plan the Delivery Story before selecting delivery_story flow, first surface or request the flow-unit choice; do not silently use DS-level Plan from the default story_by_story flow. Surfacing the choice with set-flow-unit --unit delivery_story ends the turn at its scope confirmation, as described in Delivery Story Navigator Flow; plan on the Navigator's next turn.

When the Navigator approves a pending DS-level Plan with natural language such as aprovo o plano da DS, plano da DS aprovado, or approve the Delivery Story plan, run:

mirror build approve-delivery-story-plan --journey <slug> --method ariad

Return every emitted Ariad surface verbatim, including DELIVERY_STORY_PLAN_CHECKPOINT, ARTIFACTS_MATERIALIZED, and IMPLEMENTATION_STARTED when present.

Plan approval authorizes local implementation under the approved DS Plan. After rendering the approval surfaces, do not stop to ask for a separate implementation command. Immediately begin implementing the approved plan: read the generated plan.md / test-guide.md artifacts and relevant code, edit local project files, and run appropriate checks. Still stop before hard gates: unsafe operations, scope changes, debt decisions, push, release, deploy, purchase, externally irreversible actions, and final Done/history boundaries remain explicit Navigator authorization points.

Plan Ariad Work

When the user asks to plan the pulled item, create a plan for the active item, or says a natural-language equivalent such as planeje o item puxado, run:

mirror build plan-item --journey <slug> --method ariad

Render the Plan Checkpoint visibly, and name the plan in the reply by its project-relative path: the card's story package, then /plan.md. The card holds no plan: it names the story files, index.md, plan.md, and test-guide.md, each with its state and the sections still to author. The plan is read in plan.md. Right after plan-item that file is usually the scaffold, so there is no plan to present yet: present it after it is authored, by the sequence below. Keep runtime cursor fields compact; do not let technical metadata replace the plan itself.

Plan may update runtime cursor checkpoint state and may create/update the Plan-stage story package (index.md, plan.md, and test-guide.md) only for an implementable User Story or Technical Story. Delivery Stories are never planned as the implementable unit; they must expand first. Plan must not approve the checkpoint, start implementation, change implementation files for the pulled item, change story status, commit, push, or release.

Author the plan before asking for approval

Plan writes plan.md as a scaffold: template sentences with the item's title pasted in. It is not a plan. The Objective, Scope, Acceptance Behavior, and Validation Route are what the Navigator approves from: write them for this story, in Navigator-facing language. The Non-Goals, Implementation Contract, Stop Conditions, and Approval Gate may stand as written when they are true. Unless the Plan checkpoint or build show names index.md authored, write its story statement, Outcome, and Acceptance Behavior too: it may say scaffold, partly authored, or incomplete.

The sequence:

plan-item.
Author plan.md, and index.md unless the Plan checkpoint or build show names it authored.
Run build show and return its ACTIVE_CHECKPOINT block. It must read ✓ plan.md — authored; if it does not, author what it names and run it again.
Present the plan from plan.md, section by section: the Objective, Scope, Non-Goals, Acceptance Behavior, and Validation Route as the file states them, not paraphrased into claims the file does not make. Then ask for approval.
On approval, approve-plan.

The runtime checks structure, not quality: one real line under a heading passes it. That check is a floor. The bar is a plan the Navigator can approve from.

approve-plan refuses with CHECKPOINT_REFUSED while any section it requires is missing, empty, pending, or still the scaffold's, and names each by its heading. A refusal means: author what it names, run build show, and present the plan again. Do not run approve-plan again in the same turn as if the approval were still standing: the Navigator approved a plan that did not exist yet.

done-item refuses the same way while the story's index.md still says what Expand or Plan wrote ("I want to <title>"). Write the story it is before closing it.

Conditional story Plan preauthorization

Use story-level conditional preauthorization for one active User Story or Technical Story in story_by_story flow through either of two routes:

natural explicit delegation in any cadence — the Navigator asks the Driver to create the active story Plan and execute it without another Plan approval turn, for example crie o plano e execute sem que eu precise autorizar, faça o plano e implemente com preautorização concedida, or an equivalent natural phrase;
accelerated cadence — plan-item automatically records bounded story Plan authority, so the Driver completes the Plan and continues without a Plan stop.

The Navigator does not need to recite story identity, sibling exclusions, fingerprint policy, mismatch behavior, or the Validation boundary. Ariad derives those safeguards from the active cursor and method: exact active item and level, story_by_story flow, current generation, no sibling scope, complete Plan, single use, bounded mismatch fallback, and stop at Navigator Validation.

Vague continuation such as continue, an isolated faça tudo, or não me pergunte nada does not create stepwise story authority. Selecting accelerated is itself the explicit cadence decision that authorizes Plan continuation for active implementable stories. For natural explicit delegation, run:

mirror build plan-item --journey <slug> --method ariad \
  --preauthorize-approval \
  --stop-after navigator_validation

In accelerated cadence, run ordinary plan-item without the explicit flag; the runtime automatically records bounded story Plan authority and emits the same receipt surface. Do not pause for Navigator approval after either route.

Return PLAN_CHECKPOINT, PLAN_PREAUTHORIZATION_RECORDED, and artifact surfaces verbatim. Preserve existing index.md, plan.md, and test-guide.md bytes. The receipt is not approval: the Driver-owned Plan must be authored, as in Author the plan before asking for approval, before authority can be consumed. The Objective, Scope, Acceptance Behavior, and Validation Route must be written for this story, not the scaffold's sentences, and the Non-Goals and Implementation Contract must not be empty. A plan that is not authored returns PLAN_PREAUTHORIZATION_MISMATCH with reason plan_incomplete and the sections still to author.

In the same assistant turn, after completing the exact story Plan, run:

mirror build approve-plan --journey <slug> --method ariad \
  --use-preauthorization

On exact match, return every approval and IMPLEMENTATION_STARTED surface, implement only the active story locally, and stop at Navigator Validation. On PLAN_PREAUTHORIZATION_MISMATCH, return the bounded surface and stop at ordinary Plan approval; never repair, reinterpret, or recreate authority silently.

Cancel pending story authority when the Navigator withdraws it:

mirror build cancel-plan-preauthorization --journey <slug> --method ariad

Cancellation preserves the ordinary Plan gate. Story authority is private, single-use, cursor-generation-bound, and cannot authorize a sibling story, Validation acceptance, Debt Review, Done/history, commit, push, release, deploy, purchase, or another irreversible action.

When the Navigator approves an ordinary Plan checkpoint, run:

mirror build approve-plan --journey <slug> --method ariad

If the user asks to implement while the Plan checkpoint is pending, run the guard before doing any implementation work:

mirror build check-implementation --journey <slug> --method ariad

Render the deterministic IMPLEMENTATION_GUARD surface. If the guard reports that Navigator approval is required, return the surface and stop. Do not mutate files.

Closure Records

validation.md, review.md, coherence.md, and done.md are records that Ariad seals: their last line is . A closure command rewrites a record only while its seal still matches. Anything else is left exactly as it is, and the checkpoint says preserved.

preserved is not an error. It means a person wrote or edited the file, and their version stands. The checkpoint's fields are in the surface you render, and they were not written to the file.

Never delete, rewrite, or re-seal an authored record to make Ariad write it.
Never copy a seal line into a file.
If the Navigator wants Ariad's record in the file, ask how they want their own notes kept.

Delivery Story Validation And Closure

When the active Ariad work is a Delivery Story with navigator_flow_unit=delivery_story and an approved aggregate DS Plan, route natural Navigator requests for aggregate DS closure through the Delivery Story runtime commands.

For natural validation requests such as valide a DS, valide a Delivery Story, or validação da DS aceita, run:

mirror build validate-delivery-story --journey <slug> --method ariad \
  --summary "<aggregate DS validation evidence>" \
  --navigator-accepted

For DS-level debt review requests, run:

mirror build review-delivery-story --journey <slug> --method ariad \
  --decision <no_action|defer|pay_now> \
  --summary "<DS-level debt review summary>"

For DS-level Done requests after Debt Review and Navigator closure confirmation, first align authored project state: mark the resolved Delivery Story package, every known child package/candidate row, and every canonical roadmap table row for the DS as Done. Then run:

mirror build done-delivery-story --journey <slug> --method ariad \
  --summary "<DS-level done/history summary>"

The command runs an authored roadmap closure preflight before cursor or artifact mutation. If any DS package, known child package/candidate row, or canonical roadmap row remains non-Done, the runtime refuses Done before cursor or artifact mutation and names project-relative files to align. The agent owns semantic Markdown updates; the runtime verifies explicit status evidence and never invents project meaning.

DS-level Coherence is not a separate lifecycle stage before Done. It is checked inside Done only after the authored status preflight passes, so the final surface can truthfully state that docs, roadmap, cursor, artifacts, and next-pull readiness remain consistent after closure.

Return every DELIVERY_STORY_CLOSURE_CHECKPOINT surface verbatim. Explain after the block that child User/Technical Stories remain evidence units and that push/release remain separate hard gates. Do not use these DS-level closure commands when the effective flow unit is story_by_story; preserve existing child-story lifecycle behavior in that mode.

Validate Ariad Work

After implementation is complete and before moving to Debt Review or Done, render the Validation checkpoint:

mirror build validate-item --journey <slug> --method ariad \
  --implementation-complete \
  --check "<automated check command or evidence>" \
  --checks-status <passed|failed|not_run> \
  --e2e-decision <required|not_required|waived|skipped> \
  --e2e-evidence "<E2E evidence or waiver/skipped reason>" \
  --navigator-route "<Navigator-visible validation route>" \
  --navigator-accepted \
  --expected-observation "<what the Navigator should observe>" \
  --pass-condition "<what counts as pass>" \
  --fail-condition "<what counts as fail>"

If the Navigator has already performed and accepted the validation route, also pass --navigator-accepted. Providing a route is not the same as acceptance.

Render the deterministic VALIDATION_CHECKPOINT surface. If required evidence is missing or Navigator validation has not been accepted, return the surface and stop; do not advance to Debt Review, Done, commit, push, or release.

Review Ariad Debt

After Validation has passed and before moving to Done, render the Debt Review checkpoint:

mirror build review-item --journey <slug> --method ariad \
  --debt "<debt finding, or No debt found>" \
  --decision <pending|no_action|defer|pay_now> \
  --defer-reason "<required when decision=defer>" \
  --revisit-trigger "<required when decision=defer>"

Render the deterministic DEBT_REVIEW_CHECKPOINT surface. If the decision is pending, defer without a reason/trigger, or pay_now, stop at the debt decision checkpoint. pay_now must route through a future Refactor loop before Done. Do not advance to Done, commit, push, or release while the debt decision is unresolved.

Check Ariad Coherence

After Debt Review is complete, verify Process, Project, and Product alignment:

mirror build coherence-item --journey <slug> --method ariad \
  --process "<process alignment evidence>" \
  --project "<project alignment evidence>" \
  --product "<product alignment evidence>"

Render the COHERENCE_CHECKPOINT surface. If it reports pending_coherence, correct the missing evidence and rerun the same command. Reentry is valid only for the exact navigator_coherence / last_delivery_event=coherence state. It re-evaluates the evidence; it does not bypass Coherence. Unrelated pending confirmations stay blocked, and done-item never consumes navigator_coherence.

Close Ariad Done

After Coherence is complete and the Navigator confirms there is nothing else to do in the story, render the Done checkpoint:

mirror build done-item --journey <slug> --method ariad \
  --history-action "<commit/history action taken or proposed>" \
  --roadmap-update "<roadmap/story package update>" \
  --next-recommendation "<next Pull, parent collapse, or release boundary>"

Render the deterministic DONE_CHECKPOINT surface. Done must name the history action, roadmap/story package update, and next Ariad movement. Do not push or release unless the effective policy explicitly allows it.