AI Plans
Document AI-assisted development with version-controlled markdown files
AI Plans 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 Screenshot
AI Plans Official screenshot of the tool interface
AI Plans Core 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.
AI Plans Use Cases
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
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.