agent-planner-mcp 0.2.0 → 0.3.0

package/claude-code/AUTONOMOUS_EXECUTION_GUIDE.md

@@ -0,0 +1,335 @@
+# Autonomous Plan Execution Guide
+
+This directory is configured for autonomous plan execution using Claude Code with the MCP planning system.
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Claude Code                              │
+│  ┌────────────────┐  ┌────────────────┐  ┌───────────────┐ │
+│  │ Slash Commands │→│ Task Tool      │→│ MCP Planning  │ │
+│  │ (Orchestrator) │  │ (Executors)    │  │ System (Data) │ │
+│  └────────────────┘  └────────────────┘  └───────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+         ↓                    ↓                     ↓
+    /execute-plan      general-purpose      Persistent Storage
+    /create-plan         agents           (plans, tasks, logs)
+    /plan-status
+```
+
+## Quick Start
+
+### 1. Create a Plan
+
+```bash
+# In Claude Code CLI, run:
+/create-plan
+```
+
+This interactive command will guide you through:
+- Defining your plan title and description
+- Breaking it into phases
+- Creating specific tasks with acceptance criteria
+- Adding agent instructions for autonomous execution
+
+### 2. Execute the Plan
+
+```bash
+# Start autonomous execution:
+/execute-plan <plan-id>
+```
+
+Claude will:
+- Load the plan from MCP
+- Work through tasks one by one
+- Launch specialized Task agents for each task
+- Update status in real-time
+- Log all progress
+- Report completion or blockers
+
+### 3. Monitor Progress
+
+```bash
+# Check status anytime:
+/plan-status <plan-id>
+```
+
+Shows:
+- Overall progress (% complete)
+- Current task being worked on
+- Any blockers
+- Recent activity
+- Next suggested actions
+
+## Available Commands
+
+### `/create-plan`
+Interactive plan builder that helps you structure work into phases and tasks.
+
+**When to use**: Starting a new feature, bug fix, refactoring, or any multi-step work.
+
+**Output**: A complete plan with hierarchical structure stored in MCP.
+
+### `/execute-plan <plan-id>`
+Autonomous execution orchestrator that works through tasks systematically.
+
+**When to use**: After creating a plan, or to resume interrupted execution.
+
+**What it does**:
+- Fetches tasks from the plan
+- Executes them one by one using Task agents
+- Updates MCP with progress
+- Handles errors and blockers
+- Reports final summary
+
+### `/plan-status <plan-id>`
+Real-time status reporter showing plan progress and activity.
+
+**When to use**: Check progress during execution, review completed work, identify blockers.
+
+**Output**: Formatted report with statistics, task breakdown, and recent activity.
+
+## How Autonomous Execution Works
+
+### The Execution Loop
+
+1. **Fetch Plan**: Load plan structure from MCP
+2. **Find Next Task**: Get first task with status "not_started"
+3. **Get Context**: Load task details, acceptance criteria, agent instructions
+4. **Update Status**: Mark task as "in_progress" in MCP
+5. **Execute**: Launch Task agent with full context
+6. **Wait**: Agent works autonomously (reads code, makes changes, runs tests)
+7. **Process Result**:
+   - If successful → Mark "completed", log progress, move to next task
+   - If blocked → Mark "blocked", log issue, ask user for guidance
+8. **Repeat**: Continue until all tasks done or blocked
+
+### Task Agent Execution
+
+Each task gets a dedicated `general-purpose` agent that:
+- Has access to all Claude Code tools (Read, Write, Edit, Bash, etc.)
+- Receives full task context from the plan
+- Works autonomously to complete the task
+- Reports back with summary of changes
+- Verifies acceptance criteria are met
+
+### State Management
+
+All state is stored in the MCP planning system:
+- **Plans**: Title, description, status (draft/active/completed)
+- **Nodes**: Hierarchical tasks/phases/milestones
+- **Logs**: Activity timeline (progress, challenges, decisions)
+- **Artifacts**: File references and resources
+
+**Key benefit**: Execution can be interrupted and resumed. State persists across sessions.
+
+## Writing Good Plans
+
+### Task Structure
+
+Each task should have:
+
+1. **Clear Title**: "Create user authentication API endpoint"
+2. **Description**: What needs to be done and why
+3. **Acceptance Criteria**:
+   - Specific, measurable outcomes
+   - "API returns 200 on valid credentials"
+   - "Returns 401 on invalid credentials"
+   - "Integration tests pass with 80%+ coverage"
+4. **Agent Instructions**:
+   - Specific file paths or patterns to follow
+   - Technologies/frameworks to use
+   - Testing requirements
+   - Related files to reference
+
+### Example: Good vs. Bad Tasks
+
+❌ **Bad Task**:
+```
+Title: Add login
+Description: Add login functionality
+Acceptance Criteria: Login works
+Agent Instructions: Add login
+```
+
+✅ **Good Task**:
+```
+Title: Create login API endpoint
+Description: Add POST /api/v1/auth/login endpoint that validates credentials and returns JWT token
+Acceptance Criteria:
+- Endpoint accepts email and password
+- Returns JWT token on valid credentials
+- Returns 401 on invalid credentials
+- Returns 400 on missing fields
+- Integration tests pass with 80%+ coverage
+- Swagger docs updated
+Agent Instructions:
+Create route in agent-planner/src/routes/auth.routes.js following pattern in users.routes.js.
+Create controller in src/controllers/auth.controller.js.
+Use bcrypt for password hashing.
+Generate JWT using jsonwebtoken library.
+Add validation middleware using express-validator.
+Write integration tests in tests/integration/auth.test.js.
+Run 'npm test' to verify.
+Update API docs with 'npm run docs:all'.
+```
+
+### Task Ordering
+
+Consider dependencies:
+1. Database migrations before API endpoints
+2. API endpoints before frontend components
+3. Core functionality before tests
+4. Tests before documentation
+
+## Project Context
+
+The orchestrator and agents have access to CLAUDE.md which provides:
+- Multi-repo structure (backend, frontend, MCP, homepage)
+- Development commands for each repo
+- Testing patterns
+- Authentication flow
+- Database migration system
+- Deployment procedures
+
+Agents automatically reference this context when executing tasks.
+
+## Backend-Specific Tasks
+
+For backend tasks (migrations, API endpoints, database):
+- Agents know to use `npm run db:init` after creating migrations
+- Follow patterns in src/routes/*.routes.js and src/controllers/*.controller.js
+- Add RLS policies for security
+- Update API docs with `npm run docs:all`
+- Run appropriate test suites
+
+## Frontend-Specific Tasks
+
+For frontend tasks (components, pages, hooks):
+- Agents use React + TypeScript patterns
+- Follow Tailwind CSS conventions
+- Create components in src/components/
+- Use React Query for server state
+- Write tests with React Testing Library
+
+## Tips for Success
+
+1. **Be Specific**: Vague tasks lead to vague implementations
+2. **One Thing Per Task**: Don't combine multiple concerns
+3. **Clear Success Criteria**: Agent needs to know when done
+4. **Reference Existing Code**: Help agents find patterns
+5. **Include Testing**: Every code task should mention tests
+6. **Review Agent Instructions**: These guide the autonomous agent
+
+## Troubleshooting
+
+### "Plan not found"
+- Check plan ID is correct
+- List plans with `/plan-status` (no ID) to see available plans
+
+### "Task is blocked"
+- Check logs with `/plan-status <plan-id>`
+- Review what blocked the task
+- Update agent instructions if needed
+- Manually unblock or fix issue, then change status back to "not_started"
+
+### "Agent didn't follow instructions"
+- Review agent_instructions in the task
+- Make them more specific with file paths and patterns
+- Reference similar existing code to follow
+- Update task and retry
+
+### Execution interrupted
+- No problem! Just run `/execute-plan <plan-id>` again
+- It will resume from where it left off
+- All progress is saved in MCP
+
+## MCP Configuration
+
+Your `.claude/settings.local.json` should include:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__planning-system__create_node",
+      "mcp__planning-system__create_plan",
+      "mcp__planning-system__add_log",
+      "mcp__planning-system__get_plan_summary",
+      "mcp__planning-system__batch_update_nodes",
+      "mcp__planning-system__update_node"
+    ]
+  }
+}
+```
+
+These permissions let Claude autonomously update plans without asking for approval each time.
+
+## Example Workflow
+
+```bash
+# 1. Create a plan
+/create-plan
+# → Follow prompts to create "Feature: User Notifications" plan
+# → Plan ID: abc-123
+
+# 2. Execute autonomously
+/execute-plan abc-123
+# → Claude works through all tasks
+# → Creates migration
+# → Adds API endpoints
+# → Creates frontend components
+# → Writes tests
+# → Reports completion
+
+# 3. Check status anytime (in another session if needed)
+/plan-status abc-123
+# → Shows progress: 8/10 tasks complete
+# → 2 tasks in progress
+
+# 4. When done
+/plan-status abc-123
+# → Shows: All tasks completed!
+```
+
+## Advanced: Manual MCP Tool Usage
+
+You can also use MCP tools directly:
+
+```javascript
+// List all plans
+mcp__planning-system__list_plans()
+
+// Create a plan
+mcp__planning-system__create_plan({
+  title: "Feature: Dark Mode",
+  description: "Add dark mode support across the app"
+})
+
+// Add a task
+mcp__planning-system__create_node({
+  plan_id: "abc-123",
+  node_type: "task",
+  title: "Create dark mode toggle component",
+  acceptance_criteria: "Toggle switches theme, persists preference"
+})
+
+// Update status
+mcp__planning-system__update_node({
+  plan_id: "abc-123",
+  node_id: "task-456",
+  status: "completed"
+})
+```
+
+But using the slash commands is much easier!
+
+## Next Steps
+
+1. Try creating a simple 2-3 task plan with `/create-plan`
+2. Run `/execute-plan` and watch it work
+3. Monitor with `/plan-status`
+4. Iterate and refine your task definitions
+
+Happy autonomous coding! 🚀

