teamcraft:learn-teamcraft

What this skill does

## 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

- This skill reads the plugin's **own** skill set to teach the current lineup (see The Full Picture), but never the user's project — not their work items, docs, or code. (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.
- **A built-in Definition of Done.** Beyond each item's own acceptance criteria, every item is held to a tiny baseline the models tend to skip — tests written *and actually run*, docs updated, no leftover scaffolding. It's planned for, required at completion, and checked before the PR (as overridable warnings, not red tape). Teams extend it via captured conventions.
- **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

Teamcraft's skills group into three phases. Teach the phases and their purpose (below) — but **don't recite a memorized skill list; it goes stale the moment a skill is added, renamed, or removed.** Instead, read the *current* set live and teach from that:

> Glob `${CLAUDE_PLUGIN_ROOT}/skills/*/SKILL.md` and read each one's `name` and `description` frontmatter — the `description` states what the skill does and when to use it, and is always current with the installed version. Slot each skill into the phase its purpose fits, using the rubric below. (If you can't read the plugin directory in this environment, the Teamcraft skills already available to you in context are the fallback source — teach from those.)

To describe any single skill — what it does, when to reach for it — pull straight from its `description`. That's the canonical source and never out of date.

**Phase 1 — Setup & Evolving Knowledge.** Establish the project and keep its captured knowledge current — scaffolding the repo structure, and capturing then maintaining the team's conventions, technical design, and product requirements. Not one-time waterfall steps; lifecycle skills you re-run whenever a decision changes. The capture skills create *and* maintain their docs, certify them with the provenance stamp, and can review-and-certify an inherited doc in place. *Slot here: skills whose job is scaffolding, or capturing/maintaining project knowledge.*

**Phase 2 — The Build Loop.** Take one work item from idea to merged. The stable spine is **capture a work item → (optionally scope it into a time-boxed iteration) → pick what's next → plan & implement it against the captured knowledge → validate it through the quality reviews → work through review feedback → merge it** — each step its own skill. Two guardrail **hooks** also run automatically: one pauses before risky git commands (force-push, hard reset…), the other validates a work-item file after you commit it. *Slot here: skills that move a work item through its lifecycle.*

**Phase 3 — Visibility & Reflection.** Anytime, for anyone — reporting status, visualizing the board, reflecting in a retro, keeping the always-loaded rules lean, and diagnosing what Claude actually knows about the project. *Slot here: skills that report, visualize, reflect, or diagnose rather than change work.*

## If the list feels like a lot

The backbone is small. Set up knowledge with the capture skills, then the daily loop is just **capture a work item → plan & implement → validate → merge** (with a pick-next step to choose, and the review-feedback skill 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.