Generate Features Roadmap

Analyze a repository in depth using parallel explore agents, then produce a consolidated FEATURES.md with the top 10 improvements in each of 5 categories.

Instructions

0. Check for existing FEATURES.md

Before launching any agents, check if a FEATURES.md already exists in the repo root.

• If it exists: Read it and use its structure, formatting, and any still-valid items as a starting point. The explore agents should focus on finding new or updated improvements that aren't already captured. When writing the final file, preserve valid existing items, update stale ones, and add new discoveries — don't start from scratch.
• If it doesn't exist: Proceed normally from step 1.

1. Launch 10 parallel explore agents for repo understanding

Launch these 10 agents simultaneously using the Agent tool with subagent_type: "Explore" and run_in_background: true. Each should do a thorough exploration of its assigned area:

1. Top-level repo structure — List all top-level files/directories. Read README, CLAUDE.md, and config files (package.json, pyproject.toml, docker-compose, Makefile, etc.).
2. Primary server/app #1 — Read main source files, entry points, config for the first major component. Understand purpose, APIs, tools exposed.
3. Primary server/app #2 — Same for the second major component (if exists; otherwise explore the largest module).
4. Shared/common code — Find shared libraries, utilities, base classes used across components. Note any code duplication.
5. Docker and deployment — Explore Dockerfiles, docker-compose, CI/CD pipelines, GitHub Actions, deployment configs.
6. Database and data storage — Search for database usage, vector stores, caching, data persistence patterns, schemas, migrations.
7. Protocol/framework implementation — How the core framework (MCP, REST, GraphQL, etc.) is set up, initialized, and configured.
8. Tests and test patterns — Find test directories, test files, test configs. Identify testing frameworks and coverage.
9. External API integrations — Find all HTTP clients, API base URLs, auth patterns, rate limiting. List every external service.
10. Additional components — Explore any remaining major directories, plugins, extensions, or modules not covered above.

Adapt agent #2, #3, and #10 to whatever major components actually exist in the repo. The goal is full coverage.

Wait for all 10 agents to complete before proceeding.

2. Launch 5 parallel explore agents for improvement analysis

Using the knowledge from step 1, launch these 5 agents simultaneously with subagent_type: "Explore" and run_in_background: true. Each must read the actual source files to ground recommendations in real code.

If an existing FEATURES.md was found in step 0, include its contents in each agent's prompt so they can identify what's new vs. already captured.

1. User Features — Propose exactly 10 high-impact user-facing features ranked by impact. For each: name, which component, 2-3 sentence description, complexity (Low/Medium/High).
2. Code Hygiene — Propose exactly 10 code quality improvements ranked by impact. For each: name, specific files affected, 2-3 sentence description of problem and fix, complexity.
3. Build Optimization — Propose exactly 10 build/deployment optimizations ranked by impact. For each: name, files affected, 2-3 sentence description, complexity.
4. Documentation — Propose exactly 10 documentation improvements ranked by impact. For each: name, what's missing, 2-3 sentence description, complexity.
5. Code Security — Propose exactly 10 security improvements ranked by impact. For each: name, vulnerability/gap, 2-3 sentence description of risk and mitigation, severity (Critical/High/Medium/Low), complexity.

Wait for all 5 agents to complete before proceeding.

3. Write FEATURES.md

Create or update FEATURES.md in the repo root with this structure:

# <Repo Name> — Improvement Roadmap

<One-line description of what the analysis covers.>

---

## 1. User Features (Top 10)
<Brief intro sentence.>
| # | Feature | Component | Complexity | Description |
|---|---------|-----------|------------|-------------|
| 1 | **Name** | component | Low/Med/High | Description |
...

## 2. Code Hygiene (Top 10)
| # | Improvement | Files | Complexity | Description |
...

## 3. Build & Deployment Optimization (Top 10)
| # | Optimization | Files | Complexity | Description |
...

## 4. Documentation (Top 10)
| # | Improvement | What's Missing | Complexity | Description |
...

## 5. Code Security (Top 10)
| # | Improvement | Severity | Complexity | Description |
...

## Priority Matrix

### Quick Wins (Low complexity, high impact)
- <top 6 items across all categories>

### Strategic Investments (Medium complexity, high impact)
- <top 6 items>

### Long-Term Foundations (High complexity, high impact)
- <top 3 items>

Consolidate and deduplicate across agent outputs. Use your judgment to pick the best items when agents overlap. Keep descriptions concise (1-2 sentences in the table). If updating an existing file, preserve its structure and valid items while refreshing stale entries and adding new ones.

4. Report completion

Tell the user the file is ready and give a brief summary of the top 3 quick wins and top 3 strategic investments identified.