package/claude-code/commands/README.md

@@ -0,0 +1,112 @@
+# Claude Code Slash Commands
+
+Custom slash commands for autonomous plan execution in the Talking Agents project.
+
+## Available Commands
+
+### `/create-plan`
+Interactive plan builder that guides you through creating a structured development plan.
+
+**Usage**: `/create-plan`
+
+**What it does**:
+- Asks for plan title and description
+- Helps break work into phases
+- Creates specific tasks with acceptance criteria
+- Adds agent instructions for autonomous execution
+- Stores everything in MCP planning system
+
+### `/execute-plan`
+Autonomous execution orchestrator that works through plan tasks systematically.
+
+**Usage**: `/execute-plan <plan-id>` or `/execute-plan` (will prompt for ID)
+
+**What it does**:
+- Loads plan from MCP
+- Executes tasks sequentially using Task agents
+- Updates status in real-time
+- Logs all progress
+- Handles blockers and errors
+- Reports final summary
+
+### `/plan-status`
+Status reporter showing plan progress and recent activity.
+
+**Usage**: `/plan-status <plan-id>` or `/plan-status` (will list all plans)
+
+**What it does**:
+- Shows overall progress statistics
+- Lists all tasks with current status
+- Highlights blockers
+- Shows recent activity logs
+- Suggests next actions
+
+## How They Work Together
+
+```
+1. /create-plan
+   ↓
+   Creates structured plan in MCP
+   ↓
+2. /execute-plan <plan-id>
+   ↓
+   Executes tasks autonomously
+   ↓
+3. /plan-status <plan-id>
+   ↓
+   Monitor progress anytime
+```
+
+## Requirements
+
+- MCP planning system must be configured and running
+- `.claude/settings.local.json` must have MCP permissions enabled
+- See AUTONOMOUS_EXECUTION_GUIDE.md for full setup details
+
+## Examples
+
+### Creating and executing a plan
+```
+> /create-plan
+Claude: What is this plan for?
+You: Add user profile editing feature
+
+Claude: Let me help you break this down...
+[Interactive prompts follow]
+
+Claude: Plan created! Plan ID: plan_abc123
+
+> /execute-plan plan_abc123
+Claude: Starting execution...
+Task 1/5: Create migration... ✅ Complete
+Task 2/5: Add API endpoint... ✅ Complete
+Task 3/5: Create UI component... 🔄 In progress...
+```
+
+### Checking status
+```
+> /plan-status plan_abc123
+# Plan Status Report
+
+## 📋 Plan: Add user profile editing feature
+**Status**: active
+**Progress**: 3/5 tasks complete (60%)
+
+## Task Status:
+- ✅ Completed: 3
+- 🔄 In Progress: 1
+- 📋 Not Started: 1
+```
+
+## Customization
+
+These commands can be modified by editing the .md files in this directory. Each file contains:
+- Instructions for Claude Code on how to execute the command
+- Templates for interacting with MCP
+- Guidance on error handling and edge cases
+
+## See Also
+
+- [AUTONOMOUS_EXECUTION_GUIDE.md](../AUTONOMOUS_EXECUTION_GUIDE.md) - Comprehensive guide
+- [CLAUDE.md](/CLAUDE.md) - Project architecture and patterns
+- [.claude/settings.local.json](../settings.local.json) - MCP configuration

