Name: plan-feature-v1
Author: hendrikraudik

Prompt file imported from hendrikraudik/hr-ai-training (.github/prompts/plan-feature-v1.prompt.md). Copyright stays with the author.

Create Feature Implementation Plan (v1)

First: Get Input

Ask the user: "What feature do you want to plan? Please describe the feature and its purpose."

Store their response as FEATURE_DESCRIPTION.

Objective

Transform FEATURE_DESCRIPTION into a battle-tested implementation plan through systematic codebase exploration, pattern extraction, and strategic research.

Core Principle: Plan only - no code. Create a context-rich document that enables one-pass implementation success for AI agents.

Execution Order: Codebase first, research second. Solutions must fit existing patterns.

Context

Run these commands to understand project structure:

ls -la src/ - Project structure
cat package.json | head -30 - Package info
ls src/features/ - Existing features

Read CLAUDE.md for project conventions.

Process

Phase 1: Feature Understanding

Parse the input and clarify:

Extract core problem being solved
Identify user value and business impact
Determine type: New Capability | Enhancement | Refactor | Bug Fix
Assess complexity: Low | Medium | High
Map affected systems

Create or refine user story:

As a <user type>
I want to <action/goal>
So that <benefit/value>

CHECKPOINT: If requirements are ambiguous, STOP and ask user for clarification before proceeding.

Phase 2: Codebase Intelligence

Explore the codebase to discover:

Similar Implementations
- Find analogous features in codebase
- Extract patterns with file:line references
- Identify naming conventions, error handling, logging patterns
Architecture Patterns
- Directory structure and module organization
- Service/repository/controller boundaries
- Type definitions and interfaces
Integration Points
- Files that need modification
- Registration patterns (routes, providers, exports)
- Database/API patterns if applicable
Testing Patterns
- Test framework and conventions
- Similar test examples to mirror
- Coverage requirements
Dependencies
- Relevant libraries already in use
- How they're integrated (imports, configs)
- Version constraints

CRITICAL: Document patterns with ACTUAL code snippets from codebase, not generic examples.

Phase 3: External Research (AFTER codebase analysis)

Search for:

Official documentation for involved libraries
Latest version info and breaking changes
Common implementation patterns and gotchas
Security considerations

Compile with specific anchors:

