dreamers-implement

name: dreamers-implement description: 'Implementation skill — runs one cycle against an approved plan. Writes failing tests, implements, runs tests, and exits at green tests with an AC coverage matrix. Does NOT review, push, or open a PR. Triggers: /dreamers-implement, implement this plan, execute the plan.' argument-hint: 'feature-/plan-NN-.md'

$ARGUMENTS

If no plan path was provided, halt + ask. Do not invent a plan.

Todo - Before you begin.

Declare a todo list marking all steps. at entry: Step 1 / Step 2 / Step 3 / Step 4 / Step 5 (review) / Step 6 (user test) / Step 7 (commit).

Step 1 — Read plan + write failing tests

Read the plan file. For each AC (G/W/T + *Layer: ...*), write at least one failing test at the annotated layer. Stage with git add. Don't run yet.

Step 2 — Implement

Edit production files per comment-rules + logging-discipline + testing-mandate (Kernel). Stage as you go.

Step 3 — Type-check + run tests

Run the project's type-check + test command (from .github/copilot-instructions.md). Fix inline (max 3 attempts) then halt.
Update ./test-benchmarks.md row after passing (if the project uses one).

Exit

AC coverage matrix, review summary. Next step: /dreamers-review if last cycle, otherwise another /dreamers-implement for next plan (or /dreamers-full for the wrapper).

Dreamers Kernel

# Dreamers Kernel

User overrides

Explicit user instructions can skip or alter phases/actions.

Subagent allowlist (HARD RULE)

Do not use any non-Dreamers agent unless explicitly authorized by user.

Subagent prompt — required content

Every task() invocation MUST include in the prompt:

Context — what this agent is being asked to do and why
Prior work — what was done previously, with absolute paths to any output files
What is needed — specific deliverable
Constraints — hard rules the agent must not violate
Definition of Done — how to know the work is complete
Plan file path — absolute path to the relevant plan file (if applicable)
Mandatory line: Do NOT call manage_todo_list. The skill that invoked you owns its todo.

All task() calls use mode: "sync" — the call blocks until the agent returns.

Implementation discipline

Plan adherence: edit only files in the plan's scope. No while-I'm-here cleanup, no unrelated refactors mixed with feature work.
No spec-arguing comments: never add a code comment that argues the spec permits a pattern.
Branch identity check: before the first edit, git log --oneline -3. Confirm the branch and recent commits match the expected feature. If not, halt and surface.
No dependency installs without permission. Don't run npm install, pip install, etc. without explicit user approval.
Type-check before declaring implementation done. Run the project's type-check command from .github/copilot-instructions.md and fix errors before moving on.

Commit trailer

Every commit body includes:

Co-authored-by: The Dreamers System

# Git Workflow (mandatory)

Every milestone uses a feature branch + PR — never work directly on the default branch.

Startup verification (do this FIRST)

Detect the repo's default branch:

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo "main")

Store $DEFAULT_BRANCH — use it everywhere main would have been used.

git fetch origin && git log origin/$DEFAULT_BRANCH --oneline -5 — anchor to remote truth before reading any .dreamers/ files. Workspace files are local-only and may be stale. origin/$DEFAULT_BRANCH is the authoritative record of what is actually shipped.

Branch setup (before invoking `/dreamers-implement`)

git checkout $DEFAULT_BRANCH && git pull origin $DEFAULT_BRANCH — never build off a stale local default branch.
Cut feat/<slug> from $DEFAULT_BRANCH.
Confirm .dreamers/ is in the project's .gitignore. If not, add it before any further edits.
No init commit — the first commit for the milestone is the first thing in the PR diff.

Commit discipline (non-negotiable)

Commit at end of each cycle — one commit per plan in the sequence (single-plan: one commit total; multi-plan: N commits, one per plan).
Commit before PR creation — a final commit capturing any last changes before opening the PR.
No auto-commit after PR is created — if changes are made after gh pr create, do NOT commit automatically. Ask the user first.

Push discipline (non-negotiable)

git push happens EXACTLY ONCE — immediately before gh pr create at final close-out. Never push after intermediate commits, between cycles, or at any other point in the pipeline.

Post-PR push discipline

If the user approves a post-PR commit, push with git push (no force). The PR will update automatically.

Commit structure (one commit per cycle)

Exactly one commit per plan/cycle, immediately after the reviewer findings have been applied and tests are green (and user testing, if required, is signed off).
The orchestrator stages changes with git add throughout the cycle but does not run git commit until the cycle ends.
Commit message format follows .github/instructions/git.instructions.md (if present). Pipeline-specific bits:
- Subject: feat: <plan-name> (or feat!: <plan-name> for breaking changes — see git.instructions.md for the breaking-change footer rule)

One commit per plan keeps each plan's contribution atomic. Reviewer-fix application is part of the same cycle (not separate commits).

What gets committed

Nothing in .dreamers/ is committed — all workspace files (plans, retros, improvements.md) are gitignored and stay local. Ensure .dreamers/ is in the project's .gitignore.

No worktrees

The orchestrator works directly on the feature branch. Unless explicitly requested by the user.

# Testing Coverage Mandate (MANDATORY)

Every plan must express its test coverage intent through the Acceptance Criteria's Layer annotations. The planner specifies what observable outcome the AC requires and which test layer covers it. The implementer (orchestrator at /dreamers-implement Step 1) writes the actual tests from each AC's Given/When/Then.

How test coverage is expressed in plans (new format)

Plan ACs are numbered Given/When/Then statements with a Layer annotation per AC. See plan-writing-guide.md § "Acceptance Criteria format" for the canonical spec.

<acceptance_criteria>
1. Given <state>, when <trigger>, then <observable outcome>.
   *Layer: unit.*
2. Given <state>, when <trigger>, then <observable outcome>.
   *Layer: integration.*
3. Given <state>, when <trigger>, then <observable outcome>.
   *Layer: E2E.*
</acceptance_criteria>

Layer label set (closed): unit / integration / E2E / perf. Compound labels allowed when one assertion serves two purposes (e.g., *Layer: integration / perf.*).

Test coverage intent is expressed via the *Layer: ...* annotation on each Acceptance Criterion — not via a standalone Test Cases section. Do not write a separate Test Cases section in a plan; embed the test layer directly in the AC. This keeps ACs and test specification in one place so they never drift.

Coverage requirement (every plan)

Across all of a plan's ACs, the layer mix must cover the following whenever applicable to the work — think through each layer explicitly:

Unit layer

Each significant function, method, or class in isolation.
All branches: happy path, edge cases (boundary values, empty/null/max), negative cases (invalid input, error states).
Any pure logic that does not require a real device, network, or database.

Integration layer

Interactions between layers: repository ↔ data source, ViewModel ↔ repository, service ↔ external API.
Database reads/writes (real or in-memory, not mocked).
Auth flows end-to-end within the backend.
Cloud function triggers and side-effects.

UI / E2E layer

Full user journeys through the UI: screen load → interaction → outcome visible on screen.
Navigation flows between screens.
Error and empty states rendered correctly in the UI.
Any flow that requires a real device or emulator.
Navigation change rule (mandatory): When a plan changes how a nav element behaves (tab tap, modal open, screen transition), the plan must include at least one AC with *Layer: E2E.* — not just unit/integration. Probe enforces this in the layer audit and blocks if missing.

Regression risks

Anything touching existing behavior that could break — call out the specific existing test or flow at risk in the plan's Context section.

If a layer cannot be covered automatically (e.g., camera permission flows), flag it explicitly as a manual-verification requirement in the plan's Verification section with a reason.

Probe's layer audit (consumes the new format)

During the full-pipeline review lane that includes Probe, the layer audit reads each AC's *Layer: ...* annotation to verify coverage at each layer was implemented. Probe blocks the cycle if any AC's annotated layer lacks a corresponding green test.

Test benchmarks

Each project that uses /dreamers-implement maintains a ./test-benchmarks.md file at the project root. The file records measured run times per test command so the orchestrator can set realistic timeouts.

File path: ./test-benchmarks.md at the project root (committed to version control).
Recommended-timeout formula: max(last_run_time × 2, 30s) — the 2× multiplier accounts for machine variance; 30s is a non-negotiable floor.
Orchestrator updates the row for each test command after every successful test run. Humans may edit the Notes column to capture CI environment factors or known flakiness.
Template: .github/dreamers/templates/test-benchmarks.md (catalog-relative; resolves to ~/.copilot/dreamers/templates/test-benchmarks.md at install).

# Comment Rules

Core principle

Comments must add value that the code cannot express itself. Concise, no fluff, no separators — value only.

When to comment

Non-obvious logic: why a non-obvious approach was chosen, constraints, gotchas
Public API documentation callers need to use the interface correctly
TODO/FIXME with specific, actionable notes
License headers

When NOT to comment

Code that reads naturally from well-named functions and variables
Anything that restates what the code obviously does (const isRunning does not need // tracks whether running)

Strict prohibitions

No plan/ticket references — never mention plan files, milestone names (D25, plan-3), ticket numbers, or agent names in source code
No separator comments — never use // ---, // ===, // ###, blank-comment lines, or visual dividers
No spec rationalization — never write comments arguing a spec permits a pattern; implement cleanly and let review judge
No redundant JSDoc/KDoc that only repeats the function signature
No em dashes. no exceptions

Style

One line when possible; never exceed two lines for inline comments
Write why, never what
If a comment requires more than two lines to be useful, the code needs refactoring, not more words

# Logging Discipline

Rules for log calls — what to write, what to flag in review.

Project rule first. If .github/instructions/logging.instructions.md exists, it is the binding spec.
Else: match surrounding code. Existing log calls in the same module and nearest neighbors define:
- Logger library / import path (do not introduce a new logger where one already exists).
- Level conventions in use (ERROR / WARN / INFO / DEBUG, or whatever the codebase uses).
- Message format (structured fields vs interpolated strings, key names, casing).
Never log: secrets, tokens, PII, full request/response bodies. No exceptions.
Neither rule yields a clear answer → raise an open question via request_information rather than guessing.

Do not add log calls outside the plan's scope as while-I'm-here cleanup. If the plan does not call for new logging, leave existing logging untouched unless a finding requires a change.

# Agent Failure Recovery (mandatory)

When a spawned agent hits a rate limit, crashes, or times out mid-run:

Read whatever workspace files the agent managed to write before failing.
Determine which steps completed and which remain (check workspace outputs, git log, test results).
Complete remaining steps directly (you have Read, Write, Edit, Glob, Grep, Bash in the main conversation) or re-spawn the agent scoped to only the remaining work.
Do not re-run steps that already completed — build on partial progress.