package/claude-code/commands/create-plan.md

@@ -0,0 +1,174 @@
+# Create Plan - Interactive Plan Builder
+
+You are a plan creation assistant. Help the user create a structured plan in the MCP planning system.
+
+## Step 1: Gather Plan Information
+
+Ask the user for:
+1. **Plan title**: What is this plan for?
+2. **Plan description**: What's the overall goal?
+3. **Plan scope**: Is this for:
+   - A new feature?
+   - A bug fix?
+   - A refactoring effort?
+   - Testing work?
+   - Documentation?
+   - Other?
+
+## Step 2: Create the Plan
+
+Use `mcp__planning-system__create_plan` with:
+- `title`: The plan title
+- `description`: The plan description
+- `status`: "draft" (user can activate it later)
+
+Save the returned `plan_id` - you'll need it for creating nodes.
+
+## Step 3: Break Down Into Phases
+
+Ask the user what major phases this work involves. Common patterns:
+
+**For new features**:
+- Phase 1: Backend API
+- Phase 2: Frontend UI
+- Phase 3: Testing
+- Phase 4: Documentation
+
+**For bug fixes**:
+- Phase 1: Investigation & Root Cause
+- Phase 2: Fix Implementation
+- Phase 3: Testing & Verification
+
+**For refactoring**:
+- Phase 1: Analysis & Planning
+- Phase 2: Incremental Changes
+- Phase 3: Testing & Validation
+
+For each phase, create a node using `mcp__planning-system__create_node` with:
+- `plan_id`
+- `node_type: "phase"`
+- `title`: Phase name
+- `description`: What happens in this phase
+- `status: "not_started"`
+
+## Step 4: Break Phases Into Tasks
+
+For each phase, ask the user what specific tasks are needed.
+
+**Guide the user with suggestions based on phase type**:
+
+**Backend API phase**:
+- Create database migration
+- Create/update routes
+- Create/update controllers
+- Add authentication/validation
+- Write API tests
+- Update API documentation
+
+**Frontend UI phase**:
+- Create React components
+- Set up React Query hooks
+- Add routing
+- Style with Tailwind CSS
+- Write component tests
+
+**Testing phase**:
+- Write unit tests
+- Write integration tests
+- Write E2E tests
+- Verify test coverage
+
+For each task, create a node using `mcp__planning-system__create_node` with:
+- `plan_id`
+- `node_type: "task"`
+- `parent_id`: The phase node_id
+- `title`: Task name
+- `description`: What needs to be done
+- `acceptance_criteria`: How to know it's complete (be specific!)
+- `agent_instructions`: Specific guidance for the AI agent executing this
+- `status: "not_started"`
+
+## Step 5: Add Agent Instructions (Critical!)
+
+For each task, help user write clear `agent_instructions`. These guide the autonomous agent.
+
+**Good agent instructions examples**:
+
+```markdown
+**Backend API Task**:
+Create a new Express route at /api/v1/users/:id/profile with GET and PUT methods.
+Follow patterns in src/routes/users.routes.js. Add Swagger annotations.
+Include validation middleware. Add RLS policies for the database.
+
+**Frontend Component Task**:
+Create a ProfileCard component in src/components/ProfileCard.tsx.
+Use Tailwind CSS for styling. Accept user prop with type User.
+Include loading and error states. Write tests in ProfileCard.test.tsx.
+
+**Testing Task**:
+Write integration tests for the user profile endpoints.
+Use patterns from tests/integration/users.test.js.
+Test success case, validation errors, and authentication.
+Ensure test coverage is above 80%.
+```
+
+**Key elements**:
+- Specific file paths or patterns to follow
+- Technologies/tools to use
+- Error cases to handle
+- Related files to reference
+- Testing requirements
+
+## Step 6: Review and Activate
+
+Show the user the full plan structure:
+- Plan title and description
+- All phases
+- All tasks under each phase
+- Acceptance criteria for each task
+
+Ask: "Does this look good? Any changes needed?"
+
+If approved, update plan status to "active":
+```
+mcp__planning-system__update_plan with:
+- plan_id
+- status: "active"
+```
+
+## Step 7: Next Steps
+
+Tell the user:
+```
+Plan created successfully!
+
+Plan ID: {plan_id}
+
+To execute this plan autonomously, run:
+/execute-plan {plan_id}
+
+To check status anytime:
+/plan-status {plan_id}
+```
+
+## Tips for Good Plans
+
+1. **Be specific**: Vague tasks lead to vague implementations
+2. **One concern per task**: Don't combine "add API + add UI + add tests" in one task
+3. **Clear acceptance criteria**: "Add tests" ❌ | "Add integration tests with 80%+ coverage for all CRUD operations" ✅
+4. **Reference existing code**: Help agents find patterns to follow
+5. **Include test requirements**: Every code task should mention testing
+6. **Think about order**: Some tasks depend on others being done first
+
+## Example Complete Task
+
+```json
+{
+  "title": "Create user profile API endpoint",
+  "description": "Add GET and PUT endpoints for user profile management at /api/v1/users/:id/profile",
+  "acceptance_criteria": "- GET /api/v1/users/:id/profile returns user profile\n- PUT /api/v1/users/:id/profile updates profile\n- Returns 401 if not authenticated\n- Returns 403 if accessing other user's profile\n- Swagger documentation is complete\n- Integration tests pass with 80%+ coverage",
+  "agent_instructions": "Create new route file: agent-planner/src/routes/profile.routes.js\n\nFollow the pattern in src/routes/users.routes.js:\n- Use authenticate middleware from src/middleware/auth.middleware.js\n- Create controller in src/controllers/profile.controller.js\n- Add Swagger JSDoc annotations for API docs\n- Validate request body using express-validator\n- Add RLS policy to ensure users can only access their own profile\n\nWrite integration tests in tests/integration/profile.test.js:\n- Test successful GET\n- Test successful PUT with valid data\n- Test 401 unauthorized\n- Test 403 forbidden (different user)\n- Test 400 validation errors\n\nRun npm test to verify all tests pass.\nRun npm run docs:all to update API documentation."
+}
+```
+
+Now begin helping the user create their plan!

