claude-fsd 1.0.0 → 1.1.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(git push:*)",
+      "Bash(npm publish:*)"
+    ],
+    "deny": []
+  }
+}

package/README.md

@@ -1,6 +1,19 @@
 # claude-fsd
 
-Claude Full Stack Development tools for managing development projects.
+Claude Full Stack Development (FSD) - Your AI-powered development team in a box.
+
+## What is this?
+
+Remember when junior developers were going to be replaced by AI? Well, the tables have turned. As explained in the excellent article ["Revenge of the Junior Developer"](https://sourcegraph.com/blog/revenge-of-the-junior-developer), AI has actually made junior developers more powerful than ever.
+
+This tool takes that concept to the next level by creating an entire **agent fleet** - multiple AI agents working together like a development team:
+
+- 🧑‍💻 **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
+
+Think of it as having a full development team that never sleeps, never gets tired, and always follows best practices. The AI agents work in cycles, planning tasks, implementing them, reviewing the work, and then moving on to the next task.
 
 ## Installation
 
@@ -8,35 +21,95 @@ Claude Full Stack Development tools for managing development projects.
 npm install -g claude-fsd
 ```
 
-## Usage
-
-After installation, the following commands will be available globally:
-
-### claudefsd-dev
-Development environment management tool.
+## Quick Start
 
+Just run:
 ```bash
-claudefsd-dev
+claudefsd
 ```
 
-### claudefsd-plan
-Project planning and management tool.
+You'll get an interactive menu to choose what you want to do. It's that simple!
+
+## Commands
 
+### Main wrapper command
 ```bash
-claudefsd-plan
+claudefsd         # Interactive mode (recommended for beginners)
+claudefsd dev     # Jump straight into development mode
+claudefsd plan    # Jump straight into planning mode
+claudefsd plan-gen # Generate a new project plan
 ```
 
-### claudefsd-plan-gen
-Plan generation utility.
+### Individual commands (if you know what you're doing)
 
-```bash
-claudefsd-plan-gen
+#### claudefsd-dev
+Runs the development agent fleet. This command:
+- Reads your project plan from `docs/PLAN.md`
+- Picks the next open task
+- Assigns it to the developer agent
+- Has the code reviewed by the reviewer agent
+- Tests and commits the changes if everything looks good
+- Repeats until all tasks are done
+
+Every 4th cycle, it activates "megathinking mode" for architectural planning.
+
+#### claudefsd-plan
+Interactive planning session where you work with AI to:
+- Define project requirements
+- Break down complex features into tasks
+- Prioritize and organize work
+- Update the project roadmap
+
+#### claudefsd-plan-gen
+Generates an initial project plan from scratch based on:
+- Your project requirements (`docs/REQUIREMENTS.md`)
+- Any existing code or documentation
+- Best practices for your tech stack
+
+## How it Works
+
+1. **You define what you want** in `docs/REQUIREMENTS.md`
+2. **AI creates a plan** breaking it down into manageable tasks
+3. **The agent fleet executes** the plan task by task
+4. **You review and guide** the process when needed
+
+The agents work in a continuous loop:
+```
+Plan → Develop → Review → Test → Commit → Repeat
 ```
 
 ## Requirements
 
+### Required
 - Node.js >= 14.0.0
 - Unix-like environment (macOS, Linux)
+- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` command)
+
+### Optional (but recommended)
+- [Codex](https://github.com/Codex-ai/codex) - For enhanced code review capabilities
+- OpenAI API key - For Codex features (set `OPENAI_API_KEY` environment variable)
+
+## Project Structure
+
+Your project should have:
+```
+your-project/
+├── docs/
+│   ├── PLAN.md          # The development plan (tasks to do)
+│   ├── REQUIREMENTS.md  # What you want built
+│   ├── QUESTIONS.md     # Questions for clarification
+│   └── IDEAS.md         # Future ideas and improvements
+├── logs/                # Logs from each AI session
+└── BRIEF.md            # Project overview (optional)
+```
+
+## Tips for Success
+
+1. **Start small** - Break down your project into small, clear tasks
+2. **Be specific** - The clearer your requirements, the better the results
+3. **Review regularly** - Check in on what the agents are doing
+4. **Use version control** - The agents will commit changes, but you should review them
+5. **Trust but verify** - The agents are good but not perfect
 
 ## License
 

package/bin/check-dependencies.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Function to check if a command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Function to check dependencies
+check_dependencies() {
+    local check_codex=${1:-true}  # Check codex by default
+    local missing_deps=()
+    local warnings=()
+    
+    # Check for claude
+    if ! command_exists claude; then
+        missing_deps+=("claude")
+    fi
+    
+    # Check for codex (optional but recommended)
+    if [ "$check_codex" = true ] && ! command_exists codex; then
+        warnings+=("codex is not installed. Some review features will be unavailable.")
+        warnings+=("Install it from: https://github.com/Codex-ai/codex")
+    fi
+    
+    # Check for OPENAI_API_KEY (optional for codex)
+    if [ "$check_codex" = true ] && [[ ! -v OPENAI_API_KEY ]] || [[ -z "$OPENAI_API_KEY" ]]; then
+        warnings+=("OPENAI_API_KEY is not set. Codex features will be limited.")
+        warnings+=("Set it with: export OPENAI_API_KEY='your-key-here'")
+    fi
+    
+    # Show critical errors
+    if [ ${#missing_deps[@]} -ne 0 ]; then
+        echo -e "${RED}❌ Missing required dependencies:${NC}"
+        for dep in "${missing_deps[@]}"; do
+            echo -e "  - $dep"
+            if [ "$dep" = "claude" ]; then
+                echo -e "    Install from: https://docs.anthropic.com/en/docs/claude-code"
+            fi
+        done
+        echo
+        exit 1
+    fi
+    
+    # Show warnings
+    if [ ${#warnings[@]} -ne 0 ]; then
+        echo -e "${YELLOW}⚠️  Optional dependencies:${NC}"
+        for warning in "${warnings[@]}"; do
+            echo -e "  - $warning"
+        done
+        echo
+    fi
+}
+
+# If sourced directly, run the check
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+    check_dependencies "$@"
+fi

package/bin/claudefsd

@@ -0,0 +1,93 @@
+#!/bin/bash
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Source the dependency checker
+source "$(dirname "$0")/check-dependencies.sh"
+
+# Function to display the menu
+show_menu() {
+    echo -e "${GREEN}🤖 Claude Full Stack Development (FSD) Tool${NC}"
+    echo
+    echo "This tool helps you manage development projects using AI agents."
+    echo "Think of it as your AI-powered development team!"
+    echo
+    echo "What would you like to do?"
+    echo
+    echo "  1) Development mode (default) - AI agents work on coding tasks"
+    echo "  2) Planning mode - AI agents help plan your project"
+    echo "  3) Generate initial plan - Create a new project plan from scratch"
+    echo "  4) Exit"
+    echo
+}
+
+# Check dependencies first
+check_dependencies
+
+# If no arguments provided, show interactive menu
+if [ $# -eq 0 ]; then
+    show_menu
+    read -p "Enter your choice [1]: " choice
+    choice=${choice:-1}  # Default to 1 if empty
+    
+    case $choice in
+        1)
+            echo -e "${GREEN}Starting development mode...${NC}"
+            echo
+            exec "$(dirname "$0")/claudefsd-dev"
+            ;;
+        2)
+            echo -e "${GREEN}Starting planning mode...${NC}"
+            echo
+            exec "$(dirname "$0")/claudefsd-plan"
+            ;;
+        3)
+            echo -e "${GREEN}Starting plan generation...${NC}"
+            echo
+            exec "$(dirname "$0")/claudefsd-plan-gen"
+            ;;
+        4)
+            echo "Goodbye!"
+            exit 0
+            ;;
+        *)
+            echo -e "${RED}Invalid choice. Please run again.${NC}"
+            exit 1
+            ;;
+    esac
+else
+    # If arguments provided, pass them through to the appropriate command
+    case "$1" in
+        dev)
+            shift
+            exec "$(dirname "$0")/claudefsd-dev" "$@"
+            ;;
+        plan)
+            shift
+            exec "$(dirname "$0")/claudefsd-plan" "$@"
+            ;;
+        plan-gen)
+            shift
+            exec "$(dirname "$0")/claudefsd-plan-gen" "$@"
+            ;;
+        *)
+            echo -e "${RED}Unknown command: $1${NC}"
+            echo
+            echo "Usage: claudefsd [command]"
+            echo
+            echo "Commands:"
+            echo "  dev       - Run development mode"
+            echo "  plan      - Run planning mode"
+            echo "  plan-gen  - Generate initial plan"
+            echo
+            echo "Run without arguments for interactive mode."
+            exit 1
+            ;;
+    esac
+fi

package/bin/claudefsd-dev

@@ -2,6 +2,9 @@
 
 set -e
 
+# Check dependencies
+$(dirname "$0")/check-dependencies.sh
+
 # Add counter for loop iterations
 LOOP_COUNTER=0
 
@@ -142,7 +145,9 @@ Do not include any additional commentary or explanations outside of these tagged
 
     # run the static code reviewer (codex can't do the git push part yet, so we need to follow up with claude after)
     # also run it in the background because it's very slow
-    (codex --full-auto -q "
+    # Only run if codex is available
+    if command -v codex >/dev/null 2>&1; then
+        (codex --full-auto -q "
 You are the team's static code reviewer.
 A developer has completed this task: $nexttask
 The developer's notes are at $LOGFILE-developer .
@@ -166,6 +171,9 @@ the developer to complete the task properly.
 If you have any questions of the user for the future, you can add them to QUESTIONS.md.
 If you have any ideas for the future, you can add them to IDEAS.md.
 " > $LOGFILE-reviewer) &
+    else
+        echo "Codex not available, skipping static code review" > $LOGFILE-reviewer
+    fi
 
     echo -e "\033[32m==================================================================\033[0m"
     echo -e "\033[32m== REVIEWING/TESTING/COMMITTING WORK\033[0m"

package/bin/claudefsd-plan

@@ -2,6 +2,9 @@
 
 set -e
 
+# Check dependencies
+$(dirname "$0")/check-dependencies.sh
+
 mkdir -p logs
 
 # Use a temporary directory for tmp files, as codex is sandboxed to this directory
@@ -55,8 +58,14 @@ Focus on the user's brief and answers from docs/QUESTIONS.md, and the plan.
 # run BA's
 echo "Running claude..."
 claude --dangerously-skip-permissions -p "$prompt1" | tee >(cat > $LOGFILE-ba1)
-echo "Running codex o3 (results won't display)..."
-codex -m o3 --full-auto -q "$prompt1" > $LOGFILE-ba2
+
+# Only run codex if available
+if command -v codex >/dev/null 2>&1; then
+    echo "Running codex o3 (results won't display)..."
+    codex -m o3 --full-auto -q "$prompt1" > $LOGFILE-ba2
+else
+    echo "Codex not available, skipping o3 analysis" > $LOGFILE-ba2
+fi
 
 echo -e "\033[32m==================================================================\033[0m"
 echo -e "\033[32m== ANSWER THE QUESTIONS IN QUESTIONS.md\033[0m"
@@ -68,4 +77,4 @@ read -n 1 -s
 echo "Opening QUESTIONS.md in $EDITOR..."
 $EDITOR QUESTIONS.md
 
-/usr/local/bin/claudefsd-plan-gen
+$(dirname "$0")/claudefsd-plan-gen

package/bin/claudefsd-plan-gen

@@ -2,6 +2,9 @@
 
 set -e
 
+# Check dependencies
+$(dirname "$0")/check-dependencies.sh
+
 mkdir -p logs
 
 # Use a temporary directory for tmp files, as codex is sandboxed to this directory
@@ -51,14 +54,20 @@ Focus on the user's brief and answers from docs/QUESTIONS.md, and the plan.
 # run BA's
 echo "Running claude..."
 claude --dangerously-skip-permissions -p "$prompt2" | tee >(cat > $LOGFILE-ba3-$round)
-echo "Running codex o3 (results won't display)..."
-codex -m o3 --full-auto -q "$prompt2" > $LOGFILE-ba4-$round
+
+# Only run codex if available
+if command -v codex >/dev/null 2>&1; then
+    echo "Running codex o3 (results won't display)..."
+    codex -m o3 --full-auto -q "$prompt2" > $LOGFILE-ba4-$round
+else
+    echo "Codex not available, skipping o3 analysis" > $LOGFILE-ba4-$round
+fi
 
 echo -e "\033[32m==================================================================\033[0m"
 echo -e "\033[32m== DONE\033[0m"
 echo -e "\033[32m==================================================================\033[0m"
 echo "You can now run claudefsd-dev to start the development process."
-echo "Or do one more round of $0 to cover more questions."
+echo "Or do one more round of claudefsd-plan to cover more questions."
 
 
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "claude-fsd",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Claude Full Stack Development tools for managing development projects",
   "bin": {
+    "claudefsd": "./bin/claudefsd",
     "claudefsd-dev": "./bin/claudefsd-dev",
     "claudefsd-plan": "./bin/claudefsd-plan",
     "claudefsd-plan-gen": "./bin/claudefsd-plan-gen"