# Create Plan

> Research the codebase and author a phased implementation plan under flow/plans/ from an issue / work item or task. Explicit workflow command; run only when invoked via /create-plan or explicitly asked, never autonomously.

- **Type:** Skill
- **Install:** `agentstack add skill-corticalstack-flow-create-plan`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [corticalstack](https://agentstack.voostack.com/s/corticalstack)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [corticalstack](https://github.com/corticalstack)
- **Source:** https://github.com/corticalstack/flow/tree/main/.claude/skills/create-plan
- **Website:** https://github.com/corticalstack/flow

## Install

```sh
agentstack add skill-corticalstack-flow-create-plan
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Implementation Plan

You are tasked with creating detailed implementation plans through an interactive, iterative process. You should be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications.

## CRITICAL: No Implementation Code

**DO NOT write implementation code in the plan.** This command produces a planning document, not code.

- **NO** code snippets for files to be created
- **NO** function implementations
- **NO** class definitions
- **NO** configuration file contents

Instead, describe **what** each file/component should do, not **how** it should be coded. The actual code is written during `/implement-plan`.

**Allowed in plans:**
- Shell commands for verification (e.g., `curl`, `uv run`, `pytest`)
- File paths and names
- Function/class names and their responsibilities
- API contracts (endpoint paths, request/response shapes)
- Architecture descriptions

## CRITICAL: Test-Driven Development

**TDD is the only way to write AI-generated code.** Every phase must follow this pattern:

1. **Write failing tests first** - Define expected behavior before implementation
2. **Run tests to confirm they fail** - Verify tests are actually testing something
3. **Implement until tests pass** - Write the minimum code to pass tests
4. **Verify no overfitting** - Ensure implementation isn't gaming the tests

**Phase structure must be:**
```
Phase N: [Name]
  Step 1: Write tests (describe what tests to create)
  Step 2: Run tests, confirm they fail
  Step 3: Implement (describe what to implement)
  Step 4: Run tests, confirm they pass
```

Tests provide Claude with a clear, verifiable target. Without tests, there's no way to know if the implementation is correct.

## Special Considerations for Rename Operations

When planning rename operations (directories, files, variables, modules, etc.), be **extremely thorough** in identifying all reference types:

### Research Phase Requirements

For rename operations, the research phase MUST search for multiple pattern variations:

```bash
# Path references (with slash)
grep -rn "oldname/" .

# Standalone word references (word boundaries)
grep -rn "\boldname\b" .

# Hyphenated compounds
grep -rn "oldname-" .

# Descriptive text (with trailing space)
grep -rn "oldname " .

# Case-insensitive search for variations
grep -rin "oldname" . | head -100
```

### Plan Specification Requirements

Rename operation plans MUST explicitly enumerate ALL reference types found:

**Required in "Current State Analysis":**
- ✅ **Path references**: `oldname/subdir/file.txt`
- ✅ **Descriptive text**: "oldname directory", "oldname documents", "oldname agents"
- ✅ **Compound names**: `oldname-component`, `oldname_function`
- ✅ **Configuration**: JSON/YAML/TOML key names or values
- ✅ **Documentation examples**: Commit messages, tutorials, READMEs
- ✅ **Comments**: Code comments mentioning the old name
- ✅ **Import statements**: `from oldname import`, `require('oldname')`

**Required in "Implementation Approach":**

State the EXACT patterns to be used for replacement:
```
Phase 1: Physical Renames
  - Use `git mv` for files/directories to preserve history

Phase 2: Content Updates
  - Replace "oldname/" → "newname/" (path references)
  - Replace "oldname " → "newname " (descriptive text with space)
  - Replace "oldname-" → "newname-" (hyphenated compounds)
  - Replace "\boldname\b" → "newname" (word boundaries)
  - Manual review of case variations (OldName, OLDNAME, etc.)
```

**Required in "Success Criteria":**

Include comprehensive verification commands that check for ALL patterns:
```bash
# Automated Verification:
- [ ] No path references: `grep -r "oldname/" . --exclude-dir=.git | grep -v "plan\|research" | wc -l` returns 0
- [ ] No descriptive text: `grep -r "oldname " . --exclude-dir=.git | grep -v "plan\|research" | wc -l` returns 0
- [ ] No hyphenated: `grep -r "oldname-" . --exclude-dir=.git | grep -v "plan\|research" | wc -l` returns 0
- [ ] No word boundary matches: `grep -r "\boldname\b" . --exclude-dir=.git | grep -v "plan\|research" | wc -l` returns 0
- [ ] New name exists: `grep -r "newname" . --exclude-dir=.git | wc -l` returns > 0
```

### Common Pitfalls to Avoid

❌ **Don't use narrow patterns**: `s/oldname\//newname\//g` only catches paths with slashes
✅ **Use comprehensive patterns**: Document all pattern types and verify each one

❌ **Don't say**: "Replace all references to oldname"
✅ **Do say**: "Replace ALL instances of oldname including: paths (oldname/), descriptive text (oldname directory), compound names (oldname-component), etc."

### Reference Materials

See detailed rename operation checklist: `/home/jp/.claude/projects/-home-jp-developments-jp-personal-flow/memory/rename-operations.md`

## Initial Response

When this command is invoked:

1. **Check if parameters were provided**:
   - If a file path or ticket reference was provided as a parameter, skip the default message
   - Immediately read any provided files FULLY
   - Begin the research process

2. **If no parameters provided**, respond with:
```
I'll help you create a detailed implementation plan. Let me start by understanding what we're building.

Please provide:
1. An issue / work-item URL or id (e.g., #123 on GitHub, or an Azure DevOps work item URL)
2. Or a task description with relevant context and constraints
3. Links to related research or previous implementations

I'll analyze this information and work with you to create a comprehensive plan.

Tip: You can invoke this with an issue / work-item reference: `/create-plan #123`, a full URL like `/create-plan https://github.com/owner/repo/issues/123` (GitHub), or `/create-plan https://dev.azure.com/org/project/_workitems/edit/123` (Azure DevOps)
For deeper analysis, try: `/create-plan think deeply about #123`
```

Then wait for the user's input.

## Process Steps

### Step 1: Context Gathering & Initial Analysis

1. **Fetch the work item if provided**:
   - If a tracker URL or work-item id is provided:
     - Fetch it: `tracker view  --json title,body,state,comments`
     - Transition state: `tracker set-state  planning-in-progress research-complete`
   - Read the content fully before proceeding
   - Note any linked work items, PRs, or references mentioned

2. **Read all mentioned files immediately and FULLY**:
   - Research documents (e.g., `flow/research/...`)
   - Related implementation plans
   - Any JSON/data files mentioned
   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
   - **CRITICAL**: DO NOT spawn sub-tasks before reading these files yourself in the main context
   - **NEVER** read files partially - if a file is mentioned, read it completely

3. **Spawn initial research tasks to gather context**:
   Before asking the user any questions, use specialized agents to research in parallel:

   - Use the **codebase-locator** agent to find all files related to the task
   - Use the **codebase-analyzer** agent to understand how the current implementation works
   - If relevant, use the **flow-locator** agent to find any existing flow documents about this feature

   These agents will:
   - Find relevant source files, configs, and tests
   - Trace data flow and key functions
   - Return detailed explanations with file:line references

4. **Read all files identified by research tasks**:
   - After research tasks complete, read ALL files they identified as relevant
   - Read them FULLY into the main context
   - This ensures you have complete understanding before proceeding

5. **Analyze and verify understanding**:
   - Cross-reference the issue requirements with actual code
   - Identify any discrepancies or misunderstandings
   - Note assumptions that need verification
   - Determine true scope based on codebase reality

6. **Present informed understanding and focused questions**:
   ```
   Based on the issue and my research of the codebase, I understand we need to [accurate summary].

   I've found that:
   - [Current implementation detail with file:line reference]
   - [Relevant pattern or constraint discovered]
   - [Potential complexity or edge case identified]

   Questions that my research couldn't answer:
   - [Specific technical question that requires human judgment]
   - [Business logic clarification]
   - [Design preference that affects implementation]
   ```

   Only ask questions that you genuinely cannot answer through code investigation.

### Step 2: Research & Discovery

After getting initial clarifications:

1. **If the user corrects any misunderstanding**:
   - DO NOT just accept the correction
   - Spawn new research tasks to verify the correct information
   - Read the specific files/directories they mention
   - Only proceed once you've verified the facts yourself

2. **Create a research todo list** using TodoWrite to track exploration tasks

3. **Spawn parallel sub-tasks for comprehensive research**:
   - Create multiple Task agents to research different aspects concurrently
   - Use the right agent for each type of research:

   **For deeper investigation:**
   - **codebase-locator** - To find more specific files (e.g., "find all files that handle [specific component]")
   - **codebase-analyzer** - To understand implementation details (e.g., "analyze how [system] works")
   - **codebase-pattern-finder** - To find similar features we can model after

   **For historical context:**
   - **flow-locator** - To find any research, plans, or decisions about this area
   - **flow-analyzer** - To extract key insights from the most relevant documents

   Each agent knows how to:
   - Find the right files and code patterns
   - Identify conventions and patterns to follow
   - Look for integration points and dependencies
   - Return specific file:line references
   - Find tests and examples

3. **Wait for ALL sub-tasks to complete** before proceeding

4. **Present findings and design options**:
   ```
   Based on my research, here's what I found:

   **Current State:**
   - [Key discovery about existing code]
   - [Pattern or convention to follow]

   **Design Options:**
   1. [Option A] - [pros/cons]
   2. [Option B] - [pros/cons]

   **Open Questions:**
   - [Technical uncertainty]
   - [Design decision needed]

   Which approach aligns best with your vision?
   ```

### Step 3: Plan Structure Development

Once aligned on approach:

1. **Create initial plan outline**:
   ```
   Here's my proposed plan structure:

   ## Overview
   [1-2 sentence summary]

   ## Implementation Phases:
   1. [Phase name] - [what it accomplishes]
   2. [Phase name] - [what it accomplishes]
   3. [Phase name] - [what it accomplishes]

   Does this phasing make sense? Should I adjust the order or granularity?
   ```

2. **Get feedback on structure** before writing details

### Step 4: Detailed Plan Writing

After structure approval:

1. **Write the plan** to `flow/plans/YYYY-MM-DD-gh-[issue]-[description].md`
   - Format: `YYYY-MM-DD-gh-[issue]-[description].md` where:
     - YYYY-MM-DD is today's date
     - gh-[issue] is the tracker work-item id (omit if no work item; the literal "gh-" prefix is a stable filename convention across the repo regardless of tracker)
     - description is a brief kebab-case description
   - Examples:
     - With issue: `flow/plans/2026-01-12-gh-1-research-requirements-command.md`
     - Without issue: `flow/plans/2026-01-12-improve-error-handling.md`
2. **Use this template structure**:

````markdown
# [Feature/Task Name] Implementation Plan

## Overview

[Brief description of what we're implementing and why]

## Current State Analysis

[What exists now, what's missing, key constraints discovered]

## Desired End State

[A Specification of the desired end state after this plan is complete, and how to verify it]

### Key Discoveries:
- [Important finding as a navigable link, e.g. [main.tf:42](https://github.com/{owner}/{repo}/blob/{commit}/path/to/main.tf#L42)]
- [Pattern to follow]
- [Constraint to work within]

## What We're NOT Doing

[Explicitly list out-of-scope items to prevent scope creep]

## Implementation Approach

[High-level strategy and reasoning]

## Phase 1: [Descriptive Name]

### Overview
[What this phase accomplishes]

### Step 1: Write Tests

**Test file**: `tests/test_[component].py` (or appropriate path)
**Tests to create**:
- Test case 1: [What behavior to test]
- Test case 2: [What edge case to test]
- Test case 3: [What error condition to test]

**Run tests**: `uv run pytest tests/test_[component].py -v`
**Expected result**: Tests should FAIL (no implementation yet)

### Step 2: Implement

#### [Component/File Group]
**File**: `path/to/file.ext`
**Purpose**: [What this file does]
**Key responsibilities**:
- [Responsibility 1]
- [Responsibility 2]

> **Remember**: Describe what the file should do, not the actual code. Implementation happens in `/implement-plan`.

### Step 3: Verify

**Run tests**: `uv run pytest tests/test_[component].py -v`
**Expected result**: All tests PASS

### Success Criteria:

#### Automated Verification:
- [ ] Tests written and initially fail
- [ ] Implementation complete
- [ ] All tests pass: `uv run pytest tests/ -v`
- [ ] Type checking passes (if applicable)
- [ ] Linting passes: `uv run ruff format --check .`

#### Manual Verification:
- [ ] Feature works as expected when tested manually
- [ ] Edge cases handled correctly
- [ ] No regressions in related features

**Implementation Note**: After completing this phase and all verification passes, pause for manual confirmation before proceeding to the next phase.

---

## Phase 2: [Descriptive Name]

[Similar structure with both automated and manual success criteria...]

---

## Testing Strategy

> **Note**: Each phase includes its own TDD cycle. This section provides an overview of the overall testing approach.

### Test Structure:
- Test directory: `tests/`
- Test runner: `uv run pytest`
- Test pattern: One test file per module

### Test Categories:
- **Unit tests**: Test individual functions/classes in isolation
- **Integration tests**: Test component interactions
- **E2E tests**: Test complete user flows (if applicable)

### Key Test Cases:
- [Critical behavior 1]
- [Critical behavior 2]
- [Edge case 1]
- [Error condition 1]

## Performance Considerations

[Any performance implications or optimizations needed]

## Migration Notes

[If applicable, how to handle existing data/systems]

## References

- Tracker work item: https://github.com/[owner]/[repo]/issues/[number] (GitHub example - substitute the URL shape for your tracker)
- Related research: [flow/research/[relevant].md](flow/research/[relevant].md)
- Similar implementation: [path/to/file:line](https://github.com/{owner}/{repo}/blob/{commit}/path/to/file#L{line})
````

3. **Render every code reference as a navigable markdown link.** Do not write bare `file:line` text. Gather the repo + commit once (`git rev-parse HEAD`, `git branch --show-current`, `tracker repo-info`) and form `[path:line](https://github.com/{owner}/{repo}/blob/{commit}/{path}#L{line})` (ranges as `#L{start}-L{end}`) for every reference across Current State Analysis, Key Discoveries, the implementation phases, and References. If the commit is not pushed, fall back to a repo-relative link `[path:line](path)` so every reference stays navigable. For non-GitHub trackers, substitute the host's blob-URL shape.

### Step 5: Review

1. **Present the draft plan location**:
   ```
   I've created the initial implementation plan at:
   `flow/plans/YYYY-MM-DD-gh-X-description.md`

   Please review it and let me know:
   - Are the phases properly scoped?
   - Are the success criteria specific enough?
   - Any technical details that need adjustment?
   - Missing edge cases or considerations?
   ```

2. **Iterate based on feedback** - be ready to:
   - Add missing phases
   - Adjust technical approach
   - Clarify success criteria (both automated and manual)
   - Add/remove scope items

3. **Continue refining** until the

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [corticalstack](https://github.com/corticalstack)
- **Source:** [corticalstack/flow](https://github.com/corticalstack/flow)
- **License:** MIT
- **Homepage:** https://github.com/corticalstack/flow

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-corticalstack-flow-create-plan
- Seller: https://agentstack.voostack.com/s/corticalstack
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.