sdd-apply

name	sdd-apply
description	Implement tasks from the change, writing actual code following the specs and design. Trigger: When the orchestrator launches you to implement one or more tasks from a change.
license	MIT
metadata	{"author":"gentleman-programming","version":"2.1"}
dependencies	["worktree-flow","cost-tracking"]

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 (engram | openspec | hybrid | none)

Execution and Persistence Contract

Read and follow skills/_shared/persistence-contract.md for mode resolution rules.

• If mode is engram:

  CRITICAL: mem_search returns 300-char PREVIEWS, not full content. You MUST call mem_get_observation(id) for EVERY artifact. If you skip this, you will work with incomplete specs and produce wrong code.

  STEP A — SEARCH (get IDs only — content is truncated):

  1. mem_search(query: "sdd/{change-name}/proposal", project: "{project}") → save ID
  2. mem_search(query: "sdd/{change-name}/spec", project: "{project}") → save ID
  3. mem_search(query: "sdd/{change-name}/design", project: "{project}") → save ID
  4. mem_search(query: "sdd/{change-name}/tasks", project: "{project}") → save ID (keep this ID for updates)

  STEP B — RETRIEVE FULL CONTENT (mandatory for each): 5. mem_get_observation(id: {proposal_id}) → full proposal 6. mem_get_observation(id: {spec_id}) → full spec 7. mem_get_observation(id: {design_id}) → full design 8. mem_get_observation(id: {tasks_id}) → full tasks

  DO NOT use search previews as source material.

  Mark tasks complete (update the tasks artifact as you go):

  mem_update(id: {tasks-observation-id}, content: "{updated tasks with [x] marks}")
  

  Save progress artifact:

  mem_save(
    title: "sdd/{change-name}/apply-progress",
    topic_key: "sdd/{change-name}/apply-progress",
    type: "architecture",
    project: "{project}",
    content: "{your implementation progress report}"
  )
  

  topic_key enables upserts — saving again updates, not duplicates.

  (See skills/_shared/engram-convention.md for advanced operations.)

• If mode is openspec: Read and follow skills/_shared/openspec-convention.md. Update tasks.md with [x] marks.

• If mode is hybrid: Follow BOTH conventions — persist progress to Engram (mem_update for tasks) AND update tasks.md with [x] marks on filesystem.

• If mode is none: Return progress only. Do not update project artifacts.

What to Do

Step 1: Load Skill Registry

Do this FIRST, before any other work.

1. Try engram first: mem_search(query: "skill-registry", project: "{project}") → if found, mem_get_observation(id) for the full registry
2. If engram not available or not found: read .atl/skill-registry.md from the project root
3. If neither exists: proceed without skills (not an error)

From the registry, identify and read any skills whose triggers match your task. Also read any project convention files listed in the registry.

Step 2: Read Context

Before writing ANY code:

1. Read the specs — understand WHAT the code must do
2. Read the design — understand HOW to structure the code
3. Read existing code in affected files — understand current patterns
4. Check the project's coding conventions from config.yaml

Step 3: Detect Implementation Mode

Before writing code, determine if the project uses TDD:

Detect TDD mode from (in priority order):
├── openspec/config.yaml → rules.apply.tdd (true/false — highest priority)
├── User's installed skills (e.g., tdd/SKILL.md exists)
├── Existing test patterns in the codebase (test files alongside source)
└── Default: standard mode (write code first, then verify)

IF TDD mode is detected → use Step 3a (TDD Workflow)
IF standard mode → use Step 3b (Standard Workflow)

Step 3a: Implement Tasks (TDD Workflow — RED → GREEN → REFACTOR)

When TDD is active, EVERY task follows this cycle:

FOR EACH TASK:
├── 1. UNDERSTAND
│   ├── Read the task description
│   ├── Read relevant spec scenarios (these are your acceptance criteria)
│   ├── Read the design decisions (these constrain your approach)
│   └── Read existing code and test patterns
│
├── 2. RED — Write a failing test FIRST
│   ├── Write test(s) that describe the expected behavior from the spec scenarios
│   ├── Run tests — confirm they FAIL (this proves the test is meaningful)
│   └── If test passes immediately → the behavior already exists or the test is wrong
│
├── 3. GREEN — Write the minimum code to pass
│   ├── Implement ONLY what's needed to make the failing test(s) pass
│   ├── Run tests — confirm they PASS
│   └── Do NOT add extra functionality beyond what the test requires
│
├── 4. REFACTOR — Clean up without changing behavior
│   ├── Improve code structure, naming, duplication
│   ├── Run tests again — confirm they STILL PASS
│   └── Match project conventions and patterns
│
├── 5. Mark task as complete [x] in tasks.md
└── 6. Note any issues or deviations

Detect the test runner for execution:

Detect test runner from:
├── openspec/config.yaml → rules.apply.test_command (highest priority)
├── package.json → scripts.test
├── pyproject.toml / pytest.ini → pytest
├── Makefile → make test
└── Fallback: report that tests couldn't be run automatically

Important: If any user coding skills are installed (e.g., tdd/SKILL.md, pytest/SKILL.md, vitest/SKILL.md), read and follow those skill patterns for writing tests.

Step 3b: Implement Tasks (Standard Workflow)

When TDD 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 tasks.md
└── Note any issues or deviations

Step 3c: Log Iteration to iterations.jsonl

After each task attempt (whether kept or reverted), append a JSON line to the iteration log. This creates an audit trail that future sessions can read to avoid repeating failed approaches.

Log File Location

openspec/changes/{change-name}/iterations.jsonl    ← append-only log

If mode is engram, also persist a snapshot to engram periodically (see Step 5). If mode is none, skip file writing but still track iterations in memory for the return summary.

JSON Line Schema

Each line in iterations.jsonl is a self-contained JSON object:

{
  "timestamp": "2025-01-15T10:30:00Z",
  "task_id": "1.1",
  "task_description": "Create internal/auth/middleware.go with JWT validation",
  "iteration": 1,
  "approach": "Used middleware pattern with jose library for JWT parsing",
  "before_state": {
    "files_existed": ["internal/auth/types.go"],
    "files_missing": ["internal/auth/middleware.go"],
    "tests_passing": 12,
    "tests_failing": 0
  },
  "after_state": {
    "files_created": ["internal/auth/middleware.go"],
    "files_modified": [],
    "tests_passing": 14,
    "tests_failing": 0
  },
  "outcome": "kept",
  "reason": "All tests pass, implementation matches spec REQ-01",
  "duration_tool_calls": 5,
  "deviations": []
}

Field Reference

Field	Type	Description
timestamp	string (ISO 8601)	When the attempt started
task_id	string	Task identifier from tasks.md (e.g., "1.1", "2.3")
task_description	string	Brief description from tasks.md
iteration	number	Attempt number for this task (1 = first try, 2 = retry, etc.)
approach	string	What approach was tried and key implementation decisions
before_state	object	Snapshot before the attempt: existing files, test counts
after_state	object	Snapshot after: created/modified files, test counts
outcome	enum	"kept" — changes retained, "reverted" — changes rolled back, "partial" — some changes kept
reason	string	Why the attempt was kept or reverted
duration_tool_calls	number	How many tool calls this attempt consumed
deviations	array of string	Any deviations from design, empty if none

When to Log

FOR EACH TASK attempt:
├── BEFORE implementation:
│   ├── Record timestamp, task_id, task_description
│   ├── Snapshot before_state (list relevant files, run test count if quick)
│   └── Note the approach being tried
│
├── AFTER implementation (success or failure):
│   ├── Snapshot after_state
│   ├── Determine outcome: kept / reverted / partial
│   ├── Record reason and deviations
│   └── Append the JSON line to iterations.jsonl
│
└── ON RETRY (if task failed and is being re-attempted):
    ├── Increment iteration counter
    ├── Note the NEW approach (must differ from previous)
    └── Log as a new line (do NOT overwrite the failed attempt line)

