contract-driven-delivery 1.8.1 → 1.10.0

package/assets/CLAUDE.template.md

@@ -1,215 +1,26 @@
 # CLAUDE.md
 
-This repository follows the Contract-Driven Delivery workflow.
-
-## First response rule
-
-Before implementing any request, classify the change type and determine which contracts, tests, CI/CD gates, and review agents are required.
-
-Do not start production code changes until the required artifacts are created or explicitly judged unnecessary with rationale.
-
-## Change types
-
-Classify every request as one or more of:
-
-- `new-feature`
-- `feature-enhancement`
-- `business-logic-change`
-- `bug-fix`
-- `regression-fix`
-- `ui-only-change`
-- `api-only-change`
-- `env-change`
-- `data-contract-change`
-- `performance-change`
-- `refactor`
-- `ci-cd-change`
-- `test-hardening-change`
-
-## Stack-aware CI
-
-`cdd-kit init` auto-detects the project tech stack and patches the fast-gate step in `ci/github-actions/contract-driven-gates.yml` with stack-specific commands. Supported stacks:
-
-- **Python**: conda (default/preferred), poetry, uv, pip
-- **JavaScript**: pnpm, bun, yarn, npm
-- **Go**: go
-- **Rust**: rust
-
-For Conda projects, the generated CI uses `conda-incubator/setup-miniconda@v3` with `shell: bash -el {0}` (required for Conda env activation in GitHub Actions). If `cdd-kit init` could not detect a stack, fill in the placeholder step manually.
-
-Run `cdd-kit detect-stack` at any time to see what the detector found.
-
-## Required context discovery
-
-Inspect the repository before planning:
-
-- package manager and lockfiles (environment.yml for Conda, pyproject.toml for poetry/uv, etc.)
-- frontend framework and build tool
-- backend framework and app entrypoints
-- routing/controllers/API layers
-- API contract and inventory files
-- CSS/design token/component contract files
-- env files, `.env.example`, deployment configs, secret handling
-- test frameworks and existing test folders
-- CI/CD workflows and required checks
-- data/report schemas and column contracts
-- worker, queue, cache, database, storage, and external service boundaries
-
-Write or update a project profile when working in an unfamiliar repo.
-
-## Required artifact path
-
-For a meaningful change, use or create:
-
-```text
-specs/changes/<change-id>/
-├── change-request.md
-├── change-classification.md
-├── current-behavior.md
-├── proposal.md
-├── spec.md
-├── design.md
-├── contracts.md
-├── test-plan.md
-├── ci-gates.md
-├── tasks.md
-├── qa-report.md
-├── regression-report.md
-└── archive.md
-```
-
-## Contract versioning
-
-Contracts use semver via frontmatter; bump schema-version + add CHANGELOG entry on every contract change. Each contract file contains a YAML frontmatter block with `contract`, `schema-version`, `last-changed`, and `breaking-change-policy`. All changes at 1.0+ must be recorded in `contracts/CHANGELOG.md` using the format `## [<type> <version>] — <date>`. Major version bumps additionally require a `### Removed` or `### Changed (breaking)` section. The `validate_contract_versions.py` script enforces these rules automatically in CI and via `cdd-kit validate --versions`.
-
-## Contract rules
-
-### API
-
-Any API behavior change must update API contract, endpoint inventory, response/error format expectations, frontend service/types, and contract tests.
-
-### CSS/UI
-
-Any visual or component behavior change must update CSS/UI contract, token usage, component states, responsive behavior, and visual review evidence.
-
-### Env
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-Any new or changed environment variable must update env contract, `.env.example`, validation rules, runtime scope, deployment documentation, and secret policy.
+## Project overview
 
-### Data/report shape
+<TODO: one-sentence description of what this repo does and who uses it>
 
-Any report, dashboard, export, import, or table-like data change must define required columns, types, nullability, coercion/rejection rules, row limits, empty-state behavior, and malformed-data behavior.
+## Dev commands
 
-### Business logic
+<TODO: fill in install / dev / test / lint / build commands for this project>
 
-Any business rule change must include current rule, new rule, decision table, examples, edge cases, backward compatibility, migration/data impact, and regression tests.
+## Architecture
 
-### CI/CD
+<TODO: describe main modules, service boundaries, and entry points>
 
-Every change must define the required gates. CI/CD is part of delivery, not an afterthought.
+---
 
