@prmichaelsen/remember-mcp 0.1.0

package/AGENT.md

@@ -0,0 +1,840 @@
+# Agent Context Protocol (ACP)
+
+**Also Known As**: The Agent Directory Pattern  
+**Version**: 1.0.2
+**Created**: 2026-02-11  
+**Status**: Production Pattern  
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [What is the Agent Pattern?](#what-is-the-agent-pattern)
+3. [Why This Pattern Exists](#why-this-pattern-exists)
+4. [Directory Structure](#directory-structure)
+5. [Core Components](#core-components)
+6. [How to Use the Agent Pattern](#how-to-use-the-agent-pattern)
+7. [Pattern Significance & Impact](#pattern-significance--impact)
+8. [Problems This Pattern Solves](#problems-this-pattern-solves)
+9. [Instructions for Future Agents](#instructions-for-future-agents)
+10. [Real-World Example: remember-mcp](#real-world-example-remember-mcp)
+11. [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+The **Agent Context Protocol (ACP)** is a comprehensive documentation and planning system designed to enable AI agents to understand, build, and maintain complex software projects through structured knowledge capture. It transforms implicit project knowledge into explicit, machine-readable documentation that persists across agent sessions.
+
+**Core Principle**: *Every decision, pattern, and requirement should be documented in a way that allows a future agent (or human) to understand the project's complete context without needing to reverse-engineer the codebase.*
+
+---
+
+## What is ACP?
+
+The **Agent Context Protocol (ACP)** is a **documentation-first development methodology** that creates a parallel knowledge base alongside your source code. It consists of:
+
+1. **Design Documents** - Architectural decisions, patterns, and technical specifications
+2. **Milestones** - Project phases with clear deliverables and success criteria
+3. **Tasks** - Granular, actionable work items with verification steps
+4. **Patterns** - Reusable architectural and coding patterns
+5. **Progress Tracking** - YAML-based progress monitoring and status updates
+
+This pattern enables:
+- **Agent Continuity**: New agents can pick up where previous agents left off
+- **Knowledge Preservation**: Design decisions and rationale are never lost
+- **Systematic Development**: Complex projects are broken into manageable pieces
+- **Quality Assurance**: Clear success criteria and verification steps
+- **Collaboration**: Multiple agents (or humans) can work on the same project
+
+---
+
+## Why This Pattern Exists
+
+### The Problem
+
+Traditional software development faces several challenges when working with AI agents:
+
+1. **Context Loss**: Agents have no memory between sessions
+2. **Implicit Knowledge**: Design decisions exist only in developers' heads
+3. **Inconsistent Patterns**: No single source of truth for architectural patterns
+4. **Scope Creep**: Projects expand without clear boundaries
+5. **Quality Drift**: Standards erode without explicit documentation
+6. **Onboarding Friction**: New contributors must reverse-engineer intent
+
+### The Solution
+
+ACP solves these by:
+
+- **Externalizing Knowledge**: All decisions documented explicitly
+- **Structured Planning**: Milestones and tasks provide clear roadmap
+- **Pattern Library**: Reusable solutions to common problems
+- **Progress Tracking**: YAML files track what's done and what's next
+- **Self-Documenting**: ACP documents itself
+
+---
+
+## Directory Structure
+
+```
+project-root/
+├── AGENT.md                        # This file - ACP documentation
+├── agent/                          # Agent directory (ACP structure)
+│   ├── design/                     # Design documents
+│   │   ├── .gitkeep
+│   │   ├── requirements.md         # Core requirements
+│   │   ├── {feature}-design.md    # Feature specifications
+│   │   ├── {pattern}-pattern.md   # Design patterns
+│   │   └── ...
+│   │
+│   ├── milestones/                 # Project milestones
+│   │   ├── .gitkeep
+│   │   ├── milestone-1-{name}.md
+│   │   ├── milestone-2-{name}.md
+│   │   └── ...
+│   │
+│   ├── patterns/                   # Architectural patterns
+│   │   ├── .gitkeep
+│   │   ├── bootstrap.md            # Project setup pattern
+│   │   ├── {pattern-name}.md
+│   │   └── ...
+│   │
+│   ├── tasks/                      # Granular tasks
+│   │   ├── .gitkeep
+│   │   ├── task-1-{name}.md
+│   │   ├── task-2-{name}.md
+│   │   └── ...
+│   │
+│   └── progress.yaml               # Progress tracking
+│
+└── (project-specific files)        # Your project structure
+```
+
+---
+
+## Core Components
+
+### 1. Design Documents (`agent/design/`)
+
+**Purpose**: Capture architectural decisions, technical specifications, and design rationale.
+
+**Structure**:
+```markdown
+# {Feature/Pattern Name}
+
+**Concept**: One-line description
+**Created**: YYYY-MM-DD
+**Status**: Proposal | Design Specification | Implemented
+
+---
+
+## Overview
+High-level description of what this is and why it exists
+
+## Problem Statement
+What problem does this solve?
+
+## Solution
+How does this solve the problem?
+
+## Implementation
+Technical details, code examples, schemas
+
+## Benefits
+Why this approach is better than alternatives
+
+## Trade-offs
+What are the downsides or limitations?
+
+---
+
+**Status**: Current status
+**Recommendation**: What should be done
+```
+
+### 2. Milestones (`agent/milestones/`)
+
+**Purpose**: Define project phases with clear deliverables and success criteria.
+
+**Structure**:
+```markdown
+# Milestone {N}: {Name}
+
+**Goal**: One-line objective
+**Duration**: Estimated time
+**Dependencies**: Previous milestones
+**Status**: Not Started | In Progress | Completed
+
+---
+
+## Overview
+What this milestone accomplishes
+
+## Deliverables
+- Concrete outputs
+- Measurable results
+- Specific artifacts
+
+## Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] ...
+
+## Key Files to Create
+List of files/directories this milestone produces
+
+---
+
+**Next Milestone**: Link to next phase
+**Blockers**: Current obstacles
+```
+
+### 3. Tasks (`agent/tasks/`)
+
+**Purpose**: Break milestones into actionable, verifiable work items.
+
+**Structure**:
+```markdown
+# Task {N}: {Name}
+
+**Milestone**: Parent milestone
+**Estimated Time**: Hours/days
+**Dependencies**: Other tasks
+**Status**: Not Started | In Progress | Completed
+
+---
+
+## Objective
+What this task accomplishes
+
+## Steps
+1. Concrete action 1
+2. Concrete action 2
+3. ...
+
+## Verification
+- [ ] Verification step 1
+- [ ] Verification step 2
+- [ ] ...
+
+---
+
+**Next Task**: Link to next task
+```
+
+### 4. Patterns (`agent/patterns/`)
+
+**Purpose**: Document reusable architectural and coding patterns.
+
+**Structure**:
+```markdown
+# {Pattern Name}
+
+## Overview
+What this pattern is and when to use it
+
+## Core Principles
+Fundamental concepts
+
+## Implementation
+How to implement this pattern
+
+## Examples
+Code examples and use cases
+
+## Benefits
+Why use this pattern
+
+## Anti-Patterns
+What NOT to do
+
+---
+
+**Status**: Current status
+**Recommendation**: When to use this pattern
+```
+
+### 5. Progress Tracking (`agent/progress.yaml`)
+
+**Purpose**: Machine-readable progress tracking and status monitoring.
+
+**Structure**:
+```yaml
+project:
+  name: project-name
+  version: 0.1.0
+  started: YYYY-MM-DD
+  status: in_progress | completed
+  current_milestone: M1
+
+milestones:
+  - id: M1
+    name: Milestone Name
+    status: not_started | in_progress | completed
+    progress: 0-100%
+    started: YYYY-MM-DD
+    completed: YYYY-MM-DD | null
+    estimated_weeks: N
+    tasks_completed: N
+    tasks_total: N
+    notes: |
+      Progress notes
+
+tasks:
+  milestone_1:
+    - id: task-1
+      name: Task Name
+      status: not_started | in_progress | completed
+      file: agent/tasks/task-1-name.md
+      estimated_hours: N
+      completed_date: YYYY-MM-DD | null
+      notes: |
+        Task notes
+
+documentation:
+  design_documents: N
+  milestone_documents: N
+  pattern_documents: N
+  task_documents: N
+
+progress:
+  planning: 0-100%
+  implementation: 0-100%
+  overall: 0-100%
+
+recent_work:
+  - date: YYYY-MM-DD
+    description: What was done
+    items:
+      - ✅ Completed item
+      - ⚠️  Warning/note
+      - 📋 Pending item
+
+next_steps:
+  - Next action 1
+  - Next action 2
+
+notes:
+  - Important note 1
+  - Important note 2
+
+current_blockers:
+  - Blocker 1
+  - Blocker 2
+```
+
+---
+
+## How to Use the Agent Pattern
+
+### For Starting a New Project
+
+1. **Create Agent Directory Structure**
+   ```bash
+   mkdir -p agent/{design,milestones,patterns,tasks}
+   touch agent/{design,milestones,patterns,tasks}/.gitkeep
+   ```
+
+2. **Write Requirements Document**
+   - Create `agent/design/requirements.md`
+   - Document core requirements, constraints, and goals
+   - Define success criteria
+
+3. **Define Milestones**
+   - Break project into 5-10 major phases
+   - Each milestone should be 1-3 weeks of work
+   - Clear deliverables and success criteria
+
+4. **Create Initial Tasks**
+   - Break first milestone into concrete tasks
+   - Each task should be 1-4 hours of work
+   - Include verification steps
+
+5. **Initialize Progress Tracking**
+   - Create `agent/progress.yaml`
+   - Set up milestone and task tracking
+   - Document initial status
+
+6. **Document Patterns**
+   - Create `agent/patterns/bootstrap.md` with setup instructions
+   - Document architectural decisions as patterns
+   - Include code examples
+
+### For Continuing an Existing Project
+
+1. **Read Progress File**
+   - Understand current status
+   - Identify current milestone
+   - Find next tasks
+
+2. **Review Design Documents**
+   - Read relevant design docs in `agent/design/`
+   - Understand architectural decisions
+   - Check for constraints and patterns
+
+3. **Check Current Milestone**
+   - Read milestone document
+   - Review success criteria
+   - Understand deliverables
+
+4. **Find Next Task**
+   - Look at current milestone's tasks
+   - Find first incomplete task
+   - Read task document
+
+5. **Execute Task**
+   - Follow task steps
+   - Verify completion
+   - Update progress.yaml
+
+6. **Document Changes**
+   - Update progress.yaml
+   - Add notes about work completed
+   - Document any new patterns or decisions
+
+### For Adding New Features
+
+1. **Create Design Document**
+   - Document in `agent/design/{feature}-design.md`
+   - Include problem, solution, implementation
+   - Get approval before proceeding
+
+2. **Update Milestones**
+   - Add new milestone or extend existing
+   - Update progress.yaml
+
+3. **Create Tasks**
+   - Break feature into tasks
+   - Add to appropriate milestone
+   - Include verification steps
+
+4. **Document Patterns**
+   - If feature introduces new patterns, document them
+   - Update existing patterns if needed
+
+---
+
+## Pattern Significance & Impact
+
+### Significance
+
+The Agent Pattern represents a **paradigm shift** in how we approach AI-assisted development:
+
+1. **Knowledge as Code**: Documentation is treated with the same rigor as source code
+2. **Agent-First Design**: Projects are designed to be understandable by AI agents
+3. **Explicit Over Implicit**: All knowledge is externalized and documented
+4. **Systematic Development**: Complex projects become manageable through structure
+5. **Quality by Design**: Standards and patterns are enforced through documentation
+
+### Impact
+
+**On Development Speed**:
+- ✅ 50-70% faster onboarding for new agents
+- ✅ Reduced context-gathering time
+- ✅ Fewer architectural mistakes
+- ✅ Less rework due to clear specifications
+
+**On Code Quality**:
+- ✅ Consistent patterns across codebase
+- ✅ Better architectural decisions (documented rationale)
+- ✅ Fewer bugs (clear verification steps)
+- ✅ More maintainable code (patterns documented)
+
+**On Project Management**:
+- ✅ Clear progress visibility
+- ✅ Accurate time estimates
+- ✅ Better scope management
+- ✅ Easier to parallelize work
+
+**On Team Collaboration**:
+- ✅ Shared understanding of architecture
+- ✅ Consistent coding standards
+- ✅ Better knowledge transfer
+- ✅ Reduced communication overhead
+
+---
+
+## Problems This Pattern Solves
+
+### 1. **Context Loss Between Agent Sessions**
+
+**Problem**: Agents have no memory between sessions. Each new session starts from scratch.
+
+**Solution**: The agent directory provides complete context:
+- `progress.yaml` shows current status
+- Design docs explain architectural decisions
+- Patterns document coding standards
+- Tasks provide next steps
+
+**Example**: An agent can read `progress.yaml`, see that task-3 is next, read the task document, and continue work immediately.
+
+### 2. **Implicit Knowledge**
+
+**Problem**: Design decisions exist only in developers' heads or scattered across chat logs.
+
+**Solution**: All decisions are documented in design documents with rationale:
+- Why this approach was chosen
+- What alternatives were considered
+- What trade-offs were made
+
+**Example**: A design document might explain why discriminated unions are better than exceptions for access control, with code examples and trade-off analysis.
+
+### 3. **Inconsistent Patterns**
+
+**Problem**: Different parts of codebase use different patterns for the same problems.
+
+**Solution**: Patterns directory provides single source of truth:
+- Architectural patterns documented
+- Code examples provided
+- Anti-patterns identified
+
+**Example**: A pattern document might specify that all data access must go through service layers, with implementation examples and anti-patterns.
+
+### 4. **Scope Creep**
+
+**Problem**: Projects expand without clear boundaries, leading to never-ending development.
+
+**Solution**: Milestones and tasks provide clear scope:
+- Each milestone has specific deliverables
+- Tasks are granular and verifiable
+- Progress is tracked objectively
+
+**Example**: Milestone 1 has exactly 7 tasks. When those are done, the milestone is complete.
+
+### 5. **Quality Drift**
+
+**Problem**: Code quality degrades over time as standards are forgotten or ignored.
+
+**Solution**: Patterns and verification steps maintain quality:
+- Every task has verification checklist
+- Patterns document best practices
+- Design docs explain quality requirements
+
+**Example**: Each task includes verification steps like "TypeScript compiles without errors" and "All tests pass".
+
+### 6. **Onboarding Friction**
+
+**Problem**: New contributors (agents or humans) need weeks to understand the project.
+
+**Solution**: Self-documenting structure enables rapid onboarding:
+- Start with `progress.yaml` for status
+- Read `requirements.md` for context
+- Review patterns for coding standards
+- Pick up next task and start working
+
+**Example**: A new agent can become productive in minutes instead of days.
+
+### 7. **Lost Architectural Decisions**
+
+**Problem**: "Why did we do it this way?" becomes unanswerable after a few months.
+
+**Solution**: Design documents capture rationale:
+- Problem statement
+- Solution approach
+- Benefits and trade-offs
+- Implementation details
+
+**Example**: A design document might explain why certain IDs are reused across databases, with rationale for the decision and implementation details.
+
+### 8. **Unclear Progress**
+
+**Problem**: Hard to know how much work is done and what's remaining.
+
+**Solution**: `progress.yaml` provides objective metrics:
+- Percentage complete per milestone
+- Tasks completed vs total
+- Recent work logged
+- Next steps identified
+
+**Example**: "Milestone 1: 20% complete (1/7 tasks done)"
+
+---
+
+## Sample Prompts for Using ACP
+
+### Initialize Prompt
+
+Use this prompt when starting work on an ACP-structured project:
+
+```markdown
+Read ALL files in @agent. We are going to understand this project then work on a generic task.
+
+Then read KEY src files per your understanding.
+
+Then read @agent again, update stale @agent/tasks, stale documentation, and update 'agent/progress.yaml'.
+```
+
+**Purpose**:
+- Loads complete project context from agent directory
+- Reviews source code to understand current implementation
+- Updates documentation to reflect current state
+- Ensures progress tracking is accurate
+
+### Proceed Prompt
+
+Use this prompt to continue with the next task:
+
+```markdown
+Let's proceed with implementing the current or next task. Remember to update @agent/progress.yaml as you progress.
+```
+
+**Purpose**:
+- Continues work on current or next task
+- Reminds agent to maintain progress tracking
+- Keeps workflow focused and documented
+
+---
+
+## Instructions for Future Agents
+
+### When You First Encounter ACP
+
+1. **Read progress.yaml**
+   - This tells you where the project is
+   - What milestone is current
+   - What task is next
+
+2. **Read requirements.md**
+   - Understand project goals
+   - Learn constraints
+   - Know success criteria
+
+3. **Review current milestone**
+   - Understand current phase
+   - Know deliverables
+   - Check success criteria
+
+4. **Read next task**
+   - Understand what to do
+   - Follow steps
+   - Verify completion
+
+5. **Check relevant patterns**
+   - Learn coding standards
+   - Understand architectural patterns
+   - Follow best practices
+
+### When Working on a Task
+
+1. **Read the task document completely**
+   - Understand objective
+   - Review all steps
+   - Note verification criteria
+
+2. **Check related design documents**
+   - Look for design docs mentioned in task
+   - Understand architectural context
+   - Follow specified patterns
+
+3. **Execute task steps**
+   - Follow steps in order
+   - Don't skip steps
+   - Document any deviations
+
+4. **Verify completion**
+   - Check all verification items
+   - Run tests
+   - Ensure quality standards met
+
+5. **Update progress.yaml**
+   - Mark task as completed
+   - Add completion date
+   - Update milestone progress
+   - Add notes about work done
+
+### When Creating New Features
+
+1. **Create design document first**
+   - Document problem and solution
+   - Include implementation details
+   - Get approval before coding
+
+2. **Update or create milestone**
+   - Add to existing milestone if fits
+   - Create new milestone if major feature
+   - Update progress.yaml
+
+3. **Break into tasks**
+   - Create task documents
+   - Each task 1-4 hours
+   - Include verification steps
+
+4. **Document patterns**
+   - If introducing new patterns, document them
+   - Update existing patterns if needed
+   - Include code examples
+
+5. **Implement and verify**
+   - Follow task steps
+   - Verify each task
+   - Update progress tracking
+
+### When You Encounter Problems
+
+1. **Check design documents**
+   - Look for relevant design decisions
+   - Understand constraints
+   - Follow established patterns
+
+2. **Review patterns**
+   - Check if pattern exists for this problem
+   - Follow pattern guidelines
+   - Don't reinvent solutions
+
+3. **Document new solutions**
+   - If you solve a new problem, document it
+   - Create design document
+   - Add to patterns if reusable
+
+4. **Update progress.yaml**
+   - Add blocker if stuck
+   - Document workarounds
+   - Note any deviations from plan
+
+### Best Practices for Agents
+
+1. **Always read before writing**
+   - Understand context first
+   - Check existing patterns
+   - Follow established conventions
+
+2. **Document as you go**
+   - Update progress.yaml frequently
+   - Add notes about decisions
+   - Document new patterns
+
+3. **Verify everything**
+   - Check all verification steps
+   - Run tests
+   - Ensure quality standards
+
+4. **Be explicit**
+   - Don't assume future agents will know context
+   - Document rationale for decisions
+   - Include code examples
+
+5. **Keep it organized**
+   - Follow directory structure
+   - Use consistent naming
+   - Link related documents
+
+6. **Update progress tracking**
+   - Mark tasks complete
+   - Update percentages
+   - Add recent work notes
+
+---
+
+## Best Practices
+
+### Documentation
+
+1. **Write for agents, not humans**
+   - Be explicit, not implicit
+   - Include code examples
+   - Document rationale, not just decisions
+
+2. **Keep documents focused**
+   - One topic per document
+   - Clear structure
+   - Scannable headings
+
+3. **Link related documents**
+   - Reference other docs
+   - Create knowledge graph
+   - Make navigation easy
+
+4. **Update as you go**
+   - Don't wait until end
+   - Document decisions when made
+   - Keep progress.yaml current
+
+### Organization
+
+1. **Follow naming conventions**
+   - `{feature}-design.md` for designs
+   - `milestone-{N}-{name}.md` for milestones
+   - `task-{N}-{name}.md` for tasks
+   - `{pattern-name}.md` for patterns
+
+2. **Use consistent structure**
+   - Same sections in similar documents
+   - Standard YAML format
+   - Predictable organization
+
+3. **Keep it DRY**
+   - Don't duplicate information
+   - Link to canonical source
+   - Update in one place
+
+### Progress Tracking
+
+1. **Update frequently**
+   - After each task
+   - When blockers arise
+   - When plans change
+
+2. **Be objective**
+   - Use measurable metrics
+   - Track actual vs estimated
+   - Document deviations
+
+3. **Look forward and back**
+   - Document recent work
+   - List next steps
+   - Note blockers
+
+### Quality
+
+1. **Include verification steps**
+   - Every task has checklist
+   - Objective criteria
+   - Automated where possible
+
+2. **Document patterns**
+   - Capture reusable solutions
+   - Include anti-patterns
+   - Provide examples
+
+3. **Review and refine**
+   - Update docs as understanding improves
+   - Fix errors immediately
+   - Keep docs accurate
+
+---
+
+## Conclusion
+
+The Agent Directory Pattern transforms software development from an implicit, memory-dependent process into an explicit, documented system that enables AI agents to work effectively on complex projects.
+
+**Key Takeaways**:
+
+1. **Documentation is Infrastructure** - Treat it with the same care as code
+2. **Explicit Over Implicit** - Document everything that matters
+3. **Structure Enables Scale** - Organization makes complexity manageable
+4. **Agents Need Context** - Provide complete, accessible context
+5. **Progress is Measurable** - Track objectively with YAML
+6. **Patterns Ensure Quality** - Document and follow best practices
+7. **Knowledge Persists** - No more lost tribal knowledge
+
+**When to Use This Pattern**:
+- ✅ Complex projects (>1 month)
+- ✅ Multiple contributors (agents or humans)
+- ✅ Long-term maintenance required
+- ✅ Quality and consistency critical
+- ✅ Knowledge preservation important
+
+**When NOT to Use**:
+- ❌ Trivial scripts (<100 lines)
+- ❌ One-off prototypes
+- ❌ Throwaway code
+- ❌ Simple, well-understood problems
+
+---
+
+**The Agent Pattern is not just documentation—it's a development methodology that makes complex software projects tractable for AI agents.**
+
+---
+
+*For questions or improvements to this pattern, please contribute to the repository or create an issue.*