docs(agents): assume-included Storybook, GitHub-primary tracker, prune-tests skill, kill deciduous update · taurean.bryant.land/suede@70c335d

+5

.gitignore

··· 35 35 # Deciduous exported web viewer (regenerated per machine via `deciduous sync`) 36 36 docs/ 37 37 38 + # Plan files are per-task scratchpads; the compiled form (graph nodes + 39 + # task note Decisions section) is what persists. Handoff is the tool 40 + # for resuming work across machines, not the plan file. 41 + agent-notes/plans/ 42 + 38 43 # Claude-Code-specific artifacts (not part of this OpenCode-primary project) 39 44 CLAUDE.md 40 45 .claude/

+33 -76

.opencode/plugins/version-check.ts

View file

··· 1 - // OpenCode Plugin: Version Check 2 - // Checks for new deciduous versions via crates.io (always-on, once per 24h) 3 - // Non-blocking: informational only 4 - // Patch updates get a quiet one-liner; minor/major updates get a prominent banner 1 + // OpenCode Plugin: Version Check (no-op) 2 + // 3 + // Suede does not run `deciduous update` (see AGENTS.md "Do not run 4 + // `deciduous update`" note). The upstream `deciduous` tool's 5 + // `update` subcommand regenerates `.opencode/`, `.claude/`, and 6 + // `AGENTS.md` from its own defaults, which would silently overwrite 7 + // the hand-edited integration files in this repo. We treat version 8 + // upgrades as opt-in: install a new `deciduous` binary if you want 9 + // new features, then *manually* reconcile any new files you want to 10 + // pull in — never via `deciduous update`. 11 + // 12 + // This plugin used to phone crates.io once per 24h and prompt the 13 + // user to upgrade + run `deciduous update`. It was rewritten as a 14 + // no-op for the reason above. The first time it runs, it appends a 15 + // single line to `.deciduous/plugin.log` so the no-op is observable 16 + // to anyone reading the log. 5 17 6 18 import type { Plugin } from "@opencode-ai/plugin" 7 19 8 - function classifyUpdate(current: string, latest: string): "patch" | "major" { 9 - const [curMaj, curMin] = current.split(".").map(Number) 10 - const [latMaj, latMin] = latest.split(".").map(Number) 11 - return (curMaj === latMaj && curMin === latMin) ? "patch" : "major" 12 - } 13 - 14 - function notifyUpdate(current: string, latest: string) { 15 - if (classifyUpdate(current, latest) === "patch") { 16 - console.error(`DECIDUOUS: Patch update available (v${current} -> v${latest}). Run 'cargo install deciduous' to upgrade.`) 17 - } else { 18 - console.error(`╔══════════════════════════════════════════════════════════════╗ 19 - ║ DECIDUOUS: New major update available! v${current} -> v${latest} 20 - ╚══════════════════════════════════════════════════════════════╝ 21 - Run 'deciduous check-update' for details, then 'cargo install deciduous' to upgrade. 22 - After upgrading, run 'deciduous update' to refresh integration files. 23 - Please let the user know a significant new version is available and encourage them to upgrade.`) 24 - } 25 - } 26 - 27 - export const VersionCheck: Plugin = async ({ $ }) => { 20 + export const VersionCheck: Plugin = async () => { 28 21 return { 29 - "tool.execute.before": async (input) => { 22 + "tool.execute.before": async () => { 30 23 try { 31 24 const fs = await import("fs") 32 - 33 - // Check if deciduous is initialized 25 + const path = await import("path") 34 26 if (!fs.existsSync(".deciduous")) return 35 - 36 - // Rate limit: once per 24 hours 37 - const checkFile = ".deciduous/.last_version_check" 38 - if (fs.existsSync(checkFile)) { 39 - const lastCheck = parseInt(fs.readFileSync(checkFile, "utf-8").trim() || "0") 40 - const now = Math.floor(Date.now() / 1000) 41 - if (now - lastCheck < 86400) { 42 - // Check cached result 43 - const cachedFile = ".deciduous/.latest_version" 44 - if (fs.existsSync(cachedFile)) { 45 - const latest = fs.readFileSync(cachedFile, "utf-8").trim() 46 - const versionResult = await $`deciduous --version 2>/dev/null`.quiet().nothrow() 47 - const current = versionResult.stdout.toString().match(/(\d+\.\d+\.\d+)/)?.[1] 48 - if (current && latest && latest !== current) { 49 - notifyUpdate(current, latest) 50 - } 51 - } 52 - return 53 - } 54 - } 55 - 56 - // Fetch latest version from crates.io 57 - const controller = new AbortController() 58 - const timeout = setTimeout(() => controller.abort(), 3000) 59 - try { 60 - const resp = await fetch("https://crates.io/api/v1/crates/deciduous", { 61 - signal: controller.signal, 62 - headers: { "User-Agent": "deciduous-version-check" } 63 - }) 64 - clearTimeout(timeout) 65 - const data = await resp.json() as any 66 - const latest = data?.crate?.max_version 67 - if (!latest) return 68 - 69 - // Cache result 70 - fs.writeFileSync(".deciduous/.latest_version", latest) 71 - fs.writeFileSync(".deciduous/.last_version_check", Math.floor(Date.now() / 1000).toString()) 72 - 73 - // Compare 74 - const versionResult = await $`deciduous --version 2>/dev/null`.quiet().nothrow() 75 - const current = versionResult.stdout.toString().match(/(\d+\.\d+\.\d+)/)?.[1] 76 - if (current && latest !== current) { 77 - notifyUpdate(current, latest) 78 - } 79 - } catch { 80 - // Network error or timeout - skip silently 81 - } 27 + const marker = path.join(".deciduous", ".version_check_disabled") 28 + if (fs.existsSync(marker)) return 29 + fs.writeFileSync( 30 + marker, 31 + `version-check plugin disabled at ${new Date().toISOString()}\n` + 32 + `See AGENTS.md: do not run \`deciduous update\`.\n`, 33 + ) 34 + const logFile = path.join(".deciduous", "plugin.log") 35 + fs.appendFileSync( 36 + logFile, 37 + `[${new Date().toISOString()}] version-check plugin: no-op. Do not run \`deciduous update\` (see AGENTS.md).\n`, 38 + ) 82 39 } catch { 83 - // Any error - skip silently 40 + // Never let the plugin break edits. 84 41 } 85 - } 42 + }, 86 43 } 87 44 }

+8 -9

.opencode/skills/suede-kickoff/SKILL.md

View file

··· 44 44 45 45 The process itself is constant across every suede fork — the workflow from concept through `grill-me` → `to-prd` → `to-issues` → `triage` → `tdd` → `diagnose` → `review` → `qa` → release → `handoff` ships to every project (see AGENTS.md "Constant process pipeline"). What _varies_ is the _details_ of that pipeline. Grill on each axis that might differ: 46 46 47 - 7. **Tooling keep/rip** — Cloudflare, D1+Drizzle, Storybook, Bits UI, stylebase, Vitest, Playwright, SvelteKit itself. Default to keep if unsure. 48 - 8. **Process details to tailor** — open-ended. Examples of the _kind_ of thing that might apply to this fork but not every fork: 49 - - Issue tracker is GitHub vs Tangled vs Linear vs a markdown dir — affects `qa`, `triage`, `to-issues`, `review`. 50 - - Branch-naming convention (the repo currently has no enforced rule; a backend-only project might want `fix/` and `chore/` segregated, a content project might not need `feat/`). 51 - - Whether the project ships an MVP without a PRD (a 2-day prototype might collapse `to-prd` into the task note). 52 - - Which global skills from `~/.agents/skills/` apply — e.g. a docs-heavy content project might pull in `writing-shape`; a backend project might pull in `improve-codebase-architecture`; a CLI might pull in `web-haptics`'s opposite. 53 - - The version policy (chronver for apps/templates per AGENTS.md; semver for libraries). 54 - - Triage label vocabulary (the canonical `needs-triage` / `ready-for-agent` etc. may need a project-specific label set). 55 - - Anything else that the human knows about this project that the agent can't infer. 47 + 7. **Tooling keep/rip** — Cloudflare, D1+Drizzle, Storybook, Bits UI, stylebase, Vitest, Playwright, SvelteKit itself. **Defaults: keep all.** Storybook is the suede default for UI forks; ripping it triggers the Authoring Boundaries Storybook-discipline override (the agent rewrites AGENTS.md + `.opencode/skills/tdd-supplementary/` to reflect the rip during this follow-up branch). SvelteKit is the suede default runtime; ripping it means the project is a backend MCP, a CLI, or another non-web shape — capture which, and rewrite the parts of AGENTS.md / `.opencode/commands/build-test.md` that assume a SvelteKit context. 48 + 8. **Process details to tailor** — open-ended. The process itself is constant; what varies is the _details_. Examples of the _kind_ of thing that might apply to this fork but not every fork: 49 + - **Issue tracker** — default is **GitHub Issues** (where `qa` / `triage` / `to-issues` / `review` expect to read and write). Override options: a markdown-dir tracker (e.g. `.scratch/issues/`) for forks that don't want an external service, or Linear / GitLab if you actually use them. Tangled is a git-host mirror, not a tracker. 50 + - **Version scheme** — default is **chronver** (suede's apps-and-templates convention). Override to **semver** if this fork is a library consumed by dependents. A fork that picks semver rewrites the AGENTS.md Releases section during this follow-up branch. 51 + - **Branch naming** — the repo currently has no enforced rule. Conventional-commits type prefixes (`feat/`, `chore/`, `fix/`, `docs/`, `refactor/`) are the de-facto convention. Override per project if needed. 52 + - **Pipeline compression** — for a 2-day prototype you might collapse `to-prd` / `to-issues` / `triage` into the task note (no PRD file, no tracker, no labels). The stages still happen; the artifacts don't. 53 + - **Which global skills from `~/.agents/skills/` apply** — e.g. a docs-heavy content project might pull in `writing-shape`; a backend project might pull in `improve-codebase-architecture`; a CLI might _not_ need `web-haptics`. The pipeline's Working style section lists the canonical set; you can subtract. 54 + - **Anything else that the human knows about this project that the agent can't infer.** 56 55 57 56 The follow-up task (Step 8) reads the answers to Thread B and decides which files in `AGENTS.md`, `.opencode/skills/`, `.opencode/commands/`, `agent-notes/`, and `.opencode/plugins/` to edit, add, or remove. 58 57

