@prmichaelsen/acp-mcp 0.1.0

package/agent/patterns/pattern.template.md

@@ -0,0 +1,364 @@
+# {Pattern Name}
+
+**Category**: [Architecture | Design | Code | Testing | Deployment]
+**Applicable To**: [What types of projects or components this pattern applies to]
+**Status**: [Stable | Experimental | Deprecated]
+
+---
+
+## Overview
+
+[Provide a high-level description of what this pattern is and when to use it. Include the problem space it addresses and the general approach it takes.]
+
+**Example**: "The Service Layer Pattern provides a clear separation between business logic and data access, enabling better testability, maintainability, and code reuse across different interfaces (API, CLI, etc.)."
+
+---
+
+## When to Use This Pattern
+
+[Describe the scenarios where this pattern is appropriate:]
+
+✅ **Use this pattern when:**
+- Condition 1
+- Condition 2
+- Condition 3
+
+❌ **Don't use this pattern when:**
+- Condition 1
+- Condition 2
+- Condition 3
+
+**Example**:
+
+✅ **Use this pattern when:**
+- You have complex business logic that needs to be shared across multiple interfaces
+- You want to isolate business logic from infrastructure concerns
+- You need to test business logic independently of data access
+
+❌ **Don't use this pattern when:**
+- Your application is very simple with minimal business logic
+- You're building a thin wrapper around a database
+- The overhead of additional layers outweighs the benefits
+
+---
+
+## Core Principles
+
+[List the fundamental concepts that underpin this pattern:]
+
+1. **Principle 1**: [Description]
+2. **Principle 2**: [Description]
+3. **Principle 3**: [Description]
+4. **Principle 4**: [Description]
+
+**Example**:
+
+1. **Separation of Concerns**: Business logic is isolated from data access and presentation
+2. **Single Responsibility**: Each service handles one domain concept
+3. **Dependency Injection**: Services receive their dependencies rather than creating them
+4. **Interface-Based Design**: Services depend on abstractions, not concrete implementations
+
+---
+
+## Implementation
+
+[Provide detailed implementation guidance with code examples:]
+
+### Structure
+
+[Describe the overall structure of the pattern]
+
+```
+directory-structure/
+├── component1/
+│   └── file1.ext
+└── component2/
+    └── file2.ext
+```
+
+### Code Example
+
+[Provide a complete, working example:]
+
+```typescript
+// Example implementation
+interface ExampleInterface {
+  method(): Promise<Result>;
+}
+
+class ExampleImplementation implements ExampleInterface {
+  constructor(private dependency: Dependency) {}
+  
+  async method(): Promise<Result> {
+    // Implementation
+    return result;
+  }
+}
+```
+
+### Key Components
+
+[Break down the major components:]
+
+#### Component 1: [Name]
+[Description and purpose]
+
+```typescript
+// Code example for this component
+```
+
+#### Component 2: [Name]
+[Description and purpose]
+
+```typescript
+// Code example for this component
+```
+
+---
+
+## Examples
+
+[Provide multiple real-world examples showing different use cases:]
+
+### Example 1: [Use Case Name]
+
+[Description of the scenario]
+
+```typescript
+// Complete code example
+class ConcreteExample {
+  // Implementation
+}
+
+// Usage
+const example = new ConcreteExample();
+const result = await example.doSomething();
+```
+
+### Example 2: [Use Case Name]
+
+[Description of the scenario]
+
+```typescript
+// Complete code example
+```
+
+---
+
+## Benefits
+
+[List the advantages of using this pattern:]
+
+### 1. [Benefit Name]
+[Detailed explanation of this benefit and why it matters]
+
+### 2. [Benefit Name]
+[Detailed explanation of this benefit and why it matters]
+
+### 3. [Benefit Name]
+[Detailed explanation of this benefit and why it matters]
+
+**Example**:
+
+### 1. Testability
+Business logic can be tested in isolation without requiring database connections or external services. Mock dependencies can be easily injected for unit testing.
+
+### 2. Reusability
+The same business logic can be used across multiple interfaces (REST API, GraphQL, CLI, etc.) without duplication.
+
+### 3. Maintainability
+Changes to business logic are centralized in service classes, making the codebase easier to understand and modify.
+
+---
+
+## Trade-offs
+
+[Honestly assess the downsides and limitations:]
+
+### 1. [Trade-off Name]
+**Downside**: [Description]
+**Mitigation**: [How to minimize this downside]
+
+### 2. [Trade-off Name]
+**Downside**: [Description]
+**Mitigation**: [How to minimize this downside]
+
+**Example**:
+
+### 1. Additional Complexity
+**Downside**: Adds extra layers and files to the codebase, which can feel like over-engineering for simple applications.
+**Mitigation**: Only apply this pattern when complexity justifies it. Start simple and refactor to this pattern as needs grow.
+
+### 2. Performance Overhead
+**Downside**: Additional function calls and abstractions can add minor performance overhead.
+**Mitigation**: In most applications, this overhead is negligible. Profile before optimizing.
+
+---
+
+## Anti-Patterns
+
+[Document what NOT to do - common mistakes and misuses:]
+
+### ❌ Anti-Pattern 1: [Name]
+
+**Description**: [What people do wrong]
+
+**Why it's bad**: [Consequences]
+
+**Instead, do this**: [Correct approach]
+
+```typescript
+// ❌ Bad example
+class BadExample {
+  // What not to do
+}
+
+// ✅ Good example
+class GoodExample {
+  // Correct approach
+}
+```
+
+### ❌ Anti-Pattern 2: [Name]
+
+[Similar structure as above]
+
+**Example**:
+
+### ❌ Anti-Pattern 1: God Service
+
+**Description**: Creating a single service class that handles all business logic for the entire application.
+
+**Why it's bad**: Violates single responsibility principle, becomes difficult to test and maintain, creates tight coupling.
+
+**Instead, do this**: Create focused services, each handling a specific domain concept.
+
+```typescript
+// ❌ Bad: Everything in one service
+class ApplicationService {
+  createUser() {}
+  deleteUser() {}
+  createProduct() {}
+  deleteProduct() {}
+  processPayment() {}
+  sendEmail() {}
+}
+
+// ✅ Good: Focused services
+class UserService {
+  createUser() {}
+  deleteUser() {}
+}
+
+class ProductService {
+  createProduct() {}
+  deleteProduct() {}
+}
+
+class PaymentService {
+  processPayment() {}
+}
+```
+
+---
+
+## Testing Strategy
+
+[Describe how to test code that uses this pattern:]
+
+### Unit Testing
+[Approach for unit tests]
+
+```typescript
+// Example unit test
+describe('ExampleService', () => {
+  it('should do something', async () => {
+    // Test implementation
+  });
+});
+```
+
+### Integration Testing
+[Approach for integration tests]
+
+```typescript
+// Example integration test
+```
+
+---
+
+## Related Patterns
+
+[Link to related patterns and explain relationships:]
+
+- **[Pattern Name](./pattern-name.md)**: [How it relates]
+- **[Pattern Name](./pattern-name.md)**: [How it relates]
+- **[Pattern Name](./pattern-name.md)**: [How it relates]
+
+**Example**:
+- **[Repository Pattern](./repository-pattern.md)**: Often used together; services use repositories for data access
+- **[Factory Pattern](./factory-pattern.md)**: Can be used to create service instances with proper dependencies
+- **[Dependency Injection](./dependency-injection.md)**: Essential for implementing this pattern correctly
+
+---
+
+## Migration Guide
+
+[If adopting this pattern in an existing codebase, provide migration steps:]
+
+### Step 1: [Action]
+[Detailed description]
+
+### Step 2: [Action]
+[Detailed description]
+
+### Step 3: [Action]
+[Detailed description]
+
+**Example**:
+
+### Step 1: Identify Business Logic
+Review existing code and identify business logic that's currently mixed with data access or presentation code.
+
+### Step 2: Extract to Services
+Create service classes and move business logic into them. Start with the most complex or frequently used logic.
+
+### Step 3: Refactor Dependencies
+Update calling code to use the new services. Inject dependencies rather than creating them directly.
+
+---
+
+## References
+
+[Link to external resources, papers, books, or articles:]
+
+- [Resource 1](URL): Description
+- [Resource 2](URL): Description
+- [Resource 3](URL): Description
+
+**Example**:
+- [Martin Fowler - Service Layer](https://martinfowler.com/eaaCatalog/serviceLayer.html): Original pattern description
+- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html): Related architectural concepts
+- [Domain-Driven Design](https://www.domainlanguage.com/ddd/): Context for service design
+
+---
+
+## Checklist for Implementation
+
+[Provide a checklist to ensure proper implementation:]
+
+- [ ] Services are focused on single domain concepts
+- [ ] Dependencies are injected, not created internally
+- [ ] Business logic is isolated from infrastructure concerns
+- [ ] Services have clear, well-documented interfaces
+- [ ] Unit tests cover business logic in isolation
+- [ ] Integration tests verify end-to-end functionality
+- [ ] Error handling is consistent and appropriate
+- [ ] Logging provides adequate visibility
+
+---
+
+**Status**: [Current status of this pattern document]
+**Recommendation**: [When and how to use this pattern]
+**Last Updated**: [YYYY-MM-DD]
+**Contributors**: [Names or "Community"]

package/agent/progress.template.yaml

@@ -0,0 +1,161 @@
+# Project Progress Tracking
+# This file tracks the overall progress of the project, including milestones, tasks, and recent work.
+# Update this file regularly as work progresses.
+
+project:
+  name: project-name                    # Replace with your project name
+  version: 0.1.0                        # Current version (semantic versioning)
+  started: YYYY-MM-DD                   # Date project started
+  status: not_started                   # not_started | in_progress | completed
+  current_milestone: M1                 # Current milestone identifier
+  description: |                        # Brief project description
+    A short description of what this project does and its main purpose.
+
+# Milestones represent major phases of the project
+milestones:
+  - id: M1                              # Unique milestone identifier
+    name: Milestone Name                # Descriptive name
+    status: not_started                 # not_started | in_progress | completed
+    progress: 0                         # Percentage complete (0-100)
+    started: null                       # YYYY-MM-DD when started, null if not started
+    completed: null                     # YYYY-MM-DD when completed, null if not completed
+    estimated_weeks: 2                  # Estimated duration in weeks
+    tasks_completed: 0                  # Number of tasks completed
+    tasks_total: 5                      # Total number of tasks in this milestone
+    notes: |                            # Progress notes and observations
+      Notes about this milestone's progress, blockers, or important decisions.
+  
+  - id: M2
+    name: Second Milestone Name
+    status: not_started
+    progress: 0
+    started: null
+    completed: null
+    estimated_weeks: 3
+    tasks_completed: 0
+    tasks_total: 7
+    notes: |
+      This milestone depends on M1 completion.
+
+# Tasks are granular work items within milestones
+tasks:
+  milestone_1:                          # Group tasks by milestone
+    - id: task-1                        # Unique task identifier
+      name: Task Name                   # Descriptive task name
+      status: not_started               # not_started | in_progress | completed
+      file: agent/tasks/task-1-name.md  # Path to task document
+      estimated_hours: 4                # Estimated time in hours
+      actual_hours: null                # Actual time spent (null until completed)
+      completed_date: null              # YYYY-MM-DD when completed, null if not completed
+      notes: |                          # Task-specific notes
+        Any important notes about this task.
+    
+    - id: task-2
+      name: Second Task Name
+      status: not_started
+      file: agent/tasks/task-2-name.md
+      estimated_hours: 2
+      actual_hours: null
+      completed_date: null
+      notes: |
+        Depends on task-1 completion.
+  
+  milestone_2:
+    - id: task-3
+      name: Third Task Name
+      status: not_started
+      file: agent/tasks/task-3-name.md
+      estimated_hours: 6
+      actual_hours: null
+      completed_date: null
+      notes: |
+        First task of second milestone.
+
+# Documentation tracking
+documentation:
+  design_documents: 0                   # Number of design documents created
+  milestone_documents: 0                # Number of milestone documents
+  pattern_documents: 0                  # Number of pattern documents
+  task_documents: 0                     # Number of task documents
+  last_updated: YYYY-MM-DD              # Last documentation update date
+
+# Overall progress metrics
+progress:
+  planning: 0                           # Planning phase completion (0-100%)
+  implementation: 0                     # Implementation phase completion (0-100%)
+  testing: 0                            # Testing phase completion (0-100%)
+  documentation: 0                      # Documentation completion (0-100%)
+  overall: 0                            # Overall project completion (0-100%)
+
+# Recent work log (most recent first)
+recent_work:
+  - date: YYYY-MM-DD                    # Date of work
+    description: |                      # Description of what was done
+      Brief description of work completed on this date.
+    items:                              # Specific items completed
+      - ✅ Completed item 1
+      - ✅ Completed item 2
+      - ⚠️  Warning or note about something
+      - 📋 Pending item or follow-up needed
+  
+  - date: YYYY-MM-DD
+    description: |
+      Earlier work session description.
+    items:
+      - ✅ Another completed item
+      - 📋 Something to revisit
+
+# Next steps (prioritized list)
+next_steps:
+  - Next action item 1 (highest priority)
+  - Next action item 2
+  - Next action item 3
+  - Future consideration or enhancement
+
+# General notes and observations
+notes:
+  - Important note 1 about the project
+  - Important note 2 about architectural decisions
+  - Important note 3 about dependencies or constraints
+
+# Current blockers (remove when resolved)
+current_blockers:
+  - Blocker 1: Description of what's blocking progress
+  - Blocker 2: Another blocker and potential resolution
+
+# Team and contributors (if applicable)
+team:
+  - role: Lead Developer              # Role or responsibility
+    name: Name or "Agent"             # Name or identifier
+    focus: |                          # Current focus area
+      What this person/agent is currently working on
+  
+  - role: Documentation
+    name: Name or "Agent"
+    focus: |
+      Maintaining documentation and patterns
+
+# Dependencies and integrations
+dependencies:
+  external_services:                  # External services this project depends on
+    - name: Service Name
+      status: configured | pending | blocked
+      notes: |
+        Notes about this dependency
+  
+  libraries:                          # Key library dependencies
+    - name: Library Name
+      version: 1.0.0
+      purpose: |
+        Why this library is used
+  
+  infrastructure:                     # Infrastructure requirements
+    - name: Infrastructure Component
+      status: ready | pending | blocked
+      notes: |
+        Notes about this infrastructure
+
+# Quality metrics (optional)
+quality:
+  test_coverage: 0                    # Percentage (0-100)
+  code_review_status: pending         # pending | in

package/agent/progress.yaml

@@ -0,0 +1,33 @@
+project:
+  name: acp-mcp
+  version: 0.1.0
+  started: 2026-02-22
+  status: in_progress
+  description: |
+    Support remote machine development using ACP methodology
+
+milestones: []
+
+tasks: {}
+
+documentation:
+  design_documents: 0
+  milestone_documents: 0
+  pattern_documents: 0
+  task_documents: 0
+
+progress:
+  planning: 0
+  implementation: 0
+  overall: 0
+
+recent_work: []
+
+next_steps:
+  - Define project requirements in agent/design/requirements.md
+  - Plan milestones and tasks with @acp.plan
+  - Start development with @acp.proceed
+
+notes: []
+
+current_blockers: []

package/agent/schemas/package.schema.yaml

@@ -0,0 +1,161 @@
+# Package YAML Schema
+# Schema for validating ACP package.yaml files
+# Version: 1.0.0
+
+schema_version: 1.0.0
+description: Schema for ACP package.yaml files
+
+# Required fields that must be present
+required_fields:
+  - name
+  - version
+  - description
+  - author
+  - license
+  - repository
+
+# Field definitions with validation rules
+fields:
+  name:
+    type: string
+    pattern: "^[a-z0-9-]+$"
+    description: "Package name (lowercase, alphanumeric, hyphens only)"
+    error_message: "Package name must be lowercase letters, numbers, and hyphens only"
+    
+  version:
+    type: string
+    pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+    description: "Semantic version (X.Y.Z)"
+    error_message: "Version must be in semantic versioning format (e.g., 1.0.0)"
+    
+  description:
+    type: string
+    min_length: 10
+    max_length: 200
+    description: "One-line package description"
+    error_message: "Description must be between 10 and 200 characters"
+    
+  author:
+    type: string
+    min_length: 2
+    description: "Package author name"
+    error_message: "Author name must be at least 2 characters"
+    
+  license:
+    type: string
+    description: "License identifier (e.g., MIT, Apache-2.0)"
+    error_message: "License must be specified"
+    
+  repository:
+    type: string
+    pattern: "^https?://.*\\.git$"
+    description: "Git repository URL (must end with .git)"
+    error_message: "Repository must be a valid git URL ending with .git"
+    
+  homepage:
+    type: string
+    pattern: "^https?://.*"
+    required: false
+    description: "Package homepage URL"
+    error_message: "Homepage must be a valid HTTP/HTTPS URL"
+    
+  tags:
+    type: array
+    item_type: string
+    required: false
+    description: "Tags for package discovery"
+    
+  release:
+    type: object
+    required: false
+    description: "Release configuration"
+    fields:
+      branch:
+        type: string
+        description: "Release branch name (e.g., main, master, mainline)"
+      branches:
+        type: array
+        item_type: string
+        required: false
+        description: "Additional valid release branches"
+    
+  contents:
+    type: object
+    required: true
+    description: "Package contents (patterns, commands, designs)"
+    fields:
+      patterns:
+        type: array
+        item_type: object
+        required: false
+        description: "List of pattern files (each with 'name' field)"
+        item_fields:
+          name:
+            type: string
+            required: true
+            description: "Pattern filename (e.g., namespace.pattern-name.md)"
+      commands:
+        type: array
+        item_type: object
+        required: false
+        description: "List of command files (each with 'name' field)"
+        item_fields:
+          name:
+            type: string
+            required: true
+            description: "Command filename (e.g., namespace.command-name.md)"
+      designs:
+        type: array
+        item_type: object
+        required: false
+        description: "List of design files (each with 'name' field)"
+        item_fields:
+          name:
+            type: string
+            required: true
+            description: "Design filename (e.g., namespace.design-name.md)"
+      scripts:
+        type: array
+        item_type: object
+        required: false
+        description: "List of script files (each with 'name' field)"
+        item_fields:
+          name:
+            type: string
+            required: true
+            pattern: "^[a-z0-9-]+\\.[a-z0-9-]+\\.sh$"
+            description: "Script filename with namespace (e.g., namespace.script-name.sh)"
+    
+  requires:
+    type: object
+    required: false
+    description: "Compatibility requirements"
+    fields:
+      acp:
+        type: string
+        pattern: "^>=?[0-9]+\\.[0-9]+\\.[0-9]+$"
+        description: "Minimum ACP version (e.g., >=2.0.0)"
+      npm:
+        type: object
+        required: false
+        description: "Required npm packages"
+      pip:
+        type: object
+        required: false
+        description: "Required Python packages"
+      cargo:
+        type: object
+        required: false
+        description: "Required Rust packages"
+      go:
+        type: object
+        required: false
+        description: "Required Go packages"
+
+# Reserved package names that cannot be used
+reserved_names:
+  - acp
+  - local
+  - core
+  - system
+  - global