taurean.bryant.land
a template starter repo for sveltekit projects
Merge pull request #13 from taurean/claude/readme-rewrite-pb9o1z
docs: rewrite README as a comprehensive orientation doc
author
Taurean Bryant
committer
GitHub
date
(Jun 12, 2026, 5:25 PM -0700)
commit
fabb8ecd
fabb8ecdcf9c538ff993bc5d016cb4c04fa1247b
parent
43765963
43765963dd8f5bf1e1619e4a02556b455786ff14
+144
-1
+144
-1
README.md
+144
-1
README.md
···
1
1
# Suede
2
2
3
-
SvelteKit starter template. Entry point for stack, conventions, and process: `AGENTS.md`.
3
+
A SvelteKit starter template with an agentic development process baked in.
4
+
5
+
Suede is two layers in one repo:
6
+
7
+
1. **A runtime stack** — SvelteKit on Cloudflare Pages + Workers, D1 + Drizzle for data, Vitest + Playwright for tests, Storybook for component states, stylebase + Bits UI for the design layer.
8
+
2. **A process layer** — a constant concept-to-merge pipeline, a decision graph (`deciduous`), per-task notes, in-repo skills and commands, and clear boundaries between what humans author and what agents author.
9
+
10
+
You don't build _in_ suede so much as you fork it: copy the repo, run the kickoff skill, and the new project inherits both layers with the details tailored to it.
11
+
12
+
[`AGENTS.md`](AGENTS.md) is the canonical rulebook — it's always in the agent's context (wired up via [`opencode.json`](opencode.json)) and is the source of truth wherever this README summarizes. When the two disagree, AGENTS.md wins.
13
+
14
+
## Stack
15
+
16
+
| Concern | Choice |
17
+
| --------------- | -------------------------------------------------------------------------------- |
18
+
| Framework | SvelteKit (Svelte 5) |
19
+
| Hosting | Cloudflare Pages + Workers (`wrangler`) |
20
+
| Database | Cloudflare D1 via Drizzle ORM |
21
+
| Tests | Vitest (+ Playwright browser tests) |
22
+
| Component dev | Storybook |
23
+
| UI primitives | Bits UI + [@taurean/stylebase](https://www.npmjs.com/package/@taurean/stylebase) |
24
+
| Package manager | pnpm |
25
+
26
+
Every piece is a default, not a mandate — keep/rip decisions are made per fork during kickoff (see below).
27
+
28
+
## Getting started
29
+
30
+
```bash
31
+
pnpm install
32
+
cp .env.example .env # fill in Cloudflare D1 credentials if using the DB
33
+
pnpm dev # start the dev server
34
+
```
35
+
36
+
Day-to-day scripts:
37
+
38
+
| Command | What it does |
39
+
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
40
+
| `pnpm dev` | Vite dev server |
41
+
| `pnpm build` | Production build (checks wrangler types first) |
42
+
| `pnpm preview` | Run the built Worker locally via wrangler |
43
+
| `pnpm check` | Type-check (svelte-check + wrangler types) |
44
+
| `pnpm lint` | Prettier check + ESLint |
45
+
| `pnpm format` | Prettier write |
46
+
| `pnpm test` | Vitest, single run |
47
+
| `pnpm storybook` | Storybook dev server on port 6006 |
48
+
| `pnpm db:push` / `db:generate` / `db:migrate` / `db:studio` | Drizzle workflows against D1 (each verifies `.env` first via `scripts/db-check.js`) |
49
+
50
+
The quality gate before any task is called done: `pnpm check`, `pnpm lint`, and `pnpm test` if tests changed — with command + result captured as evidence in the task note.
51
+
52
+
## Starting a new project from suede
53
+
54
+
Suede is a template you duplicate, not a dependency you install. The flow:
55
+
56
+
1. **Copy the repo.** Clone suede (or copy the working tree) to a new directory. The working tree _is_ the new project — don't work on a side copy.
57
+
2. **Install and verify.** `pnpm install`, confirm `git status` is clean.
58
+
3. **Run the kickoff skill.** Tell the agent something like _"start a new project from this template"_ or _"fork suede"_. That triggers [`suede-kickoff`](.opencode/skills/suede-kickoff/SKILL.md), which walks through:
59
+
- **Capture lineage** — record the suede chronver tag and commit hash _before_ anything destructive. The tag lands in the new `package.json` as `"suede": { "from": "<tag>" }`.
60
+
- **Reset history** — delete `.git`, init a fresh repo on `main`.
61
+
- **Grilling session** — a one-question-at-a-time interview in two threads. **Thread A** captures the project itself (name, purpose, primary user, project shape, first version). **Thread B** captures process-layer tailoring: which stack pieces to keep or rip (Cloudflare, D1, Storybook, SvelteKit itself, …), issue tracker (GitHub Issues is the default), version scheme (chronver vs semver), commit-type vocabulary, pipeline compression, and which global skills apply.
62
+
- **Bootstrap commit** — update `package.json` (name, version, `suede.from`), reset the `.deciduous/` graph, commit.
63
+
- **Branch the follow-up task** — `chore/suede-kickoff`, where the Thread B answers are turned into actual edits to `AGENTS.md`, `.opencode/`, configs, and this README. The kickoff skill deletes itself at the end of that task — it's consumed once.
64
+
65
+
The grill produces a plan; the follow-up branch produces the diff. No code is written during the interview.
66
+
67
+
Downstream forks can always trace their lineage: `package.json#suede.from` holds the suede tag they branched from.
68
+
69
+
## Working with the coding agent
70
+
71
+
Suede is built to be driven through a coding agent (OpenCode, Claude Code, or similar). The contract:
72
+
73
+
- **AGENTS.md is always loaded.** It defines the stack, the git workflow, the pipeline, and the guardrails. Agent-facing integration files live in `.opencode/` (skills, commands, plugins).
74
+
- **Authoring boundaries.** Humans own the presentation layer: Svelte component markup, `<style>` blocks, `src/lib/styles/`, design tokens. Agents own the TypeScript: `<script lang="ts">` blocks, `*.ts` in `src/lib/` and `src/routes/`, Drizzle schemas, server routes, Workers. An agent never edits markup or scoped CSS.
75
+
- **Storybook discipline.** 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 record of the human-owned visual contract.
76
+
- **The human merges.** Agents may branch, commit (with a co-author trailer crediting assistance), push branches, and apply tags — but never merge to `main` or push to it directly. Every task lands through a PR the human reviews.
77
+
- **Everything is recorded.** Decisions go in the decision graph in real time; each task ends with a note in `agent-notes/`.
78
+
79
+
## From concept to merge
80
+
81
+
Every task moves through the same pipeline. The _process_ is constant across all suede forks; the _details_ (tracker, branch convention, version scheme) are tailored at kickoff. Stages compress for small tasks — a prototype might skip the PRD file and tracker labels — but the shape stays.
82
+
83
+
| Stage | Skill | What happens |
84
+
| ----------- | ------------------------------------- | -------------------------------------------------------------------------------------------- |
85
+
| 1. Concept | — | A problem exists: in conversation, an issue, or a QA bug report |
86
+
| 2. Grill | `grill-me` / `grill-with-docs` | Stress-test the idea, one question at a time, until understanding is shared |
87
+
| 3. PRD | `to-prd` | Synthesize the conversation into a PRD: problem, stories, decisions, scope |
88
+
| 4. Issues | `to-issues` | Break the PRD into tracer-bullet vertical slices, each independently demoable |
89
+
| 5. Triage | `triage` | Label and queue: `needs-triage` → `ready-for-agent` / `ready-for-human` / `wontfix` |
90
+
| 6. Build | `tdd` (+ in-repo `tdd-supplementary`) | RED → GREEN per slice; one test, one implementation, repeat; public-interface behaviour only |
91
+
| 7. Diagnose | `diagnose` | For hard bugs: build a feedback loop first, then bisect |
92
+
| 8. Review | `review` | Two-axis PR review (Standards + Spec) in parallel sub-agents, before merge |
93
+
| 9. QA | `qa` | Conversational bug filing against the running app, producing tracker issues |
94
+
| 10. Release | (AGENTS.md "Releases") | chronver bump as the final commit on the branch; human merges and tags |
95
+
| 11. Handoff | `handoff` | When context runs out, compact the session for the next agent |
96
+
97
+
Stage skills live in the global `~/.agents/skills/` plugin; suede ships only its repo-specific supplements in `.opencode/skills/`.
98
+
99
+
### The shape of a single task
100
+
101
+
1. **Start** — pull `main`, branch `<type>/<slug>` (always from `main`, never from an in-flight branch), log a goal node with the verbatim prompt. If requirements are fuzzy, grill before touching code.
102
+
2. **During** — log action nodes before major edits, honour authoring boundaries, commit as `<type>(<scope>): <subject>` in present-tense imperative, link each commit to the graph.
103
+
3. **End** — run the quality gate, write the task note, bump the version (`chore(release): cut <version>` as the final commit), hand back. The human reviews the PR, merges, and the merge commit gets tagged on `main`.
104
+
105
+
Branch types and commit types share one vocabulary — the conventional-commits 1.0.0 list (`feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `build`, `ci`, `perf`, `style`), enumerated in AGENTS.md.
106
+
107
+
## Tools
108
+
109
+
### Decision graph (`deciduous`)
110
+
111
+
Suede tracks project decisions as a graph: `goal → options → decision → actions → outcomes`, with observations attached anywhere. Logging is real-time, not retroactive — log what you're about to do, then log how it went, and link every commit to a node. The graph records the _project's_ decisions (what the user is building and choosing), never the agent's internal process.
112
+
113
+
- Rules and the node-flow model: AGENTS.md "Decision Graph Workflow"
114
+
- Full CLI reference and workflows: [`.opencode/commands/decision.md`](.opencode/commands/decision.md)
115
+
- Session-start context recovery: [`.opencode/commands/recover.md`](.opencode/commands/recover.md)
116
+
- Web viewer: [`.opencode/commands/serve-ui.md`](.opencode/commands/serve-ui.md) · multi-user sync: [`.opencode/commands/sync.md`](.opencode/commands/sync.md)
117
+
- Two OpenCode plugins enforce the habit: `require-action-node` (no file edits without a recent action/goal node) and `post-commit-reminder` (link commits after the fact).
118
+
119
+
### Task notes (`agent-notes/`)
120
+
121
+
One markdown note per task, written at task end, never deleted. Filename `YYYY-MM-DD-NN-<slug>.md`; six fixed sections (Task, Decisions, Actions, Files touched, Verification, Follow-ups) from the [template](agent-notes/0000-00-00-00-task-template.md). Size scales with the task — trivial tasks get short notes, not skipped sections. `agent-notes/plans/` is a gitignored scratch space.
122
+
123
+
### In-repo skills (`.opencode/skills/`)
124
+
125
+
| Skill | Purpose |
126
+
| ------------------- | -------------------------------------------------------------------------- |
127
+
| `suede-kickoff` | One-shot bootstrap of a new project from a fresh suede clone (see above) |
128
+
| `tdd-supplementary` | Suede-specific TDD additions: the test prune pass and Storybook discipline |
129
+
| `pulse` | Map the system's _current_ state as decision nodes — no history, just now |
130
+
| `narratives` | Reconstruct how the system evolved, as prose narratives |
131
+
| `archaeology` | Turn those narratives into a backdated, queryable decision graph |
132
+
133
+
Cross-cutting process skills (grill-me, to-prd, tdd, review, qa, …) live in the global `~/.agents/skills/` plugin, not in the repo.
134
+
135
+
### Commands (`.opencode/commands/`)
136
+
137
+
`/build-test` (typecheck + test gate), `/decision` (graph management), `/decision-graph` (build a graph from commit history), `/recover` (session-start context recovery), `/serve-ui`, `/sync`.
138
+
139
+
## Git workflow and releases
140
+
141
+
- Branch from `main`, always. Every task is reviewed in a PR; the human is the only one who merges.
142
+
- The human is commit author; agent-made commits carry a co-author trailer.
143
+
- **chronver** by default (`YYYY.M.D[.N]`, no leading zeros): every release branch ships its own version bump as its final commit, the merge commit on `main` is tagged with the bare version string and pushed with `--follow-tags`, and `git log <prev>..<new>` is the changelog — no `CHANGELOG.md`. Libraries with dependents switch to semver at kickoff.
144
+
- Default tracker is GitHub Issues; forks can override at kickoff.
145
+
146
+
Full details: AGENTS.md "Git workflow", "Task flow", and "Releases".