codingthefuturewithai/teamcraft-jcg:learn-teamcraft

Goal

Teach TeamCraft. Give the team member a thorough, role-appropriate understanding of the plugin — the workflow, the skills available to them, how artifacts flow, and where they fit. No environment access, no setup required. This is a teaching conversation.

Hard Constraints

• No tool calls except AskUserQuestion. This skill does not read Jira, Confluence, GitHub, or the filesystem. It does not need to.
• Never transitions to doing work. Teaching only. If the team member wants to run a skill after this session, name it and explain how to invoke it — but do not run it here.
• Cowork compatible.

Establish What They Want to Learn

Ask whether they want:

• Role-specific: deep dive on their role in the TeamCraft workflow
• Full overview: the complete plugin — all phases, all roles, how everything connects
• Core skills: the essential set — if the full skill list feels overwhelming, start here

If they name a role, go deep on that role. If they want everything, walk the full workflow. If they want the core skills, use the Core Skills section below.

Core Skills — The Essential Set

TeamCraft has a lot of skills because it covers a lot of ground — from problem discovery through sprint retrospectives. That breadth can feel overwhelming. This section cuts through it: 10 skills form the backbone of the entire workflow. Everything else extends, enhances, or supports what these 10 do.

Present these in three groups and explain why each skill matters — not just what it does.

---

Foundation (run once per project)

These four skills establish the project. Without them, every downstream skill operates with less context and produces weaker results.

• teamcraft-setup — Verifies that Jira, Confluence, and GitHub MCP connections are working. Nothing else in the plugin functions without these connections. Run this first, once.

• init-project — Creates the project scaffold: .teamcraft/project.md, CLAUDE.md, .claude/rules/, .github/workflows/ci.yml. This is the local project context that the build loop reads on every issue. Without it, planning and implementation sessions start cold with no project awareness.

• capture-requirements — Produces the PRD in Confluence. The PRD is the requirements backbone — plan-sprint derives issues from it, create-issue checks PRD integrity after creation, and define-roadmap organizes it into sprint-sized delivery. Without a PRD, the team is building from memory and conversation instead of a structured, shared source of truth.

• tech-decisions — Records the technology stack and key architectural choices in Confluence. Every plan-and-implement-issue session automatically loads this document so the developer plans against established decisions, not ad-hoc choices. Without it, each developer independently decides what libraries, patterns, and approaches to use — and those decisions diverge.

---

Sprint Planning (once per sprint)

• plan-sprint — Creates Jira backlog issues, creates the sprint, and adds the issues to it. This is where the PRD turns into actual work items with acceptance criteria, technical guidance, and testing requirements. The quality of issues created here directly determines the quality of what developers build from.

---

Build Loop (repeated for every issue — the daily work)

These five skills are the core development cycle. A developer runs them in sequence for each issue in the sprint.

• fetch-issue — Loads the Jira issue and scans the codebase for relevant existing code before any planning begins. Produces a feasibility assessment: is this ready to plan, partially started, already implemented, or blocked? Prevents wasted planning on issues that aren't ready.

• plan-and-implement-issue — Loads all project context — tech decisions, conventions, tech stack, and live library documentation via Context7 — then enters Claude Code's plan mode which plans and implements the solution. Detects existing work and offers to resume. Creates the feature branch, opens a Draft PR on the first commit, implements unit by unit with TDD discipline. The developer reviews after each unit before proceeding. This is why the foundation skills matter: it pulls in everything init-project, capture-requirements, and tech-decisions produced.

• complete-issue — The quality gate before human review. Runs code health, security, and deviation reviews automatically, pushes the branch, and marks the PR ready. The Jira issue key goes in the PR body for traceability. Without this step, PRs go to review without automated quality checks.

• pr-review — The reviewer's tool. Loads the full PR diff, implementation context, and comment threads without leaving Claude Code. Leave comments, approve, request changes, or merge — all from the CLI.

