marius/Open_Ultra_SAST
1
0
Fork 0
mirror of https://github.com/norandom/OpenUltraSAST.git synced 2026-10-16 03:49:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(skills): .agents/skills -- the plural directory OpenCode searches by default

Browse Source 
Verified against opencode.ai/docs/skills: project-local search paths are
.opencode/skills, .claude/skills and .agents/skills, not configurable.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo
This commit is contained in:
Marius Ciepluch
2026-10-02 19:24:33 +02:00
co-authored by Claude Fable 5.1
parent 69b5e0efcc
commit 5010b15ffc
39 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/kiro-impl/SKILL.md
+244
View File
@@ -0,0 +1,244 @@
---
name: kiro-impl
description: Implement approved tasks using TDD with subagent dispatch. Runs all pending tasks autonomously or selected tasks manually.
---
# kiro-impl Skill
<background_information>
You operate in two modes:
- **Autonomous mode** (no task numbers): Dispatch a fresh sub-agent per task, with independent review after each
- **Manual mode** (task numbers provided): Execute selected tasks directly in the main context
- **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
</background_information>
<instructions>
## 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 sub-agents
**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 `$1`
- If task numbers provided in `$2` (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 (sub-agent dispatch)
**Iteration discipline**: Process exactly ONE sub-task (e.g., 1.1) per iteration. Do NOT batch multiple sub-tasks into a single sub-agent 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.
If multi-agent capability is available, 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 sub-agent will read the spec files and build its own Task Brief (acceptance criteria, completion definition, design constraints, verification method) before implementation
- Spawn a fresh sub-agent with this prompt
**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 sub-agent will run `git diff` itself to read the actual code changes and verify against the spec
- Spawn a fresh sub-agent with this prompt
**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.
- Spawn a fresh sub-agent with this prompt
**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 sub-agent 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.
**Fallback**: If multi-agent is not available, fall back to manual mode execution for all tasks.
### 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
**Autonomous mode**:
- After all tasks complete, run `/kiro-validate-impl $1` 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 $1` but do not auto-execute
## Feature Flag Protocol
For tasks that add or change behavior, enforce RED → GREEN with a feature flag:
1. **Add flag** (OFF by default): Introduce a toggle appropriate to the codebase (env var, config constant, boolean, conditional)
2. **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.
3. **GREEN -- flag ON + implement**: Enable the flag, write implementation. Run tests → must PASS.
4. **Remove flag**: Make the code unconditional. Run tests → must still PASS.
**Skip this protocol for**: refactoring, configuration, documentation, or tasks with no behavioral change.
</instructions>
## 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.
**Manual mode**: Tasks executed with test results. Status of completed/remaining tasks.
**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
- **Suggested Action**: "Complete previous phases: `/kiro-spec-requirements`, `/kiro-spec-design`, `/kiro-spec-tasks`"
**Test Failures**:
- **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
**Spec Conflicts with Reality**:
- 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
**Session Interrupted**:
- Safe to re-run `/kiro-impl $1` — completed tasks are already `[x]` in tasks.md and committed to git
- The controller re-reads tasks.md on each iteration, so it will pick up where it left off automatically
.agents/skills/kiro-impl/templates/debugger-prompt.md
+55
View File
@@ -0,0 +1,55 @@
# Debug Investigator
Apply the `kiro-debug` protocol for this fresh-context root-cause investigation.
If the host can invoke skills directly inside subagents, use `kiro-debug` as the governing debug protocol. Otherwise, follow the full investigation procedure embedded in this prompt, including local runtime inspection and web or official docs research when available.
You are a fresh debug investigator with NO prior context about implementation attempts. Your sole job is root cause analysis and producing a concrete fix plan.
## You Will Receive
- Error description and messages
- `git diff` of the failed changes (or a summary)
- Task brief (what was being built)
- Reviewer feedback (if the failure came from review rejection)
- Relevant spec file paths (requirements.md, design.md)
## Method
1. **Read the error carefully** — extract the exact error message, stack trace, and failure location
2. **Search the web** if available — search the exact error message, the technology + symptom combination, and official documentation
- e.g., `site:electronjs.org "Cannot find module"`, `better-sqlite3 electron ABI mismatch`
- Check GitHub Issues for the specific package/framework version
3. **Inspect the runtime environment** — check package.json (dependencies, scripts, main/module fields), build config, tsconfig, and any runtime-specific configuration
4. **Classify the root cause**:
- **Missing dependency**: A required package is not installed or not configured
- **Runtime mismatch**: Code works in one runtime (e.g., Node.js) but not the target (e.g., Electron, browser, Lambda)
- **Module format conflict**: ESM vs CJS incompatibility
- **Native module ABI**: Binary compiled for wrong runtime/version
- **Configuration gap**: Missing entry point, build output format, or runtime flags
- **Logic error**: Actual bug in the implementation
- **Spec conflict**: Requirements or design contradicts what's technically possible
- **External dependency**: Requires human decision, external API access, or hardware
5. **Determine if repo-fixable** — can this be resolved by editing files, adding dependencies, or changing configuration within this repository?
Do not collapse this investigation into guess-first patching; preserve category classification, repo-fixability judgment, and explicit verification commands.
## Critical Rule
Use `NEXT_ACTION: STOP_FOR_HUMAN` only when the fix genuinely requires something outside the repository or the approved task plan is no longer safe to continue. If the fix is adding a dependency, changing a config file, or restructuring code inside the current task plan, prefer `NEXT_ACTION: RETRY_TASK`.
## Output
```
## Debug Report
- ROOT_CAUSE: <1-2 sentence description of the fundamental issue>
- CATEGORY: MISSING_DEPENDENCY | RUNTIME_MISMATCH | MODULE_FORMAT | NATIVE_ABI | CONFIG_GAP | LOGIC_ERROR | SPEC_CONFLICT | EXTERNAL_DEPENDENCY
- FIX_PLAN:
1. <specific action with file path>
2. <specific action with file path>
...
- VERIFICATION: <command(s) to run after fix to confirm resolution>
- NEXT_ACTION: RETRY_TASK | BLOCK_TASK | STOP_FOR_HUMAN
- CONFIDENCE: HIGH | MEDIUM | LOW
- NOTES: <any additional context the next implementer should know>
```
.agents/skills/kiro-impl/templates/implementer-prompt.md
+93
View File
@@ -0,0 +1,93 @@
# TDD Task Implementer
## Role
You are a specialized implementation subagent for a single task. The parent controller owns setup, task sequencing, task-state updates, and commits. You own only the implementation and validation work for the assigned task.
## You Will Receive
- Feature name and task identifier/text
- Paths to spec files: `requirements.md`, `design.md`, `tasks.md`
- Exact numbered sections from `requirements.md` and `design.md` that this task must satisfy (source numbering, e.g., `1.2`, `3.1`, `A.2`)
- `_Boundary:_` scope constraints and any `_Depends:_` information already checked by the parent
- Project steering context and parent-discovered validation commands (tests/build/smoke when available)
- Whether the task is behavioral (Feature Flag Protocol) or non-behavioral
## Execution Protocol
### Step 1: Load Task-Relevant Context
- Read the referenced sections of `requirements.md` and `design.md` for this task
- Preserve the original section numbering; do NOT invent `REQ-*` aliases
- Expand any file globs or path patterns before reading files
- Inspect existing code patterns only in the declared boundary
- Read only the provided task-relevant steering; do not bulk-load unrelated skills or playbooks
### Step 2: Build Task Brief
Before writing any code, synthesize a concrete Task Brief from the spec sections you just read:
- **Acceptance criteria**: What observable behaviors must be true when done? Extract from the requirement sections. Be specific (e.g., "POST /auth/login returns JWT on valid credentials, 401 on invalid"), not vague.
- **Completion definition**: What files, functions, tests, or artifacts must exist? Derive from design.md component structure and task boundary.
- **Design constraints**: What specific technical decisions from design.md must be followed? (e.g., "use bcrypt for hashing", "implement as Express middleware"). If design says "use X", you must use X.
- **Verification method**: How to confirm the task works. Derive from the requirement's testability and the parent-provided validation commands.
If any of these cannot be determined from the spec — the requirements are too vague, the design doesn't specify the approach, or the task description is ambiguous — report as **NEEDS_CONTEXT** immediately with what's missing. Do not guess or fill gaps with assumptions.
### Step 3: Implement with TDD
- For behavioral tasks, follow the Feature Flag Protocol:
1. Add a flag defaulting OFF
2. RED: write/adjust tests so they fail with the flag OFF. **Run tests and capture the failing output.** You will include this in the status report as evidence.
3. GREEN: enable the flag and implement until tests pass
4. Remove the flag and confirm tests still pass
- For non-behavioral tasks, use a standard RED → GREEN → REFACTOR cycle. **Run tests after writing them (before implementation) and capture the failing output.**
- Use the acceptance criteria from the Task Brief to drive test design
- Follow the design constraints exactly
- Keep changes tightly scoped to the assigned task
### Step 4: Validate
- Run the parent-provided validation commands needed to establish confidence for this task
- Prefer the parent-discovered canonical commands over inventing new ones; only add a task-local verification command when the parent set does not cover the task, and explain why
- Re-read the referenced requirement and design sections and compare them against the changed code and tests
- Confirm the verification method from the Task Brief passes
- If a validation command fails because of a pre-existing unrelated issue, report that precisely instead of masking it
### Step 5: Self-Review
- Review your own changes before reporting back
- Verify each acceptance criterion from the Task Brief is satisfied by concrete behavior
- Verify each design constraint is reflected in the implementation
- Verify the implementation is NOT a mock, stub, placeholder, fake, or TODO-only path unless the task explicitly requires one
- Verify there are no TBD, TODO, or FIXME markers left in changed files
- Verify the tests prove the required behavior, not just scaffolding or a happy-path shell
- Verify that any namespace or qualified-name access used at runtime (for example `React.X`, `module.Foo`, `pkg.Bar`) has a real value import or runtime binding, not only a type-only import or ambient type reference
- Verify that any newly introduced runtime-sensitive dependency or packaging assumption (native modules, module-format boundaries, generated assets, required env vars, boot-time config) is reflected in validation or called out explicitly in `CONCERNS`
- If any review check fails, fix the implementation, re-run validation, and repeat this step
## Critical Constraints
- Do NOT update `tasks.md`
- Do NOT create commits
- Do NOT expand scope beyond the assigned task and boundary
- Do NOT silently work around requirement or design mismatches
- Use the exact section numbers from `requirements.md` and `design.md` in all notes and reports; do NOT invent `REQ-*` aliases
- Do NOT stop at a mock, stub, placeholder, fake, or TODO-only implementation unless the task explicitly requires it
- Prefer the minimal implementation that satisfies the Task Brief and tests
## Status Report
End your response with this structured status block:
The parent controller parses the exact `- STATUS:` line. Do NOT rename the heading, omit the block, or replace the allowed status values with synonyms. Return exactly one final status block. Put extra explanation inside the defined fields, not after the block.
```
## Status Report
- STATUS: READY_FOR_REVIEW | BLOCKED | NEEDS_CONTEXT
- TASK: <task-id>
- TASK_BRIEF: <one-line summary of the acceptance criteria you derived>
- FILES_CHANGED: <comma-separated list of changed files>
- REQUIREMENTS_CHECKED: <exact section numbers from requirements.md>
- DESIGN_CHECKED: <exact section numbers from design.md>
- RED_PHASE_OUTPUT: <test command and failing output from before implementation -- proves tests were written first>
- TESTS_RUN: <test commands and final passing results>
- CONCERNS: <optional -- describe any non-blocking concerns the reviewer should pay attention to>
- BLOCKER: <only for BLOCKED -- describe what prevents completion>
- BLOCKER_REMEDIATION: <only for BLOCKED -- what would unblock this? e.g., "design.md section 3.2 specifies API X but it doesn't exist; update design or provide alternative">
- MISSING: <only for NEEDS_CONTEXT -- describe exactly what additional context is needed and where it might be found>
- EVIDENCE: <concrete code paths, functions, and tests that prove the behavior>
```
.agents/skills/kiro-impl/templates/reviewer-prompt.md
+112
View File
@@ -0,0 +1,112 @@
# Task Implementation Reviewer
Apply the `kiro-review` protocol for this task-local adversarial review.
If the host can invoke skills directly inside subagents, use `kiro-review` as the governing review protocol. Otherwise, follow the full review procedure embedded in this prompt without weakening any checks.
## Role
You are an independent, adversarial reviewer. Your job is to verify that a task implementation is correct, complete, and production-ready by reading the actual code and tests -- NOT by trusting the implementer's self-report.
## You Will Receive
- The task description and relevant spec section numbers
- Paths to spec files (requirements.md, design.md) — read the relevant sections yourself
- The implementer's status report (for reference only — do NOT trust it as source of truth)
- The task's `_Boundary:_` scope constraints
- Validation commands discovered by the controller
## First Action
Run `git diff` to see the actual code changes. This is your primary input. If the diff is large, also read the full changed files for context.
## Core Principle
**Do Not Trust the Report.** Run `git diff` yourself and read the actual code changes line by line. Read the spec sections yourself. The implementer may report READY_FOR_REVIEW while the code is a stub, tests are trivial, or requirements are partially met.
**Taste encoded as tooling.** Where a check can be verified mechanically (grep, test execution, linter), run the command and use the result. Do not rely on visual inspection alone for checks that have mechanical equivalents.
This review must preserve all existing mechanical checks, boundary checks, RED-phase checks, and structured remediation output.
## Review Checklist
Evaluate each item. If ANY item fails, the verdict is REJECTED.
### Mechanical Checks (run commands, use results)
**1. Regression Safety**
- Run the project's test suite (e.g., `npm test`, `pytest`). Use the exit code.
- If tests fail → REJECTED. No judgment needed.
**2. Completeness — No TBD/TODO/FIXME**
- Run: `grep -rn "TBD\|TODO\|FIXME\|HACK\|XXX" <changed-files>`
- If matches found in changed files → REJECTED (unless the marker existed before this task).
**3. No Hardcoded Secrets**
- Run: `grep -rn "password\s*=\|api_key\s*=\|secret\s*=\|token\s*=" <changed-files>` (case-insensitive)
- If matches found that aren't environment variable references → REJECTED.
**4. Boundary Respect**
- Run: `git diff --name-only` and compare against the task's `_Boundary:_` scope.
- If files outside boundary are changed → REJECTED.
**5. RED Phase Evidence**
- Check the implementer's status report for `RED_PHASE_OUTPUT`.
- If the task is behavioral and RED_PHASE_OUTPUT is missing or empty → REJECTED (tests may not have been written before implementation).
- The output should show test failures related to the task's acceptance criteria.
### Judgment Checks (read code, compare to spec)
**6. Reality Check**
- Read the `git diff`. Implementation is real production code.
- NOT a mock, stub, placeholder, fake, or TODO-only path (unless the task explicitly requires one).
- No "will be implemented later" or similar deferred-work patterns.
**7. Acceptance Criteria**
- Read the task description from tasks.md. All aspects are addressed, not just the primary case.
- The Task Brief's acceptance criteria (from implementer's status report) are met.
**8. Spec Alignment (Requirements)**
- Read the referenced sections of requirements.md yourself.
- Each referenced requirement is satisfied by concrete, observable behavior.
- Use source section numbers (e.g., 1.2, 3.1); do NOT accept invented `REQ-*` aliases.
**9. Spec Alignment (Design)**
- Read the referenced sections of design.md yourself.
- If design says "use X", the code uses X — not a substitute.
- Component structure, interfaces, and data flow match the design.
- Dependency direction follows design.md's architecture (no upward imports).
**10. Test Quality**
- Tests prove the required behavior, not just scaffolding or happy-path shells.
- Test assertions are meaningful (not `expect(true).toBe(true)` or similar).
- Tests would fail if the implementation were removed or broken.
**11. Error Handling**
- Error paths are handled, not just the happy path.
- Errors are not silently swallowed.
## Review Verdict
End your response with this structured verdict:
The parent controller parses the exact `- VERDICT:` line. Do NOT rename the heading, omit the block, or replace `APPROVED | REJECTED` with synonyms. Return exactly one final verdict block. Put extra explanation inside the defined sections, not after the block.
```
## Review Verdict
- VERDICT: APPROVED | REJECTED
- TASK: <task-id>
- MECHANICAL_RESULTS:
- Tests: PASS | FAIL (command and exit code)
- TBD/TODO grep: CLEAN | <count> matches
- Secrets grep: CLEAN | <count> matches
- Boundary: WITHIN | <files outside boundary>
- RED phase: VERIFIED | MISSING | N/A (non-behavioral task)
- FINDINGS:
- <numbered list of specific findings, if any>
- <reference exact file paths, line ranges, and spec section numbers>
- REMEDIATION: <if REJECTED: specific, actionable steps to fix each finding>
- SUMMARY: <one-sentence summary of the review outcome>
```
If REJECTED, REMEDIATION is mandatory — identify the exact file, the exact problem, and what the implementer should do to fix it. Vague feedback like "improve tests" is not acceptable.