gaia-add-feature

name	gaia-add-feature
description	Triage and route a fix, enhancement, or feature through only the affected artifacts. Classifies as patch/enhancement/feature and cascades accordingly -- updating PRD, architecture, epics, test plan, threat model, and traceability as needed. Surfaces Val verdicts (PASS/WARNING/CRITICAL) and emits an assessment-doc audit trail.
allowed-tools	["Read","Write","Edit","Grep","Glob","Bash","Agent"]
orchestration_class	heavy-procedural

Orchestration Mode

SESSION_MODE=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/detect-orchestration-mode.sh")
WARNING_OUTPUT=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/orchestration-warning.sh" --skill-class heavy-procedural --mode "$SESSION_MODE")
if printf '%s' "$WARNING_OUTPUT" | grep -q '^SURFACE-WARNING: '; then
  SENTINEL_PATH=$(printf '%s' "$WARNING_OUTPUT" | sed -n 's/^SURFACE-WARNING: //p' | head -n1)
  cat "$SENTINEL_PATH"
fi

Surface contract. When the prelude cats a sentinel file — which happens once per session under Mode A (subagent dispatch) — you MUST mirror that cat'd warning text VERBATIM as the FIRST user-visible text of your response, before any skill-phase output. Claude Code auto-collapses Bash tool-call output, so the warning is invisible to users unless re-emitted as LLM turn text. Skip this step only when the prelude produced no sentinel output (Mode B, repeat invocation in same session, or out-of-scope skill class).

Setup

!${CLAUDE_PLUGIN_ROOT}/skills/gaia-add-feature/scripts/setup.sh

Memory

!${CLAUDE_PLUGIN_ROOT}/scripts/memory-loader.sh pm decision-log

Brain Context

!${CLAUDE_PLUGIN_ROOT}/scripts/brain/brain-reliance-loader.sh gaia-add-feature:cascade-entry

Mission

You are the orchestrator for adding a new feature, enhancement, or patch to the project. You classify the change scope and cascade updates through exactly the set of affected artifacts. This skill delegates to sub-workflows via subagents -- it does not perform direct edits to downstream artifacts.

This skill is the native Claude Code conversion of the legacy add-feature workflow and is hardened so that validation gates are no longer swallowed inside subagents. The classification vocabulary (patch / enhancement / feature), cascade matrix, and delegation model are preserved verbatim from the legacy workflow.

Critical Rules

• This is an orchestrator -- delegate to sub-workflows via subagents, do not perform edits directly.
• Context flows forward: PRD diff feeds architecture edit, which feeds test plan edit, which feeds story creation.
• Intelligently skip steps when not needed -- do not force all sub-workflows on every change.
• The classification vocabulary is EXACTLY: patch, enhancement, feature. Do NOT rename, alias, or refactor these terms -- downstream triage tooling and historical change requests depend on those exact strings.
• The cascade matrix (which artifacts are updated per classification) MUST match the definitions below exactly.
• Validation gates are MANDATORY surfacing points -- never silently consume Val verdicts inside a subagent. Always parse the structured return schema and apply the verdict-surfacing contract before continuing the cascade.
• A CRITICAL verdict from Val HALTS the skill before cascade execution. This applies in all execution modes (normal and YOLO).
• AskUserQuestion call MUST precede Val dispatch under Auto Mode. Step 2 entry MUST emit an AskUserQuestion tool call before the Agent-tool dispatch to Val. AskUserQuestion is substrate-enforced under Auto Mode (per the empirical evidence captured in user memory rule feedback_askuserquestion_under_automode.md, 2026-05-09); this is the primitive that catches the "auto-mode self-judgment" bypass class. Do NOT substitute stdout sentinels, Stop hooks, or pause-and-wait scripts -- they are bypassed under Auto Mode (the gaia-meeting precedent).
• Sentinel checkpoint MUST exist before Step 3. Step 2 MUST write .gaia/memory/checkpoints/add-feature-{feature_id}-val-dispatched.json via the dedicated scripts/write-val-sentinel.sh writer (which delegates to atomic tempfile + mv and constructs JSON via jq -n, never via heredoc). finalize.sh validates the sentinel before allowing cascade completion -- a missing or malformed sentinel HALTs the workflow with stderr Val gate sentinel missing.*re-invoke from a parent orchestrator thread. This is the primitive that catches the "skipped Step 2 entirely" bypass class.
• There is NO patch-mode exception to the Val gate. Patch classification still requires a dispatched Val subagent and the same verdict-surfacing contract as enhancement and feature classifications. Self-license patterns of the form "auto-judge under patch classification", "inline-judge because the diff is small", or "skip Val for trivial typo fix" are forbidden. The classification is decided in Step 1; the Val gate runs unconditionally in Step 2 before any cascade or direct edit.
• No inline Val — Val MUST be dispatched via the main-turn Agent tool. After dispatch, the skill MUST source ${CLAUDE_PLUGIN_ROOT}/scripts/lib/assert-agent-envelope.sh and invoke assert_agent_envelope {sentinel_path} against the envelope sentinel the Val persona writes; on non-zero exit HALT with the canonical error string. The LLM MUST NOT pass off its own inline review as a Val outcome, MUST NOT compose a synthetic structured return JSON in the parent thread, and MUST NOT set status: PASS without a real Agent-tool dispatch + envelope-assert success. If the Agent tool is not available in the current context (e.g., running under a fork that did not allowlist Agent), HALT immediately with the parent-thread re-invoke message in Step 2 -- do NOT self-judge the Val gate from the parent thread. The four-layer fail-closed enforcement (dispatch checkpoint + AskUserQuestion precondition + prose hardening + bats anti-pattern check) remains intact; the envelope-assert is a NEW layer on top, not a replacement.
• Dispatch prompt hygiene. The Val dispatch prompt MUST contain ONLY the raw Step 1 intake fields. The orchestrator MUST NOT (a) instruct Val on the sentinel JSON shape, field names, or hash basis — the validator persona's Sentinel-Write Contract at plugins/gaia/agents/validator.md is the single source of truth; (b) pre-load a prior run's findings, verdict, or recommendations into a re-dispatch prompt — the substrate's content-integrity guard flags this as forgery and the cascade MUST HALT; (c) invent an artifact_path value — pass feature_id as the literal artifact_path so caller and persona hash the same string. See Step 2b "Dispatch prompt hygiene" block for the full rationale.

Subagent Dispatch Contract

This skill follows the framework-wide Subagent Dispatch Contract. Every Val invocation is dispatched via the main-turn Agent tool with a read-only tool allowlist [Read, Grep, Glob, Bash, Write] (Val needs Write to emit the envelope sentinel from inside its own execution context per the Sentinel-Write Contract). Dispatch is pinned to model: claude-opus-4-7 and effort: high (Val opus pin — validation rigor is the contract).