• post-merge — Closes the loop after merge. Explicitly closes the Jira issue (GitHub PRs don't auto-close Jira issues), cleans up stale status, and syncs local git state. This step is especially important in the JCG stack because without it, Jira issues stay open after the code is merged.

---

Why these 10 and not the other 16?

The remaining skills are genuinely valuable — they cover problem discovery, roadmap planning, convention capture, QA support, stakeholder communication, sprint retrospectives, codebase analysis, and more. But they extend the core workflow rather than define it. A team can ship quality software with just these 10 skills and add the others as their process matures.

If the team member wants to know what to add next beyond the core, recommend based on role:

• Developers: address-feedback (responding to PR review threads) and fast-path (urgent work that skips sprint ceremony)
• PMs: stakeholder-update and project-health
• Tech leads: analyze-codebase and capture-conventions

Role-Specific Teaching

Teach thoroughly for the named role. Cover what the role does, which skills they use, what artifacts they produce or consume, and how their work connects to the rest of the team.

---

Developer

The developer's world is the build loop in Claude Code. Walk through each step:

• fetch-issue — Load a Jira issue and get a codebase feasibility analysis before writing any code. Read-only. The starting point for every piece of work.
• plan-and-implement-issue — Load all project context (tech decisions, conventions, live library docs via Context7) into the session, then enter Claude Code's native plan mode which plans and implements the solution. Creates the feature branch, opens a Draft PR on the first commit. Implements unit by unit with TDD discipline. Detects existing work and offers to resume.
• complete-issue — Runs code health, security, and deviation reviews before pushing. Marks the PR ready for review. The Jira issue key goes in the PR body for traceability — Jira issue closure happens explicitly via post-merge, not automatically.
• pr-review — For when the developer is acting as reviewer: reads the diff, engages PR comment threads, approves or requests changes, merges.
• address-feedback — For when the developer is the author: polls for open reviewer threads, makes changes, pushes. Thread resolution happens in the GitHub UI.
• post-merge — After the PR merges: explicitly closes the Jira issue (no auto-close from GitHub PRs), cleans up stale status, syncs local git state.
• fast-path — Urgent work that can't wait for sprint planning. Skips ceremony, preserves all quality gates.

Where issues come from: upstream — the PM runs plan-sprint which creates Jira backlog issues, creates the sprint, and adds the issues to it. The developer picks issues up from there.

Where work ends up: merged to main, Jira issue explicitly closed, ready for the next sprint.

Codebase orientation: when joining a brownfield project or inheriting a codebase, analyze-codebase is the go-to skill. It runs a quick-pass analysis of the codebase (tech stack, structure, patterns, health), then offers deeper analysis based on what you need: architecture documentation, component-level .claude/rules/ files, ADR candidates extracted from the code, convention comparison against team standards, or a CLAUDE.md audit. The architecture doc it produces lands in .teamcraft/architecture.md and becomes a lasting reference for everyone on the project.

---

Product Manager

The PM's work happens in Claude Cowork (upstream) and is the source of everything the team builds. Walk through:

• discover-problem — Facilitate structured problem discovery with a client or stakeholder before any requirements are written. Helps narrow a problem space to a sharp problem statement. Produces a discovery summary in Confluence that seeds capture-requirements.
• capture-requirements — The PM's primary requirements tool. Run a live requirements session with a client, work solo from existing material, or update an existing PRD. Produces interactive visual mockups to confirm understanding and a structured PRD in Confluence. Works for new projects and follow-ups on existing ones.
• define-roadmap — The planning layer between a baselined PRD and sprint planning. Sequences what gets built over how many sprints, with priorities, dependencies, and capacity rationale. Stored in Confluence and feeds directly into plan-sprint.
• tech-decisions is the tech lead's domain, but the PM should understand it exists: it records what stack and architecture choices were made and why, and it feeds into the developer's planning automatically.
• capture-conventions is similarly the tech lead's domain — coding standards and review process. The PM doesn't run it but benefits from knowing it exists.
• plan-sprint — The PM's primary planning tool. Takes the PRD and turns it into a Jira backlog with well-formed issues, creates the sprint, adds issues to it, and optionally starts it. The quality of issues created here determines the quality of what developers work from.
• create-issue — Create a single issue at any time: client feedback from a demo, a bug found in production, a feature request that arrived mid-sprint. This is how unplanned work enters the system properly linked and tracked.
• stakeholder-update — Generate audience-appropriate status reports from live Jira and GitHub data. Client updates, executive summaries, engineering updates — each shaped for its audience. Stored in Confluence.
• project-health — On-demand sprint health: progress, velocity, quality signals. Available any time. Returns insight, not raw data.
• sprint-retro — Structured sprint retrospective from Jira sprint data. Facilitates the conversation and writes the report to Confluence.
• qa-support — The PM can use this to understand what's ready for testing or what QA found.

The PM is the upstream anchor. If the PRD is solid and sprint planning is thorough, the entire downstream build loop runs more smoothly.

---

Tech Lead / Architect

The tech lead's work is partly upstream (setting the foundation) and partly in the build loop (review and guidance). Walk through:

• tech-decisions — Record the technology stack and key architectural choices: what was decided, what alternatives were considered, and why. Reads the PRD for context. Produces a Confluence page that flows automatically into every developer's planning session.
• capture-conventions — Document team coding standards, review process, branching rules. Also produces a Confluence page that flows automatically into developer planning.
• plan-sprint — The tech lead often co-runs sprint planning with the PM. Same skill.
• pr-review — The tech lead's code review tool. Reads the full PR diff from GitHub, leaves structured feedback threads without leaving Claude Code.
• init-project — Sets up the project scaffold in Claude Code: .teamcraft/project.md, CLAUDE.md, .claude/rules/, .github/workflows/ci.yml. Typically the tech lead's first act on a new project. Requires Claude Code with local filesystem access.
• analyze-codebase — The tech lead's tool for understanding an existing codebase systematically. Produces architecture documentation (.teamcraft/architecture.md), component-level .claude/rules/ files, ADR candidates extracted from the code, and convention comparison reports that show where a repo diverges from team standards. Essential for brownfield projects and inherited codebases.
• pipeline-health — When a GitHub Actions workflow fails or stalls, this interprets what happened and surfaces next steps.
• sync-claude-md — Keeps CLAUDE.md current as the project evolves. Adds new non-obvious patterns, removes entries the codebase has made obvious.

The tech lead's artifacts — tech decisions, conventions, and architecture documentation — are the invisible scaffolding that makes the developer build loop work. Without them, every developer planning session starts cold.

---

QA Analyst

QA's role in TeamCraft is sprint-aware and bug-focused. Walk through:

• qa-support — The QA analyst's primary tool. Surface what's ready to test in the current sprint, prepare a testing approach for a specific issue, or capture a bug from testing findings. Works entirely in Cowork — no codebase access needed.
• create-issue — When testing finds a bug, this creates a properly formed Jira issue: linked to the right project, with reproduction steps, severity, and expected vs. actual behavior. Same quality standards as issues created by the PM.
• project-health — Available to QA as a read-only sprint health check: what's in progress, what's blocked, where things stand.

QA in TeamCraft is not an afterthought. Bug findings from qa-support feed directly back into the sprint as properly tracked issues.

---

DevOps Engineer

DevOps in TeamCraft is primarily about project setup and pipeline health. Walk through:

• init-project — The DevOps engineer (or tech lead) runs this in Claude Code to set up the project scaffold: .teamcraft/project.md, CLAUDE.md, .claude/rules/, and .github/workflows/ci.yml with test, lint, and security jobs for the detected tech stack. Attempts to set branch protection rules via the GitHub API. Uses GitHub-hosted runners — no runner setup required.
• pipeline-health — Interpret GitHub Actions workflow failures and stalls. Returns an explanation of what failed and why, not raw logs.

---

Full Overview

If the team member wants the complete picture, walk through the six phases of the TeamCraft lifecycle:

1. Team setup — init-project creates the project scaffold. analyze-codebase maps an existing codebase's architecture, surfaces ADR candidates, generates component rules, and compares repo practices against team conventions. onboard orients new members to the environment. learn-teamcraft (this skill) teaches the workflow.

2. Product definition and planning — The PM runs problem discovery (discover-problem), captures requirements and produces the PRD (capture-requirements), and defines the multi-sprint roadmap (define-roadmap). The tech lead records technology choices (tech-decisions) and coding standards (capture-conventions). The PM plans the sprint (plan-sprint) and manages ad-hoc issue creation (create-issue).

3. Build loop — The developer fetches an issue (fetch-issue), loads full context and enters plan mode which plans and implements the solution (plan-and-implement-issue), and completes the work with quality gates and PR creation (complete-issue).

4. Review and merge — The reviewer reads the diff and leaves feedback (pr-review). The author addresses threads and pushes changes (address-feedback). After merge, cleanup runs and the Jira issue is explicitly closed (post-merge).

5. Visibility — Any stakeholder can check sprint health at any time (project-health). Stakeholder updates are generated from live data for any audience (stakeholder-update). Pipeline failures are interpreted on demand (pipeline-health). QA validates sprint output (qa-support).

6. Continuous improvement — The sprint retrospective is structured and recorded (sprint-retro). CLAUDE.md is kept current as the project evolves (sync-claude-md).

The two Claude products: Claude Cowork handles phases 1–2 and 5–6. Claude Code handles phases 3–4. Most skills are Cowork compatible; the build loop and init-project require Claude Code.

Close

After teaching, ask if there's anything they want to understand more deeply. If they're ready to act, name the first skill for their role and tell them what to type to invoke it. Do not run it here.