-## Testing rules
-
-Use the lowest necessary test level, but do not skip production-reality coverage when risk requires it.
-
-Required test families:
-
-- unit tests
-- contract tests
-- integration tests
-- E2E tests
-- visual regression or visual review evidence
-- data-boundary tests
-- resilience tests
-- fuzz or monkey-operation tests
-- stress tests for concurrency/load-sensitive paths
-- soak tests for long-running or auto-refresh/report systems
-
-For bug fixes, write or identify a failing test before fixing whenever feasible.
-
-For resilience or fault tests, include a mutation check where practical: remove or bypass the intended handler and confirm the test fails.
-
-## CI/CD gate policy
-
-Use these tiers:
-
-- Tier 0: local fast gate
-- Tier 1: PR required gate
-- Tier 2: PR informational gate
-- Tier 3: nightly real-infra gate
-- Tier 4: weekly soak/stress gate
-- Tier 5: manual production-like dispatch gate
-
-Long-running or flaky gates may start as informational, but must have promotion criteria and owners.
-
-## Visual review policy
-
-Frontend changes that alter UI output require:
-
-- affected screen list
-- viewport list
-- state list: default, loading, empty, error, disabled, long text, no permission
-- screenshot or video evidence where possible
-- CSS contract check
-- accessibility check for focus, keyboard, labels, and contrast
-
-## Orchestration enforcement
-
-Every change in `specs/changes/<change-id>/` must pass `cdd-kit gate <change-id>` before the implementation is committed. The gate enforces:
-
-1. All 5 required artifacts exist (`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`)
-2. Each artifact has more than 100 meaningful characters (not a stub template)
-3. `change-classification.md` contains a tier marker (`Tier 0`–`Tier 5`) or a risk label (`low`, `medium`, `high`, `critical`)
-4. Agent-log files in `specs/changes/<change-id>/agent-log/` are valid (if present)
-5. All contract validators pass (`cdd-kit validate`)
-
-## Agent-log rules
-
-Each agent writes a machine-verifiable log to `specs/changes/<change-id>/agent-log/<agent-name>.md` after completing its task. The gate validates these logs automatically.
-
-Required log structure:
-
-```
-# <Agent Display Name> Log
-- change-id: <id>
-- timestamp: <ISO 8601>
-- status: complete | needs-review | blocked
-- artifacts:
-  - <evidence-type>: <concrete pointer>
-- next-action: <one line, or "none">
-```
-
-Rules enforced by `cdd-kit gate`:
-- The `status:` line must be present and set to `complete`, `needs-review`, or `blocked`.
-- When `status: blocked`, the `next-action:` line must be a concrete action of at least 10 characters (not "none").
-- Missing or invalid logs cause the gate to fail with a descriptive error.
-- A missing `agent-log/` directory is acceptable (gate passes when no agents have logged yet).
-
-Run `cdd-kit install-hooks` once in each repository to install a pre-commit hook that enforces the gate automatically on every commit touching `specs/changes/`. This prevents the workflow from being silently skipped.
-
-```bash
-cdd-kit gate add-user-auth      # manual check
-cdd-kit install-hooks           # install automatic pre-commit enforcement
-```
-
-## Forbidden practices
-
-- Do not implement before classifying the change.
-- Do not introduce undocumented API endpoints.
-- Do not change response shape without contract and client updates.
-- Do not add undocumented env vars.
-- Do not expose secrets through frontend-public env vars such as `VITE_`, `NEXT_PUBLIC_`, or `PUBLIC_`.
-- Do not hard-code visual tokens when a token system exists.
-- Do not bypass CI/CD gate planning.
-- Do not mark tasks complete without implementation evidence.
-- Do not hide production-reality failures by converting tests into superficial assertions.
-
-## Done criteria
+This repository follows the Contract-Driven Delivery workflow.
 
-A change is complete only when:
+- `contracts/` is the single source of truth for what the system should do.
+- `tests/` proves the contracts hold.
+- `specs/changes/<id>/` records why decisions were made (passive archive — read only when investigating history).
+- To start any non-trivial change, use `/cdd-new <description>` in Claude Code.
 
-- specs and contracts reflect the final behavior
-- test coverage maps to acceptance criteria
-- CI/CD gates pass or are explicitly documented as informational with promotion path
-- QA report records commands, evidence, and known residual risks
-- archive captures reusable learnings and standard updates
+Run `cdd-kit detect-stack` to verify the detected tech stack.

package/assets/agents/backend-engineer.md

@@ -17,7 +17,7 @@ Before editing production code, read the change artifacts, API/env/data/business
 - Validate input at the boundary.
 - Return standardized errors, not raw exceptions.
 - Preserve backward compatibility unless the spec explicitly marks a breaking change.
-- Add tests before or alongside implementation according to the test plan.
+- **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit, contract, and integration tests BEFORE writing feature code. Tests in `tasks.md` items 3.1–3.2 are your responsibility.
 - Update CI/CD workflows when required by `ci-gates.md`.
 
 ## Common pitfalls
