codingthefuturewithai/teamcraft-glgd: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 an MR or 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.
• If a Drive file operation fails with a path error, read the error message to identify a valid accessible host path and retry with it.

Resolve Drive Account

Call mcp__google-drive__list_accounts before any other Drive operation:

• No accounts — Drive is not configured for this user. Tell them and skip Drive operations.
• One account — Use it. Pass account_email explicitly on every Drive tool call this session.
• Multiple accounts — Present the list, ask which account to use for this session. Pass that account_email on every Drive tool call.

If any Drive call returns a permission error, surface it: the active account may not have access to that file or folder. Offer to try another account if one is available.

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 *[IID]-* across all type prefixes (feature/, bug/, chore/).
2. Plan file check: Look for .teamcraft/plans/[IID].md.
3. Draft MR check: If a branch exists, check for an associated Draft MR via mcp__gitlab__list_merge_requests.

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

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

• [Branch: feature/42-webhook-verification]
• [Plan file: .teamcraft/plans/42.md]
• [Draft MR: !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/[IID].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 project ID and Drive URLs. Read CLAUDE.md. Read all .claude/rules/ files. If .teamcraft/project.md does not exist, check git remote context to identify the GitLab project. 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 Google Drive — offer to search by project name or accept a direct 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 GitLab using the IID from $ARGUMENTS. If $ARGUMENTS is empty, ask for the IID before proceeding. Read the full issue — title, description, acceptance criteria, labels, milestone, 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.

Drive artifacts (if URLs exist in the manifest): Do not fetch automatically. After loading local context, check whether tech decisions and conventions URLs exist in .teamcraft/project.md. If they do, note them — they will be offered to the developer in Phase 3.

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 Google Drive, local files, or anywhere accessible." If yes, load them into context before presenting the summary. 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/IID-slug, bug/IID-slug, chore/IID-slug.

Hard constraints regardless of what is found:

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

Phase 3 — Present and Confirm

Present everything to the developer 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 — or "not loaded yet" if Drive URL exists but wasn't fetched
• 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/IID-slug, bug/IID-slug, chore/IID-slug) if nothing found
• Context7 research completed: libraries researched and findings available
• Implementation constraints in effect: no MR/PR creation, no commits to default branch

If Drive URLs exist but weren't fetched, ask once:

"I found [tech decisions / conventions] in Drive. The local context looks sufficient — but do you want me to load the Drive document(s) before we plan?"

Wait for the answer and act on it before continuing.

Phase 4 — Gate

After presenting the context summary, present this question exactly. Do not ask a separate "does this look complete?" question first — this gate IS the confirmation question:

"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 numbered gate again. Never enter plan mode without an explicit "1".

Phase 5 — 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/[IID].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 (project ID, git remote namespace, Drive URLs if known), CLAUDE.md (starting with @.teamcraft/project.md, containing only what Claude Code cannot discover from the environment), and .gitlab-ci.yml (baseline 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 [IID] to execute pre-MR reviews (code health, security, deviation) and mark the merge request ready for review. This tells the developer where the thread picks up after implementation, so they don't lose the workflow.