edercnj/x-plan-task

Skill: Plan Task (slim — ADR-0012)

Purpose

Produces a detailed narrative implementation plan for a single task. The plan is a self-contained execution guide readable by a human auditor without consulting other documents. It contains: back-reference to the parent plan-story-XXXX-YYYY.md section, objective in plain language, class/component diagram scoped to this task, mapping of all existing tests impacted by this task, verbal description of what to write/change in each file, TDD cycles in TPP order described in natural language (RED/GREEN/REFACTOR), security checklist, file footprint, and explicit completion criteria (including how to mark the task as Concluída and update execution-state.json).

Triggers

• /x-plan-task --task-file <path> — task-file-first: consume a standalone task-TASK-XXXX-YYYY-NNN.md contract, write the plan next to it.
• /x-plan-task --task-file <path> --output-dir <dir> — override output directory.
• /x-plan-task --task-file <path> --no-commit — batch mode (story-0049-0017): write the plan file but SKIP the individual planning-commit. Callers (e.g., x-plan-story) aggregate N plans and issue ONE batched commit.

Invocation mode. Task-file-first is the only supported path: an orchestrator (human or x-plan-story) generates task-TASK-NNN.md files and pipes each one through this skill. See full protocol §1 for the validation rules.

Parameters

Task-file-first mode

| Parameter | Required | Description | |-----------|----------|-------------| | --task-file | Yes | Path to a task-TASK-XXXX-YYYY-NNN.md file (schema: story-0038-0001). MUST pass TaskFileParser validation. | | --output-dir | No (default: same dir as --task-file) | Directory to write plan-task-TASK-XXXX-YYYY-NNN.md. | | --force | No | Regenerate plan even if a fresh one already exists. | | --no-commit | No (default: false) | When true, skip the Planning Status Propagation commit (Phase 5.4). Plan file is still written to disk and status is still flipped Pendente -> Planejada, but the commit step is deferred to the caller. Used by x-plan-story to batch-commit N plans in a single commit (story-0049-0017). | | --dry-run | No (default: false) | When true, plan file is written to disk but Steps P2 / P4 / P5 (branch-ensure / planning-commit / push) become no-ops (RULE-007). |

Output Contract

| Artifact | Path | Produced By | |----------|------|-------------| | Task plan | <FEATURE_DIR>/plans/plan-task-TASK-XXXX-YYYY-NNN.md | Phase 5 (Write Plan) | | Status update on task file | Pendente → Planejada | Phase 5.4 (Planning Status Propagation, v2 only) | | Planning commit (batched or single) | feature/<XXXX> ref | Phase 5.4 / Step P4 (suppressed in --no-commit / --dry-run) | | Push to origin (optional) | feature/<XXXX> ref | Step P5 (suppressed in --no-commit / --dry-run) |

CRITICAL EXECUTION RULE

5 phases (0–5) framed by P1+P2 prelude and P5 epilogue. Phase 5.4 doubles as Step P4. ALL mandatory in default mode. NEVER stop before Phase 5.

Workflow Overview

P1.  WORKTREE         -> _shared/orchestrator-prelude.md (worktree-detect)
P2.  FEATURE BRANCH      -> _shared/orchestrator-prelude.md (feature-branch-ensure)
Phase 0: VALIDATE & PRE-CHECK -> args, feature-dir resolution, staleness check (inline)
Phase 1: EXTRACT CONTRACTS    -> task-file-first (1A) → Spec Resolution (1B)
Phase 2: MAP TDD CYCLES       -> TPP-ordered cycles in natural language
Phase 3: ANALYZE FILES        -> Organize affected files by architecture layer
Phase 4: SECURITY CHECKLIST   -> Task-type-aware items with CWE/OWASP refs
Phase 4.5: FILE FOOTPRINT     -> Structured write:/read:/regen: block
Phase 5: WRITE PLAN           -> Assemble + write plan-task-*.md per template
  └ 5.4 PLANNING STATUS PROPAGATION (= Step P4)  -> flip task status + batched commit
P5.  PUSH             -> x-push-branch --branch feature/<XXXX> (optional)

Steps P1 + P2 — Worktree + Feature Branch Prelude

Apply the canonical orchestrator prelude using <HOST-SKILL> = x-plan-task and <FEATURE-ID> resolved from the task source:

• Task-file mode (--task-file): extract XXXX from the task-file path (.aikittools/features/feature-XXXX/plans/task-TASK-XXXX-YYYY-NNN.md) or from the task's **Task ID:** header.

P1 is fail-open (RULE-006 advisory). P2 aborts with FEATURE_BRANCH_ENSURE_FAILED on non-zero exit. P2 is skipped on --no-commit or --dry-run per the canonical prelude contract.

