PAIR-code / PAIR-code/deliberate-lab

chore(git): adopt agents(...) Conventional Commit prefix for AI developer governance and tooling

Open
#1,258 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:git area:workspace
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:

  1. The SemVer / Changelog Distortion (feat(skills) / fix(skills)):
    Agents often label new skills or script enhancements as feat(...) because it represents a new capability in their pairing toolchain. However, feat and fix semantically 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.

  2. The "Chore Junk Drawer" (chore(skills) / chore(workspace)):
    Relegating all agent tooling to chore buries a first-class, actively developed architectural subsystem (.agents/skills/, .agents/decisions/, workspace synchronization) alongside routine janitorial tasks (lockfile updates, .gitignore tweaks, license year bumps).

  3. 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: Under feat: or fix:, 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 in AGENTS.md.
3. Standard & Tooling Compatibility
  • Conventional Commits Compliant: Conventional Commits explicitly allows project-defined types beyond feat and fix.
  • Zero SemVer / Release Notes Impact: Because agents is not feat or fix, 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
  1. Codify the agents: prefix in root and worktree AGENTS.md under Conventional Commits.
  2. Update ADR 0004 (or record in a dedicated Git conventions ADR) to formally document the type-vs-scope rule.
  3. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.