Envelope-assert step. After the Agent call returns and BEFORE consuming the Val verdict, the skill MUST source ${CLAUDE_PLUGIN_ROOT}/scripts/lib/assert-agent-envelope.sh and invoke assert_agent_envelope {sentinel_path} where {sentinel_path} = .gaia/memory/checkpoints/val-envelope-{sha256(artifact_path) first 16 hex}.json. On non-zero exit, HALT with the canonical error string HALT: Val agent envelope assertion failed — sentinel absent, malformed, or forged at {path} — DO NOT fall through to a self-judged verdict. Closes the regression class documented in feedback_add_feature_val_gate_fails_open.md.

Sentinel coexistence. Two layered sentinels coexist post-migration — they answer different questions:

• Dispatch checkpoint (.gaia/memory/checkpoints/add-feature-{feature_id}-val-dispatched.json) — validated by finalize.sh, proves dispatch HAPPENED.
• Envelope sentinel (.gaia/memory/checkpoints/val-envelope-{artifact-hash}.json) — validated by assert_agent_envelope, proves the dispatcher was AUTHENTIC (Val persona). Both MUST pass for the cascade to proceed. The two sentinel paths are distinct slugs (add-feature-...val-dispatched.json vs val-envelope-...json) and do NOT collide.

After Val returns:

1. Parse the subagent return using the structured schema: { status, summary, artifacts, findings, next }. The status field is one of PASS, WARNING, CRITICAL. Each entry in findings carries a severity of CRITICAL, WARNING, or INFO.
2. Surface the verdict to the user inline: display status and summary, then list every finding with its severity, scope, and recommended action.
3. Halt on CRITICAL -- if status == "CRITICAL" or any finding has severity == "CRITICAL", the skill HALTS before cascade execution with an actionable error message. The user must resolve the finding before the skill can resume (or abort). No assessment-doc is emitted on a CRITICAL halt.
4. Display WARNING -- findings with severity == "WARNING" are displayed inline before proceeding. The skill does NOT halt; warnings are recorded in the assessment-doc Val Findings Summary section.
5. Log INFO -- findings with severity == "INFO" are written to the workflow checkpoint and the assessment-doc Val Findings Summary but are not surfaced inline unless the user requests verbose output.

This contract is enforced uniformly. CRITICAL findings cannot be auto-dismissed in any execution mode.

YOLO Behavior

This skill conforms to the framework-wide YOLO Mode Contract.

Behavior	YOLO Action
Template-output prompts ([c]/[y]/[e])	Auto-continue (skip prompt).
Severity / filter selection	Auto-accept defaults.
Optional confirmation ("Proceed with cascade?")	Auto-confirm.
Subagent verdict display (Val review gate)	Auto-display, but a CRITICAL verdict still HALTS.
Val gate dispatch under absent Agent tool	HALT -- never auto-judge, never inline-Val. Surface Re-invoke /gaia-add-feature from a parent orchestrator thread error.
Open-question indicators (urgency, driver, CR linkage)	HALT -- never auto-skip; require human input.
Memory save prompt at end	HALT -- require human input.

In YOLO mode the Val verdict is auto-displayed but a CRITICAL verdict still halts the skill -- this is the canonical YOLO/CRITICAL interaction.

Classification Vocabulary

Changes are classified into exactly one of three categories:

Classification	Scope	Description
patch	Minimal	A one-line typo fix, copy change, or trivial correction. Touches only the directly affected doc. Does NOT cascade to PRD, architecture, epics, test plan, threat model, or traceability.
enhancement	Moderate	A story-level change such as a new acceptance criterion on an existing story. Cascades to epics + test plan + traceability. Leaves PRD, architecture, and threat model untouched unless impact is explicitly flagged.
feature	Full	A net-new user-visible capability. Full cascade across PRD, architecture, epics, test plan, threat model, and traceability.

Cascade Matrix

The cascade matrix defines which artifacts are updated for each classification:

Artifact	patch	enhancement	feature
PRD (.gaia/artifacts/planning-artifacts/prd.md)	--	--	YES
Architecture (.gaia/artifacts/planning-artifacts/architecture.md)	--	--	YES
Epics & Stories (.gaia/artifacts/planning-artifacts/epics-and-stories.md)	--	YES	YES
Test Plan (.gaia/artifacts/test-artifacts/test-plan.md)	--	YES	YES
Threat Model (.gaia/artifacts/planning-artifacts/threat-model.md)	--	--	YES
Traceability (.gaia/artifacts/test-artifacts/traceability-matrix.md)	--	YES	YES

"--" means the artifact is NOT touched for that classification. "YES" means the artifact IS updated via the appropriate sub-workflow.

Steps

Step 1 -- Capture Feature Scope

• Ask: Describe the new feature, enhancement, or fix you want to add.
• Ask: What is the urgency? Vocabulary: critical / high / medium / low.
  • critical -- blocking production or active customer impact.
  • high -- important and time-bound, fits next sprint.
  • medium -- normal backlog priority.
  • low -- nice-to-have, no time pressure.
• Ask: What is the driver? Vocabulary: user-request / bug-report / tech-debt / opportunity.
  • user-request -- explicit ask from a user, customer, or stakeholder.
  • bug-report -- defect, regression, or incorrect behaviour.
  • tech-debt -- internal quality, maintainability, or refactor.
  • opportunity -- new market, capability, or strategic improvement.
• Ask: Is this linked to a change request? If so, provide the CR ID.
• If CR exists: read .gaia/artifacts/planning-artifacts/change-request-{cr_id}.md for context (impact analysis, approval status).
• Generate feature_id in the format AF-{date}-{N} where {date} is the current date (AF-{YYYY-MM-DD}-{N}) and {N} is a monotonically increasing integer for that date. To resolve {N}, scan .gaia/artifacts/planning-artifacts/epics-and-stories.md and any prior .gaia/artifacts/planning-artifacts/assessment-AF-{date}-*.md artifacts; use the highest existing index for today plus one, or 1 if none exist.
• Classify the change as patch, enhancement, or feature based on scope analysis.
• Present the scope summary to the user for confirmation before proceeding:
  • Feature ID: {feature_id}
  • Change: {description}
  • Classification: {patch / enhancement / feature}
  • Urgency: {critical / high / medium / low}
  • Driver: {user-request / bug-report / tech-debt / opportunity}
  • CR: {cr_id or "none"}
  • Expected cascade: {list of artifacts that will be updated per the cascade matrix}

Step 1 --from-discovery mode (hydration pre-fill)

When invoked as /gaia-add-feature --from-discovery <board-item-id>, Step 1 pre-fills the intake fields from a graduated discovery board item instead of prompting the user for each field from scratch:

1. Resolve the board item. Invoke discovery-board.sh graduate --id <board-item-id> --from-discovery to validate graduation eligibility and emit the hydrated intake fields (description from title, urgency from priority, driver from source). Reject unknown, terminal, or non-Evaluated item ids BEFORE any Step 1 hydration -- the resolver dies with an actionable diagnostic.
2. Pre-fill only. The hydrated fields populate the Step 1 intake form as editable defaults. Classification is RE-DERIVED from scope analysis -- never accepted from the hydrated payload. All hydrated text is treated as untrusted data (sanitized, length-capped, control chars stripped per the discovery-board.sh sanitization helpers).
3. Scope-confirmation prompt is PRESERVED. The pre-filled scope summary is still presented to the user for confirmation before proceeding to Step 1c. Hydration does NOT bypass the scope-confirmation prompt -- it is pre-fill only, not auto-confirm.
4. Step 1c re-validation is PRESERVED. The re-validation of prereqs under the captured classification still runs with a real Val dispatch. Hydration does NOT bypass Step 1c or short-circuit to Step 2.

