edercnj/x-create-feature

Skill: x-create-feature (Unified Feature Entry Point)

Purpose

Orquestra o ciclo de criação de feature em dois modos:

• Modo A — Ciclo unificado interativo (padrão): orquestra toda a jornada de planejamento da feature em sequência, com checkpoint/resume e perguntas em aberto persistidas, dirigindo os 7 estágios: ideate → refine-business (feature) → criar histórias → refine-business (histórias) → [GATE] plan-arch → refine-técnico (histórias). A feature passa a exercer o papel de unidade de planejamento (não há mais um passo manual separado por artefato). O fluxo é conversacional: começa sem input obrigatório, entrevista o usuário via SIP, monta a spec RA9, conduz o refinamento de negócio (via x-refine-business), só então cria as histórias automaticamente, refina o negócio de cada história uma a uma, e — somente após o negócio estar 100% entendido — libera o desenho de arquitetura (x-plan-architecture) e o refinamento técnico por história (x-refine-feature/x-refine-story). Entre cada estágio há um gate interativo (PROCEED / PAUSE / ABORT): em PAUSE, o estado é persistido em feature-state.json e a skill encerra graciosamente, permitindo retomar exatamente de onde parou (inclusive no meio do refino de uma história específica) via --resume.
• Modo B — Decomposição legada (compatibilidade): quando recebe SPEC-FILE-PATH + --feature-id, executa o fluxo completo de geração de Feature + Stories + Implementation Map em worktree isolada, com PR e CI-watch.

Cenário-alvo do checkpoint/resume: um PO inicia a feature pela ideação, mas não sabe responder perguntas técnicas levantadas no refinamento/arquitetura. Em vez de bloquear, essas perguntas são registradas em openQuestions[] (não impedem o salvamento) e a feature é pausada. Um engenheiro retoma depois via x-create-feature --resume <slug>, responde as openQuestions e avança os estágios restantes.

The internal sub-skill x-internal-create-feature implements the Feature-container generation phase (not user-invocable); a geração das Stories segue a Story Creation Procedure (src/skills/x-add-story-to-feature/references/full-protocol.md §Story Creation Procedure) e a geração do Implementation Map vive em references/full-protocol.md §Implementation Map Procedure.

When to Use

• Quando o time de produto quer iniciar pela ideia em texto e sair com spec revisada em fluxo guiado.
• Quando é necessário revisar e editar seções da feature antes de avançar para refinamento.
• Quando já existe uma spec pronta e o objetivo é decompor em Feature + Stories + Map (modo legado).

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | SPEC-FILE-PATH | String | Condicional | Caminho da spec. Obrigatório no modo legado (decomposição). Opcional no modo interativo. | | --feature-id <NNNN> | String | Condicional | Obrigatório no modo legado (SPEC-FILE-PATH informado). | | --resume [<slug>] | Flag/String | Não | Retoma um ciclo de feature pausado a partir do feature-state.json. Sem slug, lista as features pausadas em .aikittools/features/ e pergunta qual retomar. | | --stop-after <stage> | String | Não | Encerra após o estágio indicado (ideate | refine | plan-arch), persistindo o estado. Útil para handoff planejado. | | --no-jira | Flag | Não | Desativa integração Jira no modo legado. | | --jira <PROJECT_KEY> | String | Não | Ativa integração Jira com projeto explícito no modo legado. | | --dry-run | Flag | Não | Mantém sem commit/push/PR nas fases legadas de saída. | | --no-interactive | Flag | Não | No modo legado, pula perguntas de desambiguação. Sem SPEC-FILE-PATH, retorna erro de uso inválido. |

Execution Modes

| Mode | Trigger | Output principal | Continuidade | |------|---------|------------------|--------------| | A — Jornada interativa (default) | Sem SPEC-FILE-PATH | Spec RA9 + histórias refinadas (negócio) + arquitetura + histórias refinadas (técnico) | Gate interativo entre estágios; feature pronta para x-implement-* | | B — Decomposição legada | Com SPEC-FILE-PATH + --feature-id | Feature + Stories + Map | PR docs/<feature-id>-<slug> -> feature/<feature-id> |

Prerequisites (mode-aware)

Common:

• knowledge/shared/interview-protocol/sequential-interview-protocol.md para o protocolo SIP.
• Permissão de escrita para salvar a spec em docs/specs/.

Mode B (decomposição legada):

