codingthefuturewithai/teamcraft-glgd: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 GitLab, Google Drive, 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 GitLab and Google Drive 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/, .gitlab-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 Google Drive. 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 Google Drive. 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 the GitLab milestone and populates it with well-formed issues. 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 GitLab 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 MR 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 MR ready. Includes Closes #IID so the issue auto-closes on merge. Without this step, MRs go to review without automated quality checks.

• mr-review — The reviewer's tool. Loads the full MR diff, implementation context, and discussion threads without leaving Claude Code. Leave comments, approve, or merge — all from the CLI.

• post-merge — Closes the loop after merge. Confirms the issue is closed in GitLab, cleans up stale labels, and syncs local git state. Prevents label drift and stale local branches from accumulating across sprints.

---

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 MR 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 GitLab 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 MR 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 MR ready for review. Includes Closes #IID so the issue auto-closes on merge.
• mr-review — For when the developer is acting as reviewer: reads the diff, checks out the branch locally, leaves structured feedback threads.
• address-feedback — For when the developer is the author: polls for open reviewer threads, makes changes, pushes, resolves addressed threads.
• post-merge — After the MR merges: verifies the issue is closed, cleans up stale labels, 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 the GitLab milestone and issues. The developer picks them up from there.

Where work ends up: merged to main, issue 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:

• 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 Google Drive. Works for new projects and follow-ups on existing ones.
• 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 GitLab milestone with a backlog of well-formed issues. 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.
• project-health — On-demand sprint health: progress, velocity, quality signals. Available any time. Returns insight, not raw data.
• sprint-retro — Structured sprint retrospective from GitLab milestone data. Facilitates the conversation and writes the report to Google Drive.
• 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 Google Drive document that flows automatically into every developer's planning session.
• capture-conventions — Document team coding standards, review process, branching rules. The PM doesn't run it but benefits from knowing it exists. Also flows automatically into developer planning.
• plan-sprint — The tech lead often co-runs sprint planning with the PM. Same skill.
• mr-review — The tech lead's code review tool. Reads the full MR diff from GitLab, checks out the source branch locally, and 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/, .gitlab-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 CI/CD pipeline 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 GitLab issue: linked to the right milestone, 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 .gitlab-ci.yml with test, quality, and security stages for the detected tech stack. Attempts to set merge protection via GitLab's GraphQL API.
• pipeline-health — Interpret CI/CD pipeline 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 captures requirements and produces the PRD (capture-requirements). 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 MR creation (complete-issue).

4. Review and merge — The reviewer reads the diff and leaves feedback (mr-review). The author addresses threads and pushes changes (address-feedback). After merge, cleanup runs automatically (post-merge).

5. Visibility — Any stakeholder can check sprint health at any time (project-health). 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.