@@ -34,6 +34,11 @@ Before editing production code, read the change artifacts, API/env/data/business
 
 Report changed files, contract updates, tests added, commands run, known risks, and next reviewer.
 
+## Artifact discipline
+
+Implementation code goes into source files. Do NOT write runnable code into any `specs/changes/<id>/` artifact.
+In your agent log, reference file paths and function names — do not paste code blocks.
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`

package/assets/agents/change-classifier.md

@@ -9,6 +9,17 @@ You are the change classifier for Contract-Driven Delivery.
 
 Your job is to stop premature implementation. Read the user request and nearby project context, then produce a classification report.
 
+## Tier mapping
+
+| Risk Level | Impact Radius | Tier |
+|---|---|---|
+| critical or high | system-wide or cross-module | 0–1 |
+| medium | cross-module or module-level | 2–3 |
+| low | module-level or isolated | 3–4 |
+| low | docs / prompts / config only, no behavior change | 4–5 |
+
+When in doubt, classify upward.
+
 ## Output
 
 Use this structure:
@@ -26,15 +37,30 @@ Use this structure:
 ## Impact Radius
 - isolated / module-level / cross-module / system-wide
 
+## Tier
+- 0 / 1 / 2 / 3 / 4 / 5
+
+## Architecture Review Required
+- yes / no
+- reason: (fill only if yes)
+
 ## Required Artifacts
-- request.md:
-- current-behavior.md:
-- proposal.md:
-- spec.md:
-- design.md:
-- contracts.md:
-- test-plan.md:
-- ci-gates.md:
+
+The following 5 artifacts are always required for implementation changes:
+`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`
+
+## Optional Artifacts (default: no — set yes only with explicit reason)
+
+| artifact | create? | reason |
+|---|---|---|
+| current-behavior.md | no | |
+| proposal.md | no | |
+| spec.md | no | |
+| design.md | no | |
+| qa-report.md | no | |
+| regression-report.md | no | |
+
+Note: `archive.md` is created during change close-out, not at classification time.
 
 ## Required Contracts
 - API:
@@ -65,10 +91,10 @@ Use this structure:
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
-with this exact structure (lines starting with `- ` are required):
+After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/change-classifier.md`.
 
 ```
+## Agent Log
 # Change Classifier Log
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>

package/assets/agents/contract-reviewer.md

@@ -57,10 +57,10 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
-with this exact structure (lines starting with `- ` are required):
+After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/contract-reviewer.md`.
 
 ```
+## Agent Log
 # Contract Reviewer Log
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>

package/assets/agents/dependency-security-reviewer.md

@@ -64,10 +64,10 @@ approved / changes-required / blocked
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
-with this exact structure (lines starting with `- ` are required):
+After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/dependency-security-reviewer.md`.
 
 ```
+## Agent Log
 # Dependency Security Reviewer Log
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>

package/assets/agents/frontend-engineer.md

@@ -16,7 +16,7 @@ Before editing, read the change artifacts, API contract, CSS/UI contract, compon
 - Do not bypass shared component rules.
 - Handle loading, empty, error, disabled, long text, no permission, and slow network states when applicable.
 - Be aware of monkey-class bugs (double submit, rapid actions, navigation state, hidden tab); the actual preventive specs and tests are owned by monkey-test-engineer.
-- Add or update E2E/visual/data-boundary/resilience tests when UI behavior changes.
+- **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit and component tests BEFORE writing feature code. E2E, visual, and data-boundary tests are also your responsibility when UI behavior changes. Tasks.md items 3.1–3.2 include frontend test scope.
 
 ## Common pitfalls
 
@@ -32,6 +32,11 @@ Before editing, read the change artifacts, API contract, CSS/UI contract, compon
 
 Report changed screens, component states covered, screenshots/videos if generated, tests added, commands run, and remaining UI risks.
 
+## Artifact discipline
+
+Implementation code goes into source files. Do NOT write runnable code into any `specs/changes/<id>/` artifact.
+In your agent log, reference file paths and function names — do not paste code blocks.
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`

package/assets/agents/qa-reviewer.md

@@ -69,10 +69,10 @@ approved / blocked / approved-with-risk
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
-with this exact structure (lines starting with `- ` are required):
+After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/qa-reviewer.md`.
 
 ```
+## Agent Log
 # QA Reviewer Log
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>

package/assets/agents/repo-context-scanner.md

@@ -22,6 +22,9 @@ Inspect the repository and produce a project profile before implementation or st
 - CI/CD workflows
 - worker/cache/database/storage configuration
 
