taurean.bryant.land
a template starter repo for sveltekit projects
docs(agents): standardize branch + commit naming, task note + opencode file conventions
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>
author
Taurean Bryant
co-author
opencode
date
(Jun 11, 2026, 6:39 PM -0700)
commit
03484654
03484654560d2bec947b4d47ef01a643133c7744
parent
384e9a1e
384e9a1ecf479b574d0e5a43d1f0afee1e83ed17
+81
-3
+1
-1
.opencode/skills/suede-kickoff/SKILL.md
+1
-1
.opencode/skills/suede-kickoff/SKILL.md
···
48
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
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
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.
51
+
- **Branch and commit naming** — the canonical list of conventional-commits types is in AGENTS.md "Branch and commit naming." Most forks inherit the canonical 10 (`feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `build`, `ci`, `perf`, `style`) as-is. Override cases: a fork that needs an extra type (e.g. `i18n` for a content-heavy project) or wants to trim one (e.g. drop `perf` for a backend MCP with no measurable perf budget) records the override here, and the agent updates AGENTS.md's "Branch and commit naming" section to reflect the fork's list.
52
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
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
54
- **Anything else that the human knows about this project that the agent can't infer.**
+35
-2
AGENTS.md
+35
-2
AGENTS.md
···
14
14
- **The agent may push branches and may apply tags, but never merges to `main` and never pushes directly to `main`.** The human reviews the PR and merges. (Pushing the release branch to the remote and tagging the human's merge commit on `main` are both agent-OK; the act of merging the PR into `main` is human-only.)
15
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.
16
16
17
+
### Branch and commit naming
18
+
19
+
The branch name and the commit-message type share a vocabulary. **Branch names** are `<type>/<slug>` where `<slug>` is a short kebab-case description of the work. **Commit messages** are `<type>(<scope>): <subject>` where `<scope>` is optional and `<subject>` is a present-tense imperative ("add X", not "added X"). The `chore(release):` type is reserved for the version-bump commit on a release branch — see the **Releases** section.
20
+
21
+
**Canonical type list** (conventional-commits 1.0.0, as of this writing):
22
+
23
+
- `feat` — new user-visible feature
24
+
- `fix` — bug fix for user-visible behaviour
25
+
- `chore` — maintenance, dependency bumps, tooling, version bumps
26
+
- `docs` — documentation only (AGENTS.md, task notes, READMEs, ADRs)
27
+
- `refactor` — code change that neither fixes a bug nor adds a feature
28
+
- `test` — test additions or corrections, no production code change
29
+
- `build` — build system or external dependency change
30
+
- `ci` — CI configuration change
31
+
- `perf` — performance improvement
32
+
- `style` — formatting, whitespace, missing semicolons, etc. (no logic change)
33
+
34
+
A fork that needs to extend the list (e.g. add `i18n` for a content-heavy project) or trim it (e.g. drop `perf` for a backend MCP that doesn't have a measurable perf budget) records the override in `suede-kickoff` Step 3 Thread B Q9. The full [conventional-commits 1.0.0 spec](https://www.conventionalcommits.org/en/v1.0.0/) is the upstream reference; AGENTS.md inherits the type list from it and re-states it here so the agent doesn't have to fetch the spec on first use.
35
+
17
36
## Layout
18
37
19
38
- `AGENTS.md` — this file
20
-
- `agent-notes/` — chronological task notes (one per task, written at end)
21
-
- `agent-notes/plans/` — plan artifacts (write-only at task end, not auto-loaded)
39
+
- `agent-notes/` — chronological task notes, one per task, written at task end. Filename: `YYYY-MM-DD-NN-<slug>.md` where `NN` is a per-day counter (`01`, `02`, ...) zero-padded to 2 digits. The counter is the order tasks _landed_, not the order they were _started_ — if the day ends with 3 notes, the next task the next day starts at `01` again, not `04`. `<slug>` is short kebab-case, lower-case, no trailing dash.
40
+
- `agent-notes/plans/` — gitignored (transient scratchpads; see Task flow for the full rule)
22
41
- `.opencode/skills/` — in-repo skills (cross-cutting process skills live in your global plugin, not here)
42
+
- `.opencode/{agents,commands,plugins,tools}/` — OpenCode integration files. All filenames in `.opencode/` use kebab-case. Skill directories are `kebab-case` and contain a single `SKILL.md`.
43
+
44
+
### Task note section headings
45
+
46
+
Every task note uses the six section headings from the template at `agent-notes/0000-00-00-00-task-template.md`, in this order:
47
+
48
+
1. `## Task` — what was asked, scope, done-when.
49
+
2. `## Decisions` — choices made, with the why.
50
+
3. `## Actions` — steps taken, with brief results or pointers.
51
+
4. `## Files touched` — list of paths with one-line descriptions of what changed.
52
+
5. `## Verification` — `pnpm check` / `pnpm test` / `pnpm lint` results, with command + outcome.
53
+
6. `## Follow-ups / stubs` — things deferred, stubbed, or flagged for later.
54
+
55
+
The template says "fill at end, not during" and "size scales with task" — trivial tasks get short notes (one or two lines per section), not skipped sections. A task note with fewer than the six sections is incomplete.
23
56
24
57
## Constant process pipeline
25
58
+45
agent-notes/2026-06-11-01-consolidate-agent-instructions.md
+45
agent-notes/2026-06-11-01-consolidate-agent-instructions.md
···
173
173
## Follow-ups / stubs (turn 3 additions)
174
174
175
175
- The 2026-06-03-02 process-updates task note's "Refinement after first commit" decision is now slightly misleading — it says "The agent hands back; merge is a human decision," which is still true but doesn't capture the new "agent may push + may tag" detail. Not worth a separate doc-edit commit; future archaeology / pulse passes can pick it up.
176
+
177
+
---
178
+
179
+
# Turn 4: standardize the tags/labels vocabulary
180
+
181
+
The user asked whether we are now standardizing the tags/labels we use. The honest answer before this turn: tags/labels were _partially_ standardized (chronver for version tags, the triage state machine for issue labels, the deciduous status vocabulary for graph nodes) but the _commit and branch naming_ vocabularies were de facto conventional-commits, not written down. The 2026-06-03-02 task note explicitly flagged this as "a future task."
182
+
183
+
The user greenlit option (c) for the type list: enumerate the canonical 10 in AGENTS.md, link to conventional-commits 1.0.0 as the upstream reference, and let forks extend or trim the list per `suede-kickoff` Thread B.
184
+
185
+
## Decisions (turn 4)
186
+
187
+
- **Branch and commit naming now standardized.** AGENTS.md "Branch and commit naming" subsection is the canonical reference. Branch names are `<type>/<slug>`; commit messages are `<type>(<scope>): <subject>`; both share a single type vocabulary. The canonical 10 types (`feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `build`, `ci`, `perf`, `style`) are the conventional-commits 1.0.0 list, enumerated inline so the agent doesn't have to fetch the spec on first use. `chore(release):` is reserved for the version-bump commit on a release branch.
188
+
189
+
- **Fork-extensible / fork-trimmable.** A fork that needs an extra type (`i18n` for a content project) or wants to drop one (`perf` for a backend MCP) records the override in `suede-kickoff` Step 3 Thread B Q8 sub-bullet "Branch and commit naming" and the agent updates AGENTS.md to match. The override lives in AGENTS.md, not in a per-fork convention file, because the agent should be able to read AGENTS.md at task start and get the right vocabulary.
190
+
191
+
- **Task note naming convention formalized.** AGENTS.md "Layout" now defines `YYYY-MM-DD-NN-<slug>.md` with the per-day counter rules. The template at `agent-notes/0000-00-00-00-task-template.md` is referenced as the source for the 6 section headings; AGENTS.md restates the 6 sections and the "all six required, not optional" rule. (The 2026-06-04-03 SuedeButton task note's follow-up flagged that some prior task notes are missing sections — the new rule is the explicit answer.)
192
+
193
+
- **OpenCode file naming standardized to kebab-case.** AGENTS.md "Layout" now states that all filenames in `.opencode/{agents,commands,plugins,tools}/` use kebab-case, and that skill directories are `kebab-case` and contain a single `SKILL.md`. Aligns with the existing files (`suede-kickoff/`, `tdd-supplementary/`, `task-lifecycle/`, `require-action-node.ts`, `post-commit-reminder.ts`).
194
+
195
+
- **What I did NOT change.** Deciduous node labels (`-c 0-100`, status `completed` / `rejected` / `pending` / `superseded` / `abandoned`) — already standardized in the global `deciduous` tool, no rule needed in suede. GitHub triage labels (`needs-triage` etc.) — already standardized in the global `triage` skill, referenced in AGENTS.md pipeline section. Storybook `tags: ['autodocs']` — Storybook's own, not our concern. Svelte / TypeScript identifier casing — language conventions, not ours.
196
+
197
+
## Actions (turn 4)
198
+
199
+
- Updated `AGENTS.md` Git workflow: new `### Branch and commit naming` subsection with the type vocabulary, branch-name format, commit-message format, and fork-extension rule.
200
+
- Updated `AGENTS.md` Layout: bullet 1 (task notes) now spells out the `YYYY-MM-DD-NN-<slug>.md` filename pattern with the per-day counter rules. New bullet 4 added for `.opencode/{agents,commands,plugins,tools}/` (kebab-case files + skill directories).
201
+
- Updated `AGENTS.md` Layout: new `### Task note section headings` subsection listing the 6 required sections from the template, in order, with the "all six required" rule.
202
+
- Updated `.opencode/skills/suede-kickoff/SKILL.md` Thread B Q8 sub-bullet "Branch and commit naming": rewritten to point at AGENTS.md's new rule, with the extension/trim override path.
203
+
204
+
## Files touched (turn 4)
205
+
206
+
- `AGENTS.md` — Git workflow (new Branch and commit naming subsection), Layout (task-note filename pattern, opencode kebab-case rule, new Task note section headings subsection).
207
+
- `.opencode/skills/suede-kickoff/SKILL.md` — Thread B Q8 sub-bullet rewritten to reference the new AGENTS.md rule.
208
+
209
+
## Verification (turn 4)
210
+
211
+
- `pnpm check` — pass. `svelte-check found 0 errors and 0 warnings`.
212
+
- `pnpm test` — pass. 5 files, 10 tests, 0 errors.
213
+
- `pnpm prettier --write` on the 2 touched files; both clean.
214
+
215
+
## Follow-ups / stubs (turn 4 additions)
216
+
217
+
- **Pre-existing task notes don't all conform to the new 6-section rule.** The 2026-06-04-03 follow-up noted that the SuedeButton task note's "Merge into main" section is in addition to the 6 standard sections, which is fine (extra sections are OK; missing ones are not). A pulse / archaeology pass could audit prior task notes and flag any that are missing required sections. Out of scope here; documented in the new rule for _future_ notes.
218
+
- **AGENTS.md is approaching 500 lines** (was ~390 before this PR, now ~498). Not yet at the threshold where it should be split, but a future consolidation pass could move the Decision Graph Workflow section to its own file (e.g. `DECISION_GRAPH.md`) and link to it from AGENTS.md. Not urgent.
219
+
- **The conventional-commits type list will eventually need updating.** When conventional-commits 1.1.0 ships (or whenever a fork-overridable extension becomes common), a future pass will need to revisit the list. The current date stamp ("as of this writing") and the upstream link make the renewal point obvious.
220
+
- **The `narratives` / `pulse` / `archaeology` skill directories are all kebab-case and contain a single `SKILL.md`** — they conform to the new rule, no action needed.