sdd:implement

Files (1)

• SKILL.md

SKILL.md (first lines)

## Shared Instructions

- [Event Journal](../../lib/instructions/event-journal.md) — append context updates to a per-spec write-ahead log; a single drain script materializes them into `.spec-context.json`
- [Transition Logging](../../lib/instructions/transition-logging.md) — transition entry shape and millisecond `at` precision (the drainer materializes one transition per journal event)
- [Hook Execution](../../lib/instructions/hook-execution.md) — run user-configured hooks at supported pipeline points
- [Branch Creation](../../lib/instructions/branch-creation.md) — optional feature-branch creation driven by `.sdd.json` `branchStage`
- [Layered Context](../../lib/instructions/layered-context.md) — Layer 2 → Layer 1 delta sync at CP3 (Step 7b)

## Context writes: journal + drain

This skill does **not** read-merge-write `.spec-context.json` on every task.
Per [event-journal](../../lib/instructions/event-journal.md), each context
update is a one-line **append** to `specs/{NNN}-{slug}/.spec-context.events.jsonl`
(cheap; no read, no merge), and a single **drain** materializes the journal into
`.spec-context.json` at the boundaries called out below.

- **On entry**, read `drainedSeq` from `.spec-context.json` (default 0) and the
  last journal line's `seq` (default 0); set your run counter to the max. Each
  append increments it by 1. Each append carries `at` (ms precision via
  `date -u +%Y-%m-%dT%H:%M:%S.%3NZ`), the current `step`/`substep`, and the
  `from` (prior step+substep) — the drainer turns each event into exactly one
  transition.
- **To drain**, run:
  ```bash
  python3 lib/scripts/drain-spec-context.py specs/{NNN}-{slug}/
  ```
  Drain at: Context Recovery (first), every ~3 solo tasks and before yielding the
  turn, each parallel-group end, before each checkpoint display (CP1/CP2/CP3),
  and before `git add` in Steps 8 and 8b. The drainer is idempotent.

## Steps

### 1. Load

If `$ARGUMENTS` is provided, use `specs/{$ARGUMENTS}/` as the target directory.
Otherwise, find the most recently modified directory under `specs/` that contains `tasks.md`.

Read in parallel:

- `specs/{NNN}-{slug}/tasks.md` — all Phase 1 tasks
- `specs/{NNN}-{slug}/spec.md` — feature name, requirements, scenarios (for CP1 verification)
- `specs/{NNN}-{slug}/plan.md` — approach, files, issue number if present
- `specs/{NNN}-{slug}/.spec-context.json` — current step/task (if exists; note if resuming mid-implement)

Determine commit scope from the primary directory being modified (e.g., `toolbar`, `ui`, `core`). If unclear, omit scope.

Determine issue number from plan.md or spec.md if present.

If no tasks found, stop: "Run `/sdd:specify`, `/sdd:plan`, and `/sdd:tasks` first."

Append a `progress` event to the journal per [event-journal](../../lib/instructions/event-journal.md) (seq counter initialized as described above):

```json
{ "seq": <n>, "at": "<ms-ISO>", "kind": "progress", "step": "implement", "substep": "phase1", "from": { "step": "tasks", "substep": null }, "set": { "currentStep": "implement", "currentTask": "T001", "progress": "phase1", "next": "implement" } }
```

(No drain needed yet — Context Recovery and the first checkpoint will drain.)

---

### 1b. Optional Branch Creation

**Skip this step on resume** — if `.spec-context.json` already showed `currentStep = "implement"` on entry, branch creation has already run (or been skipped) on the first pass.

Follow [branch-creation](../../lib/instructions/branch-creation.md) with `stage="implement"`. It is a no-op unless `.sdd.json` has `branchStage: "implement"`.

Run `pre:implement` hooks per [hook-execution](../../lib/instructions/hook-execution.md) with `vars = { slug, spec-dir, files: <empty string — no files modified yet> }`.

---

### Context Recovery (if resuming)

If `.spec-context.json` shows `currentStep = "implement"`:

0. **Drain first.** Run `python3 lib/scripts/drain-spec-context.py specs/{NNN}-{slug}/` so any events appended before the interruption are materialized before you read. The drainer is idempotent. Then initialize your seq counter (see "Context writes" above).
1. Read `.spec-context.json` fully — extract `approach`, `last_action`, `task_summaries`, `concerns`, `decisions`, `files_modified`, and `step_summaries` if present
2. Use these fields to reconstruct context efficiently:
   - `approach` tells you the implementation strategy without re-reading plan.md
   - `last_action` tells you what just happened before context was lost
   - `task_summaries` for completed tasks tells you what each task did, what files it touched, and any concerns — without re-deriving from code
   - `step_summaries.plan` (if present) provides the planned approach, file count, and risks — skip re-reading plan.md
   - `concerns` and `decisions` carry forward flagged issues and key choices
3. Read `tasks.md` — `[x]` = done, `[ ]` = remaining (still needed for remaining task definitions)
4. Read `spec.md` for scenarios (needed at CP1 for verification). If `step_summaries.specify` exists in .spec-context.json, you can skip re-reading spec.md for feature context (use the key_finding instead) — but still read it for CP1 scenario verification.
5. Skip re-reading `plan.md` if `step_summaries.plan` and `approach` exist in .spec-context.json — these provide sufficient context
6. Read `progress` from `.spec-context.json` and use it to skip completed phases:

| `progress` value | Resume point |
|-----------------|-------------|
| `phase1` | Resume from first unchecked task in Phase 1 |
| `hooks` | Skip Phase 1, resume at hooks execution |
| `code-review` | Skip Phase 1 + hooks, resume at CP1 — Code Review |
| `test-results` | Skip through CP1, resume at CP2 — Test Results |
| `commit-review` | Skip through CP2, resume at CP3 — Commit Review |
| `commit` | Skip through CP3, resume at Step 8 (stage + commit) |
| `null` or missing | Fall back to task-based recovery: resume from first unchecked task |

4. Do NOT re-run completed phases — trust the progress marker and existing checkmarks

---

### 2. Phase 1 — Core Implementation

Walk Phase 1 tasks in order. Tasks group into two execution shapes:

- **Solo task** — any task that does not start with `[P]`. Execute it by itself.
- **Parallel group** — a run of consecutive `[P]` tasks. Execute them as a batch of concurrent subagents.

#### 2a. Solo task execution

For each solo task:

1. Perform the work described in the **Do** field.
2. Run the **Verify** check.
3. Mark complete in `specs/{NNN}-{slug}/tasks.md`: `- [ ]` → `- [x]`.
4. Append one `task_done` event to the journal per [event-journal](../../lib/instructions/event-journal.md) (no read-merge; `files_modified` is `union`, `decisions`/`concerns` are `append`, the rest is `set`):
   ```json
   { "seq": <n>, "at": "<ms-ISO>", "kind": "task_done", "step": "implement", "substep": "phase1", "from": { "step": "implement", "substep": "phase1" },
     "set": { "task_summaries.{taskId}": { "status": "DONE|DONE_WITH_CONCERNS", "did": "<one line>", "files": ["..."], "concerns": ["..."] }, "currentTask": "<next T### or null>", "last_action": "<one line>" },

From alfredoperez/sdd, MIT.

More from alfredoperez/sdd