PAIR-code / PAIR-code/deliberate-lab
chore(git): adopt agents(...) Conventional Commit prefix for AI developer governance and tooling
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 96
- Forks
- 40
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 20
Description
Problem
Deliberate Lab enforces Conventional Commits (feat:, fix:, docs:, chore:, refactor:, test:, etc.) for all PR titles, commit messages, and issue titles.
Currently, AI coding agents and contributors face two competing anti-patterns when authoring commits for developer-side AI tooling and workspace automation:
-
The SemVer / Changelog Distortion (
feat(skills)/fix(skills)):
Agents often label new skills or script enhancements asfeat(...)because it represents a new capability in their pairing toolchain. However,featandfixsemantically govern user-facing product runtime behavior (experiment participants, researchers, and backend services) and drive SemVer minor/patch versioning. Internal developer tooling should not trigger version bumps or pollute release notes intended for experimenters. -
The "Chore Junk Drawer" (
chore(skills)/chore(workspace)):
Relegating all agent tooling tochoreburies a first-class, actively developed architectural subsystem (.agents/skills/,.agents/decisions/, workspace synchronization) alongside routine janitorial tasks (lockfile updates,.gitignoretweaks, license year bumps). -
The "Agents" Naming Collision (ADR 0004):
ADR 0004 identified an active naming collision between in-experiment participant/mediator LLM agents (runtime:agents) and developer-side AI coding agents (.agents/). Using standard commit types makes it difficult to distinguish whether a commit touches runtime LLM personas or developer AI pairing skills.
Proposed Solution
Adopt a new, canonical top-level Conventional Commit type: agents.
Format:
agents(<scope>): <description>
1. Structural Disambiguation (Type vs. Scope)
By reserving agents as a top-level type, the boundary established in ADR 0004 is enforced strictly by syntax position:
agents(...)as the Type: Strictly scopes developer-side AI tooling, pairing skills, decision records, and workspace automation (.agents/,.bare/)....(agents)as the Scope: Underfeat:orfix:, strictly scopes in-experiment LLM participant agents (runtime:agents).
| Example Commit | Target Layer | Meaning |
|---|---|---|
agents(skills): add pr-test-plan pairing skill |
area:workspace |
Developer AI toolchain |
agents(workspace): auto-detect merged worktrees in sync |
area:workspace |
Developer workspace scripts |
agents(decisions): record ADR on maintainer PR lifecycle |
area:workspace |
Developer architecture record |
feat(agents): add Gemma 4 persona to chat stage |
runtime:agents |
In-experiment LLM participant feature |
fix(agents): resolve prompt timeout in mediator |
runtime:agents |
In-experiment LLM participant bugfix |
2. Recommended Scopes under agents:
agents(skills): Enhancements or additions to.agents/skills/*(e.g.eval-pr,gh,pr-test-plan).agents(workspace): Bare repository scripts, worktree tooling, and developer environment configuration (workspace-sync,workspace-overview,.nvmrc).agents(decisions): Architecture decision records in.agents/decisions/*.agents(rules): Agent instructions and behavioral prompts inAGENTS.md.
3. Standard & Tooling Compatibility
- Conventional Commits Compliant: Conventional Commits explicitly allows project-defined types beyond
featandfix. - Zero SemVer / Release Notes Impact: Because
agentsis notfeatorfix, automated changelog tools will not misclassify developer-side AI updates as product releases. - Instant Discoverability: Enables clean filtering via
git log --grep="^agents"or GitHub PR searches (is:pr "agents(").
Action Items
- Codify the
agents:prefix in root and worktreeAGENTS.mdunder Conventional Commits. - Update ADR 0004 (or record in a dedicated Git conventions ADR) to formally document the type-vs-scope rule.
- Retitle issue #1257 to
agents(workspace): auto-detect and clean up merged feature worktrees in workspace-sync.
Related Context
- ADR 0004 (
0004-repository-layer-taxonomy.md) - #1247 (Codify maintainer PR evaluation protocol)
- #1257 (Auto-detect and clean up merged feature worktrees in workspace-sync)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the root and worktree AGENTS.md Conventional Commits sections and ADR 0004, then review issue #1257 for the requested title change. Done means the agents: convention and type-versus-scope rule are documented consistently, ADR 0004 is updated or a dedicated conventions ADR is recorded, and #1257 has the specified title.
Written by the indexing model from the issue text.
Assessment
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- Half a day
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100