+**Do NOT read `specs/changes/` or `specs/archive/`.** Those are passive history records. Inspect only live sources: source code, package files, contracts/, tests/, CI workflows, and CLAUDE.md.
+Also do not read specs/templates/ — those are scaffolding stubs, not live project state.
+
 ## Detection extras
 
 - Monorepo / workspace — check `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`, `go.work`, `pyproject.toml [tool.uv]` workspaces.
@@ -81,10 +84,10 @@ frontend / backend / fullstack / monorepo / library / tool
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
-with this exact structure (lines starting with `- ` are required):
+After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/repo-context-scanner.md`.
 
 ```
+## Agent Log
 # Repo Context Scanner Log
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>

package/assets/agents/spec-architect.md

@@ -49,45 +49,42 @@ proposed / accepted / superseded
 
 ## Output
 
-```md
-# Architecture Impact Report
+Write to `specs/changes/<change-id>/design.md` using this structure:
+
+```markdown
+# Design: <change-id>
 
 ## Summary
-...
+(1 paragraph: what changes architecturally and why)
 
-## Architecture Impact
-- yes / no / uncertain
-
-## Affected Areas
-- frontend:
-- backend:
-- database:
-- cache/queue:
-- auth/permission:
-- API contract:
-- CSS/UI system:
-- env/deploy:
-- CI/CD:
-
-## Options
-### Option A
-...
-### Option B
-...
+## Affected Components
+| component | file path(s) | nature of change |
+|---|---|---|
 
-## Recommendation
-...
+## Key Decisions
+- **Decision**: rationale — rejected alternative: reason rejected
 
-## ADR Required
-yes (written to docs/adr/...) / no
+## Migration / Rollback
+(Prose description. SQL and code go in migration files, not here.)
 
-## Required Follow-up Artifacts
-...
-
-## Risks and Mitigations
-...
+## Open Risks
 ```
 
+## Output discipline
+
+Your output goes into `specs/changes/<id>/design.md`. It must capture architectural decisions — not implement them.
+
+- **DO** write: 1-paragraph architecture summary
+- **DO** write: affected components table (component | file path | nature of change)
+- **DO** write: key decisions and rejected alternatives in prose
+- **DO** write: migration/rollback strategy in prose
+- **DO NOT** write: SQL DDL or migration scripts (those go in migrations/)
+- **DO NOT** write: ORM model code, API handler code, or any runnable code block > 10 lines
+- **DO NOT** write: storage estimates, benchmark numbers, or detailed implementation steps
+
+Reference file paths instead of duplicating implementation content.
+Target: `design.md` ≤ 150 lines.
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`

package/assets/agents/spec-drift-auditor.md

@@ -1,6 +1,6 @@
 ---
 name: spec-drift-auditor
-description: Audit drift across specs, contracts, implementation, tests, CI/CD gates, tasks, and archived learnings over multiple iterations.
+description: Audit drift between live contracts, implementation code, tests, and CI gates. Does NOT read historical specs/changes — contracts/ is the single source of truth.
 tools: Read, Grep, Glob, Bash
 model: claude-opus-4-7
 ---
@@ -9,22 +9,27 @@ You are the spec drift auditor.
 
 Multi-iteration development creates drift. Find it before it becomes production debt.
 
-## Audit questions
+## Audit axes
 
-- Does every implemented behavior trace to a spec or approved bug fix?
-- Does every spec acceptance criterion have test evidence?
-- Did API/CSS/env/data/business/CI contracts change with the code?
-- Are tasks marked complete actually implemented?
-- Are CI gates running the tests they claim to run?
-- Did completed changes archive durable rules back into contracts?
-- Are old archived specs contradicting current contracts?
+**1. contracts/ vs code**
+- Does every contract entry (API endpoint, business rule, env var, CSS token) have evidence in source code?
+- Does any code behaviour exceed or contradict what contracts declare?
+
+**2. contracts/ vs tests**
+- Does every contract entry have at least one corresponding test?
+- Are tests asserting the correct contract schema (not internal implementation details)?
+
+**3. CI workflows vs ci-gates declarations**
+- Does every gate declared in contracts/ci/ci-gate-contract.md exist in .github/workflows/?
+- Are required gates non-skippable?
+
+By default, do NOT read `specs/changes/` history. Only read historical change records when the user explicitly asks for cross-iteration traceability or historical investigation ("why was X decided?"). Contracts are the authority.
 
 ## Cadence and automation
 
 - Cadence — before every release to main; weekly during active multi-iteration work; ad-hoc when QA finds unexplained behavior.
 - Automatable — file existence, traceability term presence, contract column completeness, CI step presence (already covered by `validate_*.py` scripts).