• src/templates/_TEMPLATE-FEATURE.md (RA9 v2: 9 sections)
• src/templates/_TEMPLATE-STORY.md (RA9 v2: 9 sections)
• src/templates/_TEMPLATE-IMPLEMENTATION-MAP.md
• src/knowledge/shared/governance-baselines/planning-standards-ra9/knowledge.md (knowledge pack planning-standards-ra9)
• src/knowledge/shared/refinement-decomposition/decomposition-guide/knowledge.md
• Domain knowledge (dynamic): invoque Skill(skill: "x-internal-select-knowledge", args: "--kind domain --stage feature [--segment <seg>] [--product <prod>]") e leia todos os paths em required (e os recommended relevantes ao escopo) — fonte canônica de conhecimento de domínio para a feature; a leitura fixa acima é a âncora baseline.
• gh auth status deve estar OK antes de P5/P6/P7 (push/PR/CI-watch)

If any template is missing, stop and tell the user.

Execution scope constraint: uma invocação trata uma feature por vez. Para lote de features (0001..0004), execute sequencialmente por --feature-id.

Interactive Mode (default)

Sem SPEC-FILE-PATH, esta skill inicia em modo guiado e sempre pergunta primeiro pela ideia central da feature em um parágrafo. Em seguida aplica entrevistas SIP para consolidar as seções da spec.

Full protocol: knowledge/shared/interview-protocol/sequential-interview-protocol.md

Guided-question rules

• Apply the Sequential Interview Protocol (SIP) — one question at a time.
• NEVER ask questions in plain text; always use AskUserQuestion.
• Explore the codebase first — if a question can be answered from existing artifacts, derive it and skip the question.
• Choose field type based on question nature:
  • Yes/No decision → choices: ["Sim (Recomendado)", "Não"] or reversed
  • Multiple known options → choices: ["Opção A (Recomendada)", "Opção B", ...]
  • Open-ended → allow_freeform: true, no choices
• Always provide a recommended default — place it first in choices with (Recomendado) suffix, or as Sugestão: for freeform fields.
• Ask only what is needed for the current mode:
  • Modo A: completar spec funcional + RNFs + critérios de aceite.
  • Modo B: desambiguar corte/dependências de decomposição.
• Stop when enough signal is collected.
• Resolve decision dependencies one by one before asking dependent questions.
• If ambiguity remains, document explicit assumptions in generated artifacts.

Canonical ideation questions (Mode A, ask only if needed)

1. Domínio/contexto principal e problema de negócio
2. Limites de escopo explícitos (in/out)
3. Persona primária e público-alvo
4. Regras de negócio invariantes
5. Risco crítico/compliance
6. Perfil UX vs DX
7. KPI prioritário de sucesso
8. Restrições de rollout/adoção

Canonical decomposition questions (Mode B, ask only if needed)

1. Decomposition axis
   • By user journeys (Recommended)
   • By technical layers
   • By business capabilities
   • By integration boundaries
2. Story granularity target
   • Smaller stories (higher parallelism)
   • Balanced stories
   • Larger stories (fewer handoffs)
3. Primary architectural style for this feature
   • Layered/monolith module
   • Service-oriented
   • Event-driven
   • Hybrid
4. Critical NFR focus for this feature
   • Security/compliance
   • Performance
   • Reliability/resilience
   • Delivery speed/maintainability
5. Dependency strictness
   • Strict sequential phases
   • Mostly sequential with small parallel waves
   • Aggressive parallelism with risk controls
6. Jira strategy preference (if Jira enabled)
   • Cascade feature + all stories
   • Feature only
   • Keep markdown-only

Workflow Overview