package/claude-code/commands/execute-plan.md

@@ -0,0 +1,202 @@
+# Execute Plan - Autonomous Task Orchestrator
+
+You are an autonomous plan execution orchestrator. Your mission is to execute tasks from a plan stored in the MCP planning system, working through them methodically until completion.
+
+## Step 1: Identify the Plan
+
+**If user provided a plan ID**: Use it directly
+**If no plan ID provided**:
+- Use `mcp__planning-system__list_plans` with filter `status: "active"` to show available plans
+- Ask user which plan to execute
+
+## Step 2: Load Plan Structure
+
+Use `mcp__planning-system__get_plan_structure` with the plan_id to get the full hierarchy.
+
+Analyze the structure:
+- Identify all nodes with `node_type: "task"`
+- Note their current status: `not_started`, `in_progress`, `completed`, `blocked`
+- Check parent relationships (phases → tasks)
+- Review `acceptance_criteria` and `agent_instructions` for each task
+
+## Step 3: Execute Tasks Sequentially
+
+For each task with status `not_started` or `in_progress`:
+
+### 3.1 Prepare Task Context
+```
+Use mcp__planning-system__get_node_context with:
+- plan_id
+- node_id (of the task)
+
+This gives you:
+- Full task details
+- Parent nodes (phase context)
+- Existing logs
+- Artifacts
+- Child nodes if any
+```
+
+### 3.2 Update Status to In Progress
+```
+Use mcp__planning-system__update_node:
+- plan_id
+- node_id
+- status: "in_progress"
+```
+
+### 3.3 Execute Task Using Task Tool Agent
+Launch a Task tool with:
+- `subagent_type: "general-purpose"`
+- `description: "<5 word summary of task>"`
+- `prompt: "...detailed prompt below..."`
+
+**Prompt Template**:
+```
+You are executing a task from a development plan. Complete it fully and autonomously.
+
+## Task Details
+
+**Title**: {task.title}
+
+**Description**: {task.description}
+
+**Status**: {task.status}
+
+**Acceptance Criteria**:
+{task.acceptance_criteria}
+
+**Agent Instructions**:
+{task.agent_instructions}
+
+## Context from Plan
+
+**Plan**: {plan.title}
+**Phase**: {parent_node.title if exists}
+
+**Previous Logs**:
+{logs from get_node_context}
+
+**Related Artifacts**:
+{artifacts from get_node_context}
+
+## Project Context
+
+This is the Talking Agents planning system. See CLAUDE.md for architecture:
+- Multi-repo structure (agent-planner backend, agent-planner-ui frontend, agent-planner-mcp)
+- Backend: Node.js + Express + Supabase + PostgreSQL
+- Frontend: React + TypeScript + Tailwind CSS
+- Testing: Jest + Supertest for backend, React Testing Library for frontend
+
+## Your Mission
+
+1. **Read relevant code** to understand current implementation
+2. **Implement the task** following project conventions
+3. **Test your implementation** (run tests if applicable)
+4. **Verify acceptance criteria** are met
+5. **Report back** with:
+   - Summary of what you did
+   - Files created/modified
+   - Test results
+   - Any issues or blockers encountered
+   - Confirmation that acceptance criteria are met (or what's missing)
+
+## Important Notes
+
+- Follow existing patterns in the codebase
+- Run tests after making changes
+- Don't skip error handling or validation
+- Update documentation if needed
+- If blocked, explain why clearly
+
+Execute this task completely and thoroughly. Report back when done.
+```
+
+### 3.4 Process Agent Response
+
+After the Task agent completes:
+
+**If successful**:
+1. Update node status to "completed":
+   ```
+   mcp__planning-system__update_node with status: "completed"
+   ```
+
+2. Add success log:
+   ```
+   mcp__planning-system__add_log with:
+   - plan_id
+   - node_id
+   - log_type: "progress"
+   - content: "<summary of what was done>"
+   ```
+
+3. Show user a brief summary
+
+**If blocked/failed**:
+1. Update node status to "blocked":
+   ```
+   mcp__planning-system__update_node with status: "blocked"
+   ```
+
+2. Add challenge log:
+   ```
+   mcp__planning-system__add_log with:
+   - plan_id
+   - node_id
+   - log_type: "challenge"
+   - content: "<description of blocker>"
+   ```
+
+3. Ask user for guidance:
+   - What went wrong
+   - How to proceed
+   - Should we skip this task or try again?
+
+## Step 4: Continue or Finish
+
+After each task:
+- Check if there are more tasks with status `not_started`
+- If yes: Repeat Step 3 for next task
+- If no: Proceed to Step 5
+
+## Step 5: Final Summary
+
+Use `mcp__planning-system__get_plan_summary` to get statistics and show user:
+- Total tasks completed
+- Any tasks still blocked or pending
+- Overall plan status
+- Suggest next actions (e.g., "Plan complete! Ready to deploy?" or "3 tasks remaining, continue?")
+
+## Error Handling
+
+- **If a task agent fails**: Mark task as blocked, log the issue, ask user for help
+- **If MCP tools fail**: Report error to user immediately
+- **If you're unsure about a task**: Ask user for clarification before executing
+
+## Execution Guidelines
+
+1. **Work methodically**: One task at a time, no skipping
+2. **Respect dependencies**: If a task depends on another being completed first, follow the order
+3. **Be thorough**: Don't mark tasks complete unless acceptance criteria are truly met
+4. **Communicate clearly**: Keep user informed after each task
+5. **Stay autonomous**: Try to solve problems yourself before asking for help
+6. **Use project knowledge**: Refer to CLAUDE.md for patterns and commands
+
+## Special Cases
+
+**Backend tasks**:
+- Run `npm run db:init` after creating migrations
+- Run `npm test` or specific test suites
+- Update API docs with `npm run docs:all`
+
+**Frontend tasks**:
+- Check TypeScript compilation
+- Run frontend tests
+- Verify component renders correctly
+
+**Testing tasks**:
+- Run specific test suite to verify
+- Check coverage if needed
+
+Now begin execution!

