teamcraft:plan-and-implement-issue

---
name: teamcraft:plan-and-implement-issue
description: The main build skill. Fetch a work item or take a description of work, establish the work branch, research current technology docs, consult the project's captured knowledge, and enter plan mode. Use when the user says 'implement this issue', 'build this feature', 'code this up', 'start implementing feat-notification-prefs', 'plan and implement', 'let's work on this work item', or explicitly asks to implement, build, or code something specific.
argument-hint: "[work item ID (e.g. feat-notification-prefs, bug-timezone-display) or description of work]"
disable-model-invocation: false
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - EnterPlanMode
  - AskUserQuestion
  - mcp__context7__resolve-library-id
  - mcp__context7__query-docs
---

## Why This Skill Exists

Every project has decisions the team spent real time making — how they test, how they branch, what patterns they follow, what architectural boundaries exist, what the product is supposed to do. Those decisions are captured in the project for a reason. A plan that ignores them wastes the developer's time catching mistakes that shouldn't have been made.

Before planning, direct Claude to consult the relevant captured knowledge. Not by reading everything — by reading only what's relevant to the work. That's the whole point of keeping knowledge on-demand instead of always-loaded.

## What to Do

Six steps, in order. Each one must complete before the next begins. Steps 1–2 are read-only and involve zero file modifications. Steps 3+ happen on the work branch only — never on the default branch.

**1. Understand what to build (read-only).** `$ARGUMENTS` is a work item ID, a description of work, or empty. If it matches a file in `.teamcraft/work/`, read that work item. If it's a description, interview briefly — what are we building, why, and what does "done" look like? If empty, ask.

After reading the work item, if it traces back to a documented product requirement, consult the relevant sections of the captured product requirements for acceptance context. Not the whole document — just the relevant sections. This helps you understand the "why" behind the work item.

Do a quick readiness check: are the requirements clear enough to plan? If the acceptance criteria are vague, dependencies are unresolved, or something doesn't add up — surface those gaps now and let the developer decide whether to proceed or clarify first.

**This step modifies nothing. No files change. No commits happen. Branch setup comes next.**

**2. Establish the work branch — before any file modifications.** Do not modify any work item files, INDEX.md, or anything else until you're on the correct branch.

Derive the expected branch name. Follow the team's captured branching convention if one exists. If none is documented, default to `feat/<slug>`, `fix/<slug>`, or `chore/<slug>` based on the work type, with the work item ID in the slug if one exists.

Check whether a branch with that name already exists (local or remote). Three cases:

- **Doesn't exist:** create it from the default branch and check it out. Proceed.
- **Exists with substantive commits on it:** ask the developer, in two sentences: "A `<branch-name>` branch already exists with [N] commits. Do you want to resume work on that branch, or start fresh with a different branch name?" Do NOT offer rebase analysis, divergence strategies, or review of existing commits — that's out of scope for this skill. If they resume: check it out. If they want a different name: ask for one, create that branch instead.
- **Exists with no commits beyond the base / looks stale:** ask whether to reuse or recreate. If recreate, delete the old branch first.

**Never let this skill modify files on the default branch.** After this step, verify you're on the work branch. If for any reason you end up still on the default branch, stop and tell the developer — don't proceed.

**3. Capture or update the work item — on the work branch.** You're now on the correct branch. File modifications are safe.

- **Work item already exists** (it was created earlier via `create-issue`, or exists from a prior session): update its frontmatter to `status: in-progress` and `started: YYYY-MM-DD`. Update the matching row in `.teamcraft/work/INDEX.md`. Commit both with the work item ID in the message.
- **No work item exists yet:** use the `create-issue` skill. It will interview, write the work item file, update INDEX.md, and commit — all on this work branch (because that's where we are now). After it completes, read the newly created work item file to confirm the ID and acceptance criteria. Then update the frontmatter to `status: in-progress` and `started: YYYY-MM-DD`, update INDEX.md accordingly, and commit a second time to record the status transition.

Two separate commits — "work item created" and "work item started" — reads naturally in the branch history and keeps each transition atomic. The work item ID and acceptance criteria must be carried forward through the rest of this skill.

**4. Research current technology docs.** Identify the technologies this work touches and use Context7 to pull current documentation. Plans built against stale APIs produce bugs nobody catches until runtime.

**5. Consult the project's captured knowledge.** Before entering plan mode, consult the four categories of captured project knowledge that commonly apply. For each one, read the INDEX or table of contents first, then drill into only the sections relevant to this work:

- **Team operating conventions** — for anything affecting how you'll do the work (branching pattern, testing approach, commit format, coverage requirements, pre-push expectations, merge strategy). Claude defaults to its training-data priors without explicit guidance — the conventions tell you where the team deviates.
- **System architecture** — for the components this work touches. Where does this code fit in the system? What boundaries does it need to respect? What's the intended direction if the architecture is mid-migration?
- **Technology decisions** — for the areas involved. If touching persistence, consult the database decision. If touching auth, consult the auth decision. Read only the areas that apply.
- **Product requirements** — for acceptance context when the work item derives from a documented requirement. Confirm your understanding of what "done" looks like aligns with the PRD.

**Consultation discipline:** read the INDEX/TOC first. Drill into specific sections only when they're relevant. Do not read whole documents — that defeats the point of keeping knowledge on-demand. If the team has opted out of the opinionated default structure, locate the documents by reading the repo's README or browsing the standard documentation locations.

After consulting, report what you found that's relevant: conventions that apply, architectural boundaries in play, technology decisions that constrain your choices, requirements sections that shape acceptance. Surface this before plan mode so the plan reflects it — plan mode can deprioritize project context in favor of its own planning instructions.

**6. Gate.** Ask: "Ready to plan? (1) Enter plan mode (2) I need to change something first." Only "1" triggers plan mode. If you noticed conflicts between the work item, captured conventions, architecture, decisions, or the current codebase state, surface them here and let the developer decide.

When the developer selects "1", call `EnterPlanMode`. Do not create a PR — a separate skill handles that.

## Constraints

**Commit as you go.** Each logical unit of work should be committed when it's complete — don't accumulate uncommitted changes waiting to be asked. Include the work item ID in every commit message, following any commit-message format the team's captured conventions specify.

**Do not create a PR.** A separate skill handles pushing, PR creation, and review.

**All tests must pass. No exceptions.** After any code change — implementation, refactoring, or fixing a finding — run the full test suite. If ANY test fails, stop. Do not commit. Do not push. Do not mark the work as complete. Do not assume failures are "pre-existing" or "unrelated." Investigate every failure, determine whether your changes caused it, and fix it. If you genuinely cannot fix a failing test, tell the developer exactly which tests fail and why, and let them decide how to proceed. Only the developer can authorize moving forward with a failing test — you never make that call yourself.

The team's captured decisions and conventions are first-class constraints, not suggestions. When the work item conflicts with a broader team standard, the work item generally wins — but never resolve conflicts silently.

## When the Skill Is Complete

Not when code is committed. The skill is complete when the implementation is done, **all tests pass**, changes are committed, and the developer has explicitly confirmed they're satisfied. Ask them directly. Once confirmed, stop — point them to `/validate-issue` as their next step.