plan-inline

Create a TDD implementation plan directly from inline instructions in $ARGUMENTS. Creates Linear issues in Todo state.

Git Pre-flight Check

Before doing anything else, verify git state:

1. Check current branch: git branch --show-current
2. If NOT on main or master:
   • STOP with message: "Not on main branch. Please switch to main before planning: git checkout main"
3. Check for uncommitted changes: git status --porcelain
4. If there are uncommitted changes:
   • STOP with message: "Main branch has uncommitted changes. Please commit or stash them first."
5. Check if branch is up-to-date with remote: git fetch origin && git status -uno
6. If behind remote:
   • STOP with message: "Main branch is behind remote. Please pull latest: git pull origin main"

Only proceed to PLANS.md check if git state is clean.

Purpose

• Convert inline task descriptions into actionable TDD implementation plans
• Create Linear issues in Todo state for each task (bypasses Backlog)
• Explore codebase to understand existing patterns and find relevant files
• Use MCPs to gather additional context (deployments, issue tracking)
• Generate detailed, implementable plans with full file paths and Linear issue links

When to Use

Use plan-inline instead of plan-backlog when:

• The user provides a clear feature request or task description directly
• The task doesn't need to go through Linear Backlog first
• Quick planning without backlog management overhead

Use plan-backlog instead when:

• Working from existing backlog items
• Managing multiple items that should be tracked

Pre-flight Check

Before doing anything, read PLANS.md and check for incomplete work:

• If PLANS.md has content but NO "Status: COMPLETE" at the end → STOP
• Tell the user: "PLANS.md has incomplete work. Please review and clear it before planning new items."
• Do not proceed.

If PLANS.md is empty or has "Status: COMPLETE" → proceed with planning.

Verify Linear MCP: Call mcp__linear__list_teams. If unavailable, STOP and tell the user: "Linear MCP is not connected. Run /mcp to reconnect, then re-run this skill."

Discovering Team Context

Read CLAUDE.md to find the LINEAR INTEGRATION section. Look for:

• Team name (e.g., "Team: 'ProjectName'")
• Issue prefix (e.g., "Prefix: PROJ-xxx")
• State workflow (e.g., "States: Backlog → Todo → In Progress → Review → Done")
• Project-specific URLs (Linear workspace URL, deployment URLs, etc.)

If CLAUDE.md doesn't have a LINEAR INTEGRATION section, call mcp__linear__list_teams to discover the team name dynamically.

Store the discovered team name in a variable for use throughout the skill.

Arguments

$ARGUMENTS should contain the task description with context:

• What to implement or change
• Expected behavior
• Any constraints or requirements
• Related files if known

Example arguments:

• Add a function to calculate nutritional score from scanned food data
• Create a new route /api/scan that processes food barcode images
• Update food detail page to show allergen warnings

Context Gathering

IMPORTANT: Do NOT hardcode MCP names or folder paths. Always read CLAUDE.md to discover:

1. Available MCP servers - Look for the "MCP SERVERS" section to find:

   • Railway MCP for deployment context (get-logs, list-deployments, list-services, list-variables)
   • Linear MCP for issue tracking (list_issues, get_issue, create_issue, etc.)

2. Project structure - Look for "STRUCTURE" section to understand:

   • Source code organization
   • Test file locations
   • Where to add new files

3. Folder structure - Look for "FOLDER STRUCTURE" section to understand:

   • Where components are stored
   • Naming conventions for files and folders

Workflow

0. Git pre-flight check - Ensure on clean main branch (see Git Pre-flight Check section)

1. Read PLANS.md - Pre-flight check

2. Read CLAUDE.md - Understand TDD workflow, agents, project rules, available MCPs, discover team name

3. Parse $ARGUMENTS - Understand what needs to be implemented

4. Explore codebase - Use Glob/Grep/Task to find relevant files and understand patterns

5. Gather MCP context - If the task relates to:

   • Deployment → Check service status, recent logs
   • Existing issues → Check Linear for related issues or context

6. Generate plan - Create TDD tasks with test-first approach

7. Write PLANS.md - Overwrite with new plan

8. Validate plan against CLAUDE.md - Re-read CLAUDE.md and cross-check each task for missing defensive specs: error handling on external calls, timeout values where network or I/O is involved, edge cases (empty input, null values, partial results). Fix any gaps before proceeding.

9. Cross-cutting requirements sweep - Scan the entire plan for the patterns below. If a pattern appears in any task, verify the corresponding specification exists in that task's steps. If missing, add it before finalizing the plan.

   | Pattern Detected in Plan | Required Specification | |--------------------------|----------------------| | Network calls (HTTP clients, external APIs) | Timeout value and timeout error handling behavior | | Error messages shown to users (UI error states, toasts, notifications) | Sanitization — generic user message displayed, raw error logged only | | Async operations triggered by user actions (button clicks, form submits) | Cancellation or debouncing of in-flight work before starting new | | External service calls (third-party APIs, storage, messaging) | Error handling (catch) and behavior on failure | | Write operations to persistent storage (DB, files, queues) | Atomicity or rollback semantics on failure | | Repeated or concurrent user-triggered operations | Guards against duplicate submissions or race conditions |

