--- name: implement description: Stage 4 of the SDD pipeline — execute a ZettelFlow task checklist (in a GitHub issue comment) test-first (red → green → refactor), one commit per advance, keeping npm run verify green and CI green on every commit on a single feature branch. Use after a tasks comment exists and the user says "implement", "build issue #N", "work the tasks", or "start coding". Drives the tdd skill. --- # /implement — build the tasks test-first Stage 4 of the [SDD pipeline](../sdd/SKILL.md). Work the task checklist (in the GitHub issue comment) top to bottom using the **`tdd`** discipline. This stage is done by the main assistant (not a subagent) because it commits to the branch and must keep CI green at every step. ## Before starting Run `gh issue view ` — read the spec (body) and the plan + tasks comments. The tasks comment has the checklist; the plan comment has the files, guardrails, and risks. ## The loop (per task) 1. **Red** — write/extend the test named in the task; run `npm test` and watch it fail for the right reason. Import from `@jest/globals`; resolve source via the bare aliases; extend `test/__mocks__/obsidian.ts` when the unit pulls in more Obsidian API (see the `tdd` skill). 2. **Green** — make the minimal change to pass. 3. **Refactor** — clean up with the suite green. 4. **Verify** — `npm run verify` (typecheck + oxlint + jest) must be green. For score tasks also run `npm run lint:obsidian` and confirm **no new** violations. For i18n tasks confirm `en.ts`/`es.ts` key parity. 5. **Commit** — one Conventional Commit per completed task/advance (constitution §IX): `git add -A && git commit -m "(): "`. 6. **Check off the task** — mark `[x]` directly in the GitHub issue comment (edit the comment with `gh issue comment --edit-last` or find the comment id and patch it). 7. **Keep CI green** — push the branch; the CI workflow re-runs the blocking guardrails. Because `verify` is green locally, CI stays green. Fix forward if a push ever goes red — don't stack more commits on a red branch. ## Rules - **Single branch** — one `feature/*` branch for the whole issue; never commit to `main`. - **Never** introduce `innerHTML`, inline `el.style.*`, Title-case UI strings, bare `console.*`, or global `app` — they cost score (constitution §III–IV). Build DOM with `createEl`; style with `c()` + SCSS; log with `log`. - **The user's theme wins** (§XV). No hex or named colour in a stylesheet, no pixel the `--size-4-*` grid can express, Obsidian's own classes (`mod-cta`, `clickable-icon`, `setting-item`, `is-active`) before inventing one, and a shape that exists twice goes in `src/styles/utils/mixins.scss`. The guide, with Obsidian's own wording, is [`docs/development/obsidian-styling.md`](../../../docs/development/obsidian-styling.md). - Touching the **Canvas patcher**? Keep every patched access guarded and uninstalled on unload (§VI) — see issue #91 / the reviewer agent. - Update the matching `docs/` page + `mkdocs.yml` nav in the **same** commit that changes behavior (§VIII). ## Exit → stage 5 When all tasks are checked off, do **four things before declaring done**: ### 1. Docs audit (mandatory) For every user-facing change — new feature, changed behaviour, new config option, new action, changed UI text — ask: *does the existing docs page cover this?* - **New feature / behaviour change** → update the matching page under `docs/` AND check the `mkdocs.yml` nav (add an entry if the feature deserves its own page). - **New action** → add or update `docs/actions/.md`. - **New config option** → update the settings section of the relevant architecture page. - **API / public surface change** → update `docs/api/ZettelFlowAPI.md`. - **No user-facing change** (pure refactor, test, chore) → docs audit is still required; confirm explicitly that no doc update is needed and state why. This audit is a **blocking exit criterion** — do not commit the implementation without it. Docs and code travel in the same commit (or a `docs:` follow-up commit immediately after). ### 2. README placement audit — by door rank (mandatory for user-facing features) Adoption is a first-class goal and the README is the front door. For every change that ships something a *user* would care about, do not ask *"where do I add a row?"* — ask **what is this capability's door rank** ([capability doors](../../../docs/development/capability-doors.md)), and place it accordingly: - **Rank 1–3, and it asks something of the reader** (a practice loop) → the README's **first screen**: one sentence, its door, a link to its page. The first screen is bounded — something else has to leave. - **Rank 1–3, ordinary capability** → a **headline entry** in the README, a few lines, linked. - **Rank 4–5 or configuration** → **one line in the generated capability reference** (`docs/reference/capabilities.md`; regenerate with `UPDATE_DOCS=1 npx jest capabilityIndex`) plus its own docs page. The README does not grow. - **New action** → the actions page and the action count; no README row. - **No user-facing surface** (pure refactor, internal fix) → say so explicitly. Never *"add a row to the Features table"* — that table was removed in #588 precisely because one row per epic produced a 69-row changelog in which nothing could be ranked. `npm test` enforces the ceiling (`test/docs/readmeCeiling.test.ts`), that nothing shipped disappeared (`test/docs/readmeNamesKept.test.ts`) and that this rule still reads this way (`test/docs/placementRule.test.ts`). Blocking exit criterion, like the docs audit. ### 3. Walk the verification script (mandatory) Open the issue's `## How to verify` and **do it** — run every command in the automated table, then walk the manual steps in a real vault (`npm run dev:vault`). Two outcomes are failures, not paperwork: - **A step does not describe reality** → fix the spec section in the same change. A verification script nobody has walked is worth less than none, because it will be trusted. - **A manual step turned out to be automatable** → automate it and move it up into the table. This is a **blocking exit criterion** (constitution §XIV): the change is not done until someone has seen it work by following the written script. ### 4. Quality check Run the **`obsidian-plugin-quality`** skill and the **`obsidian-plugin-reviewer`** agent on the diff, and verify every acceptance criterion in the issue spec (body). ### 5. Close the issue via PR **Closing the issue (constitution §X).** Commits only *reference* the issue (`(#N)`) — they never close it. The issue is closed by the **pull request** that merges the branch to `main`: put `Closes #N` (one line per addressed issue) in the **PR body**. Do not `gh issue close` from the feature branch and do not put closing keywords in commit messages. "Issue closed" is realised when the PR merges.