package/claude-code/commands/plan-status.md

@@ -0,0 +1,145 @@
+# Plan Status - Monitor Plan Progress
+
+You are a plan status reporter. Show the user the current state of a plan from the MCP planning system.
+
+## Step 1: Identify the Plan
+
+**If user provided a plan ID**: Use it directly
+**If no plan ID provided**:
+- Use `mcp__planning-system__list_plans` to show all plans
+- Ask user which plan they want to check
+
+## Step 2: Get Plan Summary
+
+Use `mcp__planning-system__get_plan_summary` with the plan_id.
+
+This returns comprehensive statistics and metadata about the plan.
+
+## Step 3: Get Detailed Structure
+
+Use `mcp__planning-system__get_plan_structure` with:
+- `plan_id`
+- `include_details: true`
+
+This gives you the full hierarchy with all node details.
+
+## Step 4: Present Status Report
+
+Format the information in a clear, scannable way:
+
+```markdown
+# Plan Status Report
+
+## 📋 Plan: {plan.title}
+
+**Status**: {plan.status} (draft/active/completed/archived)
+**Created**: {plan.created_at}
+**Last Updated**: {plan.updated_at}
+
+**Description**: {plan.description}
+
+---
+
+## 📊 Progress Summary
+
+**Total Nodes**: {summary.total_nodes}
+- Phases: {count phases}
+- Tasks: {count tasks}
+- Milestones: {count milestones}
+
+**Task Status**:
+- ✅ Completed: {count completed} ({percentage}%)
+- 🔄 In Progress: {count in_progress}
+- 📋 Not Started: {count not_started}
+- 🚫 Blocked: {count blocked}
+
+---
+
+## 📝 Detailed Breakdown
+
+### Phase: {phase.title}
+
+**Status**: {phase.status}
+
+Tasks:
+1. ✅ {task.title} - Completed
+2. 🔄 {task.title} - In Progress
+3. 📋 {task.title} - Not Started
+4. 🚫 {task.title} - Blocked
+
+{Repeat for each phase}
+
+---
+
+## 🚨 Blockers
+
+{List any tasks with status "blocked" and their recent logs}
+
+---
+
+## 🎯 Next Actions
+
+{Suggest what should happen next based on status:}
+
+- If all tasks completed: "Plan is complete! Ready to review and close."
+- If tasks in progress: "Tasks currently being worked on. Continue monitoring."
+- If tasks not started: "Run /execute-plan {plan_id} to begin execution."
+- If tasks blocked: "Address blockers before continuing."
+```
+
+## Step 5: Show Recent Activity
+
+Use `mcp__planning-system__search` to find recent logs:
+- Query: Plan-specific search
+- Type filter: "log"
+- Limit: 10
+
+Show the most recent activity:
+```markdown
+## 📝 Recent Activity
+
+1. [{timestamp}] {log.log_type}: {log.content} (Node: {node.title})
+2. [{timestamp}] {log.log_type}: {log.content} (Node: {node.title})
+...
+```
+
+## Step 6: Offer Actions
+
+Based on the status, suggest relevant actions:
+
+```markdown
+## 🎬 Available Actions
+
+- `/execute-plan {plan_id}` - Continue autonomous execution
+- `/plan-status {plan_id}` - Refresh this status report
+- View specific task details (provide node_id)
+- Update plan status or task statuses manually
+```
+
+## Special Reporting Modes
+
+### Quick Status (one-liner)
+If user asks for quick status, just show:
+```
+Plan "{title}": {completed}/{total} tasks done ({percentage}%), {in_progress} in progress, {blocked} blocked
+```
+
+### Focus on Blockers
+If user asks about blockers specifically:
+1. Filter to only blocked tasks
+2. Get logs for each blocked task
+3. Show detailed breakdown of what's blocking each one
+
+### Timeline View
+If user asks for timeline:
+1. Get all logs ordered by timestamp
+2. Show chronological activity
+3. Highlight status changes
+
+## Error Handling
+
+- If plan_id not found: List available plans
+- If MCP tools fail: Report error clearly
+- If plan has no tasks yet: Suggest using `/create-plan`
+
+Now generate the status report!