10. Create Linear issues - Create issues in Todo state for each task

Codebase Exploration Guidelines

When to explore:

• Always explore to find existing patterns before creating new code
• Find related tests to understand testing conventions
• Locate where similar functionality already exists

How to explore:

• Use Glob for finding files by pattern: src/**/*.ts, **/*.test.ts
• Use Grep for finding code: function names, type definitions, error messages
• Use Task with subagent_type=Explore for broader questions about the codebase

What to discover:

• Existing functions that could be reused or extended
• Test file conventions and patterns
• Type definitions to reuse
• Similar implementations to follow as templates

PLANS.md Structure

Read references/plans-template.md for the complete template.

Source field: Inline request: [Summary of $ARGUMENTS]

Include: Context Gathered (Codebase Analysis + MCP Context), Tasks, Post-Implementation Checklist, Plan Summary. Omit: Investigation subsection, Triage Results subsection.

Linear Issue Creation

After writing PLANS.md, create a Linear issue for each task:

1. Use mcp__linear__create_issue with:

   • team: [Discovered team name from CLAUDE.md or mcp__linear__list_teams]
   • title: Task name
   • description: Task details from PLANS.md
   • state: "Todo"
   • labels: Infer from task type (Feature, Improvement, Bug)

2. Update PLANS.md to add **Linear Issue:** [PROJ-N](url) to each task

Task Writing Guidelines

Each task must be:

• Self-contained - Full file paths, clear descriptions
• TDD-compliant - Test before implementation
• Specific - What to test, what to implement
• Ordered - Dependencies resolved by task order
• Context-aware - Reference patterns and files discovered during exploration

Good task example:

### Task 1: Add calculateNutritionalScore function
1. Write test in src/utils/nutrition.test.ts for calculateNutritionalScore
   - Test valid food data returns correct score
   - Test missing nutrients returns partial score
   - Test empty input returns zero score
   - Follow existing utility function patterns
2. Run verifier (expect fail)
3. Implement calculateNutritionalScore in src/utils/nutrition.ts
   - Use Nutri-Score algorithm
   - Follow existing function signature patterns
4. Run verifier (expect pass)

Bad task example:

### Task 1: Add nutrition scoring
1. Add function
2. Test it

MCP Usage Guidelines

Discover available MCPs from CLAUDE.md's "MCP SERVERS" section. Common patterns:

Deployment MCPs (Railway) - Use when task involves:

• Deployment configuration
• Environment variables
• Service logs for debugging context

Issue Tracking MCPs (Linear) - Use when task involves:

• Checking existing issues for context
• Understanding related work
• Finding duplicate or related feature requests

If CLAUDE.md doesn't list MCPs, skip MCP context gathering.

Error Handling

| Situation | Action | |-----------|--------| | PLANS.md has incomplete work | Stop and tell user to review/clear PLANS.md first | | $ARGUMENTS is empty or unclear | Ask user to provide a clearer task description | | CLAUDE.md doesn't exist | Continue without project-specific rules, use general TDD practices | | Codebase exploration times out | Continue with partial context, note limitation in plan | | MCP not available | Skip MCP context gathering, note in plan what was skipped | | Task too vague to plan | Ask user for specific requirements before proceeding |

Rules

• Refuse to proceed if PLANS.md has incomplete work
• Explore codebase before planning - Find patterns to follow
• Use MCPs when relevant - Gather context from external systems (discover from CLAUDE.md)
• Every task must follow TDD (test first, then implement)
• No manual verification steps - use agents only
• Tasks must be implementable without additional context
• Always include post-implementation checklist
• Create Linear issues in Todo state (bypasses Backlog)
• Include Linear issue links in PLANS.md tasks
• Flag migration-relevant tasks — If a task changes DB schema, renames columns, changes identity models, renames env vars, or changes session/token formats, add a note in the task: "Migration note: [what production data is affected and how to migrate]". The plan MUST include a migration strategy (e.g., startup detection of old format + automatic migration). The implementer will log this in MIGRATIONS.md.
• Plans describe WHAT and WHY, not HOW at the code level. Include: file paths, function names, behavioral specs, test assertions, patterns to follow (reference existing files by path), state transitions. Do NOT include: implementation code blocks, ready-to-paste TypeScript/TSX, full function bodies. The implementer (plan-implement workers) writes all code — your job is architecture and specification. Exception: short one-liners for surgical changes (e.g., "add if (!session.x) check after the existing !session.y check") are fine.

CRITICAL: Scope Boundaries

This skill creates plans. It does NOT implement them.

1. NEVER ask to "exit plan mode" - This skill doesn't use Claude Code's plan mode feature
2. NEVER implement code - Your job ends when PLANS.md is written
3. NEVER ask ambiguous questions like "should I proceed?" or "ready to continue?"
4. NEVER start implementing after writing the plan, even if user says "yes" to something

Termination

Follow the termination procedure in references/plans-template.md: output the Plan Summary, then create branch, commit (no Co-Authored-By tags), and push.

Do not ask follow-up questions. Do not offer to implement. Output the summary and stop.