codingthefuturewithai/teamcraft:capture-team-conventions

Goal

Own the full lifecycle of this team's operating conventions and project gotchas. The authoritative document lives in the team-conventions category (opinionated default /docs/conventions.md). Specific items Claude would reliably do the wrong way without always-loaded guidance get promoted into CLAUDE.md or .claude/rules/ — with explicit developer approval per item.

Read references/example-conventions.md first. It shows the shape of the full document, the shape of promoted gotchas, and what distinguishes the two.

Why This Skill Exists

Captured conventions that Claude never consults are just documentation nobody reads. Captured conventions loaded into every session are context-budget bloat. Neither is acceptable. This skill produces one authoritative document AND selectively promotes the items Claude would actually get wrong without nudging — trusting the build-loop skills to direct consultation of everything else.

Detect What Exists

Look for an existing team-conventions document. If you find one, read it and present a brief summary to the developer before interviewing: "I see conventions documented for [areas]. What are we doing today?"

If you find conventions in a non-default location, note it. The skill still works — Claude will locate the document when consulting — but inform the developer that Teamcraft's opinionated default is /docs/conventions.md, and offer migration. If the developer declines migration, warn that mismatched expectations may degrade reliability of build-loop consultation, then proceed with the existing location.

If no conventions document exists anywhere, this is a first-time capture.

Establish Intent

The first question is what kind of capture this is. The flow depends on the answer.

Common scenarios:

1. First-time capture (new or newly-adopted project)
2. Adding a new convention area (team now has a deploy-freeze policy)
3. Updating an existing convention (merge strategy changed from merge commits to squash)
4. Capturing a newly-discovered gotcha (team realized Claude keeps getting the commit-message format wrong)
5. Cleanup (prune obsolete conventions, consolidate overlapping entries)
6. Review & certify an existing doc in place (a conventions doc already exists — often inherited or written outside Teamcraft — and the developer wants it verified and certified as accurate, not rewritten)

Ask the developer which applies. Don't run a full first-time interview on a targeted update — that's wasteful and annoying.

Ask About External Sources

Regardless of scenario, ask whether any relevant documentation exists outside the repo — old wikis, team handbooks, shared docs, onboarding guides, ADRs. Read what the developer points you to. Present what you found and let the developer decide what applies to this project now. Never auto-apply external content.

Conduct the Capture

Frame the domain and the scenario; let the conversation flow naturally. You know what operating conventions cover — branching, testing, review, merge, deploy, security, compliance, definition of done, incident handling, on-call, code style beyond linters. Ask about what matters for this scenario. For a first-time capture, be comprehensive. For a targeted update, stay narrow — don't fish for unrelated changes.

On definition of done specifically: Teamcraft already ships a baseline applied to every item — tests written/updated, run, and green; docs updated; no leftover scaffolding (../references/definition-of-done.md). When capturing a DoD here, capture only what's specific to this team on top of that floor (e.g., changelog entries, an a11y pass on UI work, integration tests for new endpoints) — don't restate the basics. The build loop honors both the baseline and what the team adds.

Do not read mechanical question lists aloud. The developer is a professional; conduct a real conversation about how their team works.

When the scenario involves retiring or consolidating content (cleanup, major updates), don't classify blocks for removal only at the block level — scan within each retiring block for embedded methodology: process rules, decision criteria, when-to-do-X signals (e.g., "when to flip a status," "when to add a principle"). Those are often the durable knowledge even when the surrounding inventory is stale. Preserve them — move them into the right section of the new doc — rather than letting them go with the block.

Present for Review

Show the full document (or the specific diff, for targeted updates) before writing. For first-time captures or major updates, start with a high-level summary the developer can course-correct on before reviewing every line.

Write the Document

Write to the opinionated default (/docs/conventions.md) unless an existing location was confirmed. Preserve structure of any existing file. Include what changed and why as part of the commit message (the skill directing commit messages handles format separately).

Certify the document. Stamp it with the Teamcraft provenance block per ../references/doc-provenance.md, so build-loop skills can tell this is teamcraft-verified rather than inherited or stale. When you authored or rewrote the content, stamp kind: created. On the review-&-certify-in-place path — the developer confirmed an existing/inherited doc is accurate and you are not rewriting it — insert or refresh ONLY the stamp block (kind: reviewed) and leave the body untouched. Source date from the system clock and plugin_version from the plugin manifest, as the reference describes.

Identify and Promote Gotchas

After the document is confirmed, walk through its contents and identify items Claude would reliably get wrong without always-loaded guidance. The test:

Could Claude figure this out from the codebase, or from reading the conventions document when a build-loop skill directs consultation? If yes, it stays only in the document. If no — Claude would default to something from training data without always-loaded guidance — it's a promotion candidate.

Good candidates: non-obvious commit-message formats, unusual branching patterns, non-standard testing tiers the team requires, conventions that explicitly override widely-held industry norms.

Weak candidates: "we use Vitest" (discoverable from package.json), "PRs need a description" (standard practice Claude follows anyway), the full text of a 10-page contribution guide.

Propose each promotion candidate to the developer individually. For each, show the text that would be promoted and the target (an always-loaded location — add to an existing rules file, add to CLAUDE.md, or create a new focused rules file). Developer approves, rejects, or edits the text. Write each approved promotion directly.

Respect Domain Ownership

This skill writes conventions, gotchas, and promotions. It does not write technology decisions (that's capture-technical-design) or product requirements (that's capture-requirements). If the conversation drifts into those areas, note it and redirect.

When You're Done

Confirm what was written and where — the conventions document plus any promoted gotchas. If the developer wants to keep capturing (more convention areas, additional gotchas), stay in the skill.

Ask the developer explicitly: "Are you satisfied with what was captured?" Wait for confirmation. This skill doesn't get to decide the work is done.

Once they're satisfied, point them to the natural next step: another capture skill if more knowledge is still undocumented (/capture-technical-design, /capture-requirements), /check-project-context to verify Claude has actually absorbed what was captured, or /plan-iteration / /pick-next-issue to start putting the conventions to work.