From hatch3r
Elicits, drafts, aligns, and persists team coding conventions and working agreements as versioned artifacts (convention doc and/or project rule). Use when setting up shared norms or reconciling conflicting style decisions.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hatch3r:hatch3r-team-convention-authorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Captures a team's tacit coding conventions and working agreements into a single versioned artifact the whole team can read and an agent can enforce. Two output shapes: a **convention doc** (`docs/process/` markdown — for human-facing working agreements: ownership, review norms, communication) and a **project rule** (`.hatch3r/overrides/rules/` — for machine-enforceable code conventions: naming,...
Captures a team's tacit coding conventions and working agreements into a single versioned artifact the whole team can read and an agent can enforce. Two output shapes: a convention doc (docs/process/ markdown — for human-facing working agreements: ownership, review norms, communication) and a project rule (.hatch3r/overrides/rules/ — for machine-enforceable code conventions: naming, structure, lint deltas — so the rule is tracked by hatch3r status/verify and regenerated into the adapter surfaces on sync, not written drift-invisibly into a generated file). The load-bearing step is Step 1: a convention written FOR a team by one person decays; a convention written BY the team through elicitation holds (team-charter methodology — see References).
Task Progress:
- [ ] Step 0: Detect ambiguity (P8 B1)
- [ ] Step 1: Elicit the team's conventions and working agreements
- [ ] Step 2: Classify each item — code convention (rule) vs working agreement (doc)
- [ ] Step 3: Cross-check against existing project rules and style guides
- [ ] Step 4: Draft to the matching template
- [ ] Step 5: Review with the team, then persist as a versioned artifact
Before any write, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target surface, or irreversibility. If any are found, ask the user via the platform-native question tool per agents/shared/user-question-protocol.md. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: which convention class is wanted (machine-enforceable code rule vs human working agreement); whether an existing convention doc/rule is being amended (a section rewrite that drops prior agreements is irreversible to readers who relied on them); the authoritative style guide for the stack (a new convention that contradicts an adopted style guide needs an explicit override decision); and who ratifies (one maintainer's preference is not a team agreement — see Step 5).
Fan-out scales with task size; token cost never justifies serializing independent work (rules/hatch3r-fan-out-discipline.md P8 B2; agents/shared/efficiency-patterns.md). Tier boundaries for THIS skill:
Emit sub_agents_spawned: { count, rationale } in your output.
A convention is only adopted if the team shaped it. Elicit, do not dictate. Ask the team (or the maintainer relaying for the team) across these prompts, one focused question per turn:
For each candidate, capture: the convention, one concrete example, and the rationale (why this over the alternative). A convention with no rationale is a preference, not an agreement — flag it for Step 5 ratification.
Route each elicited item to its output shape. The distinction drives where the artifact lands and how it is enforced.
| Item type | Output shape | Lands in | Enforcement |
|---|---|---|---|
| Machine-checkable code rule (naming, structure, import order, lint delta) | Project rule | .hatch3r/overrides/rules/<id>.md (+ .mdc companion) so hatch3r status/verify track it and sync regenerates it into the adapter surfaces; OR a linter config | Agent reads the rule each session; linter where expressible |
| Human working agreement (review norms, merge policy, communication, decision-recording) | Convention doc | docs/process/<topic>.md | Read by humans; cited in PR templates and onboarding |
| Pure-style point already owned by an adopted style guide | Neither — link to the style guide | The convention doc's "Authority" section | The style guide is the source of truth; do not restate it |
Do not duplicate a rule the adopted style guide or an existing linter config already enforces — link to it instead (single-source-of-truth; restating drifts). A code convention that a linter can check belongs in the linter config with a one-line pointer from the rule, not as prose the agent must interpret.
Write a machine rule into .hatch3r/overrides/rules/, not directly into a generated adapter surface such as .cursor/rules/*.mdc or docs/process/. A rule authored straight into the adapter output is invisible to hatch3r status/verify drift detection and is overwritten on the next sync regeneration (SA14.3-F6). The overrides subtree is the user-content surface hatch3r re-emits with overrides on every sync; docs/process/ stays the home for human working agreements only.
Before drafting, reconcile against what already exists:
description. A new convention that overlaps an existing rule is an amendment to that rule, not a new file (per content-authoring duplication check).Output of this step: a reconciliation list — { candidate, status: new | amends:<rule-id> | conflicts:<source> | duplicate-drop }.
Project rule (machine-enforceable code convention):
.hatch3r/overrides/rules/<id>.md plus the .mdc companion (same body bytes; scope: always → alwaysApply: true, scope: conditional + globs → globs: [...] + alwaysApply: false). This is the user-content override surface hatch3r tracks for drift and regenerates on sync — the same path the cursor rule importer writes to.id, description (one line, what the rule enforces), scope (always for repo-wide, or a glob for path-scoped).Convention → one concrete example → rationale. State the passing condition concretely ("test files live next to source as *.test.ts", not "tests organized well").Convention doc (docs/process/<topic>.md, working agreement):
Both shapes: every agreement carries a rationale; no agreement is stated as an unexplained mandate. Use measurable passing conditions, not subjective adjectives ("PR description states the change and the why", not "good PR descriptions").
A convention written for a team is weaker than one written by a team; ownership is built, not delegated (team-charter methodology — see References). Before persisting:
.hatch3r/overrides/rules/<id>.md + its .mdc companion. This registers the rule in the user-content override surface, so hatch3r status/verify report drift on it and hatch3r sync regenerates it into the adapter outputs (.cursor/rules/, CLAUDE.md, Copilot instructions). A convention written straight into a generated adapter file instead is drift-invisible and is clobbered on the next sync (SA14.3-F6) — never persist there. If the team is instead amending an existing canonical rule rather than adding a new one, register the delta in .hatch3r/hatch.json customization (or the .customize.md layer) for that rule id, not a fresh override file.docs/process/<topic>.md (human-facing; not a drift-tracked machine artifact).
Set the ownership footer (owner, ratifying team, last-updated) on each. Link the doc from the contributing guide or PR template so it is discoverable; an unlinked convention doc is not adopted.status: proposed — pending team ratification and list the unresolved items; do not stamp it as an adopted agreement.proposed — pending ratification); ownership + last-updated footer present.hatch3r/overrides/rules/<id>.md (+ .mdc) — or registered via .hatch3r/hatch.json customization when amending a canonical rule — so hatch3r status/verify track them and sync regenerates them; not authored straight into a generated adapter filedocs/process/, linked from contributing guide / PR template, and the negotiable-vs-default decision trail recordedhttps://google.github.io/eng-practices/review/reviewer/standard.html (accessed 2026-06-02, google.github.io, established-library / official-docs; CC-BY 3.0). Source for Step 1's authority principle (the style guide is the absolute authority on pure-style points; any style point not in the guide is personal preference) and the improvement-over-perfection framing applied to convention adoption. Repository: https://github.com/google/eng-practices.https://www.atlassian.com/work-management/project-collaboration/team-charter (accessed 2026-06-02, atlassian.com, established-library). Source for Step 1's elicitation stance and Step 5's ratification principle (a charter written BY the team holds; one written FOR the team decays — ownership is built, not delegated) and the purpose/values/roles/communication-norm component set behind the convention-doc template. Corroborated by Easy Agile, "Team Charter, Working Agreement, & Social Contract — Template and Guide." https://www.easyagile.com/blog/team-charter-working-agreement-social-contract-template-guide (accessed 2026-06-02, easyagile.com, established-library).npx claudepluginhub hatch3r/hatch3r --plugin hatch3rGuides extraction of tacit team conventions into explicit, enforceable artefacts using five structured questions. Use for new projects, AI codebase onboarding, team changes, or inconsistent AI output quality.
Authors enforceable project constitutions for greenfield projects with testable principles, enforcement mechanisms, rationale, and amendment processes.
Writes AI-optimized docs like README, CLAUDE.md, AGENTS.md, commit messages, PR descriptions using tables, checklists, absolute paths, invariants for cold project starts.