@prmichaelsen/task-mcp 0.2.0

package/agent/milestones/milestone-1-{title}.template.md

@@ -0,0 +1,206 @@
+# Milestone {N}: {Descriptive Name}
+
+**Goal**: [One-line objective that clearly states what this milestone achieves]
+**Duration**: [Estimated time: e.g., "1-2 weeks", "3-5 days"]
+**Dependencies**: [List prerequisite milestones or external dependencies, or "None"]
+**Status**: Not Started | In Progress | Completed
+
+---
+
+## Overview
+
+[Provide a comprehensive description of what this milestone accomplishes and why it's important to the project. Explain how it fits into the overall project roadmap.]
+
+**Example**: "This milestone establishes the foundational infrastructure for the project, including build system, database connections, and basic server setup. It creates the scaffolding that all future features will build upon."
+
+---
+
+## Deliverables
+
+[List concrete, measurable outputs this milestone will produce. Be specific about what will exist when this milestone is complete.]
+
+### 1. [Deliverable Category 1]
+- Specific item 1
+- Specific item 2
+- Specific item 3
+
+### 2. [Deliverable Category 2]
+- Specific item 1
+- Specific item 2
+
+### 3. [Deliverable Category 3]
+- Specific item 1
+- Specific item 2
+
+**Example**:
+
+### 1. Project Structure
+- New `project-name/` directory with organized subdirectories
+- package.json with all metadata and scripts
+- TypeScript configuration (tsconfig.json)
+- Build system using esbuild
+- Directory structure: src/, tests/, agent/
+
+### 2. Core Dependencies
+- @modelcontextprotocol/sdk installed and configured
+- Database client libraries installed
+- Development tools (TypeScript, testing framework)
+
+---
+
+## Success Criteria
+
+[Define objective, verifiable criteria that indicate this milestone is complete. Each criterion should be testable.]
+
+- [ ] Criterion 1: [Specific, measurable condition]
+- [ ] Criterion 2: [Specific, measurable condition]
+- [ ] Criterion 3: [Specific, measurable condition]
+- [ ] Criterion 4: [Specific, measurable condition]
+- [ ] Criterion 5: [Specific, measurable condition]
+
+**Example**:
+- [ ] Project builds successfully (`npm run build` completes without errors)
+- [ ] TypeScript compiles without errors (`npm run typecheck` passes)
+- [ ] All dependencies install correctly (`npm install` succeeds)
+- [ ] Basic server starts and responds to health check
+- [ ] All tests pass (`npm test` succeeds)
+
+---
+
+## Key Files to Create
+
+[List the specific files and directories that will be created during this milestone. Use a tree structure for clarity.]
+
+```
+project-root/
+├── file1.ext
+├── file2.ext
+├── directory1/
+│   ├── file3.ext
+│   └── file4.ext
+└── directory2/
+    ├── subdirectory/
+    │   └── file5.ext
+    └── file6.ext
+```
+
+**Example**:
+```
+my-project/
+├── package.json
+├── tsconfig.json
+├── esbuild.build.js
+├── .gitignore
+├── .env.example
+├── README.md
+├── src/
+│   ├── index.ts
+│   ├── server.ts
+│   ├── types/
+│   │   └── index.ts
+│   └── utils/
+│       └── logger.ts
+└── tests/
+    └── setup.test.ts
+```
+
+---
+
+## Tasks
+
+[List the tasks that comprise this milestone. Reference task documents if they exist.]
+
+1. [Task 1: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+2. [Task 2: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+3. [Task 3: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+4. [Task 4: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+
+**Example**:
+1. [Task 1: Initialize Project Structure](../tasks/task-1-initialize-project-structure.md) - Set up directories and config files
+2. [Task 2: Install Dependencies](../tasks/task-2-install-dependencies.md) - Install and configure npm packages
+3. [Task 3: Create Basic Server](../tasks/task-3-create-basic-server.md) - Implement minimal MCP server
+
+---
+
+## Environment Variables
+
+[If this milestone requires environment configuration, document it here:]
+
+```env
+# Category 1
+VAR_NAME_1=example_value
+VAR_NAME_2=example_value
+
+# Category 2
+VAR_NAME_3=example_value
+VAR_NAME_4=example_value
+```
+
+**Example**:
+```env
+# Database Configuration
+DATABASE_URL=postgresql://localhost:5432/mydb
+DATABASE_POOL_SIZE=10
+
+# API Configuration
+API_KEY=your_api_key_here
+API_URL=https://api.example.com
+
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+```
+
+---
+
+## Testing Requirements
+
+[Describe what testing should be in place by the end of this milestone:]
+
+- [ ] Test category 1: [Description]
+- [ ] Test category 2: [Description]
+- [ ] Test category 3: [Description]
+
+**Example**:
+- [ ] Unit tests for core utilities
+- [ ] Integration test for database connection
+- [ ] Server initialization test
+- [ ] Environment variable loading test
+
+---
+
+## Documentation Requirements
+
+[List documentation that should be created or updated:]
+
+- [ ] Document 1: [Description]
+- [ ] Document 2: [Description]
+- [ ] Document 3: [Description]
+
+**Example**:
+- [ ] README.md with project overview and quick start
+- [ ] API documentation for core interfaces
+- [ ] Development setup guide
+
+---
+
+## Risks and Mitigation
+
+[Identify potential risks and how to address them:]
+
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| [Risk 1] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+| [Risk 2] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+
+**Example**:
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| Database connection issues | High | Medium | Provide clear error messages and connection testing utilities |
+| Dependency conflicts | Medium | Low | Pin dependency versions and test thoroughly |
+
+---
+
+**Next Milestone**: [Link to next milestone: milestone-{N+1}-{name}.md]
+**Blockers**: [List any current blockers, or "None"]
+**Notes**: [Any additional context or considerations]

package/agent/milestones/milestone-2-task-infrastructure.md

@@ -0,0 +1,232 @@
+# Milestone 2: MCP Server Foundation
+
+**Goal**: Create task-mcp server with core task management tools
+**Duration**: 2 weeks
+**Dependencies**: None (can start immediately)
+**Status**: Not Started
+
+---
+
+## Overview
+
+This milestone creates the `task-mcp` MCP server project following the [MCP Server Bootstrap Pattern](https://github.com/prmichaelsen/remember-mcp/blob/main/agent/patterns/bootstrap.md). The server exposes task management tools via MCP protocol and uses Firebase Admin SDK for direct Firestore access.
+
+## Deliverables
+
+1. **task-mcp Project Structure**
+   - Initialize Node.js project with TypeScript
+   - Set up esbuild for bundling
+   - Configure tsconfig.json for ESM
+   - Set up testing infrastructure (Jest)
+   - Create directory structure per bootstrap pattern
+
+2. **Firebase Admin SDK Client**
+   - Wrapper class for Firestore operations
+   - Service account authentication
+   - User-scoped data access
+   - Connection management
+   - Error handling
+
+3. **Firebase Client Wrapper & Core MCP Tools** (Task 88)
+   - Firebase Admin SDK client wrapper
+   - 8 core MCP tools that return instructions:
+     * `task_get_status` - Get current status
+     * `task_get_next_step` - Get next instructions
+     * `task_update_progress` - Update progress
+     * `task_complete_task_item` - Mark task complete
+     * `task_create_milestone` - Create milestone
+     * `task_create_task_item` - Create task item
+     * `task_report_completion` - Report completion
+     * `task_add_message` - Add message to thread
+
+4. **MCP Server Implementation** (Task 89)
+   - Server class with stdio transport
+   - Server factory for multi-tenant
+   - Tool registration
+   - Request handling
+   - Error handling
+
+5. **Build Configuration** (Task 90)
+   - esbuild for bundling
+   - Watch mode for development
+   - TypeScript declaration generation
+   - Source maps
+
+6. **Deployment Configuration** (Task 91)
+   - Dockerfile for Cloud Run
+   - Cloud Run deployment config
+   - Service account setup
+   - Environment variables
+   - Deployment scripts
+
+7. **Testing** (Integrated across all tasks)
+   - Unit tests for each component
+   - E2E tests with Firestore emulator
+   - Integration tests for MCP protocol
+   - Test coverage > 80%
+
+## Success Criteria
+
+- [x] task-mcp project initialized with TypeScript
+- [x] Schemas and database service implemented
+- [ ] Firebase client wrapper created
+- [ ] All 8 core MCP tools implemented
+- [ ] MCP server starts with stdio transport
+- [ ] Tools can be called via MCP protocol
+- [ ] Firebase operations work correctly
+- [ ] User isolation enforced
+- [x] Unit tests pass (14/14 for database service)
+- [ ] E2E tests pass
+- [ ] Build configuration complete
+- [ ] Can deploy to Cloud Run
+- [ ] Service account configuration documented
+
+## Key Files to Create
+
+```
+task-mcp/
+├── src/
+│   ├── index.ts                      # CLI entry (stdio)
+│   ├── server.ts                     # Standalone server
+│   ├── server.ts.spec.ts             # Server tests
+│   ├── server-factory.ts             # Multi-tenant factory
+│   ├── server-factory.spec.ts        # Factory tests
+│   ├── client.ts                     # Firebase client
+│   ├── client.spec.ts                # Client tests
+│   ├── types.ts                      # Shared types
+│   │
+│   ├── tools/
+│   │   ├── index.ts
+│   │   ├── task-get-status.ts
+│   │   ├── task-get-status.spec.ts
+│   │   ├── task-update-progress.ts
+│   │   ├── task-update-progress.spec.ts
+│   │   ├── task-pause.ts
+│   │   ├── task-pause.spec.ts
+│   │   ├── task-resume.ts
+│   │   ├── task-resume.spec.ts
+│   │   ├── task-create-milestone.ts
+│   │   ├── task-create-milestone.spec.ts
+│   │   ├── task-create-task.ts
+│   │   ├── task-create-task.spec.ts
+│   │   ├── task-complete-task.ts
+│   │   ├── task-complete-task.spec.ts
+│   │   ├── task-complete-milestone.ts
+│   │   └── task-complete-milestone.spec.ts
+│   │
+│   └── utils/
+│       ├── logger.ts
+│       ├── logger.spec.ts
+│       ├── error-serializer.ts
+│       └── error-serializer.spec.ts
+│
+├── agent/                            # ACP docs
+│   ├── design/
+│   ├── milestones/
+│   ├── tasks/
+│   └── progress.yaml
+│
+├── package.json
+├── tsconfig.json
+├── esbuild.build.js
+├── esbuild.watch.js
+├── jest.config.js
+├── Dockerfile
+├── .env.example
+├── .gitignore
+└── README.md
+```
+
+## Tool Implementation Pattern
+
+Each tool follows the bootstrap pattern:
+
+```typescript
+// src/tools/task-get-status.ts
+import { FirebaseClient } from '../client.js'
+
+export const taskGetStatusTool = {
+  name: 'task_get_status',
+  description: 'Get current task status and progress',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      task_id: {
+        type: 'string',
+        description: 'Task ID to get status for'
+      }
+    },
+    required: ['task_id']
+  }
+}
+
+export async function handleTaskGetStatus(
+  client: FirebaseClient,
+  args: { task_id: string }
+): Promise<string> {
+  try {
+    const task = await client.getTask(args.task_id)
+    if (!task) {
+      throw new Error(`Task not found: ${args.task_id}`)
+    }
+    
+    return JSON.stringify({
+      task_title: task.title,
+      status: task.status,
+      current_milestone: task.progress.current_milestone,
+      overall_progress: task.progress.overall_percentage
+    }, null, 2)
+  } catch (error) {
+    throw new Error(`Failed to get status: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+```
+
+## Technical Decisions
+
+1. **Project Structure**: Follow MCP Bootstrap Pattern exactly
+2. **Transport**: Start with stdio, add SSE in Phase 2
+3. **Authentication**: Server factory with user_id parameter
+4. **Database**: Firebase Admin SDK with service account
+5. **Deployment**: Cloud Run for scalability
+
+## Risks and Mitigation
+
+**Risk**: Firebase Admin SDK complexity
+- **Mitigation**: Create wrapper client class, comprehensive tests
+
+**Risk**: MCP protocol learning curve
+- **Mitigation**: Follow bootstrap pattern, reference remember-mcp
+
+**Risk**: Service account security
+- **Mitigation**: Minimal permissions, audit logging, secret management
+
+## Dependencies
+
+- Firebase project with Firestore
+- Service account key
+- Node.js 18+
+- Google Cloud account (for Cloud Run)
+
+## Next Milestone
+
+[Milestone 3: agentbase.me Integration](milestone-3-agentbase-integration.md)
+
+---
+
+**Status**: In Progress (33% complete, 2/6 tasks done)
+**Estimated Effort**: 52 hours total (20 hours completed)
+**Priority**: High
+**Owner**: Development Team
+**Last Updated**: 2026-02-16
+
+## Task List
+
+- [x] Task 86: Task Data Model and Schemas (8 hours) - Completed
+- [x] Task 87: Task Database Service (12 hours) - Completed
+- [ ] Task 88: Firebase Client Wrapper & MCP Tools Foundation (16 hours)
+- [ ] Task 89: MCP Server Implementation (8 hours)
+- [ ] Task 90: Build Configuration (4 hours)
+- [ ] Task 91: Deployment Configuration (4 hours)
+
+**Total**: 52 hours estimated, 20 hours completed

package/agent/milestones/milestone-4-autonomous-execution.md

@@ -0,0 +1,235 @@
+# Milestone 4: ACP Workflow Tools
+
+**Goal**: Implement advanced ACP workflow tools in task-mcp server
+**Duration**: 2 weeks
+**Dependencies**: Milestone 3 (agentbase.me Integration)
+**Status**: Not Started
+
+---
+
+## Overview
+
+This milestone adds 5 advanced ACP workflow tools to the task-mcp server. These tools enable agents to initialize task context, get detailed status, synchronize documentation, generate reports, and validate task structure.
+
+## Deliverables
+
+1. **task_init Tool**
+   - Load all task documentation from Firestore
+   - Review completed work
+   - Identify current position
+   - Prepare for execution
+   - Return initialization summary
+
+2. **task_get_detailed_status Tool**
+   - Comprehensive status check
+   - Include all milestones and tasks
+   - Recent work history
+   - Next steps identification
+   - Blocker detection
+
+3. **task_sync Tool**
+   - Compare documented state with actual state
+   - Identify documentation drift
+   - Update documentation to match reality
+   - Log all changes
+   - Return sync report
+
+4. **task_generate_report Tool**
+   - Generate markdown or JSON report
+   - Include progress charts
+   - List accomplishments
+   - Identify next steps
+   - Suitable for sharing
+
+5. **task_validate Tool**
+   - Validate task schema
+   - Check milestone/task references
+   - Verify progress calculations
+   - Identify missing fields
+   - Suggest improvements
+
+6. **Tool Testing**
+   - Unit tests for each workflow tool
+   - E2E tests with real scenarios
+   - Integration tests with agent
+   - Performance tests
+
+7. **Documentation**
+   - Tool usage examples
+   - Best practices guide
+   - Troubleshooting guide
+   - API reference
+
+## Success Criteria
+
+- [ ] All 5 workflow tools implemented
+- [ ] Tools follow bootstrap pattern
+- [ ] Agent can use workflow tools
+- [ ] task_init prepares context correctly
+- [ ] task_sync detects drift accurately
+- [ ] task_generate_report creates valid reports
+- [ ] task_validate catches errors
+- [ ] Unit tests pass (>80% coverage)
+- [ ] E2E tests pass
+- [ ] Documentation complete
+
+## Key Files to Create
+
+```
+task-mcp/
+
+src/tools/
+├── task-init.ts
+├── task-get-detailed-status.ts
+├── task-sync.ts
+├── task-generate-report.ts
+└── task-validate.ts
+
+src/tools/__tests__/
+├── task-init.spec.ts
+├── task-init.e2e.ts
+├── task-get-detailed-status.spec.ts
+├── task-sync.spec.ts
+├── task-generate-report.spec.ts
+└── task-validate.spec.ts
+
+src/utils/
+├── report-generator.ts          # Report formatting
+├── validation-rules.ts           # Validation logic
+└── drift-detector.ts             # Drift detection
+
+docs/
+├── workflow-tools.md             # Tool documentation
+├── examples.md                   # Usage examples
+└── troubleshooting.md            # Common issues
+```
+
+## Tool Implementation Examples
+
+### task_init Tool
+
+```typescript
+// src/tools/task-init.ts
+export const taskInitTool = {
+  name: 'task_init',
+  description: 'Initialize task context by loading all documentation and reviewing state',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      task_id: {
+        type: 'string',
+        description: 'Task ID to initialize'
+      }
+    },
+    required: ['task_id']
+  }
+}
+
+export async function handleTaskInit(
+  client: FirebaseClient,
+  args: { task_id: string }
+): Promise<string> {
+  const task = await client.getTask(args.task_id)
+  if (!task) throw new Error('Task not found')
+  
+  // Load all milestones and tasks
+  const milestones = task.progress.milestones
+  const tasks = task.progress.tasks
+  
+  // Identify current position
+  const currentMilestone = milestones.find(m => m.id === task.progress.current_milestone)
+  const currentTask = tasks[task.progress.current_milestone]?.find(
+    t => t.id === task.progress.current_task
+  )
+  
+  // Prepare next steps
+  const nextSteps = determineNextSteps(task, currentMilestone, currentTask)
+  
+  return JSON.stringify({
+    status: 'initialized',
+    milestones_loaded: milestones.length,
+    tasks_loaded: Object.values(tasks).flat().length,
+    current_milestone: currentMilestone?.name,
+    current_task: currentTask?.name,
+    next_steps: nextSteps
+  }, null, 2)
+}
+```
+
+### task_generate_report Tool
+
+```typescript
+// src/tools/task-generate-report.ts
+export const taskGenerateReportTool = {
+  name: 'task_generate_report',
+  description: 'Generate comprehensive status report in markdown or JSON format',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string' },
+      format: { 
+        type: 'string', 
+        enum: ['markdown', 'json'],
+        default: 'markdown'
+      },
+      include_details: { 
+        type: 'boolean',
+        default: true
+      }
+    },
+    required: ['task_id']
+  }
+}
+
+export async function handleTaskGenerateReport(
+  client: FirebaseClient,
+  args: { task_id: string; format?: string; include_details?: boolean }
+): Promise<string> {
+  const task = await client.getTask(args.task_id)
+  if (!task) throw new Error('Task not found')
+  
+  const format = args.format || 'markdown'
+  const includeDetails = args.include_details ?? true
+  
+  if (format === 'markdown') {
+    return generateMarkdownReport(task, includeDetails)
+  } else {
+    return JSON.stringify(generateJSONReport(task, includeDetails), null, 2)
+  }
+}
+```
+
+## Technical Decisions
+
+1. **Report Format**: Support both markdown and JSON
+2. **Drift Detection**: Compare Firestore state with expected state
+3. **Validation Rules**: Extensible rule system
+4. **Performance**: Cache frequently accessed data
+
+## Risks and Mitigation
+
+**Risk**: Complex validation logic
+- **Mitigation**: Start with simple rules, add complexity incrementally
+
+**Risk**: Report generation performance
+- **Mitigation**: Lazy loading, pagination for large tasks
+
+**Risk**: Drift detection accuracy
+- **Mitigation**: Comprehensive test cases, manual verification
+
+## Dependencies
+
+- Milestone 3 (agentbase.me Integration)
+- Core task tools working
+- Agent can call MCP tools
+
+## Next Milestone
+
+[Milestone 5: Autonomous Execution & UI Polish](milestone-5-autonomous-execution-ui.md)
+
+---
+
+**Status**: Not Started
+**Estimated Effort**: 80 hours
+**Priority**: Medium
+**Owner**: Development Team