edercnj/x-implement-story

Context Management

Record only compact envelopes from x-implement-task (status/taskId/commitSha/coverage*) — no full TDD logs. Reference plan/review files by path (+score for reviews); never re-load content. Read story file once in Phase 0 via x-internal-load-story-context. Use x-internal-select-context-packs as the canonical source for implementation packs. Delegate every state mutation to x-internal-update-status.

Context-budget: high — Phase 3 requires 13+ sequential skill calls (quality gates, docs, verify, reviews, report). Emit only compact envelopes (not raw tool outputs) and drop intermediate TDD logs from context immediately after commit to prevent overflow.

Skill: Story Implementation (Thin Orchestrator — ADR-0012)

Orchestrate story end-to-end via delegation. Inline: argv parse (delegate), load context (delegate), drive task loop (x-implement-task), close story-level PR. Zero direct git/gh/mvn calls.

Flag propagation (OO-style): --target-branch <branch> (default develop) → x-implement-task + x-create-pr; --auto-merge <strategy> (default none) → x-create-pr; --feature-id <ID> (auto-derived from storyId) → x-create-pr (adds feature-XXXX label).

Triggers

• /x-implement-story story-XXXX-YYYY — full lifecycle (legacy default: target=develop, no auto-merge)
• /x-implement-story story-XXXX-YYYY --target-branch feature/0049 --auto-merge merge --feature-id 0049 — orchestrator-propagated run targeting an feature branch
• /x-implement-story story-XXXX-YYYY --task TASK-NNN — execute only a specific task (resume / targeted)
• /x-implement-story story-XXXX-YYYY --resume — continue from execution-state.json (engine x-internal-implement-story Phase 0.4 resume procedure)
• /x-implement-story story-XXXX-YYYY --auto-approve-pr — parent-branch mode (RULE-004)
• /x-implement-story story-XXXX-YYYY --worktree — standalone opt-in worktree (ADR-0004 Mode 2)
• /x-implement-story story-XXXX-YYYY --interactive — opt-in to gate menus (PROCEED/FIX-PR/ABORT)

Review Policy — MANDATORY — NON-NEGOTIABLE: Specialist (x-review-specialist) + Tech-Lead (x-review-tech-lead) reviews in Step 3.2 MUST execute unless --skip-verification / --skip-review; silent omission is a PROTOCOL_VIOLATION and subagents MUST abort with "REVIEW_SKIPPED_WITHOUT_FLAG".

Parameters

| Flag | Type | Default | Description | |------|------|---------|-------------| | STORY-ID | String | — | Positional, required. Pattern story-XXXX-YYYY. | | --target-branch | String | develop | Base branch for task + story PRs. Propagated to x-implement-task + x-create-pr. | | --auto-merge | Enum | none | merge\|squash\|rebase\|none. Propagated to x-create-pr. Requires --target-branch when not none. | | --feature-id | String(4) | auto | Auto-derived from story prefix. Propagated to x-create-pr (adds feature-XXXX label). | | --auto-approve-pr | Boolean | false | Parent-branch mode (RULE-004): task PRs target feat/story-.... | | --task | String | — | Execute only TASK-XXXX-YYYY-NNN. | | --resume | Boolean | false | Delegates resume-point detection to the engine x-internal-implement-story (Phase 0.4 resume procedure). | | --skip-verification | Boolean | false | Recovery-only. Skips Phase 3; flagged outside ## Recovery blocks. | | --skip-doc | Boolean | false | Recovery/hotfix only. Skips Phase 3.0 (x-generate-docs + x-validate-docs). | | --skip-smoke, --skip-review | Boolean | false | Bypass smoke gate / specialist + TL reviews (the only supported per-review bypass path). | | --full-lifecycle, --worktree | Boolean | false | Full execution / standalone worktree mode. | | --interactive | Boolean | false | Opt-in to 3-option gate menus (PROCEED/FIX-PR/ABORT). Default: non-interactive (Rule 20). | | --no-auto-remediation, --no-ci-watch | Boolean | false | Skip automatic PR remediation (Phase 2 CI loop + Step 3.5) / Rule 21 CI-watch. | | --allow-inline-plan | Boolean | false | Escape hatch. Bypasses PLAN_ARTIFACTS_GATE in x-internal-implement-story Phase 1. Use only when plan generation is intentionally skipped (CI/automation or recovery). |

Output Contract

| Field | Type | Description | |-------|------|-------------| | storyId, featureId | String | Story + auto-derived feature ID | | status | Enum | SUCCESS \| FAILED \| PARTIAL | | targetBranch, autoMergeStrategy | String, Enum | Resolved base branch + merge strategy | | tasksExecuted | List<{id, status, commitSha, prNumber}> | One entry per task dispatched | | prNumber / prUrl | Integer|null / String|null | Story-level PR; null without --auto-approve-pr | | verifyPassed | Boolean | Phase 3 verify-gate passed | | reportPath | String | Final report from the engine x-internal-implement-story (Phase 3.3 story report procedure) | | coverageLine / coverageBranch | Number|null | Filtered coverage | | commitSha | String|null | SHA of the last task commit; null when no task completed | | errorClass | Enum|null | TRANSIENT \| CONTEXT \| PERMANENT \| null — populated on status=FAILED; used by a parent orchestrator's retry/circuit-breaker | | retryable | Boolean|null | true when errorClass ∈ {TRANSIENT, CONTEXT}; false on PERMANENT; null on SUCCESS | | summary | String|null | Short human-readable failure cause; null on SUCCESS | | contextPressureDetected | Boolean | true when context-window pressure was observed (used by a parent orchestrator to trigger reduced-context retry) |

SubagentResult conformance: The fields errorClass, retryable, summary, and contextPressureDetected align with the SubagentResult shape consumed by a parent orchestrator (retry/backoff/circuit-breaker) when this skill runs as a subagent. Emitters MUST populate these fields on all non-SUCCESS exits.

⚠️ Mandatory Execution Summary

Read before executing. Every phase below is either MANDATORY or clearly marked CONDITIONAL/OPTIONAL. Silent omission of any MANDATORY phase is a PROTOCOL_VIOLATION (Rule 24).

| Phase | Name | Status | Bypass flag | |-------|------|--------|-------------| | 0.0 | Bug Guard | MANDATORY | — | | 0 | Args, Context & Resume | MANDATORY | — | | 0.2a | Refinement Gate | MANDATORY | exempt on hotfix/* | | 0.2b | Context Pack Selection + arch-decisions load | MANDATORY | — | | 0.2c | Application Patterns Policy Check | MANDATORY (warning only) | — | | 0.5 | API-First Contract Generation | CONDITIONAL — has_contract_interfaces=true | — | | 1 | Story Plan (via engine) | MANDATORY | --allow-inline-plan (escape hatch) | | 2 | Task Loop (x-implement-task × N, code-review task inline) | MANDATORY | --task (single task) | | 2.R | Code-Review Task — Specialist + TL reviews | MANDATORY (dispatched inline when task-type=code-review) | --skip-review (recovery only) | | 2.R.push-gate | Story Push Gate (enforce-story-push-gate.sh) | MANDATORY (before push) | exempt on hotfix/* | | 3.0 | Documentation Update (x-generate-docs + x-validate-docs) | MANDATORY | --skip-doc (recovery/hotfix only) | | 3.1 | Verify Gate (coverage + AC + consistency) | MANDATORY | --skip-verification (recovery only) | | 3.3 | Story Completion Report | MANDATORY | — | | 3.4 | Single Story Push + PR Creation | MANDATORY | — | | 3.5 | Worktree Cleanup | CONDITIONAL — CREATE mode only | — |

Phase 2.R code-review task MUST dispatch x-review-specialist + x-review-tech-lead and save reports to .aikittools/features/.../reviews/. Phase 2.R.push-gate MUST pass before any git push is executed. Phase 3.3 report MUST reference all review report paths. Phase 3.4 is the SINGLE push point for the entire story — no push happens in Phase 2 or during any task.

Error Codes

| Exit | Code | Condition | |------|------|-----------| | 1 | ARGS_INVALID | Inline arg normalization (Phase 0.1) returned non-empty errors / exit 1 | | 2 | STORY_NOT_LOADABLE | x-internal-load-story-context non-zero | | 3 | PLAN_FAILED | x-internal-build-story-plan non-zero (via x-internal-implement-story) | | 4 | TASK_FAILED | One or more tasks returned FAILED (via x-internal-implement-story) | | 5 | VERIFY_FAILED | Story Verification Procedure passed=false (Phase 3.1 inline em x-internal-implement-story) | | 6 | PR_CREATE_FAILED | x-create-pr non-zero on story-level PR (via x-internal-implement-story) | | 7 | PLAN_ARTIFACTS_MISSING | Required planning artifacts absent or invalid (via x-internal-implement-story) | | 8 | REFINEMENT_REQUIRED | Story refinementVerdict.status != "approved" or scope != "story" (Phase 0.2a gate) | | 10 | BUG_STORY_DETECTED | Story file contains template-type: bug-story — use /x-fix-bug instead (Phase 0.0 Bug Guard) |

Workflow Overview

Phase 0.0 : Bug Guard (mandatory)              (Detect bug story → reject with BUG_STORY_DETECTED)
Phase 0   : Args, Context & Resume             (inline arg normalization + load-context + refinement gate + context packs)
Phase 0.2c: Application Patterns Policy Check  (warning-only — missing application-patterns.md degrades reviews)
Phase 0.5 : API-First (conditional)            (Contract generation — feature stories only)
[DELEGATE] → x-internal-implement-story (Phases 0.3 → 3 — shared engine)

Task Loop Behavior (Phase 2) — CRITICAL

All tasks commit directly to the story branch. No per-task branches. No per-task pushes. No per-task PRs.

For each task in the story task list:

IF task.task-type == "code-review":
  → Phase 2.R: Dispatch code-review inline (see below)
ELSE:
  → Skill(skill: "x-implement-task", args: "{TASK-ID} --orchestrated --no-ci-watch")
    (commits to story branch — no branch creation, no push, no PR from x-implement-task)

Phase 2.R — Code-Review Task Dispatch (MANDATORY — last task)

The code-review task is ALWAYS the last task in the plan (task-type: code-review). When reached:

Step 2.R.1 — Specialist Reviews:

Skill(skill: "x-review-specialist", args: "STORY-ID [--scope <active-specialists>]")

Wait for all specialist reports to be saved to .aikittools/features/feature-XXXX/reviews/.

Step 2.R.2 — Tech Lead Review:

Skill(skill: "x-review-tech-lead", args: "STORY-ID")

Wait for review-tech-lead-story-XXXX-YYYY.md to be saved with decision: GO | GO-WITH-RESERVATIONS | NO-GO.

Step 2.R.3 — On NO-GO (auto-remediation loop):

IF verdict == NO-GO AND NOT --skip-review AND NOT --no-auto-remediation:
  → Skill(skill: "x-fix-pr", args: "--story STORY-ID")  (apply required changes)
  → Re-run Step 2.R.1 + 2.R.2 (max 2 cycles; 3rd failure → REVIEW_FAILED exit)

Step 2.R.4 — Mark code-review task Concluída: After GO or GO-WITH-RESERVATIONS verdict, mark the code-review task status as Concluída in execution-state.json.

Step 2.R.5 — Story Push Gate (MANDATORY before any push):

# Normal flow (code-review was run):
bash src/hooks/enforce-story-push-gate.sh --story STORY-ID

# Recovery flow (--skip-review was used — Gate 2 bypassed):
bash src/hooks/enforce-story-push-gate.sh --story STORY-ID --skip-tl-gate

# Exit 0 → continue to Phase 3 (docs → verify → report → PUSH)
# Exit 33 → ABORT with STORY_PUSH_BLOCKED

Exception: hotfix/* branches are exempt.

Step 2.R.6 — Single Story Push + PR (Phase 3.4): After all gates pass (Phase 3.0 docs, Phase 3.1 verify, Phase 3.3 report):

git push --set-upstream origin <story-branch>
Skill(skill: "x-create-pr", args: "--title \"...\" --base <targetBranch> --labels feature-XXXX")

This is the only push in the entire story lifecycle.

--skip-review bypasses Phase 2.R.1 + 2.R.2 (specialist + TL reviews). When used: the code-review task is marked as SKIPPED (counts as done for Gate 1 of the push gate), and enforce-story-push-gate.sh is invoked with --skip-tl-gate so Gate 2 (TL verdict check) is bypassed. Gate 1 (all tasks Concluída or SKIPPED) is still enforced. Use only in recovery scenarios — the absence of a TL review will be visible in the PR.

CRITICAL EXECUTION RULE

4 steps (0.0 → 0.5 → DELEGATE). Bug Guard and refinement gate are mandatory. NEVER call x-internal-implement-story before passing both gates.

Phase 0.0 — Bug Guard (Mandatory)

This skill handles feature stories ONLY. Run before any other phase, using the positional STORY-ID argument to resolve the story path.

Story path resolution (before Phase 0.1 args normalization):

STORY_FILE=".aikittools/features/feature-$(echo '<STORY-ID>' | cut -d'-' -f2)/<STORY-ID>.md"

Detect if it is a bug story by checking the frontmatter and body:

# Primary check: frontmatter field (canonical)
TEMPLATE_TYPE=$(grep '^template-type:' "$STORY_FILE" | cut -d' ' -f2)
# Secondary checks: other bug-story markers
BUG_STORY_KIND=$(grep '^bug-story-kind:' "$STORY_FILE" | cut -d' ' -f2)
BUG_PAI=$(grep '^\*\*Bug Pai:\*\*' "$STORY_FILE" | grep -oE 'bug-[0-9]{6}')

If TEMPLATE_TYPE == "bug-story" OR BUG_STORY_KIND is non-empty OR BUG_PAI is non-empty → ABORT immediately:

ERROR [BUG_STORY_DETECTED]: story-XXXX-YYYY is a bug story.
  Bug stories must be implemented via /x-fix-bug.
  Usage: /x-fix-bug --bug-id <BUG-ID> --story <story-NN-slug>
  x-implement-story handles feature stories only. Exiting.

Exit code 10 (BUG_STORY_DETECTED).

If none of the markers are present → story is a feature story; continue to Phase 0.

Phase 0 — Args, Context & Resume

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-story --phase Phase-0-Context")

Open phase tracker (close with TaskUpdate(id: phase0TaskId, status: "completed") after §0.4):

TaskCreate(subject: "{STORY_ID} › Phase 0 - Context", activeForm: "Loading story context and resume state")

0.1 Args normalization (inline — parser determinístico)

Normalize the raw argv inline against references/args-schema.json, following the Argument Normalization Procedure in references/full-protocol.md §Argument Normalization Procedure (anchors NA0–NA8) — schema validation NA1, grammar NA4, the jq-based Bash workflow NA5 (Steps 1–8), exit codes NA3, and the error matrix NA7. The procedure produces the {parsed, warnings, errors} envelope.

Consume {parsed, warnings, errors}: any non-empty errors (NA3 exit 1 / coercion / mutex / unknown-flag / enum) → abort with ARGS_INVALID; print warnings once; extract storyId, featureId (auto-derived from storyId prefix), targetBranch, autoMerge, and all flags (skipReview/skipVerification/skipSmoke/autoApprovePr/nonInteractive/worktree/task/resume/noAutoRemediation/noCiWatch/fullLifecycle) for phase propagation.

0.1a Persist interactiveMode

Write the resolved interactive mode to execution-state.json so the Stop hook enforce-continuous-flow.sh (planned — not yet implemented) can determine whether to emit nudges:

Skill(skill: "x-internal-update-status", args: "--file .aikittools/features/feature-XXXX/execution-state.json --type story --id <STORY-ID> --field interactiveMode --value <interactive|non-interactive>")

Value is "interactive" when --interactive flag was passed; otherwise "non-interactive" (Rule 20 default).

0.2 Load story context

Skill(skill: "x-internal-load-story-context", args: "--story-id <STORY-ID> --feature-id <FEATURE-ID>")

Sub-skill reads story, validates predecessors, runs 7-artifact staleness pre-check (arch/impl/test/tasks/security/compliance/per-task plans), classifies scope (SIMPLE/STANDARD/COMPLEX), detects planningMode (PRE_PLANNED/HYBRID/INLINE). Envelope: {storyPath, tasksCount, scope, planningMode, predecessorsComplete, artifactFreshness[]}. Non-zero → STORY_NOT_LOADABLE.

0.2a Refinement gate — MANDATORY (Rule 29 / ADR-0022)

Immediately after loading story context, verify the story has an approved refinement verdict. Read execution-state.json via x-internal-update-status --read-only and check refinementVerdict.status == "approved" AND refinementVerdict.scope == "story":

Skill(skill: "x-internal-update-status",
      args: "--file .aikittools/features/feature-XXXX/execution-state.json --type story --id <STORY-ID> --field refinementVerdict --read-only")

On status != "approved" OR scope != "story" → abort immediately with exit code 8 (REFINEMENT_REQUIRED):

REFINEMENT_REQUIRED: story-XXXX-YYYY is not refined (status=<status>).
  Run /x-refine-story story-XXXX-YYYY to obtain an approved verdict before implementing.

Exception: hotfix/* branches are exempt (Rule 27 Exception 2).

0.2b Canonical implementation pack selection (hybrid)

Immediately after loading story context, derive implementationCapabilities from story evidence (interfaces, impacted layers/artifacts, and active quality/security/performance/devops constraints). Keep the capability set minimal and context-driven — do not add irrelevant domains by default.

Skill(skill: "x-internal-select-context-packs",
      args: "--phase implement --capabilities <implementationCapabilities>")
Skill(skill: "x-internal-select-knowledge",
      args: "--kind technical --phase implement --capabilities <implementationCapabilities>")

Treat both selectors' output as the primary source of implementation packs for the lifecycle (union the required/recommended buckets): read all required, read only scope-relevant recommended, and include optional only when an explicit risk/policy gate requires it. Persist implementationCapabilities in orchestrator memory for Phase 2 task-level narrowing.

Architecture Decisions Loading (MANDATORY when at least one decisions file exists):

After context pack selection, check for the canonical architecture decisions file and load it as mandatory implementation context:

ARCH_BACKEND_FILE="docs/architecture/architecture-decisions-backend.md"
HAS_ARCH_DECISIONS=false
[ -f "$ARCH_BACKEND_FILE" ] && HAS_ARCH_DECISIONS=true

When HAS_ARCH_DECISIONS=true:

1. Read docs/architecture/architecture-decisions-backend.md.
2. Extract the "Patterns e Knowledge Obrigatórios" sections and load every listed pattern/knowledge file.
3. Each x-implement-task call MUST load backend decisions directly in its Phase 1.
4. All task implementation subagents MUST use excerpts from these files — anti-alucinação.

When HAS_ARCH_DECISIONS=false: log INFO: docs/architecture/architecture-decisions-backend.md not found — run /x-plan-architecture to generate it.

0.2c Application Patterns Policy Check (MANDATORY — warning only)

Immediately after arch-decisions loading, enforce the require-application-patterns policy:

ARCH_BACKEND_FILE="docs/architecture/architecture-decisions-backend.md"
APP_PATTERNS_FILE="docs/architecture/application-patterns.md"
HAS_APP_PATTERNS=false

if [ -f "$ARCH_BACKEND_FILE" ]; then
  if [ -f "$APP_PATTERNS_FILE" ]; then
    HAS_APP_PATTERNS=true
    LOG: "[Phase 0.2c] application-patterns.md found — will be loaded in Phase 2 task loop and reviews."
  else
    LOG: "WARNING [POLICY-require-application-patterns]: docs/architecture/architecture-decisions-backend.md exists but docs/architecture/application-patterns.md is missing."
    LOG: "  Run /x-plan-architecture to regenerate both files."
    LOG: "  Reviews in Phase 2.R will proceed without pattern cross-check (degraded coverage)."
    HAS_APP_PATTERNS=false
  fi
fi
# Persist HAS_APP_PATTERNS in orchestrator memory for Phase 2 task loop and Phase 2.R review dispatch.

This gate is warning-only — it NEVER blocks story execution. Missing application-patterns.md degrades review coverage but does not abort the lifecycle.

0.3 & 0.4 — Delegated to x-internal-implement-story

Phases 0.3 (worktree), 0.4 (resume), 1 (plan), 2 (task loop), and 3 (verify/report/cleanup) are all handled by the shared engine below.

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-implement-story --phase Phase-0-Context")

TaskUpdate(id: phase0TaskId, status: "completed")

Phase 0 completed. Delegating to x-internal-implement-story (Phases 0.3 → 3)...

Phase 0.5 — API-First Contract Generation (Conditional)

Activates ONLY when has_contract_interfaces=True (story declares interfaces of type rest, grpc, event-consumer, event-producer, or websocket). Open phase tracker when active:

TaskCreate(subject: "{STORY_ID} › Phase 0 - API Contract", activeForm: "Generating API-first contracts")

Generates draft OpenAPI 3.1 / Protobuf 3 / AsyncAPI 2.6 in contracts/{STORY_ID}-*.yaml|proto, validates via inline CLI linting. Full interface-to-format mapping table and generator details live in references/full-protocol.md §2.

Step 0.5.4 — Approval gate:

| nonInteractive | Behavior | | :--- | :--- | | false (default standalone) | Pause via AskUserQuestion with PROCEED / Regenerate / Abort options (3-option menu, Rule 20). Max 3 REJECTs before GATE_FIX_LOOP_EXCEEDED. | | true (non-interactive run, Rule 20 default) | Auto-PROCEED without user prompt. Log [phase-0.5] non-interactive: auto-approving contract at {CONTRACT_PATH}. The contract is preserved for human review in the story PR. |

TaskUpdate(id: phase05TaskId, status: "completed")

Delegation — x-internal-implement-story (Phases 0.3 → 3)

After Phase 0.5 completes (or is skipped when has_contract_interfaces=False), delegate all remaining phases to the shared implementation engine:

Skill(skill: "x-internal-implement-story", args:
  "--story-id <STORY-ID>
   --context-path .aikittools/features/feature-<FEATURE-ID>/
   --story-mode feature
   --target-branch <targetBranch>
   --auto-merge <autoMerge>
   --feature-id <FEATURE-ID>
   --scope <scope>
   --planning-mode <planningMode>
   [--auto-approve-pr]
   [--task <TASK-ID>]
   [--resume]
   [--skip-verification]
   [--skip-smoke]
   [--skip-review]
   [--full-lifecycle]
   [--worktree]
   [--interactive]
   [--no-auto-remediation]
   [--no-ci-watch]
   [--allow-inline-plan]
   [--agent <agent_name>]")

Consume the x-internal-implement-story output envelope and re-emit it as the x-implement-story output (fields are identical — no field mapping needed).

x-internal-implement-story completed. Lifecycle complete.

Error Envelope

| Scenario | Action | |----------|--------| | Args invalid | Inline arg normalization (Phase 0.1) non-zero → ARGS_INVALID | | Story file not found / dependency incomplete | x-internal-load-story-context non-zero → STORY_NOT_LOADABLE | | Task dependency unresolved | Mark BLOCKED via x-internal-update-status; continue | | x-implement-task fails | Mark FAILED; block propagation; TASK_FAILED (unless --task) | | Planning artifacts missing/invalid | Abort with PLAN_ARTIFACTS_MISSING; require successful Phase 1 regeneration + persistence before retry | | x-validate-docs fails after retry | DOC_VALIDATION_FAILED — abort Phase 3; operator must run /x-generate-docs + --resume | | Coverage / AC / consistency failure | Story Verification Procedure (inline em x-internal-implement-story) passed=false → VERIFY_FAILED | | x-create-pr fails | Task → FAILED; story-level → PR_CREATE_FAILED | | x-validate-dependency-policy blocks | DEP_POLICY_BLOCK (exit 20) — FIX-PR: remediate denied CVE / license / version violation (Rule 32) | | x-fix-pr compile regression | ABORT Step 3.2 with PR_FIX_COMPILE_REGRESSION | | Template missing (RULE-012) | WARN; x-internal-write-report degrades to inline format | | Corrupted execution-state.json on resume | engine's Phase 0.4 resume procedure reinitializes | | Review NO-GO > 2 cycles | Keep verifyPassed=true; flag human-gate WARNING | | Sub-skill transient error | Retry once with 2s backoff; persistent → propagate |

Full retry/backoff schedule + SubagentResult error shape live in references/full-protocol.md §6.

Recovery

Resuming after an aborted lifecycle may legitimately skip already-completed steps. The canonical signal is CLAUDE_RECOVERY_MODE=1 — set automatically by the engine's Phase 0.4 resume procedure (x-internal-implement-story) when staleWarnings != []. The PreToolUse hook enforce-no-bypass-flags.sh (planned — not yet implemented) (Rule 45) then permits the flags below with a WARNING; skips remain visible in telemetry as phase.end status=skipped. Operator-controlled sessions only — never in automated calls. CLAUDE_RECOVERY_MODE=1 is the ONLY accepted bypass variable; CLAUDE_SKIP_AUDIT=1 / CLAUDE_NO_ENFORCE=1 do NOT bypass (RULE-059-07).

| Flag | Skips | | :--- | :--- | | --skip-verification | Phase 3 (Story Verification Procedure inline em x-internal-implement-story) | | --skip-review | Step 3.2 (x-review-specialist + x-review-tech-lead) | | --skip-quality | Step 3.Q (x-validate-dependency-policy) — Recovery or hotfix/ only* | | --skip-doc | Step 3.0 (x-generate-docs + x-validate-docs) — Recovery or hotfix/ only (Rule 27 Exception 2)* | | --skip-smoke | Smoke gate inside verify | | --no-ci-watch | CI-watch step in Phase 2 | | --allow-inline-plan | PLAN_ARTIFACTS_GATE in Phase 1 of x-internal-implement-story (bypasses plan existence check) |

Idempotency (RULE-002)

--auto-merge without --target-branch → ARGS_INVALID (mutex). Idempotent: story load read-only, artifacts regen only on staleness, task dispatch short-circuits merged PRs, status mutations flock-protected, story PR re-run returns existing {prUrl, prNumber}. Full tables in references/full-protocol.md §7-8.

Knowledge Pack References

Read src/skills/x-internal-select-context-packs/SKILL.md Read src/knowledge/shared/architecture-decisions/task-hierarchy/knowledge.md Read src/knowledge/shared/governance-baselines/tool-call-grammar/knowledge.md

Integration Notes

Arg normalization (0.1) is inlined — see references/full-protocol.md §Argument Normalization Procedure (anchors NA0–NA8), references/args-schema.json. x-internal-load-story-context (0.2), x-internal-implement-story (engine — Phases 0.3→3, incl. inline resume procedure at 0.4 cond. + inline story-verification procedure at 3.1 + inline story-report procedure at 3.3), x-internal-build-story-plan (1), x-implement-task (2 per-task), x-create-pr (2 per-task+story), x-watch-pr-ci (2 CI loop), x-fix-pr (2 CI remediation + 3.2 review remediation), x-evaluate-parallelism (1), x-review-specialist/x-review-tech-lead (3.2), Story Verification Procedure (3.1 inline na engine), x-internal-write-report (3.3 render, via engine's story-report procedure), x-internal-update-status (all phases), x-manage-worktrees (0.3+3.5). Feature closeout (final PR) is handled by x-close-feature after all stories merge.

Full Protocol

Minimum viable orchestrator contract above. Complete Phase 0.3 worktree-mode decision table, Phase 1 parallelism matrix, strict planning-artifact enforcement/persistence semantics, Phase 3 verify-gate schemas + specialist-review prompt templates + TL-review NO-GO cycle protocol, resume workflow detail, retry/backoff/circuit-breaker schedule, and the SubagentResult error shape all live in references/full-protocol.md per ADR-0012.

Decision Record

ADR-0014 — Task Hierarchy and Phase Gates: Establishes story as the composition of tasks via Plan/Task-Loop/Verify/Report phases.

Optional: Version Bump After Story

After a successful story completion (when status=SUCCESS), you may optionally bump the application version following Semantic Versioning. Feature stories typically correspond to a minor increment:

Skill(skill: "x-increment-version", args: "--type minor")

This step is NOT mandatory — invoke it only when the project has explicit version management. See /x-increment-version for stack detection and commit conventions.