Commits
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Layout gains SYSTEMS_MAP.md and defers the repo map to its Layout tree
- Pipeline review stage notes the CI invocation path (pi-review.yml)
- Fix stale Thread B Q9 reference (commit-type overrides live under Q8)
- Record the pnpm-version-rejects-.N-chronver gotcha in the release steps
- Overview example swaps retired 'label vocabulary' for 'commit types'
- 'Decision Graph Workflow' header to sentence case, refs updated
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Every fork needs MINIMAX_API_KEY before pi-review.yml can run; repo
secrets don't inherit. Step 8 now sets it right after the remote is
created (op read from 1Password piped to gh secret set) and the hand-back
checklist verifies it — or it's carried as an unchecked follow-up item
when op is unavailable or the remote was deferred.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Security-review finding: gh pr checkout put the untrusted PR branch's
.pi/ in Pi's discovery path, and --approve trusted it — a fork PR could
ship a modified review skill or an extension and execute arbitrary code
with the API-key secrets in env. Now the .pi/ process layer is
snapshotted from main before the branch switch, Pi runs with --no-approve
--no-extensions --no-skills --no-prompt-templates --no-context-files
--tools read,bash, and the prompt directs it to the trusted snapshot,
treating the working tree strictly as data under review.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replace claude-review.yml with pi-review.yml. Same triggers and
hardening (/review comment gated to owner/member/collaborator, numeric
PR-number validation, dispatch input, concurrency, contents: read); the
review itself now runs via @earendil-works/pi-coding-agent in --print
mode with --approve (trusts the checked-out .pi/skills) and
--exclude-tools edit,write. Provider defaults to minimax/MiniMax-M3,
overridable via PI_REVIEW_PROVIDER / PI_REVIEW_MODEL repo variables.
Report lands as one top-level PR comment via gh (no inline-comment MCP
under Pi); the skill's no-subagent sequential fallback is pinned in the
prompt. Requires the MINIMAX_API_KEY repo secret.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Second changeset of the day (chronver .N suffix): SYSTEMS_MAP.md and the
on-demand Claude review workflow. Hand-edited bump — pnpm version rejects
four-segment chronver as invalid semver.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
.github/workflows/claude-review.yml runs the project's own two-axis
review skill (.pi/skills/review/SKILL.md) against a PR via
anthropics/claude-code-action@v1. Invoked two ways: a '/review' comment
on the PR (owner/member/collaborator only) or a workflow dispatch with a
PR number. The prompt pins the skill's bindings for CI — merge-base as
the fixed point, PR body as the spec — and the report lands as a
top-level PR comment plus inline comments. Read-only on contents;
allowedTools limited to gh/git read commands and comment posting.
Requires the ANTHROPIC_API_KEY repo secret, not yet configured.
SYSTEMS_MAP.md: add .github/workflows/ to the Layout tree (omitted at
creation) and record the new GitHub-invocable seam on the process layer.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Six areas divided by reason for change (app shell, UI foundation, stubbed
data layer, platform/deploy, verification harness, process layer), each
with mandatory Seams and Fragile fields. Opens with a commented ASCII
layout tree; the systems-map skill gains the matching format rule so the
tree is maintained (files it names move/appear/disappear) without becoming
a per-change tax.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
pnpm version bumped both manifests; the lockfile missed the release
commit's staging.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
pnpm lint (prettier --check) flagged 8 markdown files; formatting only,
no content changes. pnpm lint and pnpm check both pass after this.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- AGENTS.md: pipeline collapses 11 stages to 6 (align, cut plan, build,
review, release around the concept input); Task flow section delegates
to /skill:task; co-author trailer becomes harness-agnostic; release
checklist gains the decision-graph-value line and the full-journey run
- README: happy path updated to the six stages; .opencode references gone
- .gitignore: add tmp/ (slice-brief working copies); un-ignore
.deciduous/sync/ so the decision-graph skill's documented sync flow is
actually possible; drop the dead .opencode workspace block; reword the
stale 'OpenCode-primary' comment
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The task skill becomes the spine: goal alignment, prep (worktree,
slice-brief, draft PR), per-type execution paths, and closeout. Around it:
- task: full rewrite with frontmatter; new testing.md owns test shape
(one scenario test per user story, driven through the story's seam,
fresh-context sub-agent authorship, tiered runs, prune pass)
- review: fixed point defaults to merge-base when invoked from the task
Share step; the PR body (slice-brief) is the first spec source; runs
sequentially with a noted caveat when no sub-agent tool exists
- slice-brief: runs during task prep, becomes the draft PR body; filename
derives from the branch slug; story confirmations gain 'Done when' lines
- systems-map: mode picked from file existence; Seams and Fragile become
mandatory with honest 'none found' over silent omission
- suede-kickoff: de-OpenCode'd; remote/PR creation degrades gracefully to
tmp/KICKOFF-FOLLOWUP.md when the human defers the remote
- project-plan: rewritten as a cut map published to one plan issue; the
fuller PRD / per-issue / triage ceremony preserved under reference/
- decision-graph (new): deciduous mechanics extracted from the old
.opencode/commands/decision.md
- prompts: archaeology / narratives / pulse / request-refactor-plan gain
description frontmatter, matching the selvage prompt convention
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Remove .opencode/ (commands, plugins, tdd skill) and opencode.json — the
project is no longer OpenCode-primary; the process layer lives in .pi/.
Moves, content unchanged in this commit:
- archaeology, narratives, pulse: skills → .pi/prompts/ (user-invoked
views, not model-triggered skills)
- project-plan's to-prd / to-issues / triage subskills + triage docs →
.pi/skills/project-plan/reference/ (preserved fuller ceremony)
- request-refactor-plan: skill → prompt (re-added in the next commit)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Move `suede-kickoff` and `review` from `.opencode/skills/` to
`.pi/skills/`. Drop unreferenced skills (`caveman`, `diagnose`,
`find-skills`, `grill-me`, `grill-with-docs`, `handoff`,
`improve-codebase-architecture`, `prototype`, `qa`,
`write-a-skill`) and add `task`, `slice-brief`, `systems-map`,
and `request-refactor-plan` under `.pi/skills/`. Update
`AGENTS.md` with a suede overview section.
Replace the GitHub user-attachment URL (404s on Tangled) with a
relative path to static/suede-logo.png, so the README logo renders
identically on github.com/taurean/suede and on tangled.org.
Co-authored-by: opencode <noreply@opencode.ai>
Co-authored-by: opencode <noreply@opencode.ai>
docs(blog): revise BUILDING-WITH-SUEDE and align rulebook
feat(styles): add src/lib/styles/ and clarify branch-from-fresh-main rule
Create the human-owned CSS directory referenced in the authoring
boundaries section. The root app stylesheet stays at src/app.css
(SvelteKit convention, already imports stylebase globally); the new
dir is the home for project-specific CSS files.
Strengthen the git workflow rule that new branches come from a freshly
pulled main, not a stale local view. The original 'pull latest main'
phrasing was easy to skip when already on a feature branch.
Co-authored-by: opencode <noreply@opencode.ai>
The /tdd-supplementary skill was a continuation of /tdd, not a
supplement in the strict sense. The prune pass ('earn their keep')
is the same red flags the core TDD skill calls 'bad tests'; the
Storybook discipline is the only piece that's project-shape-specific
and not already in /tdd. Keeping them in two skills invited drift
and an 'is it in tdd or tdd-supplementary?' lookup before every
REFACTOR step.
Fold both into /tdd. New SKILL.md covers the RED-GREEN-REFACTOR flow,
the prune pass, and the Storybook discipline in one place. Delete
.opencode/skills/tdd-supplementary/.
References updated: AGENTS.md (Constant process pipeline, Working
style, Storybook override paragraph), README.md (Build stage line,
in-repo skills table), suede-kickoff (Thread B Q7 Storybook rip
override). All say '.opencode/skills/tdd/'.
Co-authored-by: opencode <noreply@opencode.ai>
Previously the process layer (grill-me, to-prd, tdd, review, qa, diagnose,
handoff, prototype, caveman, write-a-skill, improve-codebase-architecture,
find-skills, grill-with-docs, to-issues, triage) lived in the global
~/.agents/skills/ plugin. A fresh clone of suede therefore had no working
pipeline until the user installed the global plugin separately.
Move all 15 skills into .opencode/skills/. AGENTS.md, README.md,
suede-kickoff, and tdd-supplementary references to ~/.agents/skills/
are updated to the in-repo paths. A fresh clone is now self-contained
apart from the system tools checked in Step 0.
suede-kickoff Step 0 (new): a pre-flight that verifies deciduous, git,
pnpm, and node are on PATH, and surfaces gh as optional. Required tools
missing -> stop and notify the human with install instructions; do not
proceed silently.
Removed references to setup-matt-pocock-skills and docs/agents/issue-tracker.md
in to-prd, to-issues, triage, and review. The tracker is GitHub Issues,
the labels are the conventional ones in AGENTS.md, and the skills now
say so inline rather than deferring to a setup-time doc.
Co-authored-by: opencode <noreply@opencode.ai>
agent-notes/ is now scratch space, not a tracked artifact. The
BUILDING-WITH-SUEDE.md blog post lives there as a working draft;
the previously-tracked historical task notes and plan files are
deleted from the tree (they remain in git history up through
this commit).
The compiled form of work — graph nodes, closed issues, merged
PRs — is what persists. The gitignored agent-notes/ scratch
space is for drafts and per-task notes that don't need to ship.
Co-authored-by: opencode <noreply@opencode.ai>
The blog post is the first commit of the doc to the repo (was
untracked on main). Revisions per the user's feedback:
- Pipeline reframed as a happy path (concept, grill, PRD, issues,
triage, build, review, release) plus 'load when triggered' skills
(diagnose, qa, handoff, prototype, plus wraparound). The 11-stage
table is gone; review is the always-on PR-axis stage; QA is
triggered by the human reporting a bug conversationally.
- Task notes are deprecated. The 'task note is the connective tissue'
section, the 'PRD as scratchpad' subsection, and the
agent-notes-reading-list entry are cut. The compiled-form record
is now the decision graph + closed issues + merged PRs.
- Tracker is GitHub Issues. The markdown-dir / Linear / GitLab
override path is removed.
- PR-stacking version-bump rule: bump only the last PR in a same-day
stack. Multi-day stacks still bump each PR (chronver doing its
job).
- PR size: 'rarely over 1,000 lines' is now flagged as opinion.
- Agent authority strengthened: the human owns every gate between
code and production without explicit contextual permission.
Rulebook alignment (AGENTS.md, .opencode/skills/, README.md):
- AGENTS.md: dropped agent-notes/ from Layout and from the always-on
layer; dropped the 'Task note section headings' subsection; rewrote
'Tracker preconditions' and 'Releases / Tracker and remotes' to
drop the override path; rewrote Task flow End step 1+2 to land
verification in the PR description; rewrote Guardrails.
- .opencode/skills/suede-kickoff: Thread B Q8 no longer lists
override trackers; Step 8 no longer writes a task note (the
follow-up PR description is the audit trail and the process-layer
edit list); verification checklist updated accordingly.
- .opencode/skills/tdd-supplementary: Storybook-override destination
is the PR description or ADR, not the task note.
- .opencode/commands/build-test.md: one-line ref to a 2026-06-04-01
task note replaced with a deciduous decision-graph reference.
- README.md: dropped the 'Task notes' section; rewrote the
'From concept to merge' pipeline table as a happy-path list;
dropped the 'Tracker override' line; updated the README's two
other task-note references.
- .gitignore: rationale comment for agent-notes/plans/ updated to
reference the PR description (no longer the task note).
- Deleted agent-notes/0000-00-00-00-task-template.md (the template
for the deprecated artifact).
Historical agent-notes/2026-*.md files are left in place as
historical record per the deprecation interpretation (deprecate, not
purge). The Plan files gitignore entry is kept; plan files are
gitignored scratchpads for the deprecated workflow and will be
re-evaluated when the workflow is reintroduced (or removed entirely
if it isn't).
No version bump per user direction.
Co-authored-by: opencode <noreply@opencode.ai>
docs: rewrite README as a comprehensive orientation doc
Expand the 3-line stub into a full guide: stack table, getting-started
scripts, duplicating suede via the suede-kickoff skill, the coding-agent
contract (authoring boundaries, Storybook discipline, human-merges rule),
the concept-to-merge pipeline, tooling (deciduous, agent-notes, in-repo
skills, commands), and git/release conventions. Every section links back
to AGENTS.md as the canonical source.
https://claude.ai/code/session_01LTXuwuYbUkp9fEWj8VDXNj
Consolidate workflow documentation into decision.md
Delete five thin wrappers (deciduous.md, sync-graph.md, version-check.ts,
SKILL.md, deciduous.ts) that restate content already in commands/decision.md
or AGENTS.md. Fold commands/work.md and commands/document.md into
decision.md as ## Workflow: /work and ## Workflow: /document subsections so
decision.md is the single reference for all workflow details. Drop the now-
dead SKILL.md pointer from the AGENTS.md Task flow preamble.
Closes #6
https://claude.ai/code/session_01Bc9nxmsXYG6cgiwcb5GZP1
Consolidate deciduous documentation into decision.md
Removes ~210 lines of content duplicated from .opencode/commands/decision.md
(Document Attachments, Verbatim Prompts, Maintain Connections, Quick Commands,
Link Commits, Branch-Based Grouping, Audit Checklist, Git Staging Rules,
Session Start Checklist, Multi-User Sync). Keeps the four blocks AGENTS.md
uniquely owns — Node Flow Rule, Core Rule, What NOT to Log, Rule of Thumb —
and adds a pointer paragraph to decision.md. Net: 498 → 287 lines.
Closes #5
https://claude.ai/code/session_01NQCzheFXakAdCiQwjfmohb
Refactor database environment validation to separate script
Replace import-time throws in drizzle.config.ts with empty-string
defaults so pnpm check / svelte-check no longer crash for forks
without Cloudflare credentials set. Validation moves to
scripts/db-check.js, which is chained into db:push, db:generate,
and db:migrate so the failure happens with a clear message only when
the env vars are actually needed.
Closes #4
https://claude.ai/code/session_016eNQzUGcKjUPx33etijhGK
Remove vitest example files
Remove database schema and initialization files
- Run prettier --write to fix formatting across 34 files
- Remove unused catch bindings in opencode plugins
- Remove unused `output` param and `fn` import in stories
- Replace triple-slash vitest/config reference with import style
- Wire up eslint-plugin-storybook flat/recommended config
Remove speculative scaffolding (getDb factory and task table) that has
zero callers. When a real query is needed, recreate the module with the
queries that use it.
Closes #2
Removes the four scaffold files in src/lib/vitest-examples/ that were
frozen pre-bits-ui and no longer serve as useful examples.
Closes #3
https://claude.ai/code/session_01RnLjezrr6GTBfkrKRvRXtT
docs(agents): consolidate agent instructions, add constant process pipeline + standards
Co-authored-by: opencode <noreply@opencode.ai>
The user asked whether we are now standardizing the tags/labels we
use. Partial answer: chronver (version), triage (issues), deciduous
(graph nodes) were already standardized. The commit and branch naming
vocabularies were de facto conventional-commits but not written down;
the 2026-06-03-02 task note explicitly flagged this as a future task.
- AGENTS.md Git workflow: new 'Branch and commit naming' subsection
with the conventional-commits 1.0.0 type list enumerated inline.
Branch names are <type>/<slug>; commit messages are
<type>(<scope>): <subject>; the type vocabulary is shared. The
chore(release): type is reserved for the version-bump commit.
Forks extend or trim the list via suede-kickoff Thread B Q8.
- AGENTS.md Layout: task note filename pattern formalized as
YYYY-MM-DD-NN-<slug>.md with the per-day counter rules. New
bullet for .opencode/{agents,commands,plugins,tools}/ kebab-case
file naming. New 'Task note section headings' subsection listing
the 6 required sections from the template, in order, with the
'all six required' rule.
- suede-kickoff Thread B Q8 sub-bullet 'Branch and commit naming':
rewritten to point at AGENTS.md's new rule, with the
extension/trim override path.
Co-authored-by: opencode <noreply@opencode.ai>
The turn-1 / turn-2 hand-back message overstated the agent's role.
The correct rule: the agent may push branches and may apply tags,
but may not push directly to main and may not merge to main. The
human is the one who reviews the PR and merges to main; the agent
is fine doing the release-branch push and the tag.
This matches the prior-task pattern (2026-06-04-03 SuedeButton task
involved the agent pushing the branch; 2026-06-05-06 chronver task
mentioned the human tagging the merge commit but didn't preclude
the agent from doing so).
- AGENTS.md Git workflow bullet 4: agent may push + may tag, may
not push to main, may not merge to main.
- AGENTS.md Task flow End step 5: same correction.
- AGENTS.md Releases intro: removed 'the human tags' wording; the
tag-and-push step is agent-OK, only the merge-to-main is human-only.
No version bump for this turn. If the user prefers the rule
correction to ride with 2026.6.12, can rebase/re-bump.
Co-authored-by: opencode <noreply@opencode.ai>
Six follow-up points from the user after the turn-1 commit. All land
on the same branch as a separate commit so the turn-1 / turn-2 work
is independently reviewable.
- AGENTS.md Git workflow: 'Never branch off an in-flight branch.' Only
main is a valid base. In-flight work follows up on the same branch
or waits. A branch-of-branch creates a PR whose base vanishes the
moment the first PR merges.
- AGENTS.md Authoring boundaries: 'Storybook discipline' subsection
with assume-included wording. A UI primitive change is incomplete
without a story update in the same commit. The override path lives
in suede-kickoff Thread B Q7 (a fork that rips Storybook records
the override in the kickoff follow-up task note, and the agent
rewrites AGENTS.md / tdd-supplementary to reflect the rip).
- AGENTS.md Constant process pipeline: 'Tracker preconditions' para.
Stages 4/5/8/9 need a tracker. Default: GitHub Issues. Sane
overrides: markdown-dir, Linear, GitLab. Tangled is a mirror, not
a tracker. When no tracker is configured, those stages collapse to
mental checks on the task note's Follow-ups.
- AGENTS.md Releases: rewrote intro as 'mechanics constant, scheme
variable.' The fork-invariant part is the release flow mechanics;
the scheme (chronver / semver / other) is a Thread B question.
Added 'Tracker and remotes' paragraph making GitHub Issues the
default tracker and Tangled a mirror.
- AGENTS.md Decision Graph Workflow: Session Start Checklist no
longer references 'deciduous check-update'. Added a 'Do not run
deciduous update' policy paragraph (the upstream update command
regenerates .opencode/, .claude/, AGENTS.md from defaults and
silently overwrites hand-edits).
- AGENTS.md Working style: added 'tdd-supplementary' to the
build-stage skills list.
- .opencode/plugins/version-check.ts: rewritten as a no-op. Writes
a one-time marker to .deciduous/.version_check_disabled + a single
log line, then returns silently. The deciduous auto-update toggle
is deprecated upstream; disabling the plugin is the only effective
silencing.
- .gitignore: added agent-notes/plans/ with a comment explaining
the rationale (plan files are per-task scratchpads; the compiled
form persists; handoff is the resume tool).
- .opencode/skills/task-lifecycle/SKILL.md: 'Do not write a plan
file to agent-notes/plans/' — gitignored scratchpads, handoff is
the resume tool.
- .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).
- .opencode/skills/tdd-supplementary/SKILL.md (new): three
sections — Prune pass (the rule the global tdd skill is missing;
walks the tdd/tests.md Red flags checklist; deletes in the same
commit); Storybook discipline (restates the Authoring Boundaries
rule as a workflow); What's intentionally not in this skill.
Co-authored-by: opencode <noreply@opencode.ai>
The suede process layer is constant across every fork (full-stack,
content, backend, other). What varies is the details — issue tracker,
branch convention, version policy, which global skills apply. This
commit makes that contract explicit in three places:
- AGENTS.md: new 'Constant process pipeline' section with the 11-stage
table (concept -> grill -> PRD -> issues -> triage -> build ->
diagnose -> review -> QA -> release -> handoff) and the always-on
supporting layer (decision graph, task notes, git workflow, authoring
boundaries). Working style rewritten to bucket skills by pipeline
stage. Task flow Start + During steps now reference the pipeline
section as the canonical source.
- .opencode/skills/suede-kickoff/SKILL.md: Step 3 reframed as a
/grill-me session with Thread A (project) and Thread B (process-layer
customizations). Thread B is open-ended — the process is the human's,
the agent doesn't pick which ~/.agents/skills/ to load, which issue
tracker to use, or which branch convention to enforce. Step 8 splits
the decision list into process-layer edits (lead) and runtime-layer
edits.
- .opencode/commands/work.md: fixed the 'hooks will BLOCK you' claim
on line 13. The require-action-node plugin nags to .deciduous/plugin.log;
it does not block. Same fix shape in 'Why This Matters'.
- .opencode/commands/build-test.md: rewritten from stock deciduous
(cargo + Rust) to the suede defaults (pnpm + Vitest + svelte-check +
Storybook). The 2026-06-04-01 task note originally flagged this
misalignment.
Did NOT touch the other 8 stock deciduous commands — out of scope for
this task. Did NOT introduce a branch-naming convention — out of scope.
Did NOT resolve the deciduous sync boundary — out of scope.
Co-authored-by: opencode <noreply@opencode.ai>
First suede release cut through the formal chronver flow. Bumps the
package version from 2026.6.4 to 2026.6.5 (today's date, no leading
zeros). After merge, the merge commit on main gets the annotated tag
2026.6.5 and is pushed with --follow-tags.
This release includes:
- Working style section (process skills pointer, Zed plan/build note)
- Versioning rule (every release branch ships as its own version)
- Task flow section (Start / During / End sequence)
Co-authored-by: opencode <noreply@opencode.ai>
Replaces the one-line 'Task lifecycle' pointer with a full Start / During /
End flow that consolidates the rules scattered across the rest of AGENTS.md
(Authoring boundaries, Working style, Releases, Decision Graph) into one
sequence the agent can follow turn-by-turn. The procedural detail still
lives at .opencode/skills/task-lifecycle/SKILL.md; this section is the
in-context summary.
Start: pull main, branch, log goal, design in plan mode.
During: action nodes, process skills, authoring boundaries, commits,
deciduous linking.
End: verify, task note, version bump, hand back.
Co-authored-by: opencode <noreply@opencode.ai>
First suede release cut through the formal chronver flow. Bumps the
package version from 2026.6.4 to 2026.6.5 (today's date, no leading
zeros). After merge, the merge commit on main gets the annotated tag
2026.6.5 and is pushed with --follow-tags.
Co-authored-by: opencode <noreply@opencode.ai>
Working style: pointer to ~/.agents/skills/ process skills (tdd, diagnose,
prototype, review, qa, handoff, caveman, write-a-skill) plus a one-line
note that Zed's plan/build mode toggle is the human's lever. Replaces
using-superpowers as the process-skill dispatcher after the plugin kill.
Versioning rule: 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.
Co-authored-by: opencode <noreply@opencode.ai>
Adds an in-repo skill at .opencode/skills/suede-kickoff/SKILL.md that an
agent can invoke when starting a new project forked from suede.
The skill reinstantiates git, updates package.json with the suede.from
lineage field per AGENTS.md, resets .deciduous/, runs a 6-question scope
interview with the human, and branches chore/suede-kickoff for the deep
tooling-customization follow-up. The skill removes itself as the final
action of the follow-up branch.
Built via writing-skills TDD: 3 RED-phase pressure scenarios, GREEN
draft, 1 REFACTOR re-run that closed 3 residual gaps. Rationalizations
table covers 7 anti-patterns (capture-after-delete, tag-vs-version,
'be decisive' override, deciduous-skip, git-add-dot, work-on-a-copy,
no-follow-up-task).
Co-authored-by: opencode <noreply@opencode.ai>
- Layout gains SYSTEMS_MAP.md and defers the repo map to its Layout tree
- Pipeline review stage notes the CI invocation path (pi-review.yml)
- Fix stale Thread B Q9 reference (commit-type overrides live under Q8)
- Record the pnpm-version-rejects-.N-chronver gotcha in the release steps
- Overview example swaps retired 'label vocabulary' for 'commit types'
- 'Decision Graph Workflow' header to sentence case, refs updated
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Every fork needs MINIMAX_API_KEY before pi-review.yml can run; repo
secrets don't inherit. Step 8 now sets it right after the remote is
created (op read from 1Password piped to gh secret set) and the hand-back
checklist verifies it — or it's carried as an unchecked follow-up item
when op is unavailable or the remote was deferred.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Security-review finding: gh pr checkout put the untrusted PR branch's
.pi/ in Pi's discovery path, and --approve trusted it — a fork PR could
ship a modified review skill or an extension and execute arbitrary code
with the API-key secrets in env. Now the .pi/ process layer is
snapshotted from main before the branch switch, Pi runs with --no-approve
--no-extensions --no-skills --no-prompt-templates --no-context-files
--tools read,bash, and the prompt directs it to the trusted snapshot,
treating the working tree strictly as data under review.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replace claude-review.yml with pi-review.yml. Same triggers and
hardening (/review comment gated to owner/member/collaborator, numeric
PR-number validation, dispatch input, concurrency, contents: read); the
review itself now runs via @earendil-works/pi-coding-agent in --print
mode with --approve (trusts the checked-out .pi/skills) and
--exclude-tools edit,write. Provider defaults to minimax/MiniMax-M3,
overridable via PI_REVIEW_PROVIDER / PI_REVIEW_MODEL repo variables.
Report lands as one top-level PR comment via gh (no inline-comment MCP
under Pi); the skill's no-subagent sequential fallback is pinned in the
prompt. Requires the MINIMAX_API_KEY repo secret.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Second changeset of the day (chronver .N suffix): SYSTEMS_MAP.md and the
on-demand Claude review workflow. Hand-edited bump — pnpm version rejects
four-segment chronver as invalid semver.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
.github/workflows/claude-review.yml runs the project's own two-axis
review skill (.pi/skills/review/SKILL.md) against a PR via
anthropics/claude-code-action@v1. Invoked two ways: a '/review' comment
on the PR (owner/member/collaborator only) or a workflow dispatch with a
PR number. The prompt pins the skill's bindings for CI — merge-base as
the fixed point, PR body as the spec — and the report lands as a
top-level PR comment plus inline comments. Read-only on contents;
allowedTools limited to gh/git read commands and comment posting.
Requires the ANTHROPIC_API_KEY repo secret, not yet configured.
SYSTEMS_MAP.md: add .github/workflows/ to the Layout tree (omitted at
creation) and record the new GitHub-invocable seam on the process layer.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Six areas divided by reason for change (app shell, UI foundation, stubbed
data layer, platform/deploy, verification harness, process layer), each
with mandatory Seams and Fragile fields. Opens with a commented ASCII
layout tree; the systems-map skill gains the matching format rule so the
tree is maintained (files it names move/appear/disappear) without becoming
a per-change tax.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- AGENTS.md: pipeline collapses 11 stages to 6 (align, cut plan, build,
review, release around the concept input); Task flow section delegates
to /skill:task; co-author trailer becomes harness-agnostic; release
checklist gains the decision-graph-value line and the full-journey run
- README: happy path updated to the six stages; .opencode references gone
- .gitignore: add tmp/ (slice-brief working copies); un-ignore
.deciduous/sync/ so the decision-graph skill's documented sync flow is
actually possible; drop the dead .opencode workspace block; reword the
stale 'OpenCode-primary' comment
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The task skill becomes the spine: goal alignment, prep (worktree,
slice-brief, draft PR), per-type execution paths, and closeout. Around it:
- task: full rewrite with frontmatter; new testing.md owns test shape
(one scenario test per user story, driven through the story's seam,
fresh-context sub-agent authorship, tiered runs, prune pass)
- review: fixed point defaults to merge-base when invoked from the task
Share step; the PR body (slice-brief) is the first spec source; runs
sequentially with a noted caveat when no sub-agent tool exists
- slice-brief: runs during task prep, becomes the draft PR body; filename
derives from the branch slug; story confirmations gain 'Done when' lines
- systems-map: mode picked from file existence; Seams and Fragile become
mandatory with honest 'none found' over silent omission
- suede-kickoff: de-OpenCode'd; remote/PR creation degrades gracefully to
tmp/KICKOFF-FOLLOWUP.md when the human defers the remote
- project-plan: rewritten as a cut map published to one plan issue; the
fuller PRD / per-issue / triage ceremony preserved under reference/
- decision-graph (new): deciduous mechanics extracted from the old
.opencode/commands/decision.md
- prompts: archaeology / narratives / pulse / request-refactor-plan gain
description frontmatter, matching the selvage prompt convention
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Remove .opencode/ (commands, plugins, tdd skill) and opencode.json — the
project is no longer OpenCode-primary; the process layer lives in .pi/.
Moves, content unchanged in this commit:
- archaeology, narratives, pulse: skills → .pi/prompts/ (user-invoked
views, not model-triggered skills)
- project-plan's to-prd / to-issues / triage subskills + triage docs →
.pi/skills/project-plan/reference/ (preserved fuller ceremony)
- request-refactor-plan: skill → prompt (re-added in the next commit)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Move `suede-kickoff` and `review` from `.opencode/skills/` to
`.pi/skills/`. Drop unreferenced skills (`caveman`, `diagnose`,
`find-skills`, `grill-me`, `grill-with-docs`, `handoff`,
`improve-codebase-architecture`, `prototype`, `qa`,
`write-a-skill`) and add `task`, `slice-brief`, `systems-map`,
and `request-refactor-plan` under `.pi/skills/`. Update
`AGENTS.md` with a suede overview section.
Co-authored-by: opencode <noreply@opencode.ai>
Create the human-owned CSS directory referenced in the authoring
boundaries section. The root app stylesheet stays at src/app.css
(SvelteKit convention, already imports stylebase globally); the new
dir is the home for project-specific CSS files.
Strengthen the git workflow rule that new branches come from a freshly
pulled main, not a stale local view. The original 'pull latest main'
phrasing was easy to skip when already on a feature branch.
Co-authored-by: opencode <noreply@opencode.ai>
The /tdd-supplementary skill was a continuation of /tdd, not a
supplement in the strict sense. The prune pass ('earn their keep')
is the same red flags the core TDD skill calls 'bad tests'; the
Storybook discipline is the only piece that's project-shape-specific
and not already in /tdd. Keeping them in two skills invited drift
and an 'is it in tdd or tdd-supplementary?' lookup before every
REFACTOR step.
Fold both into /tdd. New SKILL.md covers the RED-GREEN-REFACTOR flow,
the prune pass, and the Storybook discipline in one place. Delete
.opencode/skills/tdd-supplementary/.
References updated: AGENTS.md (Constant process pipeline, Working
style, Storybook override paragraph), README.md (Build stage line,
in-repo skills table), suede-kickoff (Thread B Q7 Storybook rip
override). All say '.opencode/skills/tdd/'.
Co-authored-by: opencode <noreply@opencode.ai>
Previously the process layer (grill-me, to-prd, tdd, review, qa, diagnose,
handoff, prototype, caveman, write-a-skill, improve-codebase-architecture,
find-skills, grill-with-docs, to-issues, triage) lived in the global
~/.agents/skills/ plugin. A fresh clone of suede therefore had no working
pipeline until the user installed the global plugin separately.
Move all 15 skills into .opencode/skills/. AGENTS.md, README.md,
suede-kickoff, and tdd-supplementary references to ~/.agents/skills/
are updated to the in-repo paths. A fresh clone is now self-contained
apart from the system tools checked in Step 0.
suede-kickoff Step 0 (new): a pre-flight that verifies deciduous, git,
pnpm, and node are on PATH, and surfaces gh as optional. Required tools
missing -> stop and notify the human with install instructions; do not
proceed silently.
Removed references to setup-matt-pocock-skills and docs/agents/issue-tracker.md
in to-prd, to-issues, triage, and review. The tracker is GitHub Issues,
the labels are the conventional ones in AGENTS.md, and the skills now
say so inline rather than deferring to a setup-time doc.
Co-authored-by: opencode <noreply@opencode.ai>
agent-notes/ is now scratch space, not a tracked artifact. The
BUILDING-WITH-SUEDE.md blog post lives there as a working draft;
the previously-tracked historical task notes and plan files are
deleted from the tree (they remain in git history up through
this commit).
The compiled form of work — graph nodes, closed issues, merged
PRs — is what persists. The gitignored agent-notes/ scratch
space is for drafts and per-task notes that don't need to ship.
Co-authored-by: opencode <noreply@opencode.ai>
The blog post is the first commit of the doc to the repo (was
untracked on main). Revisions per the user's feedback:
- Pipeline reframed as a happy path (concept, grill, PRD, issues,
triage, build, review, release) plus 'load when triggered' skills
(diagnose, qa, handoff, prototype, plus wraparound). The 11-stage
table is gone; review is the always-on PR-axis stage; QA is
triggered by the human reporting a bug conversationally.
- Task notes are deprecated. The 'task note is the connective tissue'
section, the 'PRD as scratchpad' subsection, and the
agent-notes-reading-list entry are cut. The compiled-form record
is now the decision graph + closed issues + merged PRs.
- Tracker is GitHub Issues. The markdown-dir / Linear / GitLab
override path is removed.
- PR-stacking version-bump rule: bump only the last PR in a same-day
stack. Multi-day stacks still bump each PR (chronver doing its
job).
- PR size: 'rarely over 1,000 lines' is now flagged as opinion.
- Agent authority strengthened: the human owns every gate between
code and production without explicit contextual permission.
Rulebook alignment (AGENTS.md, .opencode/skills/, README.md):
- AGENTS.md: dropped agent-notes/ from Layout and from the always-on
layer; dropped the 'Task note section headings' subsection; rewrote
'Tracker preconditions' and 'Releases / Tracker and remotes' to
drop the override path; rewrote Task flow End step 1+2 to land
verification in the PR description; rewrote Guardrails.
- .opencode/skills/suede-kickoff: Thread B Q8 no longer lists
override trackers; Step 8 no longer writes a task note (the
follow-up PR description is the audit trail and the process-layer
edit list); verification checklist updated accordingly.
- .opencode/skills/tdd-supplementary: Storybook-override destination
is the PR description or ADR, not the task note.
- .opencode/commands/build-test.md: one-line ref to a 2026-06-04-01
task note replaced with a deciduous decision-graph reference.
- README.md: dropped the 'Task notes' section; rewrote the
'From concept to merge' pipeline table as a happy-path list;
dropped the 'Tracker override' line; updated the README's two
other task-note references.
- .gitignore: rationale comment for agent-notes/plans/ updated to
reference the PR description (no longer the task note).
- Deleted agent-notes/0000-00-00-00-task-template.md (the template
for the deprecated artifact).
Historical agent-notes/2026-*.md files are left in place as
historical record per the deprecation interpretation (deprecate, not
purge). The Plan files gitignore entry is kept; plan files are
gitignored scratchpads for the deprecated workflow and will be
re-evaluated when the workflow is reintroduced (or removed entirely
if it isn't).
No version bump per user direction.
Co-authored-by: opencode <noreply@opencode.ai>
Expand the 3-line stub into a full guide: stack table, getting-started
scripts, duplicating suede via the suede-kickoff skill, the coding-agent
contract (authoring boundaries, Storybook discipline, human-merges rule),
the concept-to-merge pipeline, tooling (deciduous, agent-notes, in-repo
skills, commands), and git/release conventions. Every section links back
to AGENTS.md as the canonical source.
https://claude.ai/code/session_01LTXuwuYbUkp9fEWj8VDXNj
Delete five thin wrappers (deciduous.md, sync-graph.md, version-check.ts,
SKILL.md, deciduous.ts) that restate content already in commands/decision.md
or AGENTS.md. Fold commands/work.md and commands/document.md into
decision.md as ## Workflow: /work and ## Workflow: /document subsections so
decision.md is the single reference for all workflow details. Drop the now-
dead SKILL.md pointer from the AGENTS.md Task flow preamble.
Closes #6
https://claude.ai/code/session_01Bc9nxmsXYG6cgiwcb5GZP1
Removes ~210 lines of content duplicated from .opencode/commands/decision.md
(Document Attachments, Verbatim Prompts, Maintain Connections, Quick Commands,
Link Commits, Branch-Based Grouping, Audit Checklist, Git Staging Rules,
Session Start Checklist, Multi-User Sync). Keeps the four blocks AGENTS.md
uniquely owns — Node Flow Rule, Core Rule, What NOT to Log, Rule of Thumb —
and adds a pointer paragraph to decision.md. Net: 498 → 287 lines.
Closes #5
https://claude.ai/code/session_01NQCzheFXakAdCiQwjfmohb
Replace import-time throws in drizzle.config.ts with empty-string
defaults so pnpm check / svelte-check no longer crash for forks
without Cloudflare credentials set. Validation moves to
scripts/db-check.js, which is chained into db:push, db:generate,
and db:migrate so the failure happens with a clear message only when
the env vars are actually needed.
Closes #4
https://claude.ai/code/session_016eNQzUGcKjUPx33etijhGK
Co-authored-by: opencode <noreply@opencode.ai>
The user asked whether we are now standardizing the tags/labels we
use. Partial answer: chronver (version), triage (issues), deciduous
(graph nodes) were already standardized. The commit and branch naming
vocabularies were de facto conventional-commits but not written down;
the 2026-06-03-02 task note explicitly flagged this as a future task.
- AGENTS.md Git workflow: new 'Branch and commit naming' subsection
with the conventional-commits 1.0.0 type list enumerated inline.
Branch names are <type>/<slug>; commit messages are
<type>(<scope>): <subject>; the type vocabulary is shared. The
chore(release): type is reserved for the version-bump commit.
Forks extend or trim the list via suede-kickoff Thread B Q8.
- AGENTS.md Layout: task note filename pattern formalized as
YYYY-MM-DD-NN-<slug>.md with the per-day counter rules. New
bullet for .opencode/{agents,commands,plugins,tools}/ kebab-case
file naming. New 'Task note section headings' subsection listing
the 6 required sections from the template, in order, with the
'all six required' rule.
- suede-kickoff Thread B Q8 sub-bullet 'Branch and commit naming':
rewritten to point at AGENTS.md's new rule, with the
extension/trim override path.
Co-authored-by: opencode <noreply@opencode.ai>
The turn-1 / turn-2 hand-back message overstated the agent's role.
The correct rule: the agent may push branches and may apply tags,
but may not push directly to main and may not merge to main. The
human is the one who reviews the PR and merges to main; the agent
is fine doing the release-branch push and the tag.
This matches the prior-task pattern (2026-06-04-03 SuedeButton task
involved the agent pushing the branch; 2026-06-05-06 chronver task
mentioned the human tagging the merge commit but didn't preclude
the agent from doing so).
- AGENTS.md Git workflow bullet 4: agent may push + may tag, may
not push to main, may not merge to main.
- AGENTS.md Task flow End step 5: same correction.
- AGENTS.md Releases intro: removed 'the human tags' wording; the
tag-and-push step is agent-OK, only the merge-to-main is human-only.
No version bump for this turn. If the user prefers the rule
correction to ride with 2026.6.12, can rebase/re-bump.
Co-authored-by: opencode <noreply@opencode.ai>
Six follow-up points from the user after the turn-1 commit. All land
on the same branch as a separate commit so the turn-1 / turn-2 work
is independently reviewable.
- AGENTS.md Git workflow: 'Never branch off an in-flight branch.' Only
main is a valid base. In-flight work follows up on the same branch
or waits. A branch-of-branch creates a PR whose base vanishes the
moment the first PR merges.
- AGENTS.md Authoring boundaries: 'Storybook discipline' subsection
with assume-included wording. A UI primitive change is incomplete
without a story update in the same commit. The override path lives
in suede-kickoff Thread B Q7 (a fork that rips Storybook records
the override in the kickoff follow-up task note, and the agent
rewrites AGENTS.md / tdd-supplementary to reflect the rip).
- AGENTS.md Constant process pipeline: 'Tracker preconditions' para.
Stages 4/5/8/9 need a tracker. Default: GitHub Issues. Sane
overrides: markdown-dir, Linear, GitLab. Tangled is a mirror, not
a tracker. When no tracker is configured, those stages collapse to
mental checks on the task note's Follow-ups.
- AGENTS.md Releases: rewrote intro as 'mechanics constant, scheme
variable.' The fork-invariant part is the release flow mechanics;
the scheme (chronver / semver / other) is a Thread B question.
Added 'Tracker and remotes' paragraph making GitHub Issues the
default tracker and Tangled a mirror.
- AGENTS.md Decision Graph Workflow: Session Start Checklist no
longer references 'deciduous check-update'. Added a 'Do not run
deciduous update' policy paragraph (the upstream update command
regenerates .opencode/, .claude/, AGENTS.md from defaults and
silently overwrites hand-edits).
- AGENTS.md Working style: added 'tdd-supplementary' to the
build-stage skills list.
- .opencode/plugins/version-check.ts: rewritten as a no-op. Writes
a one-time marker to .deciduous/.version_check_disabled + a single
log line, then returns silently. The deciduous auto-update toggle
is deprecated upstream; disabling the plugin is the only effective
silencing.
- .gitignore: added agent-notes/plans/ with a comment explaining
the rationale (plan files are per-task scratchpads; the compiled
form persists; handoff is the resume tool).
- .opencode/skills/task-lifecycle/SKILL.md: 'Do not write a plan
file to agent-notes/plans/' — gitignored scratchpads, handoff is
the resume tool.
- .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).
- .opencode/skills/tdd-supplementary/SKILL.md (new): three
sections — Prune pass (the rule the global tdd skill is missing;
walks the tdd/tests.md Red flags checklist; deletes in the same
commit); Storybook discipline (restates the Authoring Boundaries
rule as a workflow); What's intentionally not in this skill.
Co-authored-by: opencode <noreply@opencode.ai>
The suede process layer is constant across every fork (full-stack,
content, backend, other). What varies is the details — issue tracker,
branch convention, version policy, which global skills apply. This
commit makes that contract explicit in three places:
- AGENTS.md: new 'Constant process pipeline' section with the 11-stage
table (concept -> grill -> PRD -> issues -> triage -> build ->
diagnose -> review -> QA -> release -> handoff) and the always-on
supporting layer (decision graph, task notes, git workflow, authoring
boundaries). Working style rewritten to bucket skills by pipeline
stage. Task flow Start + During steps now reference the pipeline
section as the canonical source.
- .opencode/skills/suede-kickoff/SKILL.md: Step 3 reframed as a
/grill-me session with Thread A (project) and Thread B (process-layer
customizations). Thread B is open-ended — the process is the human's,
the agent doesn't pick which ~/.agents/skills/ to load, which issue
tracker to use, or which branch convention to enforce. Step 8 splits
the decision list into process-layer edits (lead) and runtime-layer
edits.
- .opencode/commands/work.md: fixed the 'hooks will BLOCK you' claim
on line 13. The require-action-node plugin nags to .deciduous/plugin.log;
it does not block. Same fix shape in 'Why This Matters'.
- .opencode/commands/build-test.md: rewritten from stock deciduous
(cargo + Rust) to the suede defaults (pnpm + Vitest + svelte-check +
Storybook). The 2026-06-04-01 task note originally flagged this
misalignment.
Did NOT touch the other 8 stock deciduous commands — out of scope for
this task. Did NOT introduce a branch-naming convention — out of scope.
Did NOT resolve the deciduous sync boundary — out of scope.
Co-authored-by: opencode <noreply@opencode.ai>
First suede release cut through the formal chronver flow. Bumps the
package version from 2026.6.4 to 2026.6.5 (today's date, no leading
zeros). After merge, the merge commit on main gets the annotated tag
2026.6.5 and is pushed with --follow-tags.
This release includes:
- Working style section (process skills pointer, Zed plan/build note)
- Versioning rule (every release branch ships as its own version)
- Task flow section (Start / During / End sequence)
Co-authored-by: opencode <noreply@opencode.ai>
Replaces the one-line 'Task lifecycle' pointer with a full Start / During /
End flow that consolidates the rules scattered across the rest of AGENTS.md
(Authoring boundaries, Working style, Releases, Decision Graph) into one
sequence the agent can follow turn-by-turn. The procedural detail still
lives at .opencode/skills/task-lifecycle/SKILL.md; this section is the
in-context summary.
Start: pull main, branch, log goal, design in plan mode.
During: action nodes, process skills, authoring boundaries, commits,
deciduous linking.
End: verify, task note, version bump, hand back.
Co-authored-by: opencode <noreply@opencode.ai>
Working style: pointer to ~/.agents/skills/ process skills (tdd, diagnose,
prototype, review, qa, handoff, caveman, write-a-skill) plus a one-line
note that Zed's plan/build mode toggle is the human's lever. Replaces
using-superpowers as the process-skill dispatcher after the plugin kill.
Versioning rule: 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.
Co-authored-by: opencode <noreply@opencode.ai>
Adds an in-repo skill at .opencode/skills/suede-kickoff/SKILL.md that an
agent can invoke when starting a new project forked from suede.
The skill reinstantiates git, updates package.json with the suede.from
lineage field per AGENTS.md, resets .deciduous/, runs a 6-question scope
interview with the human, and branches chore/suede-kickoff for the deep
tooling-customization follow-up. The skill removes itself as the final
action of the follow-up branch.
Built via writing-skills TDD: 3 RED-phase pressure scenarios, GREEN
draft, 1 REFACTOR re-run that closed 3 residual gaps. Rationalizations
table covers 7 anti-patterns (capture-after-delete, tag-vs-version,
'be decisive' override, deciduous-skip, git-add-dot, work-on-a-copy,
no-follow-up-task).
Co-authored-by: opencode <noreply@opencode.ai>