claude-fsd

# claude-fsd Automated project development - let AI build your project while you sleep. ## What is this? claude-fsd is an automated development system that runs continuous development cycles without constant supervision. Write a brief description of what you want, answer some clarifying questions, then let it build your project autonomously. Think of it like **Tesla FSD for code** - it handles the driving, but you should keep an eye on it and occasionally take the wheel when needed. ### How the Agent System Works The system operates with multiple specialized AI agents working together: - 🧑‍💻 **Developer Agent**: Writes code, implements features, fixes bugs - 📋 **Planner Agent**: Breaks down tasks, manages the development roadmap - 👀 **Reviewer Agent**: Reviews code quality, catches issues, ensures best practices - 🧪 **Tester Agent**: Runs tests, validates changes, commits clean code The agents work in continuous cycles: ``` Plan → Develop → Review → Test → Commit → Repeat ``` You can leave it running while you grab lunch or sleep - it just keeps going until it thinks the project is complete. ## Installation ```bash npm install -g claude-fsd ``` ## Quick Start ```bash claude-fsd ``` The system will walk you through the setup process: 1. **Create a BRIEF.md** - Write a short description of what you want to build 2. **Answer questions** - The AI will generate clarifying questions for you to answer 3. **Let it rip** - Start the automated development process ### Working with Multiple Projects You can run multiple projects in the same repository using the `--working-dir` parameter: ```bash # Default behavior (uses 'docs' directory) claude-fsd # Custom project directories claude-fsd --working-dir=frontend claude-fsd --working-dir=backend claude-fsd --working-dir=client-app/docs ``` ## Commands ### Main wrapper command ```bash claude-fsd # Interactive mode (recommended for beginners) claude-fsd dev # Jump straight into development mode claude-fsd interview # Interactive requirements gathering claude-fsd create-plan # Generate development plan from requirements # With custom working directory claude-fsd --working-dir=project1 dev claude-fsd --working-dir=backend interview # claudefsd also works the same way claudefsd # Same as claude-fsd ``` ### Individual commands (if you know what you're doing) #### claudefsd-dev Runs the development agent fleet. This command: - Reads your project plan from `PLAN.md` in your working directory - Intelligently selects and executes tasks (single agent for complex work, parallel agents for independent tasks) - Has the code reviewed and tested - Updates the plan to track progress - Repeats until all tasks are done Options: - `--max-time=MINUTES` - Maximum total runtime (default: 120 minutes) - `--working-dir=DIR` - Directory containing BRIEF.md and PLAN.md (default: docs) Every 4th cycle, it activates "megathinking mode" using ultrathink for deep architectural planning. **@STOP Checkpoint**: Add `@STOP` on its own line in PLAN.md to pause when all preceding tasks complete. Useful for human review or deployment gates. #### claudefsd-interview Interactive expert Q&A session that: - Analyzes your BRIEF.md with multiple AI personas (DBA, Architect, UX Expert, etc.) - Asks targeted questions to understand requirements - Saves answers in QUESTIONS.md and consolidated requirements in REQUIREMENTS.md - Supports resuming interrupted sessions #### claudefsd-create-plan Generates a comprehensive development plan based on: - Your project brief (BRIEF.md) - Interview answers (QUESTIONS.md) or requirements (REQUIREMENTS.md) - Creates PLAN.md with prioritized tasks and CLAUDE-NOTES.md with architectural analysis - Uses Claude Sonnet with ultrathink for deep strategic planning ## How it Works 1. **Write a BRIEF.md** - Describe what you want to build in your working directory 2. **Run the interview** - Answer AI-generated questions from domain experts 3. **Generate the plan** - AI creates a comprehensive development roadmap 4. **Start the development loop** - The system automatically: - Analyzes all open tasks in PLAN.md - Intelligently executes tasks (sequentially or in parallel) - Updates the plan to track progress - Repeats until all tasks are complete or **<ALL DONE>** is detected ## Monitoring Progress (Like Tesla FSD) This isn't sci-fi level "sleep through the entire project" automation - it's more like Tesla FSD. The system handles most of the work, but you should monitor it and be ready to intervene when needed. **Recommended monitoring approach:** - **Run a parallel Claude session** - Open another Claude window/tab to chat about the project - **Check status periodically** - Ask the parallel Claude: "What's the current status of my project?" - **Review the plan** - Look at `PLAN.md` in your working directory to see what's been completed - **Watch for drift** - If the system goes off track, intervene before it gets too far **When you need to course-correct:** - **Update the plan** - Add urgent fixes or redirections to the top of `PLAN.md` - **Direct intervention** - Use your parallel Claude session to directly fix issues - **The system adapts** - claude-fsd will pick up plan changes on the next loop iteration **Interruptible design:** - Hit Ctrl+C anytime to pause - Restart later with `claude-fsd dev` - Perfect for running overnight, during meetings, or while getting lunch ## Requirements ### Required - Node.js >= 14.0.0 - Unix-like environment (macOS, Linux) - [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` command) ## Project Structure **Flexible Structure:** Files can be placed in either `docs/` (default) or root directory `.` - System automatically detects file locations - Use `docs/` for larger projects to keep files organized - Use root `.` for smaller projects for simplicity Default structure (using 'docs' as working directory): ``` your-project/ ├── docs/ │ ├── BRIEF.md # Project overview and requirements │ ├── PLAN.md # The development plan (tasks with [ ] checkboxes) │ ├── CLAUDE-NOTES.md # AI architect's analysis and notes │ ├── QUESTIONS.md # Interview questions and answers │ ├── REQUIREMENTS.md # Consolidated requirements from interview │ ├── IDEAS.md # Future ideas and improvements │ └── INTERVIEW-SESSION.json # Interview session metadata ├── logs/ # Logs from each AI session └── [your code files] ``` Simple structure (files in root): ``` your-project/ ├── BRIEF.md ├── PLAN.md ├── CLAUDE-NOTES.md ├── logs/ └── [your code files] ``` With custom working directory: ``` your-project/ ├── frontend/ │ ├── BRIEF.md │ ├── PLAN.md │ └── ... ├── backend/ │ ├── BRIEF.md │ ├── PLAN.md │ └── ... └── logs/ ``` ## Tips for Success 1. **Keep your BRIEF.md concise** - A few clear paragraphs work better than lengthy specifications 2. **Answer questions thoroughly** - The AI's questions help it understand your exact needs 3. **Monitor periodically** - Check progress while it runs, especially during initial cycles 4. **Use the plan as your steering wheel** - Update `PLAN.md` to guide development direction 5. **Trust the process** - Let it run autonomously, but verify the results 6. **Use --working-dir for multiple projects** - Run different projects in parallel by specifying different directories ## Model Selection Strategy The system uses Claude Sonnet throughout with strategic ultrathinking for complex work: - **Sonnet + Ultrathink**: Used for complex architectural work requiring deep thinking - Requirements consolidation (interview) - Deep strategic planning (create-plan) - Megathinking mode (every 4th dev iteration) - **Sonnet (Standard)**: Used for regular development - Standard development tasks - Code implementation and reviews - Most development iterations - Question generation in interview ## License MIT