MODE A (default, no spec path) — jornada unificada com checkpoint/resume:

  [--resume] R.0  RESUME DETECT -> Resume Detection Procedure (inline) lê feature-state.json
                                   → entra no estágio (e história) indicado por resumePoint, exibe openQuestions abertas
                                   (ver references/full-protocol.md#resume-detection-procedure)

  STAGE 1 — IDEATE
  0.   CAPTURE IDEA      -> AskUserQuestion (parágrafo da ideia central)
  0.5  INTERVIEW SIP     -> entrevistas sequenciais (funcionais + RNFs + riscos + KPIs)
  0.8  SPEC DRAFT        -> gerar/atualizar docs/specs/SPEC-<slug>-v1.md (RA9)
  0.9  REVIEW LOOP       -> mostrar visão completa + escolher seção para editar até aprovação final
  0.95 PERSIST + GATE    -> marcar stages.ideate=DONE; GATE (PROCEED/PAUSE/ABORT)

  STAGE 2 — REFINE-BUSINESS (FEATURE)
  1.0  REFINE-BIZ        -> Skill(x-refine-business, args: "--feature <spec-path>")
                           perguntas técnicas sem resposta → registrar em openQuestions[] (não bloqueia)
  1.5  PERSIST + GATE    -> marcar stages.refineBusinessFeature=DONE + verdict; GATE (PROCEED/PAUSE/ABORT)
                           só prossegue se verdict=approved (negócio 100% entendido)

  STAGE 3 — CREATE STORIES (automático)
  2.0  CREATE            -> Skill(x-internal-create-feature ...) + x-internal-create-story-from-feature
                           + Implementation Map Procedure (inline)  (gera feature+histórias+IMPLEMENTATION-MAP — compat Fase 1)
                           (ver references/full-protocol.md#implementation-map-procedure)
  2.5  PERSIST + GATE    -> registrar stages.createStories.storyIds[]; marcar DONE; GATE (PROCEED/PAUSE/ABORT)

  STAGE 4 — REFINE-BUSINESS (HISTÓRIAS, uma a uma, com estado)
  3.0  LOOP por história -> para cada story em ordem:
                             Skill(x-refine-business, args: "--story <story-id> --feature-id <id>")
                             persistir stages.refineBusinessStories.stories.<id>; GATE granular por história
                             (PAUSE retoma na MESMA história não-DONE)
  3.5  PERSIST + GATE    -> quando todas DONE, marcar stages.refineBusinessStories=DONE

  STAGE 5 — READY-FOR-ARCHITECTURE (gate marker)
  4.0  GATE MARKER       -> se ideate+refineBusinessFeature+createStories+refineBusinessStories todos DONE,
                           marcar stages.readyForArchitecture=DONE (libera GATE 1 de x-plan-architecture)

  STAGE 6 — PLAN-ARCH  (bloqueado por GATE 1: readyForArchitecture=DONE)
  5.0  PLAN-ARCH         -> Skill(x-plan-architecture, args: "--feature-id <id>")
                           perguntas técnicas sem resposta → registrar em openQuestions[] (não bloqueia)
  5.5  PERSIST + GATE    -> marcar stages.planArch=DONE + artefato; GATE (PROCEED/PAUSE/ABORT)

  STAGE 7 — REFINE-TÉCNICO (HISTÓRIAS, uma a uma, com estado)  (bloqueado por GATE 2: planArch=DONE)
  6.0  LOOP por história -> para cada story em ordem:
                             Skill(x-refine-story, args: "--feature-id <id> <story-id>")  (refino técnico multi-persona)
                             persistir stages.refineTechStories.stories.<id>; GATE granular por história
  6.5  PERSIST + DONE    -> quando todas DONE, marcar stages.refineTechStories=DONE + currentStage=done
                           histórias tecnicamente refinadas ficam aptas a /x-implement-story (GATE 3)

MODE B (legacy, with SPEC-FILE-PATH + --feature-id):
P1.5 WORKTREE      -> Worktree Precheck Procedure (inline) + x-manage-worktrees create feature-XXXX-<slug>
                      (ver references/full-protocol.md#worktree-precheck-procedure)
P2.  BRANCH        -> x-internal-ensure-feature-branch --feature-id XXXX
1.   ANALYSIS      -> Read spec, identify rules, stories, dependencies, phases
1.2  INTERVIEW     -> Guided disambiguation (skip with --no-interactive)
1.5  JIRA          -> Determine Jira integration mode
2.   FEATURE       -> x-internal-create-feature
3.   STORIES       -> Story Creation Procedure (inline)
                      (ver x-add-story-to-feature/references/full-protocol.md §Story Creation Procedure)
4.   MAP           -> Implementation Map Procedure (inline)
                      (ver references/full-protocol.md#implementation-map-procedure)
4.5  JIRA LINKS    -> Jira dependency links (conditional)
P4.  COMMIT        -> x-commit-planning consolidated commit on docs/<feature-id>-<slug>
P5.  PUSH          -> git push docs/<feature-id>-<slug>
P6.  PR            -> gh pr create (backlog body render)
P7.  CI-WATCH      -> x-watch-pr-ci (mandatory)
5.   REPORT        -> Save files + summary

Note on consolidated commit

No Modo B, x-create-feature usa single consolidated commit na Phase P4 cobrindo feature + stories + map. No Modo A, o artefato principal é a spec RA9; não há commit obrigatório nesta etapa.

---

Detailed Protocol

O passo-a-passo completo — Mode A (ideação interativa, A.1–A.14) e as fases detalhadas do Mode B (P1.5 → Phase 5 — Save and Report) — vive em references/full-protocol.md. O ## Workflow Overview acima é o mapa operacional (cada estágio/fase → sub-skill); carregue o protocolo detalhado sob demanda ao executar.

Recovery (Render Skill Fallback — story-0066-0006)

When x-internal-render-pr-body returns exit ≠ 0 in Phase P5.5, this skill falls back to a minimal manual body in Phase P6 to ensure PR creation never aborts (RULE-004 fail-open). The fallback body lacks the <!-- template-version: 1.0 --> marker — the downstream PR audit gate (story-0066-0007) will block the merge with PR_TEMPLATE_VIOLATION. This is intentional: the preventive render path produces the marker; the detective audit gate enforces it.

The WARN message includes RENDER_EXIT (the render skill exit code) so the operator can diagnose the cause: typically OPERATIONAL_ERROR (exit 2) when _TEMPLATE-PR-BACKLOG.md is missing from src/templates/ (restore it from version control).

Error Handling

| Scenario | Action | |----------|--------| | --no-interactive sem SPEC-FILE-PATH | Abort with usage error (--no-interactive requires SPEC-FILE-PATH and --feature-id) | | --resume combinado com SPEC-FILE-PATH | Abort com --resume cannot be combined with SPEC-FILE-PATH | | --resume <slug> sem feature-state.json | Resume Detection Procedure (inline) exit 1 (STATE_FILE_MISSING) → abortar com FEATURE_STATE_MISSING | | Usuário escolhe PAUSE no gate | Persistir estado, imprimir comando de retomada, encerrar com exit 0 (não é erro) | | Pergunta técnica sem resposta no refine/plan-arch | Registrar em openQuestions[]; nunca bloquear o salvamento | | Falha ao salvar docs/specs/SPEC-<slug>-v1.md no Mode A | Abort com SPEC_WRITE_FAILED | | Spec file not found or empty | Abort: Spec file not found or is empty. | | Template file missing | Stop and tell the user which template is missing | | Worktree Precheck Procedure (inline) exit 15 | Log WARNING, proceed with caution | | x-manage-worktrees fails | Abort with WORKTREE_FAILED | | x-internal-ensure-feature-branch fails | Abort with FEATURE_BRANCH_ENSURE_FAILED | | x-commit-planning exit 4 | Abort with COMMIT_FAILED | | x-commit-planning noOp=true | Silent no-op, continue to P5 | | gh auth status fails or token lacks repo permissions | Abort with GH_AUTH_REQUIRED before P5/P6/P7 | | x-create-pr fails | Abort with PR_CREATE_FAILED | | x-watch-pr-ci exit 20 (CI_FAILED) | Abort; preserve worktree for diagnosis | | --dry-run set | Phases P4, P5, P6, P7 are no-ops | | Circular dependency detected | Abort with cycle description | | Story fails quality validation | Fix before saving — do not skip validation |

Integration Notes

| Skill | Relationship | Notes | |-------|-------------|-------| | Worktree Precheck (P1.5.1) | inlined | Idempotent re-entrancy check; procedimento PW1 em references/full-protocol.md | | x-manage-worktrees | delegates (P1.5.2) | Creates feature-XXXX-<slug> worktree | | x-internal-ensure-feature-branch | delegates (P2 + MF-P2) | Ensures feature/XXXX on local + origin (chamada aninhada preservada dentro do Implementation Map Procedure inline) | | x-internal-create-feature | follows instructions (Ph 2) | Generates Feature file | | Story Creation Procedure (Ph 3) | follows procedure | Generates Story files via x-add-story-to-feature/references/full-protocol.md §Story Creation Procedure | | Implementation Map (Ph 4) | inlined | Generates Implementation Map; procedimento MF1–MF9 em references/full-protocol.md | | x-commit-planning | delegates (P4) | Single consolidated commit on docs branch | | x-create-pr | delegates (P6) | Opens PR with auto-merge (Rule 21 docs/ exception) | | x-watch-pr-ci | delegates (P7) | MANDATORY CI-watch (Rule 45) | | x-internal-update-status | delegates (Mode A) | Canonical mutator of feature-state.json (flock discipline) | | Resume Detection (--resume) | inlined | Envelope read-only: resumePoint (granular por história) + openQuestions; procedimento R1–R6 em references/full-protocol.md | | x-refine-business | stages 2 e 4 (Mode A) | Refinamento de negócio (PO) da feature e das histórias; perguntas técnicas → openQuestions | | x-internal-create-feature / x-internal-create-story-from-feature + Implementation Map Procedure (inline) | stage 3 (Mode A) | Criação automática de feature+histórias+mapa após negócio aprovado (compat Fase 1); o mapa é gerado inline (procedimento MF1–MF9 em references/full-protocol.md) | | x-plan-architecture | stage 6 (Mode A) | Desenho de arquitetura da feature; bloqueado por GATE 1 (readyForArchitecture) | | x-refine-feature / x-refine-story | stage 7 (Mode A) | Refinamento técnico multi-persona por história; bloqueado por GATE 2 (planArch) | | x-implement-story | followed by | Implementa cada história tecnicamente refinada (sequencial) |

Backward Compatibility

x-create-feature supports two entry modes: start with no arguments (interactive ideation) or pass SPEC-FILE-PATH --feature-id (decomposition). The internal sub-skill x-internal-create-feature is not user-invocable (Rule 22 — visibility: internal); a geração das Stories segue a Story Creation Procedure (em x-add-story-to-feature/references/full-protocol.md); a geração do Implementation Map e o precheck de worktree vivem neste caller (procedimentos MF1–MF9 e PW1 em references/full-protocol.md).