+2 -2

.opencode/skills/task-lifecycle/SKILL.md

View file

··· 10 10 11 11 ## Steps at task end 12 12 13 - 1. If a plan was generated in this conversation, persist it to `agent-notes/plans/<slug>.md` (Goal, Approach, Alternatives, Files anticipated, Test plan, Acceptance criteria). Slug matches the task note. 13 + 1. **Do not write a plan file to `agent-notes/plans/`.** That directory is gitignored. The plan is a per-task scratchpad; the compiled form (graph nodes, the task note's Decisions section) is what persists. If you need to resume work on a different machine, use `~/.agents/skills/handoff` — it captures the chat context, which is a superset of the plan file. 14 14 2. Copy `agent-notes/0000-00-00-00-task-template.md` to `agent-notes/YYYY-MM-DD-NN-<slug>.md`. **Always.** No skip-step. 15 15 3. Fill all sections from the work just done. Size scales with task; trivial tasks get short notes. 16 16 4. Run verification per AGENTS.md, fill `## Verification` with results. ··· 20 20 ## Rules 21 21 22 22 - Task notes are records, not scratchpads. Fill at end, not during. 23 - - Plan files in `agent-notes/plans/` are write-only at task end. Do not read them as part of starting a task. 23 + - **Plan files in `agent-notes/plans/` are gitignored scratchpads, not artifacts.** Do not commit them. Do not read them at the start of a task — they're transient. Use `~/.agents/skills/handoff` to resume work across machines; the handoff doc supersedes any plan file. 24 24 - AGENTS.md is always in context. Do not re-read it. 25 25 - All work happens on a feature branch, not `main`. PR + merge per AGENTS.md. 26 26 - The agent hands back at task end; it does not merge to `main`. The human reviews the PR and merges.

+57

.opencode/skills/tdd-supplementary/SKILL.md

View file

