taurean.bryant.land
a template starter repo for sveltekit projects
chore: bootstrap Suede process — AGENTS.md, agent-notes template, task-lifecycle skill
author
Taurean Bryant
date
(Jun 3, 2026, 12:44 PM -0700)
commit
5a9fda9e
5a9fda9eb5ded9ac70c9b8cb48982e739df630d0
parent
d57430ca
d57430ca35182de65d1078cccaa03f94701d06b6
+92
-274
+17
.opencode/skills/task-lifecycle/SKILL.md
+17
.opencode/skills/task-lifecycle/SKILL.md
···
1
+
# Task lifecycle
2
+
3
+
End-of-task skill. Run after the work is done, before claiming completion.
4
+
5
+
## Steps
6
+
7
+
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.
8
+
2. Copy `agent-notes/0000-00-00-00-task-template.md` to `agent-notes/YYYY-MM-DD-NN-<slug>.md`. **Always.** No skip-step.
9
+
3. Fill all sections from the work just done. Size scales with task; trivial tasks get short notes.
10
+
4. Run verification per AGENTS.md, fill `## Verification` with results.
11
+
5. Hand back with a one-line summary and a pointer to the note file.
12
+
13
+
## Rules
14
+
15
+
- Task notes are records, not scratchpads. Fill at end, not during.
16
+
- Plan files in `agent-notes/plans/` are write-only at task end. Do not read them as part of starting a task.
17
+
- AGENTS.md is always in context. Do not re-read it.
+52
AGENTS.md
+52
AGENTS.md
···
1
+
# AGENTS
2
+
3
+
Cross-agent rulebook. Read at task start (always in context for OpenCode, Claude Code, etc.).
4
+
5
+
## Stack
6
+
7
+
SvelteKit · Cloudflare Pages + Workers · D1 + Drizzle · Vitest + Playwright · pnpm · stylebase + Bits UI · Storybook · Sentry + Axiom · OpenCode (primary) / Claude Code (fallback).
8
+
9
+
## Layout
10
+
11
+
- `AGENTS.md` — this file
12
+
- `agent-notes/` — chronological task notes (one per task, written at end)
13
+
- `agent-notes/plans/` — plan artifacts (write-only at task end, not auto-loaded)
14
+
- `.opencode/skills/` — in-repo skills (cross-cutting process skills live in your global plugin, not here)
15
+
16
+
## Authoring boundaries
17
+
18
+
Humans own:
19
+
- Svelte component markup
20
+
- Svelte `<style>` blocks
21
+
- CSS files in `src/lib/styles/`
22
+
- Layout, spacing, typography, design tokens
23
+
24
+
Agents own (TypeScript only):
25
+
- `<script lang="ts">` blocks within `.svelte` files
26
+
- `*.ts` files in `src/lib/`, `src/routes/`
27
+
- Drizzle schemas and queries
28
+
- Server routes, API integrations, Workers
29
+
30
+
## Task lifecycle
31
+
32
+
End-of-task skill: `.opencode/skills/task-lifecycle/SKILL.md`. Always create a task note in `agent-notes/`, regardless of task size. Size of note scales with task.
33
+
34
+
## Guardrails
35
+
36
+
Always:
37
+
- Create an `agent-notes/` entry at task end.
38
+
- Run verification before claiming done.
39
+
- Preserve `agent-notes/` history (append, never delete).
40
+
41
+
Never:
42
+
- Modify the presentation layer (Svelte markup, scoped CSS, `src/lib/styles/`).
43
+
- Skip the task note.
44
+
- Commit secrets.
45
+
46
+
## Verification before completion
47
+
48
+
- `pnpm lint` — pass
49
+
- `pnpm check` — pass
50
+
- `pnpm test` — run if tests changed
51
+
52
+
Claim done with evidence: command + result.
+2
-41
README.md
+2
-41
README.md
···
1
-
# sv
2
-
3
-
Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
4
-
5
-
## Creating a project
6
-
7
-
If you're seeing this, you've probably already done this step. Congrats!
8
-
9
-
```sh
10
-
# create a new project
11
-
npx sv create my-app
12
-
```
13
-
14
-
To recreate this project with the same configuration:
1
+
# Suede
15
2
16
-
```sh
17
-
# recreate this project
18
-
pnpm dlx sv@0.15.2 create --template minimal --types ts --add prettier eslint vitest="usages:unit,component" sveltekit-adapter="adapter:cloudflare+cfTarget:workers" drizzle="database:d1" storybook --install pnpm suede
19
-
```
20
-
21
-
## Developing
22
-
23
-
Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
24
-
25
-
```sh
26
-
npm run dev
27
-
28
-
# or start the server and open the app in a new browser tab
29
-
npm run dev -- --open
30
-
```
31
-
32
-
## Building
33
-
34
-
To create a production version of your app:
35
-
36
-
```sh
37
-
npm run build
38
-
```
39
-
40
-
You can preview the production build with `npm run preview`.
41
-
42
-
> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
3
+
SvelteKit starter template. Entry point for stack, conventions, and process: `AGENTS.md`.
+21
agent-notes/0000-00-00-00-task-template.md
+21
agent-notes/0000-00-00-00-task-template.md
···
1
+
# <slug>
2
+
3
+
## Task
4
+
<the determined task description — what was asked, what scope, what done-when>
5
+
6
+
## Decisions
7
+
- <choice made> — <why>
8
+
9
+
## Actions
10
+
- <step taken> — <brief result or pointer>
11
+
12
+
## Files touched
13
+
- `path/to/file.ts` — <what changed>
14
+
15
+
## Verification
16
+
- `pnpm lint` — pass
17
+
- `pnpm check` — pass
18
+
- `pnpm test` — not run (no test changes)
19
+
20
+
## Follow-ups / stubs
21
+
- <thing deferred, stubbed, or flagged for later>
-233
stack.md
-233
stack.md
···
1
-
# Default Stack
2
-
3
-
_Last updated: May 8, 2026_
4
-
5
-
This document defines the default technology stack across all projects. Deviations should be intentional and documented at the project level.
6
-
7
-
---
8
-
9
-
## Frontend
10
-
11
-
**SvelteKit**
12
-
13
-
Full-stack framework for all web projects. SvelteKit server routes handle in-app API needs. Vite is the local dev server. Deployed via the Cloudflare adapter.
14
-
15
-
---
16
-
17
-
## Styling
18
-
19
-
**stylebase + Bits UI via Suede**
20
-
21
-
stylebase provides global design tokens, fluid type scale, fluid spacing, layout primitives, and sensible element defaults. It is imported once globally as an npm package.
22
-
23
-
Bits UI provides headless accessible component primitives (focus traps, ARIA, keyboard navigation). Component-level styles are written in scoped Svelte CSS against stylebase tokens.
24
-
25
-
Suede is the starter template — a SvelteKit repo with Bits UI wired to stylebase, preconfigured with the full default stack. New projects begin by duplicating Suede. It is not a versioned dependency; each project owns its copy from that point. Storybook is included for developing and reviewing components in isolation.
26
-
27
-
**Design principles:**
28
-
- Screen-native only. No shadows, no skeuomorphism.
29
-
- Hierarchy through color, scale, weight, and space.
30
-
- Color is semantic, not decorative.
31
-
32
-
**Authorship model:**
33
-
All presentational code — Svelte component markup, scoped CSS, layout, spacing, typography, and Bits UI wiring — is authored by hand. LLM agents do not generate or modify presentation layer code. Agents own TypeScript logic: data fetching, server routes, Drizzle queries, form handling, API integrations, and Workers. Svelte's file structure (separate `<script>`, markup, and `<style>` blocks) enforces this boundary naturally.
34
-
35
-
---
36
-
37
-
## Backend Runtime
38
-
39
-
**SvelteKit server routes / Hono**
40
-
41
-
SvelteKit server routes handle all in-app API needs. Hono is used for standalone Cloudflare Workers or independent API services that live outside a SvelteKit app.
42
-
43
-
---
44
-
45
-
## Compute & Hosting
46
-
47
-
**Cloudflare Pages + Cloudflare Workers / Railway**
48
-
49
-
SvelteKit apps deploy to Cloudflare Pages. Standalone services and Workers deploy to Cloudflare Workers. Railway is used for anything outside the Cloudflare ecosystem — primarily Postgres-backed services and Node-based workloads.
50
-
51
-
---
52
-
53
-
## Database
54
-
55
-
**Cloudflare D1 + Drizzle / Postgres on Railway + Drizzle**
56
-
57
-
Drizzle is the ORM across all database targets. The database is selected based on deployment environment and query needs.
58
-
59
-
| Scenario | Database |
60
-
|---|---|
61
-
| Cloudflare-native projects | Cloudflare D1 |
62
-
| Full relational database needs | Postgres on Railway |
63
-
| Caching and key-value | Cloudflare KV |
64
-
| Non-Cloudflare lightweight SQL | Turso |
65
-
66
-
---
67
-
68
-
## Real-time
69
-
70
-
**Cloudflare Durable Objects / Web Push API**
71
-
72
-
Durable Objects handle in-app real-time features — one DO instance per shared resource (e.g. shared quest, collaborative session). Web Push API + Workers handle device push notifications.
73
-
74
-
---
75
-
76
-
## Social & Identity Layer
77
-
78
-
**ATProto**
79
-
80
-
ATProto is the primary social layer across all applicable projects. Private data is handled by whichever database fits the project. ATProto OAuth is used for authentication on ATProto projects.
81
-
82
-
---
83
-
84
-
## Auth
85
-
86
-
**ATProto OAuth / Better Auth**
87
-
88
-
ATProto OAuth for all ATProto projects. Better Auth for everything else — it is edge-native, has native D1 support, and integrates cleanly with SvelteKit.
89
-
90
-
---
91
-
92
-
## File & Blob Storage
93
-
94
-
**Cloudflare R2**
95
-
96
-
S3-compatible API, no egress fees, native Workers integration.
97
-
98
-
---
99
-
100
-
## CMS & Content
101
-
102
-
**Payload / Markdown + MDX**
103
-
104
-
Payload is the standard CMS. It is TypeScript-native, self-hosted, and schema-as-code. Used proactively across projects to build familiarity, not only when a CMS is strictly required.
105
-
106
-
Markdown and MDX are used for simple static content that does not warrant a CMS.
107
-
108
-
---
109
-
110
-
## Search
111
-
112
-
**Postgres FTS / Meilisearch**
113
-
114
-
Postgres FTS for Postgres projects. Meilisearch for D1 projects that need real search — it is open source, fast, and has a clean hosted option.
115
-
116
-
---
117
-
118
-
## Payments
119
-
120
-
**Stripe + Stripe Tax**
121
-
122
-
Stripe for all payment processing. Stripe Tax for automated sales tax and VAT compliance across regions.
123
-
124
-
---
125
-
126
-
## Transactional Email
127
-
128
-
**Resend**
129
-
130
-
Modern API, excellent developer experience, React Email for templates (server-side only, no React frontend required).
131
-
132
-
---
133
-
134
-
## Monitoring
135
-
136
-
**Sentry + Axiom + Cloudflare Analytics**
137
-
138
-
| Tool | Purpose |
139
-
|---|---|
140
-
| Sentry | Error tracking |
141
-
| Axiom | Log aggregation |
142
-
| Cloudflare Analytics | Traffic and CDN-level metrics |
143
-
144
-
---
145
-
146
-
## Product Analytics
147
-
148
-
**PostHog**
149
-
150
-
Event tracking, funnels, session replay, and feature flags. Used for understanding what users actually do — not just pageviews.
151
-
152
-
---
153
-
154
-
## Web Analytics
155
-
156
-
**Plausible**
157
-
158
-
Privacy-friendly, no cookies, GDPR compliant. Covers pageviews, referrers, and Web Vitals. Complements Cloudflare Analytics rather than replacing it.
159
-
160
-
---
161
-
162
-
## AI & LLM Integration
163
-
164
-
**OpenRouter**
165
-
166
-
Unified API gateway across all model providers. Model selection is per use case — better models for quality-critical tasks, cheaper models for volume. No dependency on any single provider.
167
-
168
-
---
169
-
170
-
## LLM-Assisted Coding
171
-
172
-
**OpenCode / Claude Code / Zed**
173
-
174
-
OpenCode is the primary coding agent — open source, model-agnostic, supports 75+ providers via OpenRouter including local models.
175
-
176
-
Claude Code is the fallback when OpenCode is insufficient.
177
-
178
-
Zed is the editor. Fast. AI autocomplete is available but not a primary workflow.
179
-
180
-
**LLM Documentation conventions:**
181
-
- `CLAUDE.md` at the repo root for every project: architecture context, conventions, and agent guardrails
182
-
- Skills files for reusable procedural knowledge — format standard is cross-agent compatible
183
-
- This stack document serves as a shared reference across all projects and agents
184
-
185
-
---
186
-
187
-
## CI/CD
188
-
189
-
**GitHub Actions**
190
-
191
-
Native Cloudflare Wrangler integration, largest ecosystem of actions, free for public repos.
192
-
193
-
---
194
-
195
-
## Code Hosting
196
-
197
-
**Tangled / GitHub**
198
-
199
-
Tangled for public and open source projects. GitHub for private projects, client work, and anything requiring CI/CD pipelines. DNS always managed through Cloudflare regardless of registrar.
200
-
201
-
---
202
-
203
-
## Package Manager
204
-
205
-
**pnpm**
206
-
207
-
Faster than npm, strict dependency resolution, content-addressable store, monorepo support via workspaces.
208
-
209
-
---
210
-
211
-
## Domain Registrar
212
-
213
-
**Cloudflare Registrar / Porkbun**
214
-
215
-
Cloudflare Registrar by default — at-cost pricing, no markup, native DNS management. Porkbun for TLDs not supported by Cloudflare. DNS always managed through Cloudflare regardless of registrar.
216
-
217
-
---
218
-
219
-
## Testing
220
-
221
-
**Vitest + Playwright**
222
-
223
-
Vitest for unit and integration tests — Vite-native, fast, Jest-compatible API. Playwright for end-to-end tests — native SvelteKit integration, runs cleanly in GitHub Actions CI.
224
-
225
-
---
226
-
227
-
## Mobile
228
-
229
-
**Web-first + PWA / React Native + Expo**
230
-
231
-
All projects are web-first. PWA capabilities are the default mobile story.
232
-
233
-
React Native and Expo are used when a project specifically requires genuine native feel and App Store distribution. Targets both iOS and Android from a single codebase.