After /gaia-add-feature completes successfully (backlog row lands), invoke discovery-board.sh graduate --id <board-item-id> --feature-id <feature_id> to transition the board item to Graduated and stamp the backlog feature id. A HALT at Step 1c or Step 2 leaves the board item in Evaluated state, preserving re-entrancy.

Step 1c -- Re-validate prereqs under captured classification

The initial setup.sh invocation ran under the default enhancement classification. Now that Step 1 has captured the actual classification, re-invoke setup.sh so the test-plan / traceability gates fire AGAINST that classification:

!${CLAUDE_PLUGIN_ROOT}/skills/gaia-add-feature/scripts/setup.sh \
  --classification "$CLASSIFICATION" \
  --feature-id "$FEATURE_ID"

Behaviour by classification:

• patch: the test-plan / traceability gates are SKIPPED. The re-invocation is harmless.
• enhancement / feature: the test-plan and traceability presence gates fire. If either artifact is missing, setup.sh HALTs with one of:
  • HALT: test-plan.md is missing — run /gaia-test-design first, then re-invoke /gaia-add-feature {feature_id}
  • HALT: traceability-matrix.md is missing — run /gaia-trace first, then re-invoke /gaia-add-feature {feature_id}

These HALTs are TERMINAL — the cascade does NOT proceed to Step 2. The user must bootstrap the missing artifact via the named skill, then re-invoke /gaia-add-feature with the feature_id. The path forms validate-gate.sh resolves (flat / strategy / sharded) are owned by validate-gate.sh; this skill does not duplicate that lookup.

Step 2 -- Val Review Gate (mandatory verdict surfacing)

This step is the canonical Val review gate. It restores the validation gate that previously ran silently inside the cascade subagents and is hardened with two fail-closed primitives at the Step 2 boundary: (1) an AskUserQuestion substrate-enforced halt at gate entry, (2) a sentinel checkpoint JSON written on Val PASS that finalize.sh validates before cascade completion.

Parent thread invocation required.

Val MUST be dispatched via the main-turn Agent tool. There is NO patch-mode exception -- patch, enhancement, and feature classifications all run the Val gate unconditionally.

If the Agent tool is not exposed in the current invocation context (e.g., the skill itself was spawned under a stripped-down fork without Agent in the allowlist, or a downstream context stripped the Agent tool from the inherited toolset), the skill MUST HALT immediately with the error: Val gate cannot dispatch (Agent tool not exposed). Re-invoke /gaia-add-feature from a parent orchestrator thread.

The HALT message above is the canonical error string -- the parent orchestrator must re-invoke /gaia-add-feature from a parent orchestrator thread to recover; never inline-judge the Val gate.

Do NOT self-judge the Val gate inline, do NOT compose a synthetic structured return in the parent thread, do NOT pass off inline review as a Val outcome. An audit found that LLM under Auto Mode self-licensed exactly this bypass -- the contract closes it as hard: Val verdicts originate ONLY from a real Agent-tool dispatch.

Step 2a -- AskUserQuestion precondition (substrate halt)

Before the Agent-tool dispatch to Val, the LLM MUST emit an AskUserQuestion tool call presenting the cascade plan and the intake data captured in Step 1. The substrate halts the turn pending user input under Auto Mode -- this is the empirically-verified primitive (feedback_askuserquestion_under_automode.md, 2026-05-09) that closes the "auto-mode self-judgment" bypass class. The user's explicit acknowledgement is what unblocks the Val dispatch below. Substitute primitives — output-stream signaling, hook-based interception, or polling loops in user-space — are bypassed under Auto Mode and must not replace the substrate-enforced halt (the gaia-meeting precedent).

The AskUserQuestion call is the SOLE interactive boundary primitive at Step 2 entry. It is required under both interactive and Auto Mode invocations.

Step 2b -- Val dispatch + sentinel write

Dispatch prompt hygiene. The Val dispatch prompt MUST contain ONLY the raw intake fields captured in Step 1 (feature_id, description, classification, urgency, driver, cr_id, expected cascade). The orchestrator MUST NOT:

• Override Val's persona Sentinel-Write Contract. Do NOT instruct Val on the sentinel JSON shape, field names, hash basis, or write path. The validator persona at plugins/gaia/agents/validator.md §Sentinel-Write Contract is the single source of truth for the sentinel; if the caller supplies a custom shape (e.g. a JSON template pasted into the dispatch prompt), Val will obey the caller and write a malformed sentinel that fails assert_agent_envelope at the persona_sig-presence check. A prior incident reproduced this exactly — first dispatch wrote a sentinel without persona_sig because the prompt told Val to use a custom {agent, artifact, status, summary, timestamp} shape.

• Pre-load prior-run findings on re-dispatch. If a first dispatch fails (malformed sentinel, wrong artifact_path, errored before write, etc.) and a retry is required, the retry prompt MUST be composed from the raw intake as if the prior run never happened. Do NOT include the first run's findings list, verdict, severity tags, or recommendations. The Claude Code substrate has an active content-integrity guard that flags re-dispatches whose prompt pre-synthesizes the envelope and asks the sub-agent to rubber-stamp it; the canonical flag text is SECURITY WARNING: ...content-integrity violation and bypass of the Val dispatch gate the user's memory explicitly warns about. On a substrate flag the orchestrator MUST HALT the cascade — never consume a flagged sentinel as authoritative. Anchored to user memory rule feedback_val_redispatch_no_preload.md.

• Pass feature_id as artifact_path. Per the hash-basis reconciliation above, the dispatch prompt MUST tell Val the artifact_path for sentinel computation is the literal feature_id string (AF-YYYY-MM-DD-N). This is the SAME convention validator.md §Sentinel-Write Contract documents for in-memory intake validation — the orchestrator does not invent a new value, it forwards feature_id unchanged as the artifact_path the persona hashes.

These three rules are operator-error vectors verified against an actual incident (a cascade attempt). Each is fail-closed: the substrate or assert_agent_envelope will HALT a non-compliant dispatch — but the friction of recovery is high, so adhere to the hygiene rules at dispatch time.

• Spawn a Val subagent via the main-turn Agent tool, model: claude-opus-4-7, effort: high, and the read-only tool allowlist [Read, Grep, Glob, Bash, Write] (Val needs Write to emit the envelope sentinel from inside its own execution context) (Val opus pin). Pass the intake data captured in Step 1 (feature_id, description, classification, urgency, driver, CR linkage, expected cascade). Per the Dispatch prompt hygiene block above, pass feature_id as the literal artifact_path for sentinel computation and DO NOT include a sentinel JSON template or any pre-synthesized findings in the prompt.

