codingthefuturewithai/teamcraft:learn-teamcraft

Goal

Teach how Teamcraft works — the workflow, the skills, and how they connect — to whoever needs it: a human getting oriented, or Claude building its mental model before working in a Teamcraft project. This is a teaching conversation about the plugin, not an analysis of any particular project. No files, no environment, no setup.

Hard constraints

• The only tool here is AskUserQuestion. This skill teaches the plugin, which is the same in every repo — it does not read the filesystem, the work items, or the docs. (For the state of a specific project, that's project-status or check-project-context, not this.)
• Teaching only — never transition into doing real work. If the reader is ready to act, name the skill they want and how to invoke it, then stop.
• Works anywhere, including Claude Cowork.

Read the room first

Two kinds of reader arrive here:

• Orienting — someone (often Claude itself) just needs to understand how Teamcraft fits together. Give them The Full Picture below, directly — don't gate it behind a question.
• A human who wants a guided session — ask what they'd like to focus on: the full picture, just the daily build loop, or a specific area (capturing knowledge / quality gates / visibility). Then go deep there, and teach why each piece matters, not just what it does.

When in doubt, give the full picture and offer to go deeper.

What Teamcraft is

Teamcraft is one of a family of plugins for running a software project with Claude as the primary worker. They share the same workflow shape; they differ in where the project's docs and work items live. This variant keeps everything in the repo — work items as files under .teamcraft/, project docs under /docs/ — so it needs no external tools or accounts.

The whole idea in one line: capture the team's wisdom once, have Claude consult it on every piece of work, and keep humans approving at the moments that matter. Every skill exists to make that loop reliable.

The ideas that make it work

Teach these before the skill list — the skills make sense once these land:

• Captured knowledge, by category. Four kinds of project knowledge live in known places: team conventions, system architecture, technology decisions, and product requirements. Build-loop skills consult them by category, so Claude plans against what the team actually decided instead of guessing from training-data defaults.
• Certified, not just present. Those docs carry a Teamcraft certification stamp. A consuming skill checks it: a stamped doc is trusted; an unstamped one (common in inherited repos) is flagged as UNVERIFIED so nobody trusts stale, inherited content by accident. It flags — it doesn't block.
• Always-loaded vs on-demand. A small set of non-obvious gotchas lives in CLAUDE.md / .claude/rules/ and loads every session. Everything else is on-demand — read only when a task touches it. That keeps the agent sharp without bloating every prompt.
• Work items and their lifecycle. A work item is one unit of work. It moves through five states — backlog → ready → in-progress → in-review → done — and each transition is a commit, so the git history is the audit trail.
• Handoffs happen through the repo, not between skills. Skills don't call each other. Each one reads the current state (the work item, the branch, the open PR), does its part, and updates that state; the next skill picks up from there. That's why a human can step in at any boundary.
• Human gates. Claude does the heavy lifting; the human approves the plan, decides what's worth fixing, and decides when to merge. Nothing destructive or externally visible happens without a yes.

The Full Picture — three phases

Phase 1 — Setup & Evolving Knowledge (establish the project, then keep it current)

Not one-time waterfall steps — lifecycle skills you re-run whenever a decision changes.

• init-project — scaffolds the project (.teamcraft/, the work-item index, a minimal CLAUDE.md). Run once; everything downstream assumes it exists.
• capture-team-conventions — how the team works (branching, testing, review, merge, deploy) plus project gotchas.
• capture-technical-design — system architecture and per-area technology decisions, with the why and when to revisit.
• capture-requirements — the product requirements (PRD); can decompose new requirements straight into work items.

All three create and maintain their docs, certify them with the provenance stamp, and can review-and-certify an inherited doc in place without rewriting it.

Phase 2 — The Build Loop (per work item — the daily work)

• create-issue — capture a unit of work as a structured work item with acceptance criteria.
• pick-next-issue — see the backlog by priority and choose what's next. Read-only; no recommendations — you decide.
• plan-and-implement-issue — the main build skill: establishes the work branch, consults the captured knowledge (verifying its certification), plans with you, implements, keeps tests green.
• validate-issue — the quality gate. Runs three review agents in parallel — code-health, security, and acceptance (against the work item's criteria) — presents findings, then opens/updates the PR and watches CI.
• address-review-issue — works through reviewer feedback, round by round.
• merge-issue — the only skill that marks a work item done; finalizes on the branch, then merges.

Two guardrail hooks run automatically: one pauses before risky git commands (force-push, hard reset…), the other validates a work-item file after you commit it.

Phase 3 — Visibility & Reflection (anytime, for anyone)

• project-status — an on-demand dashboard (status, aging, cycle times, throughput) generated from the repo.
• work-board — a live, drag-and-drop kanban in the browser, off the same work items.
• run-retro — a facilitated retrospective; routes decisions back to the capture skills that own them.
• refresh-project-rules — keeps the always-loaded layer lean and accurate as the code evolves.
• check-project-context — a diagnostic: what does Claude actually know about this project, and which captured docs are certified?

If fifteen skills feels like a lot

The backbone is small. Set up knowledge with the three capture-* skills, then the daily loop is just create-issue → plan-and-implement-issue → validate-issue → merge-issue (with pick-next-issue to choose, and address-review-issue when a reviewer weighs in). Everything in Phase 3 is support you reach for when you want it. A team can ship with the backbone alone and grow into the rest.

Close

When the teaching is done, ask what they'd like to go deeper on. If they're ready to act, name the first skill for what they're doing and tell them how to invoke it — then stop. Don't run it from here.