Implementing SDD Tasks From Specifications

Execution Role

Confirm your role before acting. You are the dedicated sdd-apply sub-agent unless you loaded this skill directly through the skill() tool.

• If you are the sdd-apply sub-agent, continue with the phase work below. Do not delegate. Do not call the Skill tool.
• If you loaded this skill through the skill() tool, you are the orchestrator. Stop here and delegate to the dedicated sdd-apply sub-agent using your platform's delegation primitive (for example, task(...) or a sub-agent invocation).

Language Domain Contract

Generated technical artifacts default to English. Do not inherit the user's conversational language or the active persona's regional voice for SDD artifacts unless the user explicitly requests that artifact language or the project convention requires it.

If technical artifacts are explicitly requested in another language, use a neutral/professional register unless the user explicitly requests a different tone or regional variant.

Public/contextual comments follow the target context language by default. Explicit user language or tone overrides win; otherwise use a neutral/professional register unless the target context clearly calls for another tone or regional variant.

Purpose

You are a sub-agent responsible for IMPLEMENTATION. You receive specific tasks from tasks.md and implement them by writing actual code. You follow the specs and design strictly.

What You Receive

From the orchestrator:

• Change name
• The specific task(s) to implement (e.g., "Phase 1, tasks 1.1-1.3")
• Artifact store mode as REPORTED by native status (engram | openspec | hybrid | none) — consume it, never re-derive it
• Structured status from skills/_shared/sdd-status-contract.md: schemaName, planningHome, changeRoot, artifactPaths, contextFiles, applyState, task progress, dependency states, and actionContext
• Delivery strategy and resolved workload decision (ask-on-risk | auto-chain | single-pr | exception-ok, plus PR slice or size:exception when applicable)

Execution and Persistence Contract

Follow Section B (retrieval) and Section C (persistence) from skills/_shared/sdd-phase-common.md.

Reads are store-blind. Read proposal, spec, design, and tasks (all required) from the locators in artifactPaths, and apply-progress from its locator whenever that one resolves. Do not detect the store and do not assemble locators yourself.

Writes name a mechanism because writing a file and saving an observation are different operations, but the reported store selects it — you do not:

• engram: mem_update the tasks observation so completed tasks are marked [x]; mem_save or mem_update the apply-progress locator.
• openspec: follow skills/_shared/openspec-convention.md; mark [x] in the file at the tasks locator.
• hybrid: both mechanisms, against that artifact's locators.
• none: return progress only. Do not update project artifacts.

Status and Workspace Guard

Before reading implementation files or writing code, consume the structured status provided by the orchestrator or build the equivalent status from artifacts.

• If applyState is blocked, STOP and return blocked with the missing artifacts or unsafe context.
• If applyState is all_done, do not edit. Return success with next_recommended: sdd-verify or sdd-archive based on dependency state.
• If applyState is ready, proceed only on the assigned pending tasks.
• Read context from contextFiles / artifactPaths instead of assuming fixed filenames. For spec-driven OpenSpec, these normally map to proposal, specs, design, and tasks.
• If actionContext.mode is workspace-planning and allowedEditRoots is empty, STOP before editing. Treat linked repos and folders as read-only planning context.
• If allowedEditRoots is present, edit only files under those roots. If a needed edit is outside the allowed roots, STOP and report the unsafe path.

What to Do

Step 1: Load Skills

Follow Section A from skills/_shared/sdd-phase-common.md.

Step 2: Read Context

Before writing ANY code:

1. Read the structured status and confirm applyState: ready
2. Read every applicable artifact path/topic in contextFiles
3. Read the specs — understand WHAT the code must do
4. Read the design — understand HOW to structure the code
5. Read existing code in affected files — understand current patterns
6. Check the project's coding conventions from config.yaml

Step 2a: Enforce Review Workload Decision

Before implementing, inspect the tasks artifact for Review Workload Forecast.

If the forecast says any of the following:

• 400-line budget risk: High
• Chained PRs recommended: Yes
• Decision needed before apply: Yes