• Envelope-assert step. After the Agent call returns and BEFORE consuming the Val verdict, source ${CLAUDE_PLUGIN_ROOT}/scripts/lib/assert-agent-envelope.sh and invoke assert_agent_envelope {sentinel_path} where {sentinel_path} = .gaia/memory/checkpoints/val-envelope-{sha256(artifact_path) first 16 hex}.json. For /gaia-add-feature the validation target is an in-memory intake object, not an on-disk artifact — the orchestrator MUST pass the feature_id (e.g. AF-YYYY-MM-DD-N) as the literal artifact_path string to Val so both sides compute the same sha256. The validator persona's Sentinel-Write Contract (§Sentinel-Write Contract in plugins/gaia/agents/validator.md) computes the sentinel path as sha256(artifact_path); passing feature_id as artifact_path keeps caller and persona in agreement. This is the SINGLE source of truth for the hash basis — the prior text "sha256(feature_id)" was a drift defect and is corrected here. On non-zero exit, HALT with the canonical error string HALT: Val agent envelope assertion failed — sentinel absent, malformed, or forged at {path} — DO NOT fall through to a self-judged verdict. The cascade MUST NOT proceed without a validated assessment. This closes the fail-open regression class documented in feedback_add_feature_val_gate_fails_open.md at the authenticity layer; the existing dispatch-checkpoint precondition (validated by finalize.sh) continues to guard the dispatch-happened layer. See the Subagent Dispatch Contract section above for the sentinel coexistence rationale and distinct sentinel paths.

• Non-opus mismatch guard. If a test fixture or downstream override forces a non-opus model into the dispatch context, this skill MUST emit the canonical WARNING Val dispatch on non-opus model — forcing opus and force model: claude-opus-4-7 before invoking Val. Silent degradation is forbidden.

• [Val opus-pin contract — see plugins/gaia/agents/validator.md §Val Operations]

• Val validates the intake against the codebase and ground truth and returns the structured schema: { status, summary, artifacts, findings, next }.

• Apply the Subagent Dispatch Contract above:

  1. Display status and summary inline.
  2. List every finding with its severity, scope, and recommended action.
  3. Halt on CRITICAL -- if status == "CRITICAL" or any finding has severity == "CRITICAL", HALT the skill before cascade execution with an actionable error message that includes the finding text and suggested resolution. Do NOT proceed to Step 3. Do NOT emit an assessment-doc -- the cascade did not run.
  4. Display WARNING findings inline; record them for the assessment-doc.
  5. Log INFO findings to the checkpoint and assessment-doc.

• In YOLO mode the verdict is auto-displayed (no [c]/[y]/[e] pause) but a CRITICAL verdict still HALTS. The Step 2a AskUserQuestion call is NOT bypassed in YOLO mode -- it is the substrate-enforced halt that protects against silent gate skips.

• After Val returns a non-CRITICAL verdict (PASS or WARNING), MUST write the sentinel via scripts/write-val-sentinel.sh:

  printf '%s' "$VAL_RETURN_JSON" \
    | "${CLAUDE_PLUGIN_ROOT}/skills/gaia-add-feature/scripts/write-val-sentinel.sh" \
        --feature-id "$FEATURE_ID"
  

  The writer constructs the sentinel JSON via jq -n (NOT via heredoc / cat <<EOF), validates the required keys (status enum, summary, findings array, agent=val), and writes atomically (sibling tempfile + mv). The sentinel path is .gaia/memory/checkpoints/add-feature-${FEATURE_ID}-val-dispatched.json.

  finalize.sh validates the sentinel before allowing cascade completion; a missing or malformed sentinel HALTs the skill with stderr matching Val gate sentinel missing.*re-invoke from a parent orchestrator thread.

• Only when no CRITICAL findings remain AND the sentinel write succeeded does the skill proceed to the cascade steps below.

Step 3 -- Execute Cascade (patch)

• If classification is patch:
  • Apply the fix directly to the affected document.
  • No cascade -- no downstream artifacts are touched.
  • Skip to Step 9 (Emit Assessment-Doc) then Step 10 (Summary).

Step 4 -- Edit PRD (feature only)

• If classification is feature:
  • Delegate to the edit-prd sub-workflow via subagent: add new functional and non-functional requirements.
  • Capture the PRD diff -- identify NEW requirement IDs (FR-, NFR-) added.
  • Capture the cascade classification from edit-prd (architecture impact: NONE / MINOR / SIGNIFICANT).
  • Store: prd_diff, cascade_to_arch.
• If classification is enhancement or patch: skip this step.

Step 5 -- Edit Architecture (feature only, if needed)

• If classification is feature AND cascade_to_arch != NONE:
  • Delegate to the edit-architecture sub-workflow via subagent.
  • Capture the architecture diff -- new ADRs, changed sections.
  • Store: arch_diff.
• If cascade_to_arch == NONE: inform the user "No architecture changes needed" and skip.
• If classification is enhancement or patch: skip this step.

Step 6 -- Edit Test Plan (enhancement and feature)

• If classification is enhancement or feature:
  • Prereq: the test-plan presence gate fires in setup.sh via validate-gate.sh test_plan_exists when --classification=enhancement|feature is passed. Arriving at Step 6 implies the test plan exists at the path validate-gate.sh test_plan_exists resolves (flat .gaia/artifacts/test-artifacts/test-plan.md OR strategy/ form OR sharded form). If the gate failed, this skill has already HALTed with the canonical message HALT: test-plan.md is missing — run /gaia-test-design first, then re-invoke /gaia-add-feature {feature_id} — see Step 1c re-invocation below.
  • Delegate to the edit-test-plan sub-workflow via subagent.
  • Orchestrator trigger inheritance. When delegating to /gaia-edit-test-plan, pass the three inheritance contract fields as named invocation parameters:
    • feature_description -- the feature scope captured in Step 1
    • prd_diff -- the PRD diff captured in Step 4 (empty for enhancement classification, since Step 4 is skipped -- pass only when populated)
    • arch_diff -- the architecture diff captured in Step 5 (empty for enhancement classification, since Step 5 is skipped -- pass only when populated) Pass only the subset that is populated for the current classification. /gaia-edit-test-plan Step 2 handles the partial-inheritance case by prompting for missing fields. Do NOT pass empty strings for skipped fields -- omit them so the downstream three-case branch routes to PARTIAL rather than FULL with empty values.
  • Capture test plan additions (new test case IDs).
  • Store: test_diff.
• If classification is patch: skip this step.

Step 7 -- Edit Threat Model (feature only)

• If classification is feature:
  • Check if .gaia/artifacts/planning-artifacts/threat-model.md exists.
  • If it exists: update the threat model to account for new attack surfaces introduced by the feature.
  • Store: threat_model_diff.
• If classification is enhancement or patch: skip this step.

Step 8 -- Add Feature Stories (enhancement and feature)

Step 8 pre-flight — deterministic parent-epic inference:

Before story-creation logic runs, invoke the advisory parent-epic inference helper to surface a deterministic parent epic when affected_skills can be unambiguously mapped to one open epic:

parent_epic_match=$(bash "${CLAUDE_PLUGIN_ROOT}/skills/gaia-add-feature/scripts/lib/infer-parent-epic.sh" \
  --affected-skills "$AFFECTED_SKILLS")

The helper emits exactly one of three modes on stdout (exit 0 always):

• deterministic <epic_key> — exactly one open epic in epics-and-stories.md matched the affected_skills list. Parent epic is set to <epic_key> automatically; the LLM does NOT re-judge.
• ambiguous: <epic_key_1>,<epic_key_2>,... — two or more open epics matched. The LLM judges among the listed candidates (or files a new epic if none fit).
• no-match — zero open epics matched. The LLM falls through to its standard fallback heuristic (typically: file a new epic).

Record the result in the assessment-doc Cascade Plan as parent_epic_match: <mode> [— <details>]. Examples:

• parent_epic_match: deterministic — <epic_key>
• parent_epic_match: ambiguous — <epic_key_1>,<epic_key_2>
• parent_epic_match: no-match

"Open epic" definition (consumed by the helper): an epic detail block in epics-and-stories.md is OPEN unless its body contains (case-insensitive) **Status: closed**, **Status: retired**, or **Status: sunset**.

Empty affected_skills is handled cleanly: the helper emits no-match and exits 0. Cascades with no skill-touching scope proceed normally.

Two modes:

• inline-dispatch (legacy default for YOLO): /gaia-add-stories is dispatched as a Skill-to-Skill delegate; story files are materialized in-cascade. Behavior preserved verbatim from earlier cascades.
• deferred-seed-brief (new default for non-YOLO): story keys are reserved (allocate next-free Sxxx numbers per epic via next-story-id.sh); a ### Story seed brief for <story_key> subsection is appended to the assessment-doc with proposed AC text (1-5 draft ACs), expected epic (key + name), and dependency notes (hard deps, soft deps, blocks). User dispatches /gaia-create-story <key> as a follow-up.

Default selection:

Run bash $PLUGIN/scripts/yolo-mode.sh is_yolo to detect YOLO state:

• exit 0 (YOLO active) → default mode is inline-dispatch (legacy preserved; YOLO's "no interrupting" contract requires materializing story files in-cascade).
• exit non-zero (YOLO inactive) → default mode is deferred-seed-brief (explicit checkpoint between cascade plan and story materialization).

--step-8-mode=<mode> CLI override:

If the orchestrator passed --step-8-mode <inline-dispatch|deferred-seed-brief> (or the inline form --step-8-mode=<mode>), the override takes precedence over the YOLO-derived default. setup.sh validates the value and rejects unknown values with gaia-add-feature: invalid --step-8-mode value (expected inline-dispatch or deferred-seed-brief, got: <value>).

Before/After default selection:

• BEFORE: all cascades used inline-dispatch by default regardless of YOLO state. /gaia-add-stories was always pulled into the main turn.
• AFTER: YOLO → inline-dispatch (legacy preserved); non-YOLO → deferred-seed-brief (new default).
• Rationale: the main-turn orchestration model makes inline sub-skill dispatch heavier than under the legacy fork-context model — the main turn now carries both the cascade reasoning AND the story-creation skill's context. The deferred-seed-brief alternative keeps the cascade focused on planning artifacts and defers story-file materialization to a separate user-initiated /gaia-create-story invocation. A smoke-test surfaced this as a friction point.

Mode dispatch (the actual Step 8 body):

• If classification is enhancement or feature:

  • If step_8_mode == inline-dispatch: delegate to the add-stories sub-workflow via subagent, passing feature_description, prd_diff, arch_diff, and cr_id.

  • Capture new story keys and epic assignments.

  • Store: new_stories.

  • Per user rule feedback_priority_flag_never_auto_set.md, stories created by this skill MUST have priority_flag: null regardless of urgency. Triage and /gaia-sprint-plan decide priority sequencing.

    Memory rule (verbatim — survives context compaction):

    Stories produced by /gaia-add-feature MUST have priority_flag: null by default. Do NOT auto-set priority_flag: 'next-sprint' during triage or cascade, even when:

    • The driver is high-urgency.
    • All stories are P1.
    • The brief classifies the work as technical-debt / regression remediation.

  • If step_8_mode == deferred-seed-brief: reserve story keys via next-story-id.sh --epic <epic_key> for each proposed story; for each reserved key, append a ### Story seed brief for <story_key> subsection to the assessment-doc containing (a) proposed title, (b) 1-5 draft ACs at planning fidelity (full polish happens in /gaia-create-story), (c) expected epic (key + name), (d) dependency notes (hard deps, soft deps, blocks), (e) a manual-test note (see below). Do NOT call /gaia-add-stories — story-file materialization is deferred to a separate user-initiated /gaia-create-story <key> invocation. Record new_stories as the list of RESERVED keys (not materialized files). The memory rule above (no auto-set of the priority flag) still applies — the user MUST NOT promote a seed-brief story to the elevated-priority value until /gaia-create-story materializes it.

  Manual-test note (carry the manual-test signal through the cascade). A feature or enhancement that introduces a user-facing capability needs a manual / functional verification pass, not just automated tests. When the cascaded story touches a user-facing surface (web, server / API, mobile, or desktop platform in the project, or a UI/UX-bearing capability), carry that signal forward so the downstream authoring step opts the story into manual verification:

  • inline-dispatch: instruct the add-stories delegate to apply the surface-aware manual-test offer (the create-story authoring step sets manual_verification: true and fills the ## Manual Test section for a user-facing story).
  • deferred-seed-brief: record the manual-test note in the seed brief (one line naming the surface(s) and what a manual run should exercise) so the follow-up /gaia-create-story carries the offer through. A patch classification introduces no new surface and is not annotated.

• If classification is patch: skip this step.

Step 8a -- Intake-time dispatch-verb enforcement

For every story produced by Step 8 (classification enhancement or feature), invoke the deterministic intake check BEFORE 8b updates traceability:

for story_path in "${new_story_paths[@]}"; do
  !scripts/lib/intake-dispatch-verb-check.sh --story-file "$story_path"
done

The helper sources scripts/lib/dispatch-verb-match.sh and HALTs with the canonical message HALT: dispatch-verb AC #<n> ("<excerpt>") lacks a companion integration-test AC. Add an integration-test AC, OR annotate this AC with <!-- gaia:contract-only: <reason> --> if the dispatch is contract-only. when a story has a dispatch-verb AC without integration coverage and without a contract-only override.

This step MUST run AFTER stories are written by Step 8 (the helper needs the file on disk) and BEFORE Step 8b (traceability would otherwise record stories that fail the drift-prevention contract). The LLM never inlines the taxonomy or re-implements the matcher — SSOT contract.

If classification is patch: skip this step.

Step 8b -- Update Traceability (enhancement and feature)

• If classification is enhancement or feature:
  • Prereq: the traceability-matrix presence gate fires in setup.sh via validate-gate.sh traceability_exists when --classification=enhancement|feature is passed. Arriving at Step 8b implies the matrix exists at the path validate-gate.sh traceability_exists resolves (flat / strategy / sharded). If the gate failed, this skill has already HALTed with the canonical message HALT: traceability-matrix.md is missing — run /gaia-trace first, then re-invoke /gaia-add-feature {feature_id} — see Step 1c re-invocation.
  • Ground the dispatch in the canonical story registry. When delegating to the traceability sub-workflow, the dispatch prompt MUST pin epics-and-stories.md as the authoritative source for every story key → scope mapping, and MUST instruct the sub-agent to key each story-detail row by looking the story up by its E<N>-S<M> key in that registry — never by sequentially / positionally numbering the things being mapped (e.g. one row per service, per requirement, or per file). Test cases are assigned to the canonical story that owns the behaviour they exercise. Positional keying silently mis-maps test cases to the wrong stories and breaks the requirements→tests audit trail.
  • Delegate to the traceability sub-workflow via subagent to regenerate the traceability matrix.
  • Verify new FR / NFR IDs, test cases, and stories are linked.
• If classification is patch: skip this step.

Step 8b-check -- Post-cascade traceability consistency gate (enhancement and feature)

• If classification is enhancement or feature, AFTER Step 8b has regenerated the matrix, run the deterministic cross-artifact consistency check. The add-feature Val gate (Step 2) validates the cascade plan pre-execution and never sees the regenerated matrix — this step is the post-execution gate that asserts the matrix the sub-agent just wrote is consistent with the canonical story registry:

  !${CLAUDE_PLUGIN_ROOT}/scripts/validate-traceability-consistency.sh \
    --check scope --severity halt --format text
  

  The check is READ-ONLY. It walks every E<N>-S<M> referenced in a story-detail table row of the traceability matrix and asserts the row's declared scope is compatible with that key's scope/title in epics-and-stories.md (header titles + materialized story files). On a scope mismatch it exits non-zero and the skill MUST HALT with the canonical message:

  HALT: traceability-matrix.md references story keys whose scope is inconsistent with epics-and-stories.md — re-run Step 8b grounding the traceability dispatch in the canonical story registry (see the offending rows above), then re-invoke /gaia-add-feature {feature_id}

  Record the gate verdict (PASS / the offending rows) in the assessment-doc Val Findings Summary section so the audit trail captures it. The default --check scope gates on mis-keyed story-detail rows (the high-signal defect signature); invented-key references to retired/orphan epics are surfaced as advisory and do not block. A caller may run --check existence or --check all for a stricter audit.

• If classification is patch: skip this step.

Step 8c -- Re-shard touched documents

Cascade execution may have written to one or more monolith documents: .gaia/artifacts/planning-artifacts/prd.md, .gaia/artifacts/planning-artifacts/architecture.md, and/or .gaia/artifacts/planning-artifacts/epics-and-stories.md (and, transitively via Step 8 sub-workflow, story files and traceability). Once the cascade finishes, MUST re-shard each touched monolith so the per-section shards stay aligned with the monolith. This step honours the monolith-vs-shard sync contract — it is not optional unless the user passes --monolith-only for an explicit atomic same-PR edit (e.g., when the cascade and the re-shard will land in the same commit and the user prefers to invoke /gaia-shard-doc manually at PR-merge time).

• If $ARGUMENTS contains --monolith-only: skip this step entirely. Record reshard: skipped (--monolith-only) in the assessment-doc Cascade Plan section. The user takes responsibility for re-running /gaia-shard-doc (or merging shards back to the monolith) before commit.
• Otherwise, build the touched-monolith set from the prior cascade steps:
  • if Step 4 (Edit PRD) ran -> include .gaia/artifacts/planning-artifacts/prd.md
  • if Step 5 (Edit Architecture) ran -> include .gaia/artifacts/planning-artifacts/architecture.md
  • if Step 8 (Add Feature Stories) ran -> include .gaia/artifacts/planning-artifacts/epics-and-stories.md
  • for patch classification: include only the directly-edited monolith (no cascade ran)
• For each monolith in the touched set, invoke /gaia-shard-doc <path>. /gaia-shard-doc is unchanged in this story — only the cascade invocation pattern changes.
• After all re-shards return, run ${CLAUDE_PLUGIN_ROOT}/scripts/check-monolith-shard-sync.sh against the project root. The check is advisory (always exits 0). If it emits any WARNING lines, surface those WARNINGs to the user and record them in the assessment-doc Val Findings Summary section so the audit trail captures the residual drift — they indicate one or more re-shards did not converge and the user must investigate before commit.
• Record the per-monolith reshard: invoked (gaia-shard-doc) decisions in the assessment-doc Cascade Plan section so the audit trail captures the invocations.

This step runs in YOLO mode automatically — re-sharding is deterministic and needs no user prompt. It is purely additive: skills that did not previously include this step continue to function for backwards compatibility.

Step 9 -- Emit Assessment-Doc Artifact

This step runs only after the cascade completes successfully and Val returned no CRITICAL findings in Step 2. If Step 2 halted on CRITICAL, no assessment-doc is emitted -- the user must resolve the CRITICAL finding first and re-invoke the skill.

• Write the assessment-doc to .gaia/artifacts/planning-artifacts/assessment-{feature_id}.md with the following sections:

  • Header -- feature_id, date, author, classification, urgency, driver, CR linkage.
  • Classification -- the chosen classification (patch / enhancement / feature) with a one-line scope rationale.
  • Affected Artifacts -- the list of artifacts touched per the cascade matrix for the chosen classification, with the actual diff summaries captured during the cascade. Skipped artifacts are listed with "(skipped: classification = {patch|enhancement})" so the audit trail is explicit.
  • Cascade Plan -- a numbered list of the sub-workflows dispatched in order, with the resulting diff IDs (new FR / NFR IDs, ADR numbers, test case IDs, story keys) captured at each step. For patch classification this section reads "(no cascade -- direct edit applied)".
  • Val Findings Summary -- the verdict from Step 2 (PASS / WARNING) plus the full list of WARNING and INFO findings with their severity, scope, and recommended action. CRITICAL findings never appear here because they would have halted the skill before this step.

• The assessment-doc serves as the audit trail: who proposed what change, what Val said about it, what artifacts ended up touched, and which follow-up stories were created. It is written ONLY after the cascade completes successfully.

• Before the Finalize block runs, MUST export FEATURE_ID so the finalize.sh sentinel guard can locate the Val-dispatch sentinel: export FEATURE_ID="${feature_id}". The guard treats an unexported FEATURE_ID as a legacy fixture path (skipped) -- production cascades MUST always export it.

Step 10 -- Summary

• Present the final summary:

  Change Addition Complete: {description}

  Artifact	Status	Details
  Feature ID	{feature_id}	{AF-YYYY-MM-DD-N}
  Classification	{patch / enhancement / feature}	{scope rationale}
  Urgency	{critical / high / medium / low}	--
  Driver	{user-request / bug-report / tech-debt / opportunity}	--
  Val Verdict	{PASS / WARNING}	{N WARNING findings}
  PRD	{Updated / Skipped}	{new FR/NFR IDs or "N/A"}
  Architecture	{Updated / Skipped}	{new ADRs or "N/A"}
  Test Plan	{Updated / Skipped / Not found}	{new test case IDs or reason}
  Threat Model	{Updated / Skipped}	{changes or "N/A"}
  Stories	{Created / Skipped}	{new story keys or "N/A"}
  Traceability	{Regenerated / Skipped}	{linkage status}
  Assessment Doc	{emitted / skipped}	.gaia/artifacts/planning-artifacts/assessment-{feature_id}.md

  Next steps:

  • For each new story: run /gaia-create-story {story_key} to elaborate.
  • To start development: run /gaia-sprint-plan or /gaia-correct-course.
  • To audit this change later: read .gaia/artifacts/planning-artifacts/assessment-{feature_id}.md.

References

• Structured subagent return schema (status / summary / artifacts / findings / next).
• Native Execution Model via Claude Code Skills + Subagents + Plugins + Hooks.
• Scripts-over-LLM for Deterministic Operations. The Val gate and assessment-doc emit are LLM-judgment steps and intentionally do NOT introduce new scripts.
• Review Gate via sequential subagents. Val invocations follow this isolation pattern with a read-only tool allowlist.
• Subagent Dispatch Contract -- Mandatory Verdict Surfacing.
• YOLO Mode Contract -- Consistent Non-Interactive Behavior.
• Add-feature orchestrator with classification vocabulary and cascade matrix.
• Restore the validation gate inside /gaia-add-feature.
• Auto-sharding policy; monolith-vs-shard sync contract.
• Static monolith-shard-sync check.
• Cascade-skill auto-invoke for /gaia-shard-doc (Step 8c above + --monolith-only opt-out).
• "Val verdicts originate ONLY from a real Agent-tool dispatch" hard contract; closes the inline-Val
  • auto-judge-in-patch-mode bypass class.
• The /gaia-add-feature Val-gate fail-open under fork isolation (precedent for the prose-hardening clauses above).
• Val-dispatch contract hardening: reconciles the hash basis between SKILL.md and validator.md, adds Dispatch prompt hygiene prose covering caller-side sentinel-shape override and prior-findings pre-loading on re-dispatch.

Changelog

• 2026-06-24 — --from-discovery hydration bridge. Added Step 1 --from-discovery <board-item-id> mode that pre-fills the Step 1 intake fields (description, urgency, driver) from a graduated discovery board item. Classification is re-derived from scope analysis, never accepted from hydration. The scope-confirmation prompt and Step 1c re-validation are explicitly preserved -- hydration is pre-fill only, not bypass. The board item transitions to Graduated only after the backlog row lands; a HALT at Step 1c or Step 2 leaves the item in Evaluated state (re-entrancy preserved). All hydrated fields are sanitized (control chars stripped, length-capped) and artifact paths are confined repo-relative. Coverage: plugins/gaia/tests/discovery-graduate.bats (33 cases covering track auto-detect, per-track bars, fail-closed AI-id validation, hydration behaviour, side-effect ordering).
• 2026-06-10 — Post-cascade traceability consistency gate + traceability-dispatch grounding. Added Step 8b-check, a deterministic post-execution gate (scripts/validate-traceability-consistency.sh) that runs after Step 8b regenerates the matrix and HALTs when a story-detail row's scope is inconsistent with the canonical story registry (epics-and-stories.md, header titles + materialized story files). Closes the structural gap where the Step 2 Val gate validates only the cascade plan pre-execution and never re-validates the matrix the traceability sub-agent writes. Step 8b prose also gained a grounding clause: the traceability dispatch MUST pin epics-and-stories.md as authoritative and key each story-detail row by looking the story up by its key, never by positional/sequential numbering of the things being mapped (the defect: a sub-agent numbering rows per cloud-service produced an off-by-one that mis-mapped test cases to the wrong stories). The gate defaults to --check scope (gates on mis-keyed rows — the high-signal signature; invented-key references to retired epics are advisory). Sibling to the epic/story-key registry integrity audit (validate-epic-registry.sh) — that asserts key uniqueness + epic non-orphaning; this asserts traceability references are scope-consistent with the registry. Coverage: plugins/gaia/tests/validate-traceability-consistency.bats (13 cases incl. defect reproduction, false-positive guard, file-only-key registration, all three --check modes).
• 2026-05-14 — Deterministic parent-epic inference. Added scripts/lib/infer-parent-epic.sh — advisory helper that maps comma-separated affected_skills to open epics in .gaia/artifacts/planning-artifacts/epics-and-stories.md. Emits one of three modes on stdout (exit 0 always): deterministic <epic_key> / ambiguous: <key1>,<key2>,... / no-match. Step 8 prose updated with a pre-flight subsection that invokes the helper before story-creation logic; the result is recorded in the assessment-doc Cascade Plan as parent_epic_match: <mode> [— <details>]. Open-epic definition: a detail block is OPEN unless **Status: closed**, **Status: retired**, or **Status: sunset** appears within it. Empty affected_skills cleanly emits no-match. Closes the drift surfaced by a smoke test (LLMs reading a long epics-and-stories.md inconsistently picked between parent-epic candidates).
• 2026-05-14 — Step 8 deferred-seed-brief mode + step_8_mode Cascade Plan field. Step 8 prose rewritten to document TWO modes: inline-dispatch (legacy default for YOLO, materializes story files in-cascade) and deferred-seed-brief (new default for non-YOLO, reserves story keys + emits ### Story seed brief for <story_key> subsections in the assessment-doc; user dispatches /gaia-create-story <key> as a follow-up). Default selection is YOLO-keyed: YOLO active → inline-dispatch (legacy preserved); YOLO inactive → deferred-seed-brief (new default). setup.sh gained a --step-8-mode <inline-dispatch|deferred-seed-brief> CLI override (and inline form) with canonical rejection stderr gaia-add-feature: invalid --step-8-mode value (expected inline-dispatch or deferred-seed-brief, got: <value>). The Before/After default flip is documented explicitly — reviewers see the policy change, not just a new field. Rationale: the main-turn orchestration model makes inline sub-skill dispatch heavier than under the legacy fork-context model; a smoke-test surfaced this as a friction point.
• 2026-05-14 — Steps 6/8b HALT-or-bootstrap on missing canonical test artifacts. setup.sh gained two new optional CLI flags (--classification <patch|enhancement|feature>, --feature-id <AF-{date}-{N}>) parsed BEFORE resolve-config so the classification is available when gates fire. Under classification enhancement / feature, setup.sh invokes validate-gate.sh test_plan_exists and validate-gate.sh traceability_exists (extending the existing prd_exists / epics_and_stories_exists consumer pattern). On either gate failure, setup.sh die's with canonical stderr HALT: test-plan.md is missing — run /gaia-test-design first, then re-invoke /gaia-add-feature {feature_id} (or the /gaia-trace mirror). Patch classifications skip both gates. SKILL.md Steps 6 + 8b prose rewritten to document the prereq contract; Step 1c re-invocation added so the classification captured in Step 1 flows back to setup.sh. Closes the drift surfaced by a smoke test (Step 6 silently skipped its Test Plan edit because the artifact did not yet exist on disk).
• 2026-05-14 — Intake-time dispatch-verb enforcement. Added Step 8a between Step 8 (Add Feature Stories) and Step 8b (Update Traceability). The step invokes scripts/lib/intake-dispatch-verb-check.sh --story-file <path> for every story produced by Step 8. The helper sources scripts/lib/dispatch-verb-match.sh and HALTs with the canonical message when a dispatch-verb AC lacks a companion integration-test AC and has no <!-- gaia:contract-only: <reason> --> override. Closes the documented drift class (dispatch-verb ACs landing without integration coverage). Story-template.md and validate-frontmatter.sh gain a new 16th required delivered: boolean field (default true) — the bookkeeping primitive a later story will consume for retroactive back-fill.
• 2026-05-13 — Sentinel-Write Writer Shift. Following an incident, the Val sentinel write has been relocated from the Val sub-agent context to the orchestrator's main turn. Val now RETURNS the sentinel content inside the envelope; the orchestrator writes the sentinel via the helper plugins/gaia/scripts/lib/write-val-envelope.sh. The writer accepts Val's returned envelope shape DIRECTLY — it unwraps a nested sentinel_envelope (passing persona_sig through verbatim) or accepts a flat top-level sentinel, with no caller-side reshaping. This closes the Claude Code substrate content-integrity false-fire that blocked the cascade end-to-end after the bridge migration landed. Forgery resistance preserved via persona_sig binding to validator.md's on-disk sha256. The Step 2b dispatch contract now reads: (1) spawn Val via Agent tool; (2) write sentinel by piping Val's returned envelope straight into write-val-envelope.sh --envelope-stdin (captures the path on stdout); (3) source assert-agent-envelope.sh; (4) assert_agent_envelope against the captured path; (5) HALT on non-zero; (6) consume verdict. The four-layer fail-closed enforcement (dispatch checkpoint, AskUserQuestion precondition, dispatch prompt hygiene, bats anti-pattern check) is preserved intact. Coverage: helper-level bats in plugins/gaia/tests/write-val-envelope.bats; existing bats in plugins/gaia/tests/val-bridge-migration.bats continues to pass (assertion logic unchanged); validator.md §Sentinel-Write Contract rewritten to specify the return-channel.
• 2026-05-13 — Dispatch prompt hygiene + hash-basis reconcile. Fixed three operator-error vectors surfaced by a cascade attempt (substrate content-integrity HALT). (a) Reconciled the envelope sentinel hash basis: Step 2b body had drifted to sha256(feature_id) while the Subagent Dispatch Contract section and validator persona §Sentinel-Write Contract both say sha256(artifact_path). Step 2b now matches; the convention is documented as "pass feature_id as the literal artifact_path" so caller and persona hash the same string. Validator persona amended with the same convention. (b) Added an explicit "Dispatch prompt hygiene" block to Step 2b enumerating three forbidden patterns: caller-side sentinel JSON shape override (causes Val to write a malformed sentinel that fails assert_agent_envelope), prior-findings pre-loading on re-dispatch (substrate content-integrity guard flags as forgery), and artifact_path invention (breaks hash agreement). Anchored to memory rule feedback_val_redispatch_no_preload.md. (c) Mirrored the hygiene rule into Critical Rules so it survives Step 2b skim. No script changes — write-val-sentinel.sh and finalize.sh are unchanged; the bug surface is entirely in the SKILL.md prose contract with Val.
• 2026-05-13 — Val Bridge Migration, FINAL self-referential migration. Migrated /gaia-add-feature Step 2 Val gate from fork isolation to main-turn Agent-tool dispatch. Added the post-dispatch envelope-assert step (source assert-agent-envelope.sh + assert_agent_envelope + HALT on non-zero) at Step 2b. The four-layer fail-closed enforcement (sentinel checkpoint, AskUserQuestion precondition, prose hardening, bats anti-pattern check) is preserved intact — the envelope-assert is a NEW layer ON TOP, not a replacement. Two layered sentinels coexist at distinct paths: dispatch checkpoint .gaia/memory/checkpoints/add-feature-{feature_id}-val-dispatched.json (validated by finalize.sh, proves dispatch HAPPENED) and envelope sentinel .gaia/memory/checkpoints/val-envelope-{artifact-hash}.json (validated by assert_agent_envelope, proves dispatcher was AUTHENTIC Val persona). Closes feedback_add_feature_val_gate_fails_open.md at the authenticity layer. Coverage by bats in plugins/gaia/tests/val-bridge-migration.bats; the prior verdict-surfacing bats suite continues to pass.

Mode B Readiness

Driving teammate turns (MANDATORY under team orchestration). Declaring readiness above sets up the spawn / relay / shutdown bookkeeping seams — it does NOT by itself drive a teammate. When SESSION_MODE == team, the orchestrator MUST drive each teammate turn per the canonical Mode B teammate round-trip contract at knowledge/mode-b-round-trip-contract.md: emit a real SendMessage(to: <handle>) whose message ends with the reply-routing reminder, let the teammate reply via SendMessage(to: team-lead) (one-shot re-prompt on idle-without-reply; never fabricate the reply), then relay the received body to the transcript / artifact. The bridge functions named above are bookkeeping only; the round-trip itself is an orchestrator-driven, main-turn loop.

No discretionary Mode A fall-through. The team-mode round-trip is mandatory when the session resolves to team orchestration — "it is a small / focused / quick step" is NOT a license to fall back to one-shot Mode A, and a slow reply is the cross-turn-boundary case (wait or re-prompt once), not a fallback trigger. The ONLY legitimate fall-through is a real MODE_B_FALLBACK token emitted by the bridge at spawn time (substrate genuinely unavailable).

This skill is Mode B-ready. Under the team-orchestration mode, the authoring subagent work that the prose above describes as inline subagent dispatch is instead routed through the shared execution bridge library at ${CLAUDE_PLUGIN_ROOT}/scripts/lib/execution-mode-b-bridge.sh, which itself layers on the shared dispatch library ${CLAUDE_PLUGIN_ROOT}/scripts/lib/dispatch-teammate.sh.

• Spawn seam. The cascade-authoring subagent updates the affected artifacts. The orchestration runs execution_spawn_subagent <authoring-persona> "gaia-add-feature" to obtain a persistent teammate handle. The clean-room gate in the shared library refuses any reviewer persona before a teammate is created.
• Relay seam. Each authoring turn is relayed verbatim to the team lead via execution_relay_turn <handle> <payload>, so the assessment-doc audit trail and the cascaded artifacts are identical to the Mode A subagent-dispatch path — only the dispatch seam differs, never the produced output.
• Shutdown seam. At skill exit the orchestration runs execution_shutdown, which delegates to shutdown_all so no teammate pane is left orphaned.
• Honest fallback. Live Mode B is not exercisable in every Claude Code context. When the substrate is absent the bridge degrades to the existing Mode A foreground dispatch and emits a single MODE_B_FALLBACK token to stderr; the Mode A behaviour documented above remains the source of truth.

Finalize

!${CLAUDE_PLUGIN_ROOT}/skills/gaia-add-feature/scripts/finalize.sh