Repository navigation
docs(agents): conventional commits and subagent workflow for agents - #385
Open
TheMeinerLP wants to merge 4 commits into
Open
TheMeinerLP wants to merge 4 commits into
TheMeinerLP wants to merge 4 commits into
Conversation
Configures OpenSpec's per-artifact rules so proposal, task and archive work is generated with Conventional Commits messages and titles from the start, matching what release-please expects to read from squash-merged pull requests. Claude-Session: https://claude.ai/code/session_012ZzvomAnwjAS3et96Avp7s
Replaces the vague "follow the existing style" guidance with an explicit Conventional Commits rule (type(scope): summary, allowed types from release-please-config.json, breaking-change footer) since pull requests are squash-merged and release-please reads the PR title as the commit on main. Also corrects two stale statements: lint has pnpm lint/lint:fix scripts, and a Vitest suite now exists under tests/ and runs in CI. Claude-Session: https://claude.ai/code/session_012ZzvomAnwjAS3et96Avp7s
Adds a root CLAUDE.md that imports AGENTS.md and layers on only what it lacks: exact vitest invocations, test-environment details, deployment and image-provider facts, the OpenSpec planning workflow, and how work should be split across main-session orchestration and Sonnet/Haiku subagents. Every claim was checked against the current tree so nothing stale (edge-cache numbers, the finished MD3 migration, the unmerged season layer) carried over. Claude-Session: https://claude.ai/code/session_012ZzvomAnwjAS3et96Avp7s
CLAUDE.md overstated openspec/config.yaml as enforcing Conventional Commits on every artifact and operation. It only adds rules to the proposal and tasks artifacts and advisory guidance for apply and archive; nothing in it enforces anything. Claude-Session: https://claude.ai/code/session_012ZzvomAnwjAS3et96Avp7s
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
launchpad | 8fb2124 | Commit Preview URL Branch Preview URL |
Sep 24 2026, 07:17 AM |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
openspec/config.yaml(new): per-artifact OpenSpec rules that requireConventional Commits for every generated proposal and task, matching what
release-please reads.
AGENTS.md: replaces the vague "follow the existing style" commit rulewith an explicit Conventional Commits requirement (
type(scope): summary,the exact types from
release-please-config.json,!+BREAKING CHANGE:footer for breaking changes, and a note that PR titles are squash-merged
onto
main). Also fixes two statements that had gone stale onmain: lintnow has
pnpm lint/pnpm lint:fixscripts, and a Vitest suite existsunder
tests/and runs in CI viapnpm test.CLAUDE.md(new): importsAGENTS.mdand adds only what it lacks —exact
vitestinvocations, test-environment specifics, deployment/imageprovider facts, the OpenSpec planning workflow, and a short
"Working with subagents" section describing how orchestration is split
across the main session and Sonnet/Haiku subagents.
Rationale
only commit message release-please ever sees on
main; it must be a validConventional Commit or the version bump and changelog break.
AGENTS.md(read by every agent and humancontributor) and enforcing it in
openspec/config.yaml(read while anagent drafts OpenSpec artifacts) removes a recurring source of
release-please mismatches.
CLAUDE.mdthat only states whatAGENTS.mddoesn't lowers thetoken cost of every Claude Code session in this repo, instead of
duplicating or contradicting
AGENTS.md.Verification
openspec doctor→ OpenSpec root: ok.openspec list --json→ succeeded, listed the three existing changes.node -eYAML parse ofopenspec/config.yaml→ parsed with top-level keysschema,rules,operations.pnpm install --frozen-lockfile→ succeeded (node_modules was missing).pnpm quality→ ESLint errors 192, warnings 17, TypeScript errors 3 — allequal to baseline, no regression.
pnpm exec vitest run tests/architecture→ 19 files / 76 tests passed.CLAUDE.md(D1 binding, image provider fallback,i18n prefix strategy,
.nuxtrcchurn,@vitest-environmentusage,md3-tokens.mjs --check) was checked directly againstnuxt.config.ts,vitest.config.ts,scripts/md3-tokens.mjsand thetests/tree on thisbranch. Stale points from the original draft were dropped: the MD3
PENDING_MIGRATIONlist and pre-MD3 legacy tokens no longer exist onmain(removed in chore(design-system): remove the legacy tokens and document MD3 #371), the season layer (layers/season,feat/halloween-season) isn't merged and was left out entirely, and theedge-caching numbers are covered by AGENTS.md's own "Caching and SEO
signals" section instead of being repeated.
https://claude.ai/code/session_012ZzvomAnwjAS3et96Avp7s