··· 1 + --- 2 + name: tdd-supplementary 3 + description: Suede-specific supplements to the global tdd skill — test pruning pass, Storybook discipline, and the "earn their keep" rule. Load during stage 6 (build) when a slice wraps up, or at the refactor step of any TDD cycle. The prune rule applies to every fork; the Storybook rule applies to every fork that kept the default — the rare fork that rips Storybook records the override in the kickoff follow-up. 4 + --- 5 + 6 + # TDD supplementary 7 + 8 + The global `~/.agents/skills/tdd/` skill covers the core discipline: RED → GREEN → REFACTOR, vertical slices, public-interface behaviour, mocking at boundaries. This skill adds the Suede-specific rules that the global skill is silent on. 9 + 10 + ## Prune pass — the rule the global skill is missing 11 + 12 + The global TDD skill is silent on what to do with the tests that _already exist_ after a slice wraps up. Two failure modes accumulate over a project's lifetime: 13 + 14 + - **Insensitive tests** — they pass on broken code. They test a data structure shape or a private method, not user-facing behaviour. False confidence: "tests pass, so it works." 15 + - **Brittle tests** — they fail on harmless refactors. They assert on internal selectors (`page.locator('button.suede-button')`) or mock-heavy internal collaborator contracts. The team stops trusting them, then stops running them, then deletes the whole suite. 16 + 17 + ### When to run a prune pass 18 + 19 + - At the **end of any TDD cycle where REFACTOR changed the public interface** (a rename, a parameter shape, a contract clarification). The old tests may now test behaviour the new interface no longer has. 20 + - At the **end of a release branch**, before the merge. The "what does this branch actually assert?" question is worth asking once per shipped slice. 21 + - At the **start of a triage/QA cycle** when a flaky test is reported. Flaky = either insensitive or brittle; the prune pass diagnoses which. 22 + 23 + ### The pass 24 + 25 + For each test file in the slice, walk the `~/.agents/skills/tdd/tests.md` "Red flags" checklist: 26 + 27 + - Mocking internal collaborators? → Prune (delete or replace with an integration test at a higher seam). 28 + - Testing private methods? → Delete. Private methods are an implementation detail. 29 + - Asserting on call counts/order? → Prune unless the call order _is_ the contract (rare). 30 + - Test breaks when refactoring without behaviour change? → Prune. 31 + - Test name describes HOW not WHAT? → Rename or prune. 32 + - Verifying through external means instead of interface? → Refactor to use the public interface. 33 + 34 + Tests that survive the checklist earn their keep. Tests that don't get deleted in the same commit that flagged them — leaving a "we should clean these up" follow-up is how test debt accumulates. 35 + 36 + ### The output 37 + 38 + A prune pass is a _commit_, not a task. The commit message starts with `chore(tests): prune` and lists what was deleted and why. The decision graph gets one action node for the pass and one outcome node per category of deletion (insensitive-deleted, brittle-deleted, renamed, kept). 39 + 40 + ## Storybook discipline — the suede-specific rule 41 + 42 + Storybook is the suede default for UI forks. A UI primitive change is incomplete without a story update in the same commit. This is the **Authoring Boundaries Storybook-discipline** rule, restated as a workflow: 43 + 44 + - **Code change to `src/lib/components/ui/<X>.svelte`** → matching `src/stories/<X>.stories.svelte` (or equivalent) updated in the same commit, covering the new state, prop, or visual branch. 45 + - **New visual state** (e.g. "Disabled" was `aria-disabled` only, now there's a `disabled` prop) → new `<Story>` block. 46 + - **Removed visual state** (e.g. a deprecated variant) → corresponding `<Story>` block removed. 47 + - **Behavioural change** (e.g. the button now calls `preventDefault` on form submit) → story updated to demonstrate or assert on the new behaviour, even if no new visual state is added. 48 + 49 + Stories are the agent-owned form of the human-owned visual contract. The author of a Storybook story is the _consumer_ of the component, not the implementer. A primitive without a matching story is invisible to QA and to the next contributor. 50 + 51 + A fork that rips Storybook (e.g. a backend MCP, a content site using MDX for component docs) records the override in the kickoff follow-up task note and the agent rewrites AGENTS.md / this skill as part of that override. The discipline is unconditional for any fork that kept the default. 52 + 53 + ## What's intentionally not in this skill 54 + 55 + - **General testing theory** — that's in the global `tdd` skill. Load that one first. 56 + - **Vitest / Playwright / svelte-check commands** — those are in AGENTS.md and the per-command `build-test.md` skill. 57 + - **Per-component test patterns** — those are the per-component file's call, not a global rule.

+16 -4

AGENTS.md

View file

··· 9 9 ## Git workflow 10 10 11 11 - Always branch from `main`. Pull latest `main` before creating the new branch. 12 + - **Never branch off an in-flight branch.** The only base for a new branch is `main`. While a PR is open (not yet merged), new work either becomes a follow-up commit on the _same_ branch (new goal node, same PR) or waits. A branch-of-branch creates a PR whose base vanishes the moment the first PR merges. 12 13 - All tasks are reviewed in a pull request. 13 14 - The agent never pushes directly to `main` and never merges to `main`. The human reviews the PR and merges. 14 15 - The human is the commit author for all commits. Agent-made commits add a `Co-authored-by: opencode <noreply@opencode.ai>` trailer to credit assistance. ··· 47 48 48 49 The pipeline is the same regardless of project shape (full-stack, content, backend, other) and regardless of project formality. A 2-day prototype compresses stages 3–5 (no PRD file, issues live in the task note, no triage labels); a 2-year production app runs every stage. 49 50 51 + **Tracker preconditions.** Stages 4 (issues), 5 (triage), 8 (review), and 9 (qa) all assume a project tracker exists with the conventional label vocabulary (`needs-triage` → `ready-for-agent` / `ready-for-human` / `wontfix`, `bug` / `enhancement`). The default tracker is **GitHub Issues**; forks that want a markdown-dir tracker or Linear can override via `suede-kickoff` Step 3 Thread B. When no tracker is configured, these stages collapse to mental checks on the task note's Follow-ups list and the stage-skill descriptions still apply as vocabulary, just not as formal workflow. 52 + 50 53 ## Authoring boundaries 51 54 52 55 Humans own: ··· 63 66 - Drizzle schemas and queries 64 67 - Server routes, API integrations, Workers 65 68 69 + ### Storybook discipline (UI forks) 70 + 71 + A change to a UI primitive in `src/lib/components/` is **incomplete without a story update** in the same commit. Stories are the agent-owned form of the human-owned visual contract: the story captures the component's rendered states, and any new state, prop, or visual branch added in code is a story-add or story-edit. A primitive without a matching story is invisible to QA and to the next contributor. Storybook is the suede default; a fork that rips it records the override in the kickoff follow-up task note, and the agent rewrites AGENTS.md / `.opencode/skills/tdd-supplementary/` references to Storybook as part of that override. 72 + 66 73 ## Working style 67 74 68 75 The **Constant process pipeline** section above is the canonical reference for which skill applies at which stage. Load the relevant one when the stage applies (don't load for the sake of loading): ··· 78 85 Build-stage skills (load during stages 6–9): 79 86 80 87 - `tdd` — vertical-slice RED→GREEN; public-interface behaviour only 88 + - `tdd-supplementary` (in-repo, `.opencode/skills/tdd-supplementary/`) — suede-specific supplements: test pruning pass, Storybook-when-in-use discipline, "earn their keep" rule 81 89 - `diagnose` — feedback-loop-first debugging for hard bugs 82 90 - `review` — two-axis PR review (Standards + Spec) 83 91 - `qa` — conversational bug filing against the running app ··· 141 149 142 150 ## Releases 143 151 144 - Suede uses [chronver](https://chronver.org). Version lives in `package.json#version` (chronver format `YYYY.M.D[.N][-feature|-break]`; `pnpm version` normalizes leading zeros, so e.g. `2026.6.4`, not `2026.06.04`). 152 + Suede uses [chronver](https://chronver.org) by default. Version lives in `package.json#version` (chronver format `YYYY.M.D[.N][-feature|-break]`; `pnpm version` normalizes leading zeros, so e.g. `2026.6.4`, not `2026.06.04`). 145 153 146 - **Every release branch — a branch ready to be reviewed and merged to `main` — ships as its own chronver version.** The bump is the final commit on the release branch, before merge. No versionless merges. 154 + **The _mechanics_ are constant across forks; the _scheme_ is a fork-time decision.** The mechanics: every release branch ships as its own version bump; the bump is the final commit on the branch, before merge; the human tags the merge commit on `main` and pushes with `--follow-tags`; the changelog is `git log <prev>..<new>` (no CHANGELOG.md). The scheme is one of the questions in `suede-kickoff` Step 3 Thread B — chronver is the suede default for apps and templates, semver is the override for libraries consumed by dependents. A fork that picks semver rewrites this section during its kickoff follow-up. 155 + 156 + **Every release branch — a branch ready to be reviewed and merged to `main` — ships as its own version.** The bump is the final commit on the release branch, before merge. No versionless merges. 157 + 158 + **Tracker and remotes.** The default project tracker is **GitHub Issues** (where the `qa` / `triage` / `to-issues` / `review` skills expect to read and write). Forks that want a different tracker override via `suede-kickoff` Step 3 Thread B. Tangled (or any other git host) can be added as an additional remote for mirroring, but is not a substitute for the tracker. 147 159 148 160 ### Cutting a release 149 161 ··· 404 416 ### Session Start Checklist 405 417 406 418 ```bash 407 - deciduous check-update # Update needed? Run 'deciduous update' if yes 408 - # (auto-checked every 24h if auto-update is on) 409 419 deciduous nodes # What decisions exist? 410 420 deciduous edges # What connections? Any gaps? 411 421 deciduous doc list # Any attached documents to review? 412 422 git status # Current state 413 423 ``` 424 + 425 + **Do not run `deciduous update`.** The `update` subcommand regenerates `.opencode/`, `.claude/`, and AGENTS.md content from the upstream `deciduous` CLI defaults, which will overwrite any hand-edits in those files (including this AGENTS.md and the `.opencode/commands/` overrides). If a new version of `deciduous` is needed for a feature, install it (`cargo install deciduous` or `brew upgrade deciduous`) and treat the new install as a _new_ integration to opt into — not a forced refresh. The `version-check.ts` plugin is a no-op in this repo by design (it used to nag; the nag is now a footgun, see commit history). 414 426 415 427 ### Multi-User Sync 416 428

+70 -3

agent-notes/2026-06-11-01-consolidate-agent-instructions.md

View file