Reading Previous Iterations

When starting a task, check if iterations.jsonl exists and contains entries for the same task_id:

IF iterations.jsonl contains entries for current task_id:
├── Read all entries for that task
├── Identify approaches that were REVERTED (failed approaches)
├── Do NOT repeat a reverted approach — try a different strategy
├── Use kept entries as context for dependent tasks
└── If all reasonable approaches have been tried and reverted:
    STOP and report to orchestrator as BLOCKED

This prevents the classic failure loop where agents retry the same broken approach indefinitely.

Step 4: 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 5: Persist Progress (Ralph Loop Compliance)

This step is MANDATORY — do NOT skip it.

This step serves dual purposes: (1) standard progress persistence for sdd-verify, and (2) Ralph Loop state handoff so the NEXT sub-agent batch starts with fresh context and complete knowledge.

If mode is engram:

1. Update the tasks artifact with completion marks:

   mem_update(id: {tasks-observation-id}, content: "{updated tasks with [x] marks}")
   

2. Save progress report in Ralph Loop format:

   mem_save(
     title: "sdd/{change-name}/apply-progress",
     topic_key: "sdd/{change-name}/apply-progress",
     type: "architecture",
     project: "{project}",
     content: "{Ralph Loop progress report — see format below}"
   )
   

If mode is openspec or hybrid: tasks.md was already updated in Step 4.

If mode is hybrid: also call mem_save and mem_update as above.

If you skip this step, sdd-verify will NOT be able to find your progress and the pipeline BREAKS. Additionally, the next Ralph Loop batch will lack context and may produce inconsistent code.

Ralph Loop Progress Report Format

The apply-progress artifact MUST include these sections to enable clean handoff to the next fresh sub-agent:

## Apply Progress — {change-name} (Batch {N})

### Completed Tasks
- [x] {task ID}: {brief summary of what was done}

### Files Changed
| File | Action |
|------|--------|
| `path/to/file.ext` | Created |
| `path/to/other.ext` | Modified |

### Discovered Patterns
{Conventions found during implementation that are NOT in specs/design.
These get relayed to subsequent batches so they maintain consistency.}
- {pattern 1}
- {pattern 2}

### Deviations from Design
{Any places where implementation diverged from design.md and why.
"None — implementation matches design." if no deviations.}

### Iteration Log Summary
| Task | Attempts | Final Outcome | Approaches Tried |
|------|----------|---------------|-----------------|
| {task_id} | {N} | kept/reverted | {brief list} |

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

Persisting iterations.jsonl to Engram

If mode is engram or hybrid, save a snapshot of the iteration log after each batch:

mem_save(
  title: "sdd/{change-name}/iterations",
  topic_key: "sdd/{change-name}/iterations",
  type: "architecture",
  project: "{project}",
  content: "{full contents of iterations.jsonl}"
)

This allows future sessions to recover the iteration log even if the filesystem artifact is lost.

Reading Ralph Loop Context

If the orchestrator passes a RALPH LOOP CONTEXT block in your prompt, you are a continuation batch. In that case:

1. Read the listed discovered patterns and apply them to your implementation
2. Check files modified by previous batches to understand current state (read the actual files, do not assume)
3. Do NOT repeat work already marked as completed
4. Add any NEW discovered patterns to your progress report for the next batch

Step 6: Return Summary

Return to the orchestrator:

## Implementation Progress

**Change**: {change-name}
**Mode**: {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} |

### Tests (TDD mode only)
| Task | Test File | RED (fail) | GREEN (pass) | REFACTOR |
|------|-----------|------------|--------------|----------|
| 1.1 | `path/to/test.ext` | ✅ Failed as expected | ✅ Passed | ✅ Clean |
| 1.2 | `path/to/test.ext` | ✅ Failed as expected | ✅ Passed | ✅ Clean |

{Omit this section if standard mode was used.}

