codingthefuturewithai/teamcraft-jcg:plan-and-implement-issue

Goal

Load everything Claude Code needs to plan this issue well, confirm it with the developer, then enter plan mode with all of it live in context. The developer drives when plan mode starts — never before they explicitly say so.

Hard Constraints

• Do NOT enter plan mode until the developer explicitly chooses it. The only trigger for EnterPlanMode is the developer selecting the numbered option below. Not a yes answer to a general question. Not an ambiguous response. A specific numbered choice.
• Do NOT create a PR during or after plan mode implementation. Post-implementation TeamCraft skills handle this — complete-issue. This constraint must be carried into plan mode as an explicit instruction to Claude.
• Do NOT commit to the default branch. Implementation always happens on a feature branch. This constraint must be carried into plan mode.

Phase 0 — Check for Existing Work

Before loading any context, check whether work already exists for this issue:

1. Branch check: Look for branches matching *[ISSUE-KEY]* across all type prefixes (feature/, bug/, chore/).
2. Plan file check: Look for .teamcraft/plans/[ISSUE-KEY].md.
3. Draft PR check: If a branch exists, check for an associated Draft PR via gh pr list --head [branch-name].

If existing work is found, present what was found and ask:

"It looks like there's existing work for this issue:"

• [Branch: feature/PROJ-42-webhook-verification]
• [Plan file: .teamcraft/plans/PROJ-42.md]
• [Draft PR: #12 — Draft: Add webhook verification]

"What would you like to do?"

1. Resume — pick up where this left off
2. Start fresh — discard the existing plan and re-plan from scratch
3. Let me review first — show me the existing plan before I decide

If the developer chooses 1 (Resume): Read the existing plan file, checkout the existing branch, and enter plan mode with the plan context loaded. Carry the instruction: "An implementation plan already exists at .teamcraft/plans/[ISSUE-KEY].md. Resume implementation from where it left off — do not re-plan unless the developer asks."

If the developer chooses 2 (Start fresh): Continue to Phase 1 as normal. The new plan will overwrite the existing plan file.

If the developer chooses 3 (Review): Show the plan file contents, then re-present the choice between Resume and Start fresh.

If no existing work is found, proceed directly to Phase 1.

Phase 1 — Load Context

Work in parallel where possible. Load everything before presenting anything.

Project manifest and conventions (local first): Read .teamcraft/project.md for the Jira project key, Jira project ID, GitHub repo, and Confluence page IDs. Read CLAUDE.md. Read all .claude/rules/ files. If .teamcraft/project.md does not exist, check git remote context to identify the GitHub repo, and ask the developer for the Jira project key. If neither .teamcraft/project.md nor CLAUDE.md exists, stop before loading anything else and tell the developer: no local project context was found. Ask whether they have tech decisions or conventions documents in Confluence — offer to search by project name or accept a direct page ID or URL. Load whatever they provide before continuing. This is not optional — planning without knowing the team's tech decisions and conventions produces the wrong implementation.

The issue: Fetch the issue from Jira using mcp__sooperset-mcp-atlassian__jira_get_issue with the issue key from $ARGUMENTS. If $ARGUMENTS is empty, ask for the issue key before proceeding. Read the full issue — title, description, acceptance criteria, status, labels, sprint, comments.

Tech stack: Detect from the codebase — package.json, go.mod, Cargo.toml, pyproject.toml, requirements.txt, pom.xml, build.gradle. Read whichever are present.

Context7 research — mandatory: Identify the libraries and frameworks this issue will touch based on the tech stack and issue requirements. Use mcp__context7__resolve-library-id and mcp__context7__query-docs to pull current API documentation for each one. This is not optional and is not left to plan mode to decide. Do it now, as part of context loading, so the results are live when the developer reviews the context summary.

Confluence artifacts (if page IDs exist in the manifest): If tech decisions or conventions page IDs exist in .teamcraft/project.md, load them now — do not defer to a later phase. Use mcp__sooperset-mcp-atlassian__confluence_get_page directly with the page ID. These documents contain decisions and conventions that directly affect how the implementation should be planned. Loading them now means plan mode starts with complete context.

If .teamcraft/project.md does not contain page IDs but the developer mentioned Confluence docs, or the issue references them, use mcp__sooperset-mcp-atlassian__confluence_search to locate the pages — search results include the page ID, which you then pass to mcp__sooperset-mcp-atlassian__confluence_get_page to retrieve the full content.

UI design artifacts (optional): Ask the developer once: "Do you have any visual references for this work — mockups, wireframes, style guides, or screenshots? These can be in Confluence, local files, or anywhere accessible." If yes, load them into context before moving on. If no, move on — this is not a blocker.

Phase 2 — Fill Gaps with Defaults

For each critical area, check what was found locally. Where nothing was found, apply the default and flag it as a default — not silently.

Testing approach — TDD is the rule: The approach is TDD: write the failing test first, implement until it passes, refactor. Red-green-refactor. This applies unless .claude/rules/, the conventions doc, or the developer explicitly states otherwise for this issue. If something in the loaded context contradicts TDD, surface it to the developer. Do not silently deviate.

Code coverage — default on: Set up code coverage tooling appropriate to the detected tech stack during implementation. Choose the standard coverage tool for the stack (e.g., Jest's built-in coverage for Node/TypeScript, pytest-cov for Python, go test -cover for Go, JaCoCo for Java/Gradle, tarpaulin for Rust). The recommended starting threshold is 80% line coverage — this is a recommendation, not a gate. If .claude/rules/, the conventions doc, or the tech decisions doc specifies a different threshold or a different coverage tool, use that instead. If the developer says no coverage, respect that.

Coverage setup means: install/configure the coverage tool, add a coverage script or command to the project's test configuration, and run coverage as part of the test suite. The plan should include this as part of the testing strategy — not as an afterthought.

Branch naming: Check .claude/rules/ and the conventions doc. If no convention is found, the default is: feature/ISSUE-KEY-slug, bug/ISSUE-KEY-slug, chore/ISSUE-KEY-slug.

Hard constraints regardless of what is found:

• Do NOT create a PR — post-implementation TeamCraft skills handle this
• Never commit to the default branch

Phase 3 — Present and Confirm

All context gathering is complete. Do not ask any more questions about loading documents — that was Phase 1's job. Present what was loaded as a structured summary:

• Issue: title, acceptance criteria, any ambiguities
• Tech stack detected: what was found and where
• Conventions loaded: source (CLAUDE.md, rules file, conventions doc) — or DEFAULT if nothing found
• Tech decisions loaded: source (Confluence page, local file) — or "none found" if no tech decisions document exists anywhere
• Testing approach: TDD (red-green-refactor) — note if anything in loaded context overrides this
• Code coverage: tool and threshold — DEFAULT (80% line coverage with stack-appropriate tooling) or source if overridden
• Branch naming: source, or DEFAULT (feature/ISSUE-KEY-slug, bug/ISSUE-KEY-slug, chore/ISSUE-KEY-slug) if nothing found
• Context7 research completed: libraries researched and findings available
• Implementation constraints in effect: no PR creation, no commits to default branch

Then present the gate. This is the only question in Phase 3 — no other questions before or after it:

"Does this context look right? What would you like to do?"

1. Enter plan mode — I'm ready to plan implementation
2. I need to add or change something first
3. Not yet — let's discuss the issue more

"1" is the only trigger for EnterPlanMode. Every other response — "yes", "go ahead", "looks good", "let's do it", any affirmative that is not the number 1 — must be treated as conversation. Answer it, then present this gate again. Never enter plan mode without an explicit "1".

If the developer selects "2", handle whatever they need (load additional context, change a default, answer a question), then re-present the full summary and gate.

Phase 4 — Enter Plan Mode

Call EnterPlanMode. The context loaded in Phases 1–3 is live in the conversation and carries into plan mode.

Plan persistence — carry this instruction into plan mode: "Let Claude Code's plan mode work naturally — explore, design, and present the plan through the native plan mode UI. Do not write a separate plan file before the plan is approved. After the developer approves the plan and implementation begins, persist a copy of the approved plan to .teamcraft/plans/[ISSUE-KEY].md (create the .teamcraft/plans/ directory if it doesn't exist) as the first implementation step. This saved copy is consumed by the deviation reviewer when the issue is completed — without it, the deviation review cannot compare the plan against the implementation."

Greenfield scaffolding sequence (apply when repo is empty and no project manifest exists): If the implementation requires a scaffolding tool (composer, Laravel installer, framework init, etc.), the plan must follow this exact sequence:

1. Run the scaffolding tool first — the framework init command requires an empty directory
2. Immediately after scaffolding succeeds, generate the project files inline as part of this issue: .teamcraft/project.md (GitHub repo owner/repo, Jira project key, Jira project ID, Jira site URL, Confluence page IDs if known), CLAUDE.md (starting with @.teamcraft/project.md, containing only what Claude Code cannot discover from the environment), and .github/workflows/ci.yml (baseline GitHub Actions pipeline for the detected stack)
3. Compliance review pass — read the scaffolded code against the conventions and tech decisions just captured; flag any deviations before committing

This sequence means init-project is not needed separately for greenfield projects that go through this plan. The plan IS the project initialization.

The plan must include a "What to do next" section at the end — after implementation is complete, the developer should run complete-issue [ISSUE-KEY] to execute pre-PR reviews (code health, security, deviation) and mark the pull request ready for review. This tells the developer where the thread picks up after implementation, so they don't lose the workflow.