Phases 0–5

The detailed inline protocol for each phase (validation rules, TPP cycle structure, mandatory plan template, security checklist by task type, File Footprint inference rules, Planning Status Propagation CLI commands) lives in references/full-protocol.md:

• Context selection (pre-Phase 1): resolve task-scoped-capabilities with anti-inflation rules: baseline architecture,testing,security; add runtime/language capability (for example java) only when evidenced by the task/repo; add database/performance only when explicitly required by task scope or NFRs. Then invoke both x-internal-select-context-packs --phase plan --capabilities <task-scoped-capabilities> (patterns) and x-internal-select-knowledge --kind technical --phase plan --capabilities <task-scoped-capabilities> (technical knowledge), and load all required assets from the union before task-plan synthesis. Both selectors are canonical (the patterns one applies hybrid technology assessment internally); include recommended only when scope-relevant and avoid parallel hardcoded pack lists.

• Phase 0.5 — Tech Context & Layer Guidance (MANDATORY when tech-context.config.json exists): After context selection, load the technology profile and derive layer-specific coding guidance:

  Skill(skill: "x-internal-evaluate-tech-context",
        args: "--phase plan --capabilities <task-scoped-capabilities>")
  

  From the response, derive LAYER_TECH_GUIDANCE:

  1. Extract technology.backend, technology.database, technology.messageBroker, technology.apiProtocol, technology.auth from techProfile.technology.

  2. Read task.layer from the task-file (e.g., "Adapter Inbound", "Domain", "Application").

  3. Read task.type from the task-file (e.g., "REST endpoint", "JPA repository", "Domain service").

  4. Apply the Layer Tech Guidance Table from references/full-protocol.md §Layer Tech Guidance (see table below for inline reference) to produce:

     {
       "stack": "java-spring",
       "layer": "Adapter Inbound",
       "mechanism": "REST",
       "annotations": "@RestController\n@RequestMapping(\"/api/v1/...\")\n@Valid\n@RequestBody\nResponseEntity<>",
       "namingConvention": { "class": "*Controller", "method": "verbNoun" },
       "testConvention": { "type": "@WebMvcTest", "annotations": "@MockBean, @Autowired MockMvc", "mock": "MockMvc.perform()" },
       "patternRefs": ["src/patterns/{your-grouper}/backing-services-integration-rest-server/catalog.md", "src/patterns/{your-grouper}/standards-language-java21-spring3/catalog.md"]
     }
     

  5. If techProfile.inputsUsed.config = false → set LAYER_TECH_GUIDANCE = null. Log WARNING: tech-context.config.json not found — Section 2.6 will be N/A.

  Inline Layer Tech Guidance Table (canonical reference — full table in references/full-protocol.md §Layer Tech Guidance):

  | Stack + Layer + Mechanism | Annotations / Interfaces | Naming | Test Type | |---------------------------|--------------------------|--------|-----------| | java-spring + Domain | Plain Java/records; no Spring annotations; domain exceptions | *Entity, *ValueObject, *Exception | @ExtendWith(MockitoExtension.class) | | java-spring + Port | Java interfaces only; no @Service; typed domain parameters | *Port (outbound), *UseCase (inbound) | @ExtendWith(MockitoExtension.class) | | java-spring + Adapter Inbound (REST) | @RestController, @RequestMapping, @Valid, @RequestBody, ResponseEntity<> | *Controller | @WebMvcTest, @MockBean, MockMvc | | java-spring + Adapter Inbound (gRPC) | @GrpcService, extends *Grpc.*ImplBase, StreamObserver | *GrpcService | @SpringBootTest, gRPC test channel | | java-spring + Adapter Outbound (JPA) | @Repository, extends JpaRepository<>, @Transactional, @Entity, @Column | *JpaRepository, *JpaEntity | @DataJpaTest, @Testcontainers | | java-spring + Adapter Outbound (Kafka) | @KafkaListener, KafkaTemplate<>, @Payload, @Header | *KafkaConsumer, *KafkaProducer | @EmbeddedKafka, @SpringBootTest | | java-spring + Application | @Service, constructor injection; implements *UseCase port | *Service | @ExtendWith(MockitoExtension.class), @Mock ports | | java-spring + Config | @Configuration, @Bean, @ConditionalOnProperty | *Config, *Configuration | @SpringBootTest (integration) |

• Phase 0.5B — Architecture Decisions Loading (MANDATORY when at least one decisions file exists):

  After Layer Tech Guidance, check for backend decisions file:

  if [ -f "docs/architecture/architecture-decisions-backend.md" ]; then
    echo "HAS_ARCH_DECISIONS=true"
  fi
  

  When at least one file exists, the plan writer subagent MUST:

  1. Read every pattern/knowledge path listed in the "Patterns e Knowledge Obrigatórios" section.
  2. For each file listed, load it and extract the excerpt relevant to this task's layer/type.
  3. Include extracted excerpts directly in Section 2.6 (Contexto de Implementação) of the task plan.

• Instrução de conteúdo explícito de patterns (Anti-Alucinação):

  Para cada componente, endpoint, query, ou integração a ser implementado nesta task, o plano DEVE incluir o trecho literal do pattern ou rule aplicável — não apenas o caminho do arquivo.

  Regra: Para cada item em ## File Footprint do tipo write:, o plano DEVE ter ao menos uma das seguintes entradas na Section 2.6:

  • Trecho literal de anotações/interfaces obrigatórias (ex: @RestController, @Valid, ResponseEntity<>)
  • Trecho literal de configuração mínima (ex: connection pool, timeout)
  • Trecho literal de campos HTTP obrigatórios (status codes, headers)
  • Trecho literal de parâmetros de resiliência (circuit breaker threshold, retry count)

  Formato obrigatório:

  > **Pattern aplicado** (`<caminho/do/pattern.md>`):
  > ```
  > <trecho literal copiado do arquivo de pattern — máx. 20 linhas>
  > ```
  

  Se não houver pattern aplicável → escrever explicitamente: Nenhum pattern específico aplicável a este item.

• Phase 0 — Validate & Pre-Check (§Phase 0): parse args, resolve FEATURE_DIR (exact or suffix variant), resolve paths, and run the staleness check (mtime comparison) — skip regeneration when plan is fresh and --force not set.