package/claude-code/settings.template.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__planning-system__create_node",
+      "mcp__planning-system__create_plan",
+      "mcp__planning-system__add_log",
+      "mcp__planning-system__get_plan_summary",
+      "mcp__planning-system__batch_update_nodes",
+      "mcp__planning-system__update_node"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server interface for the Planning System API",
   "main": "src/index.js",
   "bin": {
@@ -12,6 +12,7 @@
     "test": "jest",
     "test:tools": "node test-tools.js",
     "setup": "node src/setup.js",
+    "setup-claude-code": "node src/setup-claude-code.js",
     "prepublishOnly": "echo 'Ready to publish agent-planner-mcp'"
   },
   "keywords": [
@@ -47,6 +48,7 @@
   },
   "files": [
     "src/",
+    "claude-code/",
     "README.md",
     "LICENSE"
   ]

package/src/setup-claude-code.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import readline from 'readline';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+function question(query) {
+  return new Promise(resolve => rl.question(query, resolve));
+}
+
+function copyRecursive(src, dest) {
+  const exists = fs.existsSync(src);
+  const stats = exists && fs.statSync(src);
+  const isDirectory = exists && stats.isDirectory();
+
+  if (isDirectory) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    fs.readdirSync(src).forEach(childItemName => {
+      copyRecursive(
+        path.join(src, childItemName),
+        path.join(dest, childItemName)
+      );
+    });
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function mergeSettings(existingPath, templatePath) {
+  let existing = {};
+  if (fs.existsSync(existingPath)) {
+    existing = JSON.parse(fs.readFileSync(existingPath, 'utf8'));
+  }
+
+  const template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+
+  // Merge permissions
+  if (!existing.permissions) {
+    existing.permissions = { allow: [] };
+  }
+  if (!existing.permissions.allow) {
+    existing.permissions.allow = [];
+  }
+
+  // Add planning-system permissions if not already present
+  template.permissions.allow.forEach(permission => {
+    if (!existing.permissions.allow.includes(permission)) {
+      existing.permissions.allow.push(permission);
+    }
+  });
+
+  return existing;
+}
+
+async function main() {
+  console.log('🚀 Agent Planner Claude Code Setup\n');
+  console.log('This will install the autonomous execution orchestration system.\n');
+
+  // Ask for target directory
+  const defaultTarget = process.cwd();
+  const target = await question(`Installation directory [${defaultTarget}]: `) || defaultTarget;
+
+  const claudeDir = path.join(target, '.claude');
+  const commandsDir = path.join(claudeDir, 'commands');
+  const settingsPath = path.join(claudeDir, 'settings.local.json');
+
+  // Show what will be installed
+  console.log('\n📦 Will install:');
+  console.log('  - Slash commands: /create-plan, /execute-plan, /plan-status');
+  console.log('  - Documentation: AUTONOMOUS_EXECUTION_GUIDE.md');
+  console.log('  - Settings: permissions for MCP planning-system tools\n');
+
+  const confirm = await question('Proceed with installation? (y/n): ');
+  if (confirm.toLowerCase() !== 'y') {
+    console.log('Installation cancelled.');
+    rl.close();
+    return;
+  }
+
+  try {
+    // Create .claude directory structure
+    console.log('\n📁 Creating directory structure...');
+    if (!fs.existsSync(claudeDir)) {
+      fs.mkdirSync(claudeDir, { recursive: true });
+    }
+    if (!fs.existsSync(commandsDir)) {
+      fs.mkdirSync(commandsDir, { recursive: true });
+    }
+
+    // Copy commands
+    console.log('📝 Installing slash commands...');
+    const sourceCommandsDir = path.join(__dirname, '..', 'claude-code', 'commands');
+    copyRecursive(sourceCommandsDir, commandsDir);
+
+    // Copy guide
+    console.log('📚 Installing documentation...');
+    const sourceGuide = path.join(__dirname, '..', 'claude-code', 'AUTONOMOUS_EXECUTION_GUIDE.md');
+    const destGuide = path.join(claudeDir, 'AUTONOMOUS_EXECUTION_GUIDE.md');
+    fs.copyFileSync(sourceGuide, destGuide);
+
+    // Merge settings
+    console.log('⚙️  Configuring permissions...');
+    const templatePath = path.join(__dirname, '..', 'claude-code', 'settings.template.json');
+    const mergedSettings = mergeSettings(settingsPath, templatePath);
+    fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2));
+
+    console.log('\n✅ Installation complete!\n');
+    console.log('📖 Next steps:');
+    console.log('  1. Ensure agent-planner-mcp is configured in your Claude Code MCP settings');
+    console.log('  2. Read the guide: .claude/AUTONOMOUS_EXECUTION_GUIDE.md');
+    console.log('  3. Create your first plan: /create-plan');
+    console.log('  4. Execute autonomously: /execute-plan <plan-id>\n');
+    console.log('🎯 Available commands:');
+    console.log('  /create-plan   - Interactive plan builder');
+    console.log('  /execute-plan  - Autonomous execution orchestrator');
+    console.log('  /plan-status   - Progress monitoring\n');
+
+  } catch (error) {
+    console.error('\n❌ Installation failed:', error.message);
+    process.exit(1);
+  }
+
+  rl.close();
+}
+
+main();