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:
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)
Determine review mode from the invocation:
--review required or omitted → required
--review inline → inline
--review off, skip review, or without review → off
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) Review the task:
If review mode is required:
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
If review mode is inline:
Apply kiro-review in the parent context using the same task evidence and the actual git diff
If review mode is off:
Skip task-local review
Record in the parent context that task-local review was skipped for this task
d) Handle reviewer verdict:
If review mode is off:
Do not fabricate a reviewer verdict
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
Otherwise:
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
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:
required: 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.
inline: Apply kiro-review in the main context before marking the task complete.
off: Skip task-local review, but note that kiro-validate-impl becomes the primary quality gate before any feature-level completion claim.
MARK COMPLETE:
required|inline: Only after review returns APPROVED, apply kiro-verify-completion, then update the checkbox from - [ ] to - [x] in tasks.md.
off: Apply kiro-verify-completion, then update the checkbox from - [ ] to - [x] in tasks.md.
Step 4: Final Validation
Autonomous mode:
After all tasks complete, run /kiro-validate-impl {feature} as a GO/NO-GO gate
If validation returns GO → before reporting feature success, apply kiro-verify-completion to the feature-level claim using the validation result and fresh supporting evidence
If validation returns NO-GO:
Fix only concrete findings from the validation report
Cap remediation at 3 rounds; if still NO-GO, stop and report remaining findings
If validation returns MANUAL_VERIFY_REQUIRED → stop and report the missing verification step
Manual mode:
Suggest running /kiro-validate-impl {feature} but do not auto-execute
If review mode is off, treat /kiro-validate-impl {feature} as mandatory before any feature-level success claim
Feature Flag Protocol
For tasks that add or change behavior, enforce RED → GREEN with a feature flag:
Add flag (OFF by default): Introduce a toggle appropriate to the codebase (env var, config constant, boolean, conditional -- agent chooses the mechanism)
RED -- flag OFF: Write tests for the new behavior. Run tests → must FAIL. If tests pass with flag OFF, the tests are not testing the right thing. Rewrite.
GREEN -- flag ON + implement: Enable the flag, write implementation. Run tests → must PASS.
Remove flag: Make the code unconditional. Run tests → must still PASS.
Skip this protocol for: refactoring, configuration, documentation, or tasks with no behavioral change.
Critical Constraints
Strict Handoff Parsing: Never infer implementer STATUS or reviewer VERDICT from surrounding prose; only the exact structured fields count
No Destructive Reset: Never use git checkout ., git reset --hard, or similar destructive rollback inside the implementation loop
Selective Staging: NEVER use git add -A or git add .; always stage explicit file paths
Bounded Review Rounds: Max 2 implementer re-dispatch rounds per reviewer rejection, then debug
Bounded Debug: Max 2 debug rounds per task (debug + re-implementation per round); if still failing → BLOCKED
Bounded Remediation: Cap final-validation remediation at 3 rounds
Output Description
Autonomous mode: For each task, report:
Task ID, implementer status, reviewer verdict
Files changed, commit hash
After all tasks: final validation result (GO/NO-GO)
Manual mode:
Tasks executed: task numbers and test results
Status: completed tasks marked in tasks.md, remaining tasks count
Format: Concise, in the language specified in spec.json.
Safety & Fallback
Error Scenarios
Tasks Not Approved or Missing Spec Files:
Stop Execution: All spec files must exist and tasks must be approved
Stop Implementation: Fix failing tests before continuing
Action: Debug and fix, then re-run
All Tasks Blocked:
Stop and report all blocked tasks with reasons
Human review needed to resolve blockers
Spec Conflicts with Reality:
If a requirement or design conflicts with reality (API doesn't exist, platform limitation), block the task with _Blocked: <reason>_ -- do not silently work around it
Upstream Ownership Detected:
If review, debug, or validation shows that the root cause belongs to an upstream, foundation, shared-platform, or dependency spec, do not patch around it inside the downstream feature
Route the fix back to the owning upstream spec, keep the downstream task blocked until that contract is repaired, and re-run validation/smoke for dependent specs after the upstream fix lands
Task Plan Invalidated During Implementation:
If debug returns NEXT_ACTION: STOP_FOR_HUMAN because of task ordering, boundary, or decomposition problems, stop and return for human review of tasks.md or the approved plan instead of forcing a code workaround