AI Plans
Document AI-assisted development with version-controlled markdown files
What is AI Plans? Complete Overview
AI Plans is a documentation tool designed specifically for tracking AI-assisted development tasks. It creates structured markdown documents that capture the complete lifecycle of AI interactions during development, including original requests, implementation plans, task tracking, and issue resolutions. These documents live in a repository's /plans/ directory, creating a searchable history of AI decision-making processes. The tool is primarily targeted at developers and teams using AI assistants in their workflow who need to maintain context and learn from past AI interactions. AI Plans solve the problem of losing valuable AI reasoning and decision-making context that typically gets lost in commit messages and PR descriptions.
AI Plans Interface & Screenshots
AI Plans Official screenshot of the tool interface
What Can AI Plans Do? Key Features
Structured Documentation
AI Plans use a standardized markdown format with required sections including Summary, Original Request, AI's Plan, AI's TODOs, and Major Issues. This structure ensures consistent documentation of the AI's decision-making process throughout the implementation lifecycle.
Version Control Integration
Plans are stored as markdown files in your repository's /plans/ directory, allowing them to be version-controlled alongside your code. This creates a linked history where each commit's code changes can be correlated with the AI's planning process.
Real-time Context for AI
Because plans are stored as files in your repository, they remain immediately accessible to AI tools during implementation. This enables AI assistants to understand past decisions and patterns without needing to search through git history.
Progress Tracking
The TODOs section with completion status provides granular tracking of implementation progress. Status indicators (✅ for completed, ⏳ for in-progress) give a clear picture of what work has been done and what remains.
Problem-Solution Archive
The Major Issues section documents challenges encountered during implementation and their resolutions. This creates a knowledge base of solutions that can be referenced when similar problems arise in the future.
Best AI Plans Use Cases & Applications
New Feature Implementation
When adding a new feature like user authentication, AI Plans document the initial request, the AI's proposed architecture (e.g., JWT tokens, protected routes), implementation steps, and track progress through completion. This creates a full record of the AI's reasoning and approach.
Complex Bug Resolution
For complex bugs requiring investigation, AI Plans record the problem statement, the AI's diagnostic approach, attempted solutions, and final resolution. This documentation helps with similar future issues and prevents re-investigation of dead ends.
Architectural Refactoring
During architectural changes, AI Plans capture the reasoning behind refactoring decisions, the step-by-step migration plan, and any compatibility issues encountered. This preserves context that would otherwise be lost in implementation commits.
Team Onboarding
New team members can review AI Plans to understand how the team has used AI in past projects, learning from documented approaches, solutions, and patterns without needing to interrogate git history.
How to Use AI Plans: Step-by-Step Guide
Create a plans directory in your repository by running 'mkdir plans' in your terminal. This will be the home for all your AI Plan documents.
Configure your AI assistant to create plan documents automatically. Provide instructions like: 'When working on features or fixes, create an AI Plan in /plans/ documenting the request, your approach, TODOs, and any issues encountered.'
As you work on features or complex fixes, have your AI generate the plan document following the standard format. Name files using the convention /plans/YYYY-MM-DD-description.md for chronological organization.
Update the plan document throughout implementation, particularly the TODOs section to reflect completed tasks and the Major Issues section to document any problems encountered and their solutions.
Commit plan documents alongside related code changes to maintain a linked history. Use the plans during code reviews and retrospectives to improve your team's AI usage patterns.
AI Plans Pros and Cons: Honest Review
Pros
Considerations
Is AI Plans Worth It? FAQ & Reviews
While ADRs document high-level architectural decisions, AI Plans focus on the workflow of AI-assisted development - tracking tasks, TODOs, and implementation steps. ADRs are occasional while AI Plans are created multiple times per day for substantive development tasks.
Create AI Plans for substantive feature additions, complex bug fixes, architectural changes, new dependencies, or multi-step implementations. Skip for simple changes like typo fixes, style adjustments, or straightforward documentation updates.
No, AI Plans complement these by capturing the AI's reasoning and decision-making process that doesn't fit in commit messages. They provide additional context about how and why solutions were implemented in a particular way.
The standard format is recommended for consistency, but you can extend it with additional sections as needed for your project while maintaining the core structure that makes plans useful for AI context.
AI tools can read the plan files in your repository to understand past decisions and approaches to similar problems, enabling them to provide more context-aware suggestions without needing to search git history.