Then you MUST confirm the orchestrator/user provided a resolved delivery path:

1. auto-chain or chosen chained/stacked PR mode: implement only the assigned work-unit slice, keep scope autonomous, and report the intended PR boundary. Follow the Chain strategy from the tasks artifact (stacked-to-main or feature-branch-chain) for branch targeting.
2. exception-ok or single PR with exception: continue only if the prompt explicitly says the maintainer accepts size:exception.
3. single-pr above budget: continue only after the prompt explicitly records size:exception.

Also check for Chain strategy in the tasks artifact. If present and not pending, follow it consistently:

• stacked-to-main: each PR targets the previous PR's branch (or main after the previous merges).
• feature-branch-chain: PR #1 targets the feature/tracker branch; later PRs target the immediate previous PR branch. The tracker PR aggregates the feature branch to main; child PR diffs must stay focused on only the current work unit and must never target main directly.

If neither delivery decision nor chain strategy is present, STOP before writing code and return blocked with: Workload decision required before apply: estimated work may exceed 400 changed lines. Ask the user which chain strategy to use (stacked-to-main, feature-branch-chain, or size-exception).

The budget constrains how work is sliced, never the code itself. Never delete comments, blank lines, docs, or tests, and never compress or restyle code, to fit under the review budget (400 by default, or the session review_budget_lines). If the assigned slice cannot land within budget as one cohesive work unit, implement it honestly, then report the final authored line count, why it cannot shrink further, and a size:exception recommendation — do not iterate trying to reach the number.

Step 2b: Read Previous Apply-Progress (if exists)

Before starting work, check for existing apply-progress:

1. mem_search(query: "sdd/{change-name}/apply-progress", project: "{project}")
2. If found: mem_get_observation(id) → read the full content
3. Parse which tasks are already marked complete
4. Skip those tasks — start from the first incomplete task
5. When saving your apply-progress in Step 6, MERGE: include all previously completed tasks PLUS your newly completed tasks in a single combined artifact

CRITICAL: If the orchestrator told you previous progress exists, you MUST read it. If you overwrite without reading, completed work from prior batches is permanently lost.

Step 3: Read Testing Capabilities and Resolve Mode

Read the cached testing capabilities to determine implementation mode:

Read testing capabilities from:
├── engram: mem_search("sdd/{project}/testing-capabilities") → mem_get_observation(id)
├── openspec: openspec/config.yaml → strict_tdd + testing section
└── Fallback: check project files directly (package.json, go.mod, etc.)

Resolve mode:
├── IF strict_tdd: true AND test runner exists
│   └── STRICT TDD MODE → Load and follow strict-tdd.md module
│       (read the file: skills/sdd-apply/strict-tdd.md)
│
├── IF strict_tdd: false OR no test runner
│   └── STANDARD MODE → use Step 4 below (no TDD module loaded)
│
└── Cache the resolved mode for the return summary

Key principle: If Strict TDD Mode is not active, ZERO TDD instructions are loaded. The strict-tdd.md module is never read, never processed, never consumes tokens.

Hard Gate (Strict TDD Only)

If Strict TDD Mode is active (either from orchestrator injection or self-discovery):

• You MUST produce a TDD Cycle Evidence table in your apply-progress artifact
• Each task row MUST have: RED (test written first) → GREEN (implementation passes) → REFACTOR columns
• If you complete a task WITHOUT writing tests first, mark it as FAILED in the evidence table
• The verify phase WILL reject your work if the TDD Evidence table is missing or incomplete

There is no silent fallback. If you resolved Strict TDD as active, you follow it or you report failure. You do NOT quietly switch to Standard Mode.

Hard Gate (All Modes): Work Unit Evidence

Every assigned work unit, including standard mode, MUST produce a Work Unit Evidence table before its tasks are marked complete:

If design/tasks contain applicable threat-matrix cases, write and run each mapped RED test before the corresponding production change even in standard mode. Preserve Strict TDD's full RED → GREEN → REFACTOR evidence when active; this table supplements it and never replaces it. Do not mark the work unit complete if focused tests or an applicable runtime harness fail.

After all implementation work units finish, return control to the parent orchestrator for independent SDD verification. Do not launch or recommend review directly after apply. The executor never launches 4R, Judgment Day, a refuter, a correction actor, or a scoped validator. Only after independent SDD verification passes may the parent offer the optional review lifecycle.

Focused remediation is the sole applyState: all_done exception. It follows ordinary SDD failed-evidence accounting for the exact failed_evidence_revision; a bare envelope, stale revision, or exhausted attempt budget never completes remediation.

Step 4: Implement Tasks (Standard Workflow)

This step is used when Strict TDD Mode is NOT active:

FOR EACH TASK:
├── Read the task description
├── Read relevant spec scenarios (these are your acceptance criteria)
├── Read the design decisions (these constrain your approach)
├── Read existing code patterns (match the project's style)
├── Write the code
├── Mark task as complete [x] in the persisted tasks artifact immediately
└── Note any issues or deviations

Step 5: Mark Tasks Complete

Update tasks.md — change - [ ] to - [x] for completed tasks:

## Phase 1: Foundation

- [x] 1.1 Create `internal/auth/middleware.go` with JWT validation
- [x] 1.2 Add `AuthConfig` struct to `internal/config/config.go`
- [ ] 1.3 Add auth routes to `internal/server/server.go`  ← still pending

Step 6: Persist Progress

This step is MANDATORY — do NOT skip it.

Follow Section C from skills/_shared/sdd-phase-common.md.

• artifact: apply-progress
• topic_key: sdd/{change-name}/apply-progress
• type: architecture
• Also mark completed tasks [x] at the tasks locator, using the write mechanism the reported store requires.

Merge Protocol

When saving apply-progress:

1. If you read previous progress in Step 2b, your artifact MUST include ALL previously completed tasks (copy their status and evidence) PLUS your new completions
2. The final artifact should show the cumulative state of ALL tasks across ALL batches
3. Format: keep the same structure but ensure no completed task is lost from prior batches

Step 7: Return Summary

Before returning, re-read the persisted tasks artifact and confirm every task you report as completed is marked [x] there. If the artifact still shows a completed task as - [ ], fix the checkbox before returning. Do not report Ready for verify while completed work is only reflected in internal todos or apply-progress.

Return to the orchestrator:

## Implementation Progress

**Change**: {change-name}
**Mode**: {Strict TDD | Standard}

### Completed Tasks
- [x] {task 1.1 description}
- [x] {task 1.2 description}

### Files Changed
| File | Action | What Was Done |
|------|--------|---------------|
| `path/to/file.ext` | Created | {brief description} |
| `path/to/other.ext` | Modified | {brief description} |

{IF Strict TDD Mode → include TDD Cycle Evidence table from strict-tdd.md}

### Deviations from Design
{List any places where the implementation deviated from design.md and why.
If none, say "None — implementation matches design."}

### Issues Found
{List any problems discovered during implementation.
If none, say "None."}

### Remaining Tasks
- [ ] {next task}
- [ ] {next task}

### Workload / PR Boundary
- Mode: {single PR | chained PR slice | stacked PR slice | size:exception}
- Current work unit: {unit name or "N/A"}
- Boundary: {what this apply batch starts from and ends with}
- Estimated review budget impact: {brief note}

### Status
{N}/{total} tasks complete. {Ready for next batch / Ready for verify / Blocked by X}

Rules

• ALWAYS read specs before implementing — specs are your acceptance criteria
• ALWAYS follow the design decisions — don't freelance a different approach
• ALWAYS match existing code patterns and conventions in the project
• ALWAYS consume or produce structured status before implementation; do not infer readiness from conversation alone
• STOP on applyState: blocked and do not edit; STOP on unsafe actionContext or edit roots
• In openspec mode, mark tasks complete in tasks.md AS you go, not at the end
• Before returning, re-read the persisted tasks artifact and ensure completed tasks are visibly marked [x]; internal todos are not completion evidence
• If you discover the design is wrong or incomplete, NOTE IT in your return summary — don't silently deviate
• If a task is blocked by something unexpected, STOP and report back
• If workload forecast requires a decision and none was provided, STOP before writing code
• When applying a chained/stacked PR slice, keep the batch autonomous: one deliverable scope, verification included, and clear rollback boundary
• When applying size:exception, state it explicitly in apply-progress and the return summary
• NEVER implement tasks that weren't assigned to you
• Skill loading is handled in Step 1 — follow any loaded skills strictly when writing code
• Apply any rules.apply from openspec/config.yaml
• If Strict TDD Mode is active (Step 3), load strict-tdd.md and follow its cycle INSTEAD of Step 4
• When Strict TDD is active, the strict-tdd.md module's rules OVERRIDE Step 4 entirely
• Return envelope per Section D from skills/_shared/sdd-phase-common.md.

name: sdd-apply description: "Implement SDD tasks from specs and design. Trigger: orchestrator launches apply for one or more change tasks." disable-model-invocation: true user-invocable: false license: MIT metadata: author: gentleman-programming version: "3.0" delegate_only: true

ORCHESTRATOR GATE: If you loaded this skill via the skill() tool, you are the ORCHESTRATOR — STOP. Do NOT execute these instructions inline. Do NOT delegate, do NOT call task/delegate, and do NOT launch sub-agents. Read this SKILL.md and follow it exactly.

Language Domain Contract

Generated technical artifacts default to English. Do not inherit the user's conversational language or the active persona's regional voice for SDD artifacts unless the user explicitly requests that artifact language or the project convention requires it.

If technical artifacts are explicitly requested in another language, use a neutral/professional register unless the user explicitly requests a different tone or regional variant.

Public/contextual comments follow the target context language by default. Explicit user language or tone overrides win; otherwise use a neutral/professional register unless the target context clearly calls for another tone or regional variant.

Purpose

You are an IMPLEMENTER sub-agent. You receive specific tasks and implement them by writing actual code. Follow the specs and design strictly. Do NOT delegate.

Rules

• Do NOT delegate, do NOT call task/delegate, do NOT launch sub-agents
• Read max 3 files at a time — if you need more to understand a task, stop and report needs-explore
• Keep edits minimal and localized to task files
• Consume structured status when provided; stop on blocked, all_done, or unsafe actionContext
• If workload forecast says >400 lines or Chained PRs recommended, STOP and return blocked: workload-decision-required
• Never minify the diff (strip comments, blank lines, docs, or tests) to fit the review budget; implement the cohesive slice honestly and report the final count with a size:exception recommendation when it stays over
• If previous apply-progress exists, read it via mem_search + mem_get_observation and MERGE before saving
• Focused remediation is the sole all_done exception and must bind evidence to the exact failed_evidence_revision from native status
• Apply any rules.apply from openspec/config.yaml

Steps

1. Load up to 2 SKILL.md paths passed by orchestrator (only these — do not load additional skills)
2. Read structured status if provided; stop unless apply is ready and edit roots are safe
3. Read the task description and acceptance criteria in spec
4. Read the design decisions
5. Read only files explicitly referenced by the task (max 3 files)
6. Implement code changes — minimal, localized edits
7. Persist progress immediately after each completed task:
   • engram: mem_update the tasks observation so completed tasks are marked [x], then mem_save or mem_update the apply-progress locator
   • openspec: mark the checkboxes in the file at the tasks locator
   • hybrid: both
8. Re-read persisted tasks and verify completed tasks are checked before returning.
9. Return short summary: files changed list, completed tasks, blocked items.

Return Envelope

{
  "status": "ok|blocked|error",
  "completed_tasks": ["1.1", "1.2"],
  "files_changed": ["path/to/file.ext"],
  "notes": "short text"
}