dev_plan

Assemble rich context for implementing GitHub issues.

Overview

dev_plan fetches a GitHub issue and assembles comprehensive context for AI assistants to create implementation plans. Instead of generating heuristic task breakdowns, it provides:

• Full issue content with comments
• Relevant code snippets from semantic search
• Related commits from git history (v0.4+)
• Detected codebase patterns
• Metadata for token budgeting

Philosophy: Provide data, let LLMs reason. AI assistants create better plans when given rich context.

Parameters

Example Output

Compact Format

# Issue #42: Add user preferences API
 
**Author:** alice | **State:** open | **Labels:** enhancement, api
 
## Description
 
We need an API endpoint for user preferences. Should support:
- GET /preferences - retrieve current preferences
- PUT /preferences - update preferences
 
## Comments
 
**bob** (2024-01-15):
Consider using the existing validation middleware from src/middleware/validation.ts
 
## Relevant Code
 
### UserController (class)
**File:** `src/api/controllers/user.ts` | **Relevance:** 85%
**Reason:** Similar pattern
 
```typescript
export class UserController {
  async getUser(req: Request, res: Response) {
    // ...
  }
}

validateBody (function)

File: src/middleware/validation.ts | Relevance: 72% Reason: Relevant type definition

export function validateBody(schema: Schema) {
  // ...
}

Codebase Patterns

• Test naming: *.test.ts
• Test location: tests/

Related Commits ✨ v0.4

[92%] Add user preferences schema

Hash: a1b2c3d | Author: bob | Date: 2024-01-10 Related to preferences feature groundwork.

[85%] Implement validation middleware

Hash: e4f5g6h | Author: alice | Date: 2024-01-05 Similar pattern for request validation.

Context assembled at 2024-01-20T10:30:00Z | ~1250 tokens

### Verbose Format (JSON)

```json
{
  "issue": {
    "number": 42,
    "title": "Add user preferences API",
    "body": "We need an API endpoint...",
    "labels": ["enhancement", "api"],
    "author": "alice",
    "comments": [...]
  },
  "relevantCode": [
    {
      "file": "src/api/controllers/user.ts",
      "name": "UserController",
      "type": "class",
      "snippet": "export class UserController {...}",
      "relevanceScore": 0.85,
      "reason": "Similar pattern"
    }
  ],
  "codebasePatterns": {
    "testPattern": "*.test.ts",
    "testLocation": "__tests__/"
  },
  "metadata": {
    "generatedAt": "2024-01-20T10:30:00Z",
    "tokensUsed": 1250
  }
}

How It Works

1. Fetch issue — Retrieves issue with comments via GitHub CLI
2. Search code — Finds relevant code using semantic search
3. Search history — Finds related commits via semantic search (v0.4+)
4. Detect patterns — Identifies test naming and location patterns
5. Assemble context — Packages everything for LLM consumption

Requirements

⚠️ GitHub CLI required. dev_plan uses gh to fetch issue data.

# Install GitHub CLI
brew install gh  # macOS
# or visit https://cli.github.com
 
# Authenticate
gh auth login

Use Cases

Implementation Planning

Assemble context for issue #42 so I can create an implementation plan

Understanding Requirements

Get the full context for issue #123 including comments

Code Discovery

What existing code is relevant to implementing issue #55?

Tips

• Comments are valuable — They often contain design decisions and constraints
• Relevant code shows patterns — Use it to understand existing conventions
• Codebase patterns help — Know where to put tests and how to name them
• Token budget matters — Reduce if context is too large

Migration from v0.2

In v0.2, dev_plan generated heuristic task breakdowns with estimates. In v0.3+, it returns raw context instead.

Why the change? AI assistants create better plans when given comprehensive context rather than our heuristic guesses.

Old parameters removed:

• detailLevel — No longer applicable
• useExplorer — Now always uses code search (controlled by includeCode)

Related Tools

• dev_history — Search git history directly
• dev_search — Search for more relevant code
• dev_refs — Understand relationships in relevant code
• dev_gh — Search related issues/PRs