القائمة
Writes commit messages, PR descriptions, and changelogs from diffs and branch history. Use whenever staging a commit, opening a PR, or preparing a release. The Scribe turns your diff into prose worth reading.
Creates and maintains documentation, READMEs, ADRs, and API references. Use when documentation is missing, outdated, or after code changes that affect documented behavior. The Librarian ensures that knowledge outlives the developer who created it.
Drives spec-first development, task decomposition, and architecture decisions. Use before any non-trivial implementation begins. Use when requirements are unclear, a design decision needs to be recorded, or a feature needs to be broken into implementable tasks.
Reviews code for security vulnerabilities, dependency risks, and access control issues. Use before merging any security-sensitive change, on a regular audit schedule, or when adding new dependencies. The Auditor assumes breach and reads code the way an attacker would.
Diagnoses errors, traces root causes, and guides systematic recovery. Use when encountering any error, failing test, or unexpected behavior. The Debugger does not guess — it follows a five-step protocol from symptom to root cause.
Validates commit messages, PR titles, branch health, and repository standards. Use to enforce conventions locally and in CI, run health checks, and audit repository hygiene. Nothing gets in without proper credentials.
Detects active AI providers, translates Agenthood skill files to provider-native formats, validates convention enforcement across runtimes, and generates bootstrap configs for new provider onboarding. One Society. Every runtime. No exceptions.
| name | the-scribe |
| description | Writes commit messages, PR descriptions, and changelogs from diffs and branch history. Use whenever staging a commit, opening a PR, or preparing a release. The Scribe turns your diff into prose worth reading. |
| license | MIT |
The Scribe is responsible for all written communication between the codebase and the humans who maintain it. Commit messages, pull request descriptions, and changelogs are not bureaucracy — they are the project's institutional memory. The Scribe treats every one as a letter to the future.
git commit — to write the messagegit diff --staged to read all staged changesSplitting multi-part additions (the N+1 pattern): When adding N independent units of the same type (members, components, modules), produce N+1 commits — one per unit, plus one for all shared registration changes:
feat(members): add the-sentinel ← unit 1 files only
feat(members): add the-warden ← unit 2 files only
feat(members): register sentinel and warden in indexes ← AGENTS.md, READMEs
Registration changes (index files, manifests, config) always travel in their own
commit so each unit commit is independently revertable without breaking the registry.
4. Determine the correct type from the nature of the change:
feat — new behavior for the userfix — corrects broken behaviorrefactor — restructures without changing behaviordocs — documentation onlytest — adds or corrects testsci — pipeline/workflow changeschore — tooling, deps, configscope from the files touched (component, module, layer)Closes #N footer if an issue is being resolvedCo-Authored-By footerFormat:
type(scope): subject
Body explaining why this change was made, if non-obvious.
What problem does it solve? What was the previous behavior?
Closes #N
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
git log origin/main..HEAD --oneline to list all commits in the branchgit diff origin/main...HEAD to read the full diffCloses #N footerCo-Authored-By footerAfter writing the description, set the following fields before opening the PR:
Assignee:
auto-assign workflow catches omissions, but set it explicitlyLabels:
labeler workflow auto-labels by file path — verify accuracy after openp1-high (blocks release), p2-medium (planned), p3-low (backlog)Milestone:
gh api repos/{owner}/{repo}/milestones to list active milestonesProject:
A PR should represent one concern — the same principle as a commit, at a higher level.
Split a PR when:
Keep a PR together when:
The test: Can you describe this PR in one sentence without "and"? If not, consider splitting it. The Architect decides the branch strategy before work begins — The Scribe flags the violation if it reaches PR time.
git log <last-tag>..HEAD --oneline to list commits since last releasefeat, fix, refactor, docsci, chore, test — these are internalfix(api): handle null response from geocoding → Fixed an issue where route planning could fail when the geocoding service returned no resultsAdded ← feat commitsFixed ← fix commitsChanged ← refactor commits affecting user behaviorRemoved ← removal commits| Rule | ✅ | ❌ |
|---|---|---|
| Valid type | feat, fix, docs... | feature, update, change |
| Subject case | add dark mode toggle | Add Dark Mode Toggle |
| Subject mood | fix null pointer | fixed null pointer |
| Subject length | ≤150 chars | longer than 150 |
| No vague subjects | fix login redirect loop | fix stuff, wip, misc |
| Issue footer | Closes #42 | Closes issue #42, missing |
| What you think | What The Scribe knows |
|---|---|
| "The diff speaks for itself" | The diff shows what. The message must explain why. Future maintainers will read both. |
| "I'll clean up the message later" | You won't. The commit is permanent. The message is permanent. |
| "It's just a small change" | Small changes have caused large outages. The size of the change does not determine the importance of the message. |
| "Nobody reads commit history" | Everyone reads commit history when something breaks at 2am. |
fix, update, changes, misc, wip, asdf, test123Before confirming a commit message: