fimoklei/pm-ai-playbook/kiro-impl

kiro-impl Skill

Role

You operate in two modes:

• Autonomous mode (no task numbers): Dispatch a fresh subagent per task, with independent review after each
• Manual mode (task numbers provided): Execute selected tasks directly in the main context

Core Mission

• Success Criteria:
• All tests written before implementation code
• Code passes all tests with no regressions
• Tasks marked as completed in tasks.md
• Implementation aligns with design and requirements
• Independent reviewer approves each task before completion

Execution Steps

Step 1: Gather Context

If steering/spec context is already available from conversation, skip redundant file reads. Otherwise, load all necessary context:

• .kiro/specs/{feature}/spec.json, requirements.md, design.md, tasks.md
• Core steering context: product.md, tech.md, structure.md
• Additional steering files only when directly relevant to the selected task's boundary, runtime prerequisites, integrations, domain rules, security/performance constraints, or team conventions that affect implementation or validation
• Relevant local agent skills or playbooks only when they clearly match the task's host environment or use case; read the specific artifact(s) you need, not entire directories

Parallel Research

The following research areas are independent and can be executed in parallel:

1. Spec context loading: spec.json, requirements.md, design.md, tasks.md
2. Steering, playbooks, & patterns: Core steering, task-relevant extra steering, matching local agent skills/playbooks, and existing code patterns

After all parallel research completes, synthesize implementation brief before starting.

Preflight

Validate approvals:

• Verify tasks are approved in spec.json (stop if not, see Safety & Fallback)

Discover validation commands:

• Inspect repository-local sources of truth in this order: project scripts/manifests (package.json, pyproject.toml, go.mod, Cargo.toml, app manifests), task runners (Makefile, justfile), CI/workflow files, existing e2e/integration configs, then README*
• Derive a canonical validation set for this repo: TEST_COMMANDS, BUILD_COMMANDS, and SMOKE_COMMANDS
• Prefer commands already used by repo automation over ad hoc shell pipelines
• For SMOKE_COMMANDS, choose the lightest trustworthy runtime-liveness check for the app shape (for example: root URL load, Electron launch, CLI --help, service health endpoint, mobile simulator/e2e harness if one already exists)
• Keep the full command set in the parent context, and pass only the task-relevant subset to implementer and reviewer subagents

Establish repo baseline:

• Run git status --porcelain and note any pre-existing uncommitted changes

Step 2: Select Tasks & Determine Mode

Parse arguments:

• Extract feature name from first argument
• If task numbers provided (e.g., "1.1" or "1,2,3"): manual mode
• If no task numbers: autonomous mode (all pending tasks)

Build task queue:

• Read tasks.md, identify actionable sub-tasks (X.Y numbering like 1.1, 2.3)
• Major tasks (1., 2.) are grouping headers, not execution units
• Skip tasks with _Blocked:_ annotation
• For each selected task, check _Depends:_ annotations -- verify referenced tasks are [x]
• If prerequisites incomplete, execute them first or warn the user
• Use _Boundary:_ annotations to understand the task's component scope

Step 3: Execute Implementation

Autonomous Mode (subagent dispatch)

Iteration discipline: Process exactly ONE sub-task (e.g., 1.1) per iteration. Do NOT batch multiple sub-tasks into a single subagent dispatch. Each iteration follows the full cycle: dispatch implementer → review → commit → re-read tasks.md → next.

Context management: At the start of each iteration, re-read tasks.md to determine the next actionable sub-task. Do NOT rely on accumulated memory of previous iterations. After completing each iteration, retain only a one-line summary (e.g., "1.1: READY_FOR_REVIEW, 3 files changed") and discard the full status report and reviewer details.

For each task (one at a time):

a) Dispatch implementer:

• Read templates/implementer-prompt.md from this skill's directory
• Construct a prompt by combining the template with task-specific context:
• Task description and boundary scope
• Paths to spec files: requirements.md, design.md, tasks.md
• Exact requirement and design section numbers this task must satisfy (using source numbering, NOT invented REQ-* aliases)
• Task-relevant steering context and parent-discovered validation commands (tests/build/smoke as relevant)
• Whether the task is behavioral (Feature Flag Protocol) or non-behavioral
• Previous learnings: Include any ## Implementation Notes entries from tasks.md that are relevant to this task's boundary or dependencies (e.g., "better-sqlite3 requires separate rebuild for Electron"). This prevents the same mistakes from recurring.
• The implementer subagent will read the spec files and build its own Task Brief (acceptance criteria, completion definition, design constraints, verification method) before implementation
• Dispatch via Agent tool as a fresh subagent

b) Handle implementer status:

• Parse implementer status only from the exact ## Status Report block and - STATUS: field.
• If STATUS is missing, ambiguous, or replaced with prose, re-dispatch the implementer once requesting the exact structured status block only. Do NOT proceed to review without a parseable READY_FOR_REVIEW | BLOCKED | NEEDS_CONTEXT value.
• READY_FOR_REVIEW → proceed to review
• BLOCKED → dispatch debug subagent (see section below); do NOT immediately skip
• NEEDS_CONTEXT → re-dispatch once with the requested additional context; if still unresolved → dispatch debug subagent

c) Dispatch reviewer:

• Read templates/reviewer-prompt.md from this skill's directory
• Construct a review prompt with:
• The task description and relevant spec section numbers
• Paths to spec files (requirements.md, design.md) so the reviewer can read them directly
• The implementer's status report (for reference only — reviewer must verify independently)
• The reviewer must apply the kiro-review protocol to this task-local review.
• Preserve the existing task-specific context: task text, spec refs, _Boundary:_ scope, validation commands, implementer report, and the actual git diff as the primary source of truth.
• The reviewer subagent will run git diff itself to read the actual code changes and verify against the spec
• Dispatch via Agent tool as a fresh subagent

d) Handle reviewer verdict:

• Parse reviewer verdict only from the exact ## Review Verdict block and - VERDICT: field.
• If VERDICT is missing, ambiguous, or replaced with prose, re-dispatch the reviewer once requesting the exact structured verdict only. Do NOT mark the task complete, commit, or continue to the next task without a parseable APPROVED | REJECTED value.
• APPROVED → before marking the task [x] or making any success claim, apply kiro-verify-completion using fresh evidence from the current code state; then mark task [x] in tasks.md and perform selective git commit
• REJECTED (round 1-2) → re-dispatch implementer with review feedback
• REJECTED (round 3) → dispatch debug subagent (see section below)

e) Commit (parent-only, selective staging):

• Stage only the files actually changed for this task, plus tasks.md
• NEVER use git add -A or git add .
• Use git add <file1> <file2> ... with explicit file paths
• Commit message format: feat(<feature-name>): <task description>

f) Record learnings:

• If this task revealed cross-cutting insights, append a one-line note to the ## Implementation Notes section at the bottom of tasks.md

g) Debug subagent (triggered by BLOCKED, NEEDS_CONTEXT unresolved, or REJECTED after 2 remediation rounds):

The debug subagent runs in a fresh context — it receives only the error information, not the failed implementation history. This avoids the context pollution that causes infinite retry loops.

• Read templates/debugger-prompt.md from this skill's directory
• Construct a debug prompt with:
• The error description / blocker reason / reviewer rejection findings
• git diff of the current uncommitted changes
• The task description and relevant spec section numbers
• Paths to spec files so the debugger can read them
• The debugger must apply the kiro-debug protocol to this failure investigation.
• Preserve rich failure context: error output, reviewer findings, current git diff, task/spec refs, and any relevant Implementation Notes.
• When available, the debugger should inspect runtime/config state and use web or official documentation research to validate root-cause hypotheses before proposing a fix plan.
• Dispatch via Agent tool as a fresh subagent

Handle debug report:

• Parse NEXT_ACTION from the debug report's exact structured field.
• If NEXT_ACTION: STOP_FOR_HUMAN → append _Blocked: <ROOT_CAUSE>_ to tasks.md, stop the feature run, and report that human review is required before continuing
• If NEXT_ACTION: BLOCK_TASK → append _Blocked: <ROOT_CAUSE>_ to tasks.md, skip to next task
• If NEXT_ACTION: RETRY_TASK → preserve the current worktree; do NOT reset or discard unrelated changes. Spawn a new implementer subagent with the debug report's FIX_PLAN, NOTES, and the current git diff, and require it to repair the task with explicit edits only
• If the new implementer succeeds (READY_FOR_REVIEW → reviewer APPROVED) → normal flow
• If the new implementer also fails → repeat debug cycle (max 2 debug rounds total). After 2 failed debug rounds → append _Blocked: debug attempted twice, still failing — <ROOT_CAUSE>_ to tasks.md, skip
• Max 2 debug rounds per task. Each round: fresh debug subagent → fresh implementer. If still failing after 2 rounds, the task is blocked.
• Record debug findings in ## Implementation Notes (this helps subsequent tasks avoid the same issue)

`(P)` markers: Tasks marked (P) in tasks.md indicate they have no inter-dependencies and could theoretically run in parallel. However, kiro-impl processes them sequentially (one at a time) to avoid git conflicts and simplify review. The (P) marker is informational for task planning, not an execution directive.

Completion check: If all remaining tasks are BLOCKED, stop and report blocked tasks with reasons to the user.

Manual Mode (main context)

For each selected task:

1. Build Task Brief: Before writing any code, read the relevant sections of requirements.md and design.md for this task and clarify:

• What observable behaviors must be true when done (acceptance criteria)
• What files/functions/tests must exist (completion definition)
• What technical decisions to follow from design.md (design constraints)
• How to confirm the task works (verification method)

2. Execute TDD cycle (Kent Beck's RED → GREEN → REFACTOR):

• RED: Write test for the next small piece of functionality based on the acceptance criteria. Test should fail.
• GREEN: Implement simplest solution to make test pass, following the design constraints.
• REFACTOR: Improve code structure, remove duplication. All tests must still pass.
• VERIFY: All tests pass (new and existing), no regressions. Confirm verification method passes.
• REVIEW: Apply kiro-review before marking the task complete. If the host supports fresh subagents in manual mode, use a fresh reviewer; otherwise perform the review in the main context using the kiro-review protocol. Do NOT continue until the verdict is parseably APPROVED.
• MARK COMPLETE: Only after review returns APPROVED, apply kiro-verify-completion, then update the checkbox from - [ ] to - [x] in tasks.md.

Step 4: Final Validation