• Phase 1 — Extract Contracts (§Phase 1): 1A task-file-first (validate per task-schema.md, project into TaskContract); 1B Spec Resolution (read plan-story-XXXX-YYYY.md > Section 2.6.1 from the parent story plan — locate the interface/method entry whose Camada matches this task's layer AND whose Interface / Classe name matches the interface/class this task implements; project into TaskSpec with fields: signature, precondition, postcondition, expectedExceptions — used to populate Section 2.5 of the task plan; if plan-story is absent or Section 2.6 is N/A, set TaskSpec = nil and log a WARNING).

• Phase 2 — Map TDD Cycles (TPP Order) (§Phase 2): generate 3–6 cycles in strict Transformation Priority Premise order; Cycle 1 MUST be degenerate; each cycle described in natural language (RED test, GREEN minimal impl, REFACTOR, commit subject). When TaskSpec != nil, each cycle MUST include a Spec ref annotation pointing to the interface/method from TaskSpec.signature.

• Phase 3 — Analyze Affected Files by Layer (§Phase 3): organize files in Domain → Port → Adapter → Application → Config → Test order; mark CREATE/MODIFY.

• Phase 4 — Security Checklist (§Phase 4): task-type-aware items (Endpoint/API, Persistence/DB, Domain Logic, Config, Integration) with CRITICAL/HIGH/MEDIUM severity and CWE/OWASP refs.

• Phase 4.5 — Compute File Footprint (§Phase 4.5): emit machine-readable ## File Footprint block (write:/read:/regen: sub-sections, alphabetically sorted, empty sub-sections omitted) for downstream /x-evaluate-parallelism consumption.

• Phase 5 — Write Plan (§Phase 5): assemble and write plan-task-TASK-XXXX-YYYY-NNN.md per _TEMPLATE-TASK-PLAN.md; prepend MANDATORY origin marker frontmatter; sections 1–8 with OBRIGATÓRIO markers per template. Section 2.5 is populated from TaskSpec (Phase 1B): if TaskSpec != nil, write the method signature block and pre/postcondition table; if TaskSpec == nil, write "N/A — plan-story sem Seção 2.6 ou task sem interface estrutural". Section 2.6 (Contexto de Implementação) is populated from LAYER_TECH_GUIDANCE (Phase 0.5): if LAYER_TECH_GUIDANCE != nil, populate all subsections (Stack/Layer/Mechanism table, Annotations/Interfaces block, Naming Convention table, Test Convention table, Pattern References list); if LAYER_TECH_GUIDANCE == nil, write "N/A — tech-context.config.json não encontrado ou layer não mapeado."

• Phase 5.4 — Planning Status Propagation (§Planning Status Propagation, alias of Step P4): v2-gated Pendente → Planejada status flip via native **Status:** field rewrite; commit gated by --no-commit.

Step P4 — Planning Status Commit (alias)

The planning-commit step is performed inside Phase 5.4. When --no-commit=true or --dry-run=true, that step becomes a no-op ("[no-commit] Plan written; commit deferred to caller" or "dry-run, skipping commit"). No additional P4 invocation is issued; this alias exists so the P1–P5 convention is readable end-to-end. See full protocol §Step P4 for the rationale.

Step P5 — Push to Origin (optional)

If --dry-run or --no-commit is set, skip.

Otherwise delegate to x-push-branch:

Skill(skill: "x-push-branch", args: "--branch feature/<XXXX>")

On push failure, log a WARNING and continue — local commit is preserved. See full protocol §Step P5.

Error Envelope

Canonical orchestrator-wide error codes (FEATURE_BRANCH_ENSURE_FAILED, COMMIT_FAILED, fail-open vs fail-closed conventions, --dry-run semantics) live in _shared/error-handling-orchestrator.md. Rows below are skill-specific.

Task-file-first mode

| Scenario | Exit Code | Message | |----------|-----------|---------| | Task file missing or unreadable | 1 | Task file invalid: file not found at {path} | | Task file schema violations (story-0038-0001) | 1 | Task file invalid: {violations} | | Testability not declared (§2.3 empty / multiple checked) | 3 | Testability not declared (RULE-TF-01). Declare Testability: Independent OR Requires Mock OR Coalesced | | Output dir not writable | 2 | Output dir not writable: {path} | | Plan generated | 0 | Plan written to {path} | | Plan exists and fresh (no --force) | 0 | Task plan already exists and is up-to-date |

Integration Notes

| Skill | Relationship | Context | |-------|-------------|---------| | x-plan-story | complementary | x-plan-story generates task breakdown; x-plan-task generates per-task execution plans | | x-implement-story | called-by | Phase 2 (PRE_PLANNED mode) reads task plans to drive implementation | | x-implement-task | consumed-by | Task plans serve as implementation guides for the developer | | x-plan-tests | complementary | x-plan-tests covers story-level tests; x-plan-task maps per-task TDD cycles | | x-manage-worktrees | calls (Step P1) | Detect-context (RULE-001) | | x-internal-ensure-feature-branch | calls (Step P2) | Ensure feature/<ID> exists locally + origin (RULE-001) | | x-commit-changes | calls (Phase 5.4 / Step P4) | Commit plan + status flip in standalone mode | | x-push-branch | calls (Step P5) | Push canonical feature branch to origin (optional) |

Knowledge Pack References

| Pack | Files | Purpose | |------|-------|---------| | selector | x-internal-select-context-packs | Canonical plan-pack selection by phase/capability (filesystem-based discovery — no CSV) | | testing | src/patterns/{your-grouper}/testing-unit-java21/catalog.md, src/patterns/{your-grouper}/testing-unit-spring3/catalog.md | TDD strategy, unit/integration/acceptance test support | | architecture | src/patterns/{your-grouper}/standards-architecture-hexagonal/catalog.md | Layer definitions, package structure, dependency rules | | security | src/patterns/{your-grouper}/security-api-owasp-top10/catalog.md | OWASP Top 10, security checklist items | | parallelism-heuristics | src/patterns/ai-kit-tools/skills/parallelism-heuristics/pattern.md | File Footprint semantics (write/read/regen sub-sections) consumed by Phase 4.5 | | coding-standards | knowledge/shared/governance-baselines/coding-standards-rule/knowledge.md | Hard limits, naming and SOLID principles (language-agnostic baseline) |

Execution note: this table lists common candidates. Runtime loading MUST follow x-internal-select-context-packs output (required first, then scope-relevant recommended).

Anti-Patterns

• Do NOT write implementation code — only plan the approach
• Do NOT skip degenerate cases in TDD cycles (Cycle 1 is ALWAYS degenerate)
• Do NOT generate security items unrelated to the task type
• Do NOT list files outside the task scope
• Do NOT include cycles beyond what the task complexity requires (CRUD tasks need 3-4 cycles, not 8)
• Do NOT ignore the task's layer assignment — files must align with the declared layer
• Do NOT generate cycles in non-TPP order (never start with complex cases)

Full Protocol

Minimum viable contract above. Detailed phase-by-phase workflow (validation rules, mandatory plan template with all OBRIGATÓRIO sections, TPP cycle structure, security checklist by task type, File Footprint inference rules R1–R5, origin-marker frontmatter, Rule 22 Planning Status Propagation with native **Status:** field rewrites, P4/P5 telemetry markers) lives in references/full-protocol.md per ADR-0012 (skill body slim-by-default).