agent-planner-mcp 0.5.0 → 0.5.1

package/claude-code/AUTONOMOUS_EXECUTION_GUIDE.md

@@ -1,335 +0,0 @@
-# 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

@@ -1,112 +0,0 @@
-# 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

@@ -1,174 +0,0 @@
-# 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!