- [Docs Title](https://url#specific-section)
  - Key insight: What we learned
  - Why needed: How it applies to our implementation

Phase 4: UX Design (REQUIRED)

Create ASCII diagrams showing before/after UX:

BEFORE:
┌─────────────────────────────────────┐
│  [Current user flow or state]       │
│  Show what exists today             │
└─────────────────────────────────────┘

AFTER:
┌─────────────────────────────────────┐
│  [New user flow or state]           │
│  Show what will exist after         │
│  implementation                     │
└─────────────────────────────────────┘

Document interaction changes:

What screens/endpoints change
New user actions available
Changed data flows

Phase 5: Strategic Design

Think deeply about:

How does this fit existing architecture?
What are critical dependencies and execution order?
What could go wrong? (edge cases, race conditions)
Performance implications?
Security considerations?

Design decisions:

Approach chosen with rationale
Alternatives rejected with reasons
What we're NOT building (explicit scope limits)

Phase 6: Generate Implementation Plan

Save to: .agents/plans/{feature-name}.plan.md

Create the plan file with this structure:

# Feature: {Feature Name}

## Summary
{One paragraph: What we're building and the high-level approach}

## User Story
As a {user type}
I want to {action}
So that {benefit}

## Problem Statement
{What specific problem this solves}

## Solution Statement
{How we're solving it}

## Metadata
- **Type**: New Capability | Enhancement | Refactor | Bug Fix
- **Complexity**: Low | Medium | High
- **Systems Affected**: {list}
- **Dependencies**: {external libs/services}

---

## UX Design

### Before
{ASCII diagram of current state}

### After
{ASCII diagram of new state}

### Interaction Changes
- {Change 1}
- {Change 2}

---

## Mandatory Reading

**CRITICAL: Read these files before implementing:**

| File | Lines | Why |
|------|-------|-----|
| `path/to/file.ts` | 15-45 | Pattern for X to mirror |

**External Documentation:**
- [Doc Title](url#section) - Why needed

---

## Patterns to Mirror

**Naming Convention:**
```typescript
// FROM: src/features/example/service.ts:10-15
{actual code snippet}

Error Handling:

// FROM: src/core/api/errors.ts:50-60
{actual code snippet}

Files to Change

File	Action	Justification
`path/new.ts`	CREATE	{why}
`path/existing.ts`	UPDATE	{why}

NOT Building (Scope Limits)

{Explicit out-of-scope item 1}
{Explicit out-of-scope item 2}

Step-by-Step Tasks

Execute in order. Each task is atomic and independently verifiable.

Task 1: {ACTION} {target}

IMPLEMENT: {specific detail}
MIRROR: path/to/pattern.ts:XX-YY
IMPORTS: {required imports}
GOTCHA: {known issue to avoid}
VALIDATE: {executable command}

Task 2: {ACTION} {target}

...

Validation Commands

Level 1: Static Analysis

bun run lint && npx tsc --noEmit

Level 2: Unit Tests

bun test {specific-pattern}

Level 3: Full Suite

bun test && bun run build

Acceptance Criteria

All specified functionality implemented
Validation commands pass (Level 1-3)
Unit tests added with 80%+ coverage
Code follows project patterns exactly
No regressions in existing tests


---

## Output

**File created**: `.agents/plans/{feature-name}.plan.md`

**Report to user:**
- Summary of feature and approach
- Full path to plan file
- Complexity assessment
- Key risks or considerations
- Confidence score (1-10) for one-pass implementation success
- Next step: "To implement, run: `/execute-plan .agents/plans/{feature-name}.plan.md`"

## Success Criteria

- **Context Complete**: All patterns, gotchas, and integration points documented
- **Implementation Ready**: Tasks executable top-to-bottom without questions
- **Pattern Faithful**: Every new file mirrors existing codebase style
- **Validation Defined**: Every task has executable verification command
- **One-Pass Target**: Confidence score 1-10 for first-attempt success

Install plan-feature-v1 and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# Create Feature Implementation Plan (v1) ## First: Get Input **Ask the user**: "What feature do you want to plan? Please describe the feature and its purpose." Store their response as `FEATURE_DESCRIPTION`. --- ## Objective Transform `FEATURE_DESCRIPTION` into a battle-tested implementation plan through systematic codebase exploration, pattern extraction, and strategic research. **Core Principle**: Plan only - no code. Create a context-rich document that enables one-pass implementation success for AI agents. **Execution Order**: Codebase first, research second. Solutions must fit existing patterns. ## Context Run these commands to understand project structure: - `ls -la src/` - Project structure - `cat package.json | head -30` - Package info - `ls src/features/` - Existing features Read `CLAUDE.md` for project conventions. ## Process ### Phase 1: Feature Understanding **Parse the input and clarify:** - Extract core problem being solved - Identify user value and business impact - Determine type: New Capability | Enhancement | Refactor | Bug Fix - Assess complexity: Low | Medium | High - Map affected systems **Create or refine user story:** ``` As a <user type> I want to <action/goal> So that <benefit/value> ``` **CHECKPOINT**: If requirements are ambiguous, STOP and ask user for clarification before proceeding. --- ### Phase 2: Codebase Intelligence **Explore the codebase to discover:** 1. **Similar Implementations** - Find analogous features in codebase - Extract patterns with file:line references - Identify naming conventions, error handling, logging patterns 2. **Architecture Patterns** - Directory structure and module organization - Service/repository/controller boundaries - Type definitions and interfaces 3. **Integration Points** - Files that need modification - Registration patterns (routes, providers, exports) - Database/API patterns if applicable 4. **Testing Patterns** - Test framework and conventions - Similar test examples to mirror - Coverage requirements 5. **Dependencies** - Relevant libraries already in use - How they're integrated (imports, configs) - Version constraints **CRITICAL**: Document patterns with ACTUAL code snippets from codebase, not generic examples. --- ### Phase 3: External Research (AFTER codebase analysis) **Search for:** - Official documentation for involved libraries - Latest version info and breaking changes - Common implementation patterns and gotchas - Security considerations **Compile with specific anchors:** ```markdown - [Docs Title](https://url#specific-section) - Key insight: What we learned - Why needed: How it applies to our implementation ``` --- ### Phase 4: UX Design (REQUIRED) **Create ASCII diagrams showing before/after UX:** ``` BEFORE: ┌─────────────────────────────────────┐ │ [Current user flow or state] │ │ Show what exists today │ └─────────────────────────────────────┘ AFTER: ┌─────────────────────────────────────┐ │ [New user flow or state] │ │ Show what will exist after │ │ implementation │ └─────────────────────────────────────┘ ``` **Document interaction changes:** - What screens/endpoints change - New user actions available - Changed data flows --- ### Phase 5: Strategic Design **Think deeply about:** - How does this fit existing architecture? - What are critical dependencies and execution order? - What could go wrong? (edge cases, race conditions) - Performance implications? - Security considerations? **Design decisions:** - Approach chosen with rationale - Alternatives rejected with reasons - What we're NOT building (explicit scope limits) --- ### Phase 6: Generate Implementation Plan **Save to**: `.agents/plans/{feature-name}.plan.md` Create the plan file with this structure: ```markdown # Feature: {Feature Name} ## Summary {One paragraph: What we're building and the high-level approach} ## User Story As a {user type} I want to {action} So that {benefit} ## Problem Statement {What specific problem this solves} ## Solution Statement {How we're solving it} ## Metadata - **Type**: New Capability | Enhancement | Refactor | Bug Fix - **Complexity**: Low | Medium | High - **Systems Affected**: {list} - **Dependencies**: {external libs/services} --- ## UX Design ### Before {ASCII diagram of current state} ### After {ASCII diagram of new state} ### Interaction Changes - {Change 1} - {Change 2} --- ## Mandatory Reading **CRITICAL: Read these files before implementing:** | File | Lines | Why | |------|-------|-----| | `path/to/file.ts` | 15-45 | Pattern for X to mirror | **External Documentation:** - [Doc Title](url#section) - Why needed --- ## Patterns to Mirror **Naming Convention:** ```typescript // FROM: src/features/example/service.ts:10-15 {actual code snippet} ``` **Error Handling:** ```typescript // FROM: src/core/api/errors.ts:50-60 {actual code snippet} ``` --- ## Files to Change | File | Action | Justification | |------|--------|---------------| | `path/new.ts` | CREATE | {why} | | `path/existing.ts` | UPDATE | {why} | --- ## NOT Building (Scope Limits) - {Explicit out-of-scope item 1} - {Explicit out-of-scope item 2} --- ## Step-by-Step Tasks Execute in order. Each task is atomic and independently verifiable. ### Task 1: {ACTION} {target} - **IMPLEMENT**: {specific detail} - **MIRROR**: `path/to/pattern.ts:XX-YY` - **IMPORTS**: {required imports} - **GOTCHA**: {known issue to avoid} - **VALIDATE**: `{executable command}` ### Task 2: {ACTION} {target} ... --- ## Validation Commands ### Level 1: Static Analysis ```bash bun run lint && npx tsc --noEmit ``` ### Level 2: Unit Tests ```bash bun test {specific-pattern} ``` ### Level 3: Full Suite ```bash bun test && bun run build ``` --- ## Acceptance Criteria - [ ] All specified functionality implemented - [ ] Validation commands pass (Level 1-3) - [ ] Unit tests added with 80%+ coverage - [ ] Code follows project patterns exactly - [ ] No regressions in existing tests ``` --- ## Output **File created**: `.agents/plans/{feature-name}.plan.md` **Report to user:** - Summary of feature and approach - Full path to plan file - Complexity assessment - Key risks or considerations - Confidence score (1-10) for one-pass implementation success - Next step: "To implement, run: `/execute-plan .agents/plans/{feature-name}.plan.md`" ## Success Criteria - **Context Complete**: All patterns, gotchas, and integration points documented - **Implementation Ready**: Tasks executable top-to-bottom without questions - **Pattern Faithful**: Every new file mirrors existing codebase style - **Validation Defined**: Every task has executable verification command - **One-Pass Target**: Confidence score 1-10 for first-attempt success

{ "prompt": "# Create Feature Implementation Plan (v1)\n\n## First: Get Input\n\n**Ask the user**: \"What feature do you want to plan? Please describe the feature and its purpose.\"\n\nStore their response as `FEATURE_DESCRIPTION`.\n\n---\n\n## Objective\n\nTransform `FEATURE_DESCRIPTION` into a battle-tested implementation plan through systematic codebase exploration, pattern extraction, and strategic research.\n\n**Core Principle**: Plan only - no code. Create a context-rich document that enables one-pass implementation success for AI agents.\n\n**Execution Order**: Codebase first, research second. Solutions must fit existing patterns.\n\n## Context\n\nRun these commands to understand project structure:\n- `ls -la src/` - Project structure\n- `cat package.json | head -30` - Package info\n- `ls src/features/` - Existing features\n\nRead `CLAUDE.md` for project conventions.\n\n## Process\n\n### Phase 1: Feature Understanding\n\n**Parse the input and clarify:**\n\n- Extract core problem being solved\n- Identify user value and business impact\n- Determine type: New Capability | Enhancement | Refactor | Bug Fix\n- Assess complexity: Low | Medium | High\n- Map affected systems\n\n**Create or refine user story:**\n\n```\nAs a <user type>\nI want to <action/goal>\nSo that <benefit/value>\n```\n\n**CHECKPOINT**: If requirements are ambiguous, STOP and ask user for clarification before proceeding.\n\n---\n\n### Phase 2: Codebase Intelligence\n\n**Explore the codebase to discover:**\n\n1. **Similar Implementations**\n - Find analogous features in codebase\n - Extract patterns with file:line references\n - Identify naming conventions, error handling, logging patterns\n\n2. **Architecture Patterns**\n - Directory structure and module organization\n - Service/repository/controller boundaries\n - Type definitions and interfaces\n\n3. **Integration Points**\n - Files that need modification\n - Registration patterns (routes, providers, exports)\n - Database/API patterns if applicable\n\n4. **Testing Patterns**\n - Test framework and conventions\n - Similar test examples to mirror\n - Coverage requirements\n\n5. **Dependencies**\n - Relevant libraries already in use\n - How they're integrated (imports, configs)\n - Version constraints\n\n**CRITICAL**: Document patterns with ACTUAL code snippets from codebase, not generic examples.\n\n---\n\n### Phase 3: External Research (AFTER codebase analysis)\n\n**Search for:**\n\n- Official documentation for involved libraries\n- Latest version info and breaking changes\n- Common implementation patterns and gotchas\n- Security considerations\n\n**Compile with specific anchors:**\n\n```markdown\n- [Docs Title](https://url#specific-section)\n - Key insight: What we learned\n - Why needed: How it applies to our implementation\n```\n\n---\n\n### Phase 4: UX Design (REQUIRED)\n\n**Create ASCII diagrams showing before/after UX:**\n\n```\nBEFORE:\n┌─────────────────────────────────────┐\n│ [Current user flow or state] │\n│ Show what exists today │\n└─────────────────────────────────────┘\n\nAFTER:\n┌─────────────────────────────────────┐\n│ [New user flow or state] │\n│ Show what will exist after │\n│ implementation │\n└─────────────────────────────────────┘\n```\n\n**Document interaction changes:**\n\n- What screens/endpoints change\n- New user actions available\n- Changed data flows\n\n---\n\n### Phase 5: Strategic Design\n\n**Think deeply about:**\n\n- How does this fit existing architecture?\n- What are critical dependencies and execution order?\n- What could go wrong? (edge cases, race conditions)\n- Performance implications?\n- Security considerations?\n\n**Design decisions:**\n\n- Approach chosen with rationale\n- Alternatives rejected with reasons\n- What we're NOT building (explicit scope limits)\n\n---\n\n### Phase 6: Generate Implementation Plan\n\n**Save to**: `.agents/plans/{feature-name}.plan.md`\n\nCreate the plan file with this structure:\n\n```markdown\n# Feature: {Feature Name}\n\n## Summary\n{One paragraph: What we're building and the high-level approach}\n\n## User Story\nAs a {user type}\nI want to {action}\nSo that {benefit}\n\n## Problem Statement\n{What specific problem this solves}\n\n## Solution Statement\n{How we're solving it}\n\n## Metadata\n- **Type**: New Capability | Enhancement | Refactor | Bug Fix\n- **Complexity**: Low | Medium | High\n- **Systems Affected**: {list}\n- **Dependencies**: {external libs/services}\n\n---\n\n## UX Design\n\n### Before\n{ASCII diagram of current state}\n\n### After\n{ASCII diagram of new state}\n\n### Interaction Changes\n- {Change 1}\n- {Change 2}\n\n---\n\n## Mandatory Reading\n\n**CRITICAL: Read these files before implementing:**\n\n| File | Lines | Why |\n|------|-------|-----|\n| `path/to/file.ts` | 15-45 | Pattern for X to mirror |\n\n**External Documentation:**\n- [Doc Title](url#section) - Why needed\n\n---\n\n## Patterns to Mirror\n\n**Naming Convention:**\n```typescript\n// FROM: src/features/example/service.ts:10-15\n{actual code snippet}\n```\n\n**Error Handling:**\n```typescript\n// FROM: src/core/api/errors.ts:50-60\n{actual code snippet}\n```\n\n---\n\n## Files to Change\n\n| File | Action | Justification |\n|------|--------|---------------|\n| `path/new.ts` | CREATE | {why} |\n| `path/existing.ts` | UPDATE | {why} |\n\n---\n\n## NOT Building (Scope Limits)\n\n- {Explicit out-of-scope item 1}\n- {Explicit out-of-scope item 2}\n\n---\n\n## Step-by-Step Tasks\n\nExecute in order. Each task is atomic and independently verifiable.\n\n### Task 1: {ACTION} {target}\n\n- **IMPLEMENT**: {specific detail}\n- **MIRROR**: `path/to/pattern.ts:XX-YY`\n- **IMPORTS**: {required imports}\n- **GOTCHA**: {known issue to avoid}\n- **VALIDATE**: `{executable command}`\n\n### Task 2: {ACTION} {target}\n...\n\n---\n\n## Validation Commands\n\n### Level 1: Static Analysis\n```bash\nbun run lint && npx tsc --noEmit\n```\n\n### Level 2: Unit Tests\n```bash\nbun test {specific-pattern}\n```\n\n### Level 3: Full Suite\n```bash\nbun test && bun run build\n```\n\n---\n\n## Acceptance Criteria\n\n- [ ] All specified functionality implemented\n- [ ] Validation commands pass (Level 1-3)\n- [ ] Unit tests added with 80%+ coverage\n- [ ] Code follows project patterns exactly\n- [ ] No regressions in existing tests\n```\n\n---\n\n## Output\n\n**File created**: `.agents/plans/{feature-name}.plan.md`\n\n**Report to user:**\n- Summary of feature and approach\n- Full path to plan file\n- Complexity assessment\n- Key risks or considerations\n- Confidence score (1-10) for one-pass implementation success\n- Next step: \"To implement, run: `/execute-plan .agents/plans/{feature-name}.plan.md`\"\n\n## Success Criteria\n\n- **Context Complete**: All patterns, gotchas, and integration points documented\n- **Implementation Ready**: Tasks executable top-to-bottom without questions\n- **Pattern Faithful**: Every new file mirrors existing codebase style\n- **Validation Defined**: Every task has executable verification command\n- **One-Pass Target**: Confidence score 1-10 for first-attempt success", "variables": [], "notes": "Create comprehensive feature implementation plan with codebase analysis and research", "metadata": { "source": { "provider": "github-prompts", "repository": "https://github.com/hendrikraudik/hr-ai-training", "path": ".github/prompts/plan-feature-v1.prompt.md", "ref": "ff6f8f871c6d95ec0d5efcd1b42759cc69c0d549", "url": "https://github.com/hendrikraudik/hr-ai-training/blob/ff6f8f871c6d95ec0d5efcd1b42759cc69c0d549/.github/prompts/plan-feature-v1.prompt.md", "key": "hendrikraudik/hr-ai-training/.github/prompts/plan-feature-v1.prompt.md" } } }

plan-feature-v1

About