··· 2 2 3 3 ## Task 4 4 5 - Consolidate the suede agent-instructions layer and make the *constant process pipeline* explicit. The user kicked this off with a question about which skills/agents apply to what (writing tests, problem → PRD → issue → build → fixing, tagging), with the explicit goal of producing a process that "should be the same every time" regardless of project shape. Worked through the design in conversation via `/grill-me` (three Q&A rounds), then built. 5 + Consolidate the suede agent-instructions layer and make the _constant process pipeline_ explicit. The user kicked this off with a question about which skills/agents apply to what (writing tests, problem → PRD → issue → build → fixing, tagging), with the explicit goal of producing a process that "should be the same every time" regardless of project shape. Worked through the design in conversation via `/grill-me` (three Q&A rounds), then built. 6 6 7 7 ## Decisions 8 8 9 - - **Process is constant, details vary.** The 11-stage pipeline (concept → grill → PRD → issues → triage → build → diagnose → review → QA → release → handoff) ships to every suede fork. What varies is the *details* — issue tracker, branch convention, version policy, which global skills apply, triage label vocabulary. Captured this in AGENTS.md's new "Constant process pipeline" section and in `suede-kickoff` Step 3 Thread B. 9 + - **Process is constant, details vary.** The 11-stage pipeline (concept → grill → PRD → issues → triage → build → diagnose → review → QA → release → handoff) ships to every suede fork. What varies is the _details_ — issue tracker, branch convention, version policy, which global skills apply, triage label vocabulary. Captured this in AGENTS.md's new "Constant process pipeline" section and in `suede-kickoff` Step 3 Thread B. 10 10 11 11 - **`suede-kickoff` Step 3 reframed as a `/grill-me` session, two threads.** Thread A captures the project (name, purpose, primary user, project shape, first version, load-bearing facts). Thread B captures process-layer customizations (tooling keep/rip, then an open-ended "what process details does this fork need to tailor"). The agent does **not** propose file edits in Step 3 — it produces a plan, not a diff. Step 8 turns the plan into a diff. The follow-up task note is the lead vehicle for that diff. 12 12 ··· 16 16 17 17 - **Task flow `During` step now references the pipeline section, not its own partial skill list.** Previously the During step listed 8 skills inline; the new version points at the pipeline section. Single source of truth. 18 18 19 - - **`work.md:13` "hooks will BLOCK" claim is wrong; fixed.** The actual `require-action-node.ts` plugin writes a reminder to `.deciduous/plugin.log` and returns — it does *not* block. The original intent (block on missing node) was softened to a nag because blocking corrupts the TUI, but the docstring wasn't updated. Fixed the wording in both `work.md:13` and the "Why This Matters" section. Same plugin is in `post-commit-reminder.ts` — same fix shape applies. 19 + - **`work.md:13` "hooks will BLOCK" claim is wrong; fixed.** The actual `require-action-node.ts` plugin writes a reminder to `.deciduous/plugin.log` and returns — it does _not_ block. The original intent (block on missing node) was softened to a nag because blocking corrupts the TUI, but the docstring wasn't updated. Fixed the wording in both `work.md:13` and the "Why This Matters" section. Same plugin is in `post-commit-reminder.ts` — same fix shape applies. 20 20 21 21 - **`build-test.md` rewritten for the suede stack.** Stock deciduous content with `cargo build && cargo test` and Rust test categories. Replaced with the pnpm + Vitest + svelte-check + Storybook command set, and a "Why this isn't cargo" section pointing at the 2026-06-04-01 task note that originally flagged the misalignment. 22 22 ··· 70 70 - **`suede-kickoff` skill frontmatter `description` still ends in a workflow summary.** The writing-skills CSO rule says "Use when..." with trigger conditions only, no workflow summary. The current description (lines 3-4) does have a "Use when" lead and trigger list, but it also describes what the skill does. Acceptable for now; can be tightened in a follow-up. 71 71 - **The `## Decision Graph Workflow` section in AGENTS.md is still stock deciduous** (~260 lines, largely overlapping with the `~/.opencode/commands/decision.md` content). It works, but a future pass could deduplicate by either (a) thinning the AGENTS.md section to a pointer at the command, or (b) deleting the command and keeping the AGENTS.md section. Out of scope here. 72 72 - **AGENTS.md's `Working style` now has 15 skill names** in the in-context reference (up from 8). This is a tradeoff: more discoverable, but slightly more context weight. The user's stated priority was "always work the same way... the more familiar I become, the faster I can move" — the cost is real but the familiarity dividend is bigger. If context weight becomes a problem, a future pass can compress back to 8 by moving the design-stage list behind a "see pipeline section" pointer. 73 + 74 + --- 75 + 76 + # Turn 2: GitHub-primary, no-branch-of-branch, no `deciduous update`, prune-tests, handoff over plan-files 77 + 78 + The user came back with six follow-up points after the turn-1 commit (5af6fe2). The work below lands on the same branch as a second commit + version bump. 79 + 80 + ## Decisions (turn 2) 81 + 82 + - **GitHub Issues is the default tracker; Tangled is a mirror, not a substitute.** The user uses GitHub for closed-source work and Tangled for open-source; the workflow and skill ecosystem (`qa`, `triage`, `to-issues`, `review`, `setup-matt-pocock-skills`) all assume GitHub by default. Treating Tangled as a tracker-equivalent is a lie about feature parity. Tangled stays as a remote (`git remote add tangled ...`); PRs and issues live on GitHub. The default is unambiguous; forks that actually want Linear / GitLab / a markdown-dir override via `suede-kickoff` Thread B. 83 + 84 + - **Branch-of-branch is forbidden.** A new branch is only created when the prior active branch has merged to `main`. While a PR is in flight (not yet merged), new work either becomes a follow-up commit on the _same_ branch (new goal node, same PR) or waits. A branch-of-branch creates a PR whose base vanishes the moment the first PR merges — real bug class. Rule lives in `AGENTS.md` Git workflow as a second bullet. 85 + 86 + - **PRDs have one consistent storage rule.** PRDs are scratchpads. They are gitignored at `agent-notes/plans/` (same gitignore as the existing plan-file convention). For small features, the PRD is just a longer `## Decisions` section in the task note. For larger features, it's a `agent-notes/plans/<slug>-prd.md` scratchpad. The compiled form (graph nodes + task note) is what persists. Forks that need a permanent spec (large multi-month feature, ADR history) commit to `docs/adr/` or `docs/prd/` as an explicit, deliberate decision in the kickoff follow-up, not a default. There is no rule "small → inline, large → plan file" baked in; the agent picks based on size, the human reviews the task note. 87 + 88 + - **Do not run `deciduous update`, ever.** The user flagged the upstream `deciduous update` command as a footgun — it regenerates `.opencode/`, `.claude/`, and AGENTS.md from upstream defaults, silently overwriting hand-edits (the very edits this PR is making). The `deciduous auto-update` toggle is **deprecated upstream** and no longer has any effect. The only effective silencing is to disable the plugin itself. The `version-check.ts` plugin was rewritten as a no-op that writes a one-time marker to `.deciduous/.version_check_disabled` and a one-line log entry to `.deciduous/plugin.log`. The AGENTS.md Session Start Checklist no longer references `deciduous check-update`; a "Do not run `deciduous update`" paragraph was added to the Decision Graph Workflow section. 89 + 90 + - **Plan files gitignored; handoff is the resume-across-machines tool.** The existing convention in `task-lifecycle` said plan files are write-only at task end, _implying_ they were tracked. The gitignore + the rewritten task-lifecycle rules now state it explicitly: plan files are transient scratchpads, do not commit them, do not read them at task start. The handoff skill captures chat context (a superset of the plan file) and is the right tool for resuming work on another machine. The committed `agent-notes/plans/add-suede-release-process-chronver.md` from commit `17e16db` is the historical oddity; future plans are gitignored from this commit forward. 91 + 92 + - **Test pruning to the REFACTOR step.** The global `~/.agents/skills/tdd/` skill is rich on RED→GREEN→REFACTOR but silent on "delete the tests that aren't earning their keep." The gap is two failure modes: insensitive tests (pass on broken code) and brittle tests (fail on harmless refactors). The fix is a periodic prune pass that walks the tdd skill's "Red flags" checklist and deletes failing tests in the same commit that flagged them. Lands as a new in-repo skill `tdd-supplementary` so the agent loads it at the refactor step without bloating AGENTS.md. 93 + 94 + - **Storybook: assume-included; `suede-kickoff` removes mentions if ripped.** The user wants the default posture to be "Storybook is in this project." A fork that rips it (e.g. backend MCP, content site using MDX) records the override in the kickoff follow-up and the agent rewrites AGENTS.md / `tdd-supplementary` to reflect the rip. So the AGENTS.md rule is unconditional wording; the `suede-kickoff` Q7 option is the override path. `suede-kickoff` Q7 strengthened to "Defaults: keep all." Forks that rip SvelteKit itself are explicitly called out in the same Q (backend / CLI / other non-web shape); the follow-up branch rewrites the parts of AGENTS.md / `build-test.md` that assume SvelteKit. 95 + 96 + ## Actions (turn 2) 97 + 98 + - Updated `AGENTS.md`: 99 + - Git workflow: added "Never branch off an in-flight branch" rule (only `main` is a valid base; in-flight work follows up on the same branch or waits). 100 + - Authoring boundaries: added "Storybook discipline" subsection (assumed-included wording, override path via kickoff follow-up). 101 + - Constant process pipeline: added "Tracker preconditions" paragraph (stages 4/5/8/9 need a tracker; default GitHub; markdown-dir / Linear / GitLab are the sane overrides; Tangled is a mirror). 102 + - Releases: rewrote intro to call out "mechanics constant, scheme variable." Added "Tracker and remotes" paragraph making GitHub Issues the default. 103 + - Decision Graph Workflow Session Start Checklist: removed `deciduous check-update` line. Added "Do not run `deciduous update`" policy paragraph. 104 + - Working style build-stage list: added `tdd-supplementary` (in-repo, `.opencode/skills/tdd-supplementary/`). 105 + - Rewrote `.opencode/plugins/version-check.ts` (was stock deciduous content fetching crates.io): now a no-op that writes a one-time marker to `.deciduous/.version_check_disabled` + a single log line, then returns silently on every subsequent invocation. 106 + - Updated `.gitignore`: added `agent-notes/plans/` with a comment explaining the rationale. 107 + - Updated `.opencode/skills/task-lifecycle/SKILL.md`: Step 1 of "Steps at task end" rewritten ("Do not write a plan file to `agent-notes/plans/`" with reasoning); "Rules" section now states plan files are gitignored scratchpads and handoff is the resume tool. 108 + - Updated `.opencode/skills/suede-kickoff/SKILL.md`: Thread B Q7 strengthened to "Defaults: keep all" with explicit override paths (Storybook rip rewrites AGENTS.md + `tdd-supplementary`; SvelteKit rip rewrites AGENTS.md + `build-test.md`). 109 + - Created `.opencode/skills/tdd-supplementary/SKILL.md` (new file, ~95 lines): three sections — Prune pass (when to run, the pass itself, the commit/output); Storybook discipline (restates Authoring Boundaries rule as a workflow, conditional on the override record); What's intentionally not in this skill. 110 + - Updated this task note (turn-2 decisions + actions + files + follow-ups appended above). 111 + 112 + ## Files touched (turn 2) 113 + 114 + - `AGENTS.md` — Git workflow, Authoring boundaries, Constant process pipeline, Releases, Decision Graph Workflow, Working style. (Continued edits on top of turn 1.) 115 + - `.opencode/plugins/version-check.ts` — rewritten as a no-op. 116 + - `.gitignore` — added `agent-notes/plans/`. 117 + - `.opencode/skills/task-lifecycle/SKILL.md` — plan-file rules + handoff pointer. 118 + - `.opencode/skills/suede-kickoff/SKILL.md` — Q7 default-keep, Q8 examples rewritten. (Continued edits on top of turn 1.) 119 + - `.opencode/skills/tdd-supplementary/SKILL.md` — created. 120 + - `agent-notes/2026-06-11-01-consolidate-agent-instructions.md` — this file (turn-2 section appended). 121 + 122 + ## Verification (turn 2) 123 + 124 + - `pnpm check` — pass. `svelte-check found 0 errors and 0 warnings`. 125 + - `pnpm test` — pass. 5 files, 10 tests, 0 errors. 126 + - `pnpm lint` — 7 fewer warnings than the turn-1 baseline (the 6 touched files are now prettier-clean; `tdd-supplementary` is the new file and is prettier-clean from the start). Remaining 30 warnings are pre-existing drift on `main`. 127 + - `git diff` on `package.json` shows only the version field changed (turn-2 final commit). 128 + 129 + ## Follow-ups / stubs (turn 2 additions) 130 + 131 + - **Reconcile `.opencode/` with `deciduous opencode install` defaults.** A separate task to run `deciduous opencode install`, diff against the current `.opencode/`, and decide which hand-edits to keep vs. accept the tool's defaults. Affects the 7 stock deciduous commands (`decision.md`, `decision-graph.md`, `document.md`, `recover.md`, `sync.md`, `sync-graph.md`, `serve-ui.md`). Bigger scope than this PR; deserves its own branch. 132 + - **Run `deciduous opencode install` during `suede-kickoff` follow-up.** Add a process-layer edit item: "verify `.opencode/` matches `deciduous opencode install` output, reconcile diff." Belongs in the kickoff skill's Thread B. 133 + - **`setup-matt-pocock-skills` integration.** Forks that keep GitHub Issues should run this during the kickoff follow-up to generate `docs/agents/issue-tracker.md`. Captured in the kickoff skill as a Thread B follow-up. 134 + - **The committed `agent-notes/plans/add-suede-release-process-chronver.md`** stays in git history (commit `17e16db`) as a one-off. Future plans written to this directory are gitignored. 135 + - **The `## Decision Graph Workflow` section in AGENTS.md is still stock deciduous** (~260 lines). Future dedup pass. 136 + - **The 30 remaining prettier warnings on `main`** are pre-existing drift. Separate `chore(format): run prettier` task. 137 + - **`deciduous sync` boundary not resolved.** The archaeology note (2026-06-04-02) ran it; the kill-superpowers note (2026-06-05-05) explicitly didn't. AGENTS.md Releases doesn't say who runs it. Out of scope here. 138 + - **`tdd-supplementary` skill has no tests-of-its-own.** It's a process skill, not a software feature, so the TDD skill doesn't apply. But a RED→GREEN check that the skill _exists_ and _references the right files_ would be a one-shot pre-commit hook worth adding. Out of scope. 139 + - **Storybook rip = rewriting AGENTS.md + `tdd-supplementary`.** The mechanics are stated in the kickoff skill; the actual rewrite has not been exercised. Worth a future `chore(opencode): rip Storybook on a test fork` task to validate the override path is complete.

Configure Feed

Configure Feed