### Iteration Log
| Task | Attempts | Outcome | Approach |
|------|----------|---------|----------|
| {task_id} | {N} | kept | {brief approach description} |
| {task_id} | {N} | reverted → kept | Attempt 1: {failed approach}. Attempt 2: {successful approach} |

{Omit rows for tasks that succeeded on first attempt with no notable decisions.}

### 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}

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

Discovery Relay (Parallel Apply Only)

When running in parallel apply mode (worktrees), sub-agents are isolated and cannot see each other's work. The discovery relay protocol bridges this gap.

Saving Discoveries

After completing your assigned task(s), check if you encountered any non-obvious runtime insights (API constraints, initialization order, type quirks, pattern deviations, performance gotchas).

If YES — save each discovery to engram:

mem_save(
  title: "sdd/{change-name}/discoveries/wave-{wave-number}/task-{task-id}",
  topic_key: "sdd/{change-name}/discoveries/wave-{wave-number}/task-{task-id}",
  type: "discovery",
  project: "{project}",
  content: "**What**: {one-line insight}
**Why**: {what you were doing when you found it}
**Where**: {file paths affected}
**Impact**: {which future tasks or areas need this}"
)

If NO discoveries — skip. Do NOT save empty discoveries.

Reading Injected Discoveries

If your prompt contains a DISCOVERIES FROM PREVIOUS WAVES block, read it carefully before implementing. These are runtime insights from completed tasks in prior waves. Use them to:

• Avoid repeating known mistakes
• Follow constraints discovered by other sub-agents
• Apply optimizations already identified

When to Save vs Skip

Scenario	Save Discovery?
Found API constraint not in design	Yes
Discovered initialization order dependency	Yes
Used a pattern already in specs	No
Hit a bug in a dependency	Yes
Task completed without surprises	No
Found performance optimization opportunity	Yes

Keep each discovery under 100 words. Concise > comprehensive.

See own/skills/discovery-relay/SKILL.md for the full protocol.

Critical Rules

1. Tool Call Budget Cap: You have a maximum of 20 tool calls per task. Track your tool call count. If you reach 15 calls without completing the task, STOP debugging/retrying, summarize what you accomplished, what failed, and what remains — then return to the orchestrator. Do NOT spiral into retry loops. A concise failure report is more valuable than burning context on hopeless retries.

2. Surgical Changes Only: Every changed line MUST trace back to the user's request or the assigned task in tasks.md. Do NOT perform drive-by refactoring — no renaming unrelated variables, no reformatting untouched code, no "while I'm here" cleanups. If you notice unrelated issues, report them in your summary under "Issues Found" but do NOT fix them. The diff should contain ZERO surprises.

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
• In openspec mode, mark tasks complete in tasks.md AS you go, not at the end
• 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
• 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 TDD mode is detected (Step 3), ALWAYS follow the RED → GREEN → REFACTOR cycle — never skip RED (writing the failing test first)
• When running tests during TDD, run ONLY the relevant test file/suite, not the entire test suite (for speed)
• Return a structured envelope with: status, executive_summary, detailed_report (optional), artifacts, next_recommended, and risks
• ALWAYS include discovered patterns in your apply-progress artifact (Ralph Loop compliance) — even if you think they are "obvious". The next sub-agent has zero context from your session.
• When receiving Ralph Loop context from the orchestrator, treat discovered patterns as constraints — do NOT contradict them unless the specs explicitly say otherwise
• NEVER include your full reasoning, debug traces, or tool call history in the progress artifact — only structured summaries. The goal is minimal, actionable context for the next fresh agent.
• ALWAYS log each task attempt to iterations.jsonl AFTER the attempt completes (Step 3c) — this is non-negotiable for learning across sessions
• ALWAYS check iterations.jsonl for previous failed approaches BEFORE starting a task — do NOT repeat reverted approaches
• NEVER overwrite or edit existing lines in iterations.jsonl — it is append-only
• If a task has 3+ reverted attempts in the log, STOP and report as BLOCKED — do not burn context on a 4th attempt