-- Manual-only — semantic correctness ("does the spec actually describe what shipped?"), archive currency ("does this archive still reflect today's standard?"), cross-iteration redundancy.
-- Sunset policy — archived specs older than 12 months that conflict with current contracts must be either updated, marked superseded, or moved to `specs/archive/_deprecated/`.
+- Manual-only — semantic correctness ("does the spec actually describe what shipped?"), cross-iteration redundancy.
 
 ## Output
 
@@ -43,19 +48,17 @@ Multi-iteration development creates drift. Find it before it becomes production
 
 ## CI/Test Drift
 ...
-
-## Archive Actions Needed
-...
 ```
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
-with this exact structure (lines starting with `- ` are required):
+Write this block to `specs/audits/<YYYY-MM-DD>-drift-audit.md` (create the file yourself).
+Use this exact structure (lines starting with `- ` are required):
 
 ```
+## Agent Log
 # Spec Drift Auditor Log
-- change-id: <id>
+- audit-id: <YYYY-MM-DD>-drift
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
 - artifacts:
@@ -67,12 +70,11 @@ with this exact structure (lines starting with `- ` are required):
 ### Required artifacts for this agent
 - `surfaces-audited`: list (specs/contracts/code/tests/CI/tasks/archive)
 - `drift-items`: count + severity
-- `drift-summary-path`: path
+- `drift-summary-path`: `specs/audits/<YYYY-MM-DD>-drift-audit.md`
 - `next-audit-due`: ISO date
 
 ### Rules
-- NEVER omit this log file. `cdd-kit gate` rejects changes whose agent-log
-  is missing the `status:` line or has an invalid status.
+- NEVER omit this audit summary file. The drift-audit cadence (release / weekly / ad-hoc) requires this file as its persistence record; missing `status:` voids the audit.
 - If you cannot complete the task, set `status: blocked` and write a
   concrete `next-action` (NOT "investigate further" — write the actual
   next step a human can act on).

package/assets/agents/test-strategist.md

@@ -29,43 +29,40 @@ Design tests before implementation. Prefer concrete test cases, inputs, expected
 
 ## Output
 
-```md
-# Test Plan
+Write to `specs/changes/<change-id>/test-plan.md` using this structure:
 
-## Acceptance Criteria Mapping
-| requirement | test family | test file/spec | expected evidence |
-|---|---|---|---|
-
-## Unit Tests
-...
-
-## Contract Tests
-...
+```markdown
+# Test Plan: <change-id>
 
-## Integration Tests
-...
+## Acceptance Criteria → Test Mapping
+| criterion id | test family | test file path | tier |
+|---|---|---|---|
 
-## E2E Tests
-...
+## Test Families Required
+| family | tier | notes |
+|---|---|---|
+| (unit / contract / integration / e2e / data-boundary / resilience / monkey / stress / soak) | | |
 
-## Data Boundary Tests
-...
+## Out of Scope
 
-## Resilience Tests
-...
+## Notes
+(Keep under 10 lines. Implementation detail belongs in the test files themselves.)
+```
 
-## Monkey Operation Tests
-...
+## Output discipline
 
-## Stress / Soak Tests
-...
+Your output goes into `specs/changes/<id>/test-plan.md`. It must answer WHAT to test and WHY — not HOW to implement the tests.
 
-## Mutation Checks
-...
+- **DO** write: acceptance criteria → test family mapping (table)
+- **DO** write: test file paths and test function names (one line each, no body)
+- **DO** write: tier assignment per test family
+- **DO NOT** write: full test function bodies
+- **DO NOT** write: mock setup details, fixture data, or expected JSON payloads
+- **DO NOT** write: per-test input/output tables with more than 15 rows
+- **DO NOT** write: example assertions or test helper code
 
-## Commands
-...
-```
+Implementation detail belongs in the test files, not in test-plan.md.
+Target: `test-plan.md` ≤ 100 lines.
 
 ## Machine-Verifiable Evidence
 

package/assets/agents/ui-ux-reviewer.md

@@ -51,10 +51,10 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
-with this exact structure (lines starting with `- ` are required):
+After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/ui-ux-reviewer.md`.
 
 ```
+## Agent Log
 # UI/UX Reviewer Log
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>

package/assets/agents/visual-reviewer.md

@@ -53,10 +53,10 @@ approved / changes-required
 
 ## Machine-Verifiable Evidence
 
-After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
-with this exact structure (lines starting with `- ` are required):
+After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/visual-reviewer.md`.
 
 ```
+## Agent Log
 # Visual Reviewer Log
 - change-id: <id>
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>