edercnj/x-internal-implement-story

🔒 INTERNAL SKILL Esta skill é invocada apenas por outras skills (orquestradores). NÃO é destinada a invocação direta pelo usuário. Callers: x-implement-story (feature stories) e x-fix-bug (bug stories). Extrai as Phases 0.3 → 3 do x-implement-story original em uma engine compartilhada parametrizada por --context-path e --story-mode. Segue convenção ADR-0012 (slim SKILL.md + references/full-protocol.md).

Skill: x-internal-implement-story (slim — ADR-0012)

Purpose

Engine compartilhada que executa as Phases 0.3 a 3 do ciclo de implementação de uma story. Recebe a story já carregada e validada pelo wrapper (contexto, refinement gate, context packs), e executa:

• Phase 0.3 — Worktree decision
• Phase 0.4 — Resume (conditional)
• Phase 1 — Plan
• Phase 2 — Task Execution Loop
• Phase 3 — Verify, Report & Cleanup

O path base (--context-path) é agnóstico ao tipo de contexto: pode ser um diretório de feature (.aikittools/features/feature-XXXX/) ou de bug (.aikittools/bugs/bug-NNNNNN/). Todos os artefatos são resolvidos relativamente a este path.

Triggers

Invocado exclusivamente por orquestradores (Rule 13 INLINE-SKILL):

Skill(skill: "x-internal-implement-story",
      args: "--story-id story-0080-0003
             --context-path .aikittools/features/feature-0080/
             --story-mode feature
             --target-branch feature/0080
             --auto-merge merge
             --feature-id 0080")

Skill(skill: "x-internal-implement-story",
      args: "--story-id story-01-regression-test
             --context-path .aikittools/bugs/bug-000001/
             --story-mode bug
             --target-branch develop")

Parameters

| Flag | Type | Required | Default | Description | |------|------|----------|---------|-------------| | --story-id | String | M | — | ID da story (qualquer formato válido) | | --context-path | String | M | — | Diretório base dos artifacts (features/feature-XXXX/ ou bugs/bug-NNNNNN/) | | --story-mode | Enum | M | — | feature ou bug — controla PR template e status update semantics | | --target-branch | String | O | develop | Branch base para PRs de task e story | | --auto-merge | Enum | O | none | merge\|squash\|rebase\|none | | --feature-id | String(4) | O | — | Passado quando --story-mode=feature; usado para labels de PR (feature-XXXX) | | --auto-approve-pr | Boolean | O | false | Parent-branch mode (RULE-004) | | --task | String | O | — | Executar somente TASK-XXXX-YYYY-NNN (single task / resume) | | --resume | Boolean | O | false | Ativa o Resume Story Procedure inline (Phase 0.4) | | --skip-verification | Boolean | O | false | Recovery-only: pula Phase 3 | | --skip-smoke | Boolean | O | false | Pula smoke gate em verify | | --skip-review | Boolean | O | false | Pula specialist + TL reviews | | --full-lifecycle | Boolean | O | false | Full execution mode | | --worktree | Boolean | O | false | Standalone opt-in worktree (ADR-0004 Mode 2) | | --interactive | Boolean | O | false | Opt-in para gate menus (PROCEED/FIX-PR/ABORT) | | --no-auto-remediation | Boolean | O | false | Pula PR remediation automática | | --no-ci-watch | Boolean | O | false | Pula Rule 21 CI-watch | | --scope | Enum | O | — | SIMPLE\|STANDARD\|COMPLEX (herdado do Phase 0.2 do wrapper) | | --planning-mode | Enum | O | — | PRE_PLANNED\|HYBRID\|INLINE (herdado do Phase 0.2 do wrapper) | | --allow-inline-plan | Boolean | O | false | Escape hatch de recovery. Permite construção inline de planos quando planningGate=PLAN_REQUIRED. Uso restrito a cenários de recovery explicitamente aprovados. |

Output Contract

Mesmo contrato de output do x-implement-story:

| Field | Type | Description | |-------|------|-------------| | storyId, contextPath, storyMode | String | Parâmetros de entrada resolvidos | | status | Enum | SUCCESS \| FAILED \| PARTIAL | | targetBranch, autoMergeStrategy | String, Enum | Branch base + estratégia de merge | | tasksExecuted | List<{id, status, commitSha, prNumber}> | Uma entrada por task despachada | | prNumber / prUrl | Integer|null / String|null | Story-level PR | | verifyPassed | Boolean | Phase 3 verify gate passed | | reportPath | String | Relatório final do Story Report Procedure inline (Phase 3.3) | | coverageLine / coverageBranch | Number|null | Coverage filtrado | | commitSha | String|null | SHA do último commit de task; null quando nenhuma task completou | | errorClass | Enum|null | TRANSIENT \| CONTEXT \| PERMANENT \| null | | retryable | Boolean|null | true quando errorClass ∈ {TRANSIENT, CONTEXT} | | summary | String|null | Causa de falha; null em SUCCESS | | contextPressureDetected | Boolean | true quando context-window pressure detectada |

Error Codes

| Exit | Code | Condition | |------|------|-----------| | 3 | PLAN_FAILED | x-internal-build-story-plan non-zero | | 4 | TASK_FAILED | Uma ou mais tasks retornaram FAILED | | 5 | VERIFY_FAILED | Story Verification Procedure (inline, Phase 3.1) passed=false | | 6 | PR_CREATE_FAILED | x-create-pr non-zero no story-level PR | | 7 | PLAN_ARTIFACTS_MISSING | Artefatos de planejamento ausentes ou inválidos |

Workflow Overview

Phase 0.3 : Worktree decision          (x-manage-worktrees detect-context)
Phase 0.4 : Resume (conditional)       (Resume Story Procedure inline — references/full-protocol.md)
Phase 1   : Plan                       (x-internal-build-story-plan --context-path)
Phase 2   : Task Execution Loop        (x-implement-task + x-create-pr + ci-watch + fix-pr)
Phase 3   : Verify, Report & Cleanup   (Story Verification Procedure inline + Story Report Procedure inline + cleanup)

CRITICAL EXECUTION RULE

5 fases (0.3–3). TODAS as fases até Phase 2 são obrigatórias. NUNCA pare antes de Phase 2 completar. Print >>> Phase N completed. Proceeding to Phase N+1 (...)... entre fases; >>> Phase 3 completed. Lifecycle complete. ao final.

Phase 0.3 — Worktree Decision (Rule 14 + ADR-0004)

Skill(skill: "x-manage-worktrees", args: "detect-context") → aplicar decisão 3-way (REUSE/CREATE/ERROR); set STORY_OWNS_WORKTREE em memória.

| inWorktree | --worktree flag | Mode | Ação | | :--- | :--- | :--- | :--- | | true | any | REUSE | Reutilizar; STORY_OWNS_WORKTREE=false | | false | present | CREATE | Provisionar worktree dedicado; STORY_OWNS_WORKTREE=true | | false | absent | ERROR | Abort ARGS_INVALID: requer --worktree para execução standalone |

Phase 0.4 — Resume (conditional on --resume)

Executar inline o Resume Story Procedure (R-Step 1→6) em references/full-protocol.md §Resume Story Procedure com --story-id <STORY-ID> --context-path <CONTEXT-PATH> (strict read-only, apenas Bash).

Envelope: {resumePoint, tasksCompleted[], tasksPending[], lastCommitSha, staleWarnings[]}. Use tasksPending como filtro de iteração do Phase 2; print staleWarnings uma vez.

Phase 0.3 + 0.4 completed. Proceeding to Phase 1 (Plan)...

Phase 1 — Plan (PLAN_ARTIFACTS_GATE)

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

PLAN_ARTIFACTS_GATE — MANDATORY (não bypassável sem --allow-inline-plan)

Antes de qualquer ação de planejamento, verificar o campo planningGate do envelope retornado por x-internal-load-story-context (Phase 0.2 wrapper):

SE context.planningGate == "PASSED" (planningMode=PRE_PLANNED):

[LOG] "[phase-1] GATE PASSED — planningMode=PRE_PLANNED. All planning artifacts are fresh."
[LOG] "[phase-1] Skipping plan build. Proceeding to Phase 2 (Task Execution Loop)."

Pular todo o restante do Phase 1 e ir diretamente para Phase 2.

SE context.planningGate == "PLAN_REQUIRED" (planningMode=HYBRID ou INLINE):

Verificar se o flag --allow-inline-plan foi passado:

• SE --allow-inline-plan NÃO foi passado → ABORTAR com exit code 7:

ERROR [PLAN_ARTIFACTS_MISSING]: Planning artifacts are absent or stale for {STORY-ID}.

  Missing plan-story : {context.artifacts.missingPlanStory}
  Missing plan-tasks : {context.artifacts.missingPlanTasks | join(", ")}
  Stale artifacts    : {context.artifacts.stale | join(", ")}

  Implementation CANNOT start without complete, fresh planning artifacts.

  To generate all planning artifacts, run:
    /x-plan-story {story_id}

  Then re-run:
    /x-implement-story {story_id}

  Use --allow-inline-plan only for recovery scenarios where inline planning is explicitly required.

• SE --allow-inline-plan FOI passado → logar WARNING e invocar plan build (escape hatch de recovery):

WARNING [PLAN_ARTIFACTS_GATE_BYPASSED]: --allow-inline-plan flag detected.
  Building planning artifacts inline. This is a recovery escape hatch — use with caution.

Skill(skill: "x-internal-build-story-plan",
      args: "--story-id <STORY-ID> --context-path <CONTEXT-PATH> --scope <SCOPE> [--skip-review]")

Consumir o envelope flat-path {archPlan, implPlan, testPlan, taskBreakdown, taskMap, securityAssessment, complianceAssessment, scope, skipped}. Em non-zero → exit PLAN_FAILED. Persistir em memória — nunca reler os arquivos de artefato.

Strict planning-artifact gate (secundário): quando --allow-inline-plan está ativo, se qualquer artefato obrigatório no envelope for null → abort com PLAN_ARTIFACTS_MISSING (não entrar no Phase 2 com planejamento parcial).

1.6 Planning artifact persistence (escape hatch only)

Quando --allow-inline-plan ativo, persistir outputs em um commit dedicado antes do Phase 2:

Skill(skill: "x-commit-planning",
      args: "--scope docs --paths <CONTEXT-PATH>/plans/ <CONTEXT-PATH>/execution-state.json
             --subject \"docs(<STORY-ID>): persist planning artifacts\"")

Parallelism gate

Skill(skill: "x-evaluate-parallelism", args: "--scope=story --story=<STORY-ID>")

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

Phase 1 completed. Proceeding to Phase 2 (Task Execution Loop)...

Phase 2 — Task Execution Loop (RULE-001)

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

Ler tasks de <CONTEXT-PATH>/plans/tasks-story-<STORY-ID>.md (artefato OBRIGATÓRIO). Se ausente → abort com PLAN_ARTIFACTS_MISSING. Aplicar filtro tasksPending do Phase 0.4 quando resumindo. Para cada task não em DONE/BLOCKED:

2.1 Per-task dispatch

1. Checar deps em <CONTEXT-PATH>/execution-state.json; não resolvida → BLOCKED via x-internal-update-status, skip.
2. Derivar taskCapabilities narrowing implementationCapabilities com evidências da task.
3. Dispatch TDD:

   Skill(skill: "x-implement-task", model: "sonnet",
         args: "<TASK-ID> --orchestrated --target-branch <targetBranch>
                [--auto-merge <strategy>] [--context-path <CONTEXT-PATH>]
                [--auto-approve-pr]")
   

   Retorna {status, taskId, commitSha, branchName, coverageLine, coverageBranch}.
4. PR creation:

   Skill(skill: "x-create-pr", model: "haiku",
         args: "<TASK-ID> --target-branch <targetBranch> --auto-merge <strategy>
                [--feature-id <FEATURE-ID>] [--auto-approve-pr]")
   

   --feature-id é passado apenas quando --story-mode=feature.
5. CI-watch (a menos que --no-ci-watch):

   Skill(skill: "x-watch-pr-ci", args: "--pr-number <prNumber>")
   

6. CI remediation loop (quando CI_FAILED/TIMEOUT): até 3 ciclos com x-fix-pr.
7. Status:

   Skill(skill: "x-internal-update-status",
         args: "--file <CONTEXT-PATH>/execution-state.json --type task --id <TASK-ID>
                --field status --value <STATUS>")
   

2.2 Fail-fast + story-level PR

Em status=FAILED, marcar dependentes BLOCKED e sair do Phase 2 com TASK_FAILED (a menos que --task). Com --auto-approve-pr, após todas as tasks serem concluídas:

Skill(skill: "x-create-pr", model: "haiku",
      args: "--story-id <STORY-ID> --head feat/story-<STORY-ID>
             --target-branch <targetBranch> --auto-merge <strategy>
             [--feature-id <FEATURE-ID>]")

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

Phase 2 completed. All tasks executed. Proceeding to Phase 3 (Verify & Report)...

Phase 3 — Verify, Report & Cleanup

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

Pulado apenas com --skip-verification (recovery-only).

3.Q Quality Gates — MANDATORY conditional

Sequência: dep-policy (D-R11 fast-fail).

Skill(skill: "x-validate-dependency-policy", model: "haiku",
      args: "--story-id <STORY-ID> --report <CONTEXT-PATH>/reports/dep-policy-validation-report-<STORY-ID>.md")

3.0 Documentation — MANDATORY (Rule 31)

Skill(skill: "x-generate-docs", model: "sonnet", args: "--story-id <STORY-ID>")
Skill(skill: "x-validate-docs", model: "sonnet",
      args: "--story-id <STORY-ID> --report-path <CONTEXT-PATH>/reports/doc-validate-report-<STORY-ID>.md")

3.1 Verify gate — MANDATORY TOOL CALL

Executar inline o Story Verification Procedure (VS-Step 1→8) em references/full-protocol.md §Story Verification Procedure com --story-id <STORY-ID> --context-path <CONTEXT-PATH> [--coverage-threshold-line 95] [--coverage-threshold-branch 90] (apenas Bash, strict read-only contra o source tree — roda o build tool, parseia coverage XML, mapeia AC → teste e smoke opcional; não cria branches, não muta state nem escreve reports). Consumir o envelope {passed, coverageDelta, failures, acCheckResults}.

Persiste <CONTEXT-PATH>/reports/verify-envelope-<STORY-ID>.json. Em passed=false → VERIFY_FAILED.

3.2 Specialist + Tech-Lead reviews — MANDATORY (a menos que --skip-review)

Skill(skill: "x-review-specialist", model: "sonnet", args: "<STORY-ID>")
Skill(skill: "x-review-pr", model: "sonnet", args: "<STORY-ID>")

3.3 Final report — MANDATORY TOOL CALL

Executar inline o Story Report Procedure (W-Step 1→7) em references/full-protocol.md §Story Report Procedure com --story-id <STORY-ID> --context-path <CONTEXT-PATH> --output <CONTEXT-PATH>/reports/story-completion-report-<STORY-ID>.md O render continua delegado a x-internal-write-report no W-Step 6 via Skill(skill: "x-internal-write-report", ...). Consumir o envelope {reportPath, summary}.

3.4 Status finalize

Finalizar via x-internal-update-status: Story **Status:** → Concluída, state.json → COMPLETE.

Skill(skill: "x-internal-update-status",
      args: "--file <CONTEXT-PATH>/execution-state.json --type story --id <STORY-ID>
             --field status --value COMPLETE")

3.5 Worktree cleanup (standalone Mode 2 only)

Gated por STORY_OWNS_WORKTREE:

• true + passed → Skill(skill: "x-manage-worktrees", args: "remove --id <STORY-ID>") + re-sync
• true + failed → preservar (Rule 14 §4)
• false → skip

Final gate:

Skill(skill: "x-internal-verify-phase-gates", model: "haiku",
      args: "--mode final --skill x-internal-implement-story --phase Phase-3-Verify
             --expected-artifacts <CONTEXT-PATH>/plans/arch-story-<STORY-ID>.md,
               <CONTEXT-PATH>/plans/plan-story-<STORY-ID>.md,
               <CONTEXT-PATH>/plans/tests-story-<STORY-ID>.md,
               <CONTEXT-PATH>/plans/tasks-story-<STORY-ID>.md,
               <CONTEXT-PATH>/plans/task-implementation-map-story-<STORY-ID>.md,
               <CONTEXT-PATH>/reports/verify-envelope-<STORY-ID>.json,
               <CONTEXT-PATH>/reports/story-completion-report-<STORY-ID>.md,
               <CONTEXT-PATH>/reports/doc-validate-report-<STORY-ID>.md")

Phase 3 completed. Lifecycle complete.

Review Policy — MANDATORY — NON-NEGOTIABLE

Specialist (x-review-specialist) + Tech-Lead (x-review-pr) em Step 3.2 DEVEM executar a menos que --skip-verification / --skip-review; omissão silenciosa é PROTOCOL_VIOLATION → subagents DEVEM abortar com "REVIEW_SKIPPED_WITHOUT_FLAG".

Recovery

Flags de bypass aceitos (apenas CLAUDE_RECOVERY_MODE=1):

| Flag | Pula | | :--- | :--- | | --skip-verification | Phase 3 inteiro | | --skip-review | Steps 3.2 (reviews) | | --skip-quality | Step 3.Q (quality gates) — Recovery ou hotfix/* only | | --skip-doc | Step 3.0 (docs) — Recovery ou hotfix/* only | | --skip-smoke | Smoke gate dentro de verify | | --no-ci-watch | CI-watch no Phase 2 |

Integration Notes

Callers diretos:

• x-implement-story — feature stories, passa --story-mode feature --context-path .aikittools/features/feature-XXXX/ --feature-id XXXX
• x-fix-bug — bug stories, passa --story-mode bug --context-path .aikittools/bugs/bug-NNNNNN/

Procedimentos inline (em references/full-protocol.md):

• Resume Story Procedure (0.4) — apenas Bash, strict read-only.
• Story Verification Procedure (3.1) — apenas Bash, strict read-only (roda build tool + coverage + AC mapping + smoke opcional). Operação leaf: sem chamadas aninhadas a outras skills.
• Story Report Procedure (3.3) — coleta de dados em Bash + render delegado a x-internal-write-report (W-Step 6).

Sub-skills invocadas: x-internal-build-story-plan (1), x-implement-task (2 por task), x-create-pr (2 por task+story), x-watch-pr-ci (2 CI loop), x-fix-pr (2 CI remediation + 3.2), x-internal-write-report (3.3 render, via Story Report Procedure), x-internal-update-status (todas as fases), x-manage-worktrees (0.3+3.5), x-evaluate-parallelism (1).

Full Protocol

Protocolo completo em references/full-protocol.md per ADR-0012.