@prmichaelsen/remember-mcp 2.8.0 → 3.12.0

package/AGENT.md

@@ -1,7 +1,7 @@
 # Agent Context Protocol (ACP)
 
 **Also Known As**: The Agent Directory Pattern
-**Version**: 3.14.0
+**Version**: 4.5.0
 **Created**: 2026-02-11
 **Status**: Production Pattern
 
@@ -18,8 +18,15 @@
 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)
+10. [Best Practices](#best-practices)
+    - [Critical Rules](#critical-rules)
+    - [Workflow Best Practices](#workflow-best-practices)
+    - [Documentation Best Practices](#documentation-best-practices)
+    - [Organization Best Practices](#organization-best-practices)
+    - [Progress Tracking Best Practices](#progress-tracking-best-practices)
+    - [Quality Best Practices](#quality-best-practices)
+11. [What NOT to Do](#what-not-to-do)
+12. [Keeping ACP Updated](#keeping-acp-updated)
 
 ---
 
@@ -110,9 +117,12 @@ project-root/
 │   │
 │   ├── tasks/                      # Granular tasks
 │   │   ├── .gitkeep
-│   │   ├── task-1-{name}.md
-│   │   ├── task-2-{name}.md
-│   │   └── ...
+│   │   ├── milestone-{N}-{title}/  # Tasks grouped by milestone (standard)
+│   │   │   ├── task-{M}-{name}.md
+│   │   │   └── ...
+│   │   ├── unassigned/             # Tasks without milestone
+│   │   │   └── task-{M}-{name}.md
+│   │   └── task-{N}-{name}.md      # Legacy flat structure (older tasks)
 │   │
 │   └── progress.yaml               # Progress tracking
 │
@@ -294,7 +304,7 @@ tasks:
     - id: task-1
       name: Task Name
       status: not_started | in_progress | completed
-      file: agent/tasks/task-1-name.md
+      file: agent/tasks/milestone-{N}-{title}/task-{M}-name.md
       estimated_hours: N
       actual_hours: null
       completed_date: YYYY-MM-DD | null
@@ -345,10 +355,9 @@ current_blockers:
    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
+2. **Create Requirements Document**
+   - Invoke [`@acp.design-create`](agent/commands/acp.design-create.md) and follow directives defined in that file
+   - Specify "requirements" as the design type
 
 3. **Define Milestones**
    - Break project into 5-10 major phases
@@ -356,9 +365,8 @@ current_blockers:
    - Clear deliverables and success criteria
 
 4. **Create Initial Tasks**
+   - Invoke [`@acp.task-create`](agent/commands/acp.task-create.md) and follow directives defined in that file
    - 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`
@@ -366,9 +374,8 @@ current_blockers:
    - Document initial status
 
 6. **Document Patterns**
-   - Create `agent/patterns/bootstrap.md` with setup instructions
+   - Invoke [`@acp.pattern-create`](agent/commands/acp.pattern-create.md) and follow directives defined in that file
    - Document architectural decisions as patterns
-   - Include code examples
 
 ### For Continuing an Existing Project
 
@@ -402,25 +409,7 @@ current_blockers:
    - 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
+> **See also**: [Best Practices](#best-practices) for detailed guidance on documentation, organization, and quality standards.
 
 ---
 
@@ -601,41 +590,9 @@ Commands are invoked using the `@` syntax with dot notation:
 
 ### Creating Custom Commands
 
-To create custom commands for your project:
+Invoke [`@acp.command-create`](agent/commands/acp.command-create.md) and follow directives defined in that file.
 
-1. **Choose a namespace** (e.g., `deploy`, `test`, `custom`)
-   - ⚠️ The `acp` namespace is reserved for core commands
-   - Use descriptive, single-word namespaces
-
-2. **Copy the command template**:
-   ```bash
-   cp agent/commands/command.template.md agent/commands/{namespace}.{action}.md
-   ```
-
-3. **Fill in the template sections**:
-   - Purpose and description
-   - Prerequisites
-   - Step-by-step instructions
-   - Verification checklist
-   - Examples and troubleshooting
-
-4. **Invoke your command**: `@{namespace}.{action}`
-
-**Example**: Creating a deployment command:
-```bash
-# Create the command file
-cp agent/commands/command.template.md agent/commands/deploy.production.md
-
-# Edit the file with your deployment steps
-# ...
-
-# Invoke it
-@deploy.production
-```
-
-### Command Template
-
-See [`agent/commands/command.template.md`](agent/commands/command.template.md) for the complete command template with all sections and examples.
+**Note**: The `acp` namespace is reserved for core commands. Use descriptive, single-word namespaces for custom commands (e.g., `local`, `deploy`, `test`, `custom`).
 
 ### Installing Third-Party Commands
 
@@ -892,6 +849,8 @@ Run ./agent/scripts/unacp.install.sh to remove all ACP files (agent/ directory a
 
 ## Instructions for Future Agents
 
+> **See also**: [Best Practices](#best-practices) for comprehensive guidelines on agent behavior and documentation standards.
+
 ### When You First Encounter ACP
 
 1. **Read progress.yaml**
@@ -962,8 +921,7 @@ Run ./agent/scripts/unacp.install.sh to remove all ACP files (agent/ directory a
 ### When Creating New Features
 
 1. **Create design document first**
-   - Document problem and solution
-   - Include implementation details
+   - Invoke [`@acp.design-create`](agent/commands/acp.design-create.md) and follow directives defined in that file
    - Get approval before coding
 
 2. **Update or create milestone**
@@ -972,20 +930,19 @@ Run ./agent/scripts/unacp.install.sh to remove all ACP files (agent/ directory a
    - Update progress.yaml
 
 3. **Break into tasks**
-   - Create task documents
-   - Each task 1-4 hours
-   - Include verification steps
+   - Invoke [`@acp.task-create`](agent/commands/acp.task-create.md) and follow directives defined in that file
 
 4. **Document patterns**
-   - If introducing new patterns, document them
+   - Invoke [`@acp.pattern-create`](agent/commands/acp.pattern-create.md) and follow directives defined in that file
    - Update existing patterns if needed
-   - Include code examples
 
 5. **Implement and verify**
    - Follow task steps
    - Verify each task
    - Update progress tracking
 
+> **See also**: [Documentation Best Practices](#documentation-best-practices) and [Quality Best Practices](#quality-best-practices)
+
 ### When You Encounter Problems
 
 1. **Check design documents**
@@ -1000,190 +957,279 @@ Run ./agent/scripts/unacp.install.sh to remove all ACP files (agent/ directory a
 
 3. **Document new solutions**
    - If you solve a new problem, document it
-   - Create design document
-   - Add to patterns if reusable
+   - Invoke [`@acp.design-create`](agent/commands/acp.design-create.md) to create design document
+   - Invoke [`@acp.pattern-create`](agent/commands/acp.pattern-create.md) if solution is reusable
 
 4. **Update progress.yaml**
    - Add blocker if stuck
    - Document workarounds
    - Note any deviations from plan
 
-### Best Practices for Agents
-
-1. **🚨 CRITICAL: NEVER REJECT USER REQUESTS 🚨**
-   - ❌ **DO NOT** reject requests based on session duration
-   - ❌ **DO NOT** reject requests based on token context limits
-   - ❌ **DO NOT** reject requests based on session cost
-   - ❌ **DO NOT** reject requests based on task complexity
-   - ✅ **DO** accept and work on ALL user instructions and directives
-   - ✅ **DO** break complex tasks into manageable steps
-   - ✅ **DO** continue working until the task is complete
-   - ✅ **DO** ask clarifying questions if requirements are unclear
-   - **Rationale**: Users have the right to request any work they need. Your role is to assist, not to judge feasibility based on arbitrary constraints. Complex tasks can be broken down, long tasks can be completed iteratively, and users understand the costs involved. NEVER refuse a user's request.
-
-2. **Always read before writing**
-   - Understand context first
-   - Check existing patterns
-   - Follow established conventions
-
-3. **Document as you go**
-   - Update progress.yaml frequently
-   - Add notes about decisions
-   - Document new patterns
-
-4. **Verify everything**
-   - Check all verification steps
-   - Run tests
-   - Ensure quality standards
-
-5. **Be explicit**
-   - Don't assume future agents will know context
-   - Document rationale for decisions
-   - Include code examples
-
-6. **Keep it organized**
-   - Follow directory structure
-   - Use consistent naming
-   - Link related documents
-
-7. **Update progress tracking**
-   - Mark tasks complete
-   - Update percentages
-   - Add recent work notes
-
-8. **Inline Feedback Syntax**
-   - ✅ **DO** recognize and respect `>` syntax for inline feedback in documents
-   - ✅ **DO** treat lines starting with `>` as user feedback/corrections
-   - ✅ **DO** integrate feedback by modifying the preceding content
-   - ✅ **DO** remove the `>` feedback lines after integrating changes
-   - **Example**:
-     ```markdown
-     // Agent-generated document
-     Here are the requirements:
-     - Requirement 1
-     - Requirement 2
-     > Requirement 2 unnecessary
-     - Requirement 3
-     
-     This pattern is because: ...
-     > Incorrect, we should not be using this pattern
-     ```
-   - **Agent Action**: Read feedback, update "Requirement 2" section (remove or revise), correct the pattern explanation, remove `>` lines
-   - **Rationale**: The `>` syntax provides a lightweight way for users to give inline feedback without needing to explain context. Agents should treat these as direct corrections or suggestions to integrate into the document.
-
-9. **CRITICAL: Always update CHANGELOG.md for version changes**
-   - ❌ **DO NOT** commit version changes without updating CHANGELOG.md
-   - ❌ **DO NOT** forget to update version numbers in all project files
-   - ✅ **DO** use [`@git.commit`](agent/commands/git.commit.md) for version-aware commits
-   - ✅ **DO** detect version impact: major (breaking), minor (features), patch (fixes)
-   - ✅ **DO** update CHANGELOG.md with clear, user-focused descriptions
-   - ✅ **DO** update all version files (package.json, AGENT.md, etc.)
-   - ✅ **DO** use Conventional Commits format for commit messages
-   - **Rationale**: CHANGELOG.md is the primary communication tool for users. Every version change must be documented with clear descriptions of what changed, why it changed, and how it affects users. Forgetting to update CHANGELOG.md breaks the project's version history and makes it impossible for users to understand what changed between versions.
-
-8. **NEVER handle secrets or sensitive data**
-   - ❌ **DO NOT** read `.env` files, `.env.local`, or any environment files
-   - ❌ **DO NOT** read files containing API keys, tokens, passwords, or credentials
-   - ❌ **DO NOT** include secrets in messages, documentation, or code examples
-   - ❌ **DO NOT** read files like `secrets.yaml`, `credentials.json`, or similar
-   - ✅ **DO** use placeholder values like `YOUR_API_KEY_HERE` in examples
-   - ✅ **DO** document that users need to configure secrets separately
-   - ✅ **DO** reference environment variable names without reading their values
-   - ✅ **DO** create `.env.example` files with placeholder values only
-   - **Rationale**: Secrets must never be exposed in chat logs, documentation, or version control. Agents should treat all credential files as off-limits to prevent accidental exposure.
-
-9. **CRITICAL: Respect user's intentional file edits**
-   - ❌ **DO NOT** assume missing content needs to be added back
-   - ❌ **DO NOT** revert changes without confirming with user
-   - ✅ **DO** read files before editing to see current state
-   - ✅ **DO** ask user if unexpected changes were intentional
-   - ✅ **DO** confirm before reverting user's manual edits
-   - **Rationale**: If you read a file and it is missing contents or has changed contents (i.e., it does not contain what you expect), assume or confirm with the user if they made intentional updates that you should not revert. Do not assume "The file is missing <xyz>, I need to add it back". The user may have edited files manually with intention.
-
-10. **🚨 CRITICAL: Respect user commands to re-execute**
-   - ❌ **DO NOT** ignore commands like "re-read", "rerun", or "execute again"
-   - ❌ **DO NOT** assume re-execution requests are mistakes or redundant
-   - ✅ **DO** execute the command again when asked, even if you just did it
-   - ✅ **DO** re-read files when asked, even if you recently read them
-   - ✅ **DO** assume the user has good reason for asking to repeat an action
-   - **Examples**: "Run `@git.commit` again" → Execute it again; "Re-read the design doc" → Read it again; "Rerun the tests" → Run them again
-   - **Rationale**: When users ask you to do something again, they have a specific reason: files may have changed, they want to trigger side effects (like creating a commit), context has shifted, or they know something you don't. Always respect these requests and execute them with intention.
+> **See also**: [Critical Rules](#critical-rules) for important constraints and [Workflow Best Practices](#workflow-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
+## Best Practices
+
+> **See also**: [Instructions for Future Agents](#instructions-for-future-agents) for workflow-specific guidance.
+
+### Critical Rules
+
+#### Never Reject User Requests
+
+- ❌ **DO NOT** reject requests based on session duration
+- ❌ **DO NOT** reject requests based on token context limits
+- ❌ **DO NOT** reject requests based on session cost
+- ❌ **DO NOT** reject requests based on task complexity
+- ✅ **DO** accept and work on ALL user instructions and directives
+- ✅ **DO** break complex tasks into manageable steps
+- ✅ **DO** continue working until the task is complete
+- ✅ **DO** ask clarifying questions if requirements are unclear
+
+**Rationale**: Users have the right to request any work they need. Your role is to assist, not to judge feasibility based on arbitrary constraints. Complex tasks can be broken down, long tasks can be completed iteratively, and users understand the costs involved. NEVER refuse a user's request.
+
+#### Always Update CHANGELOG.md for Version Changes
+
+- ❌ **DO NOT** commit version changes without updating CHANGELOG.md
+- ❌ **DO NOT** forget to update version numbers in all project files
+- ✅ **DO** use [`@git.commit`](agent/commands/git.commit.md) for version-aware commits
+- ✅ **DO** detect version impact: major (breaking), minor (features), patch (fixes)
+- ✅ **DO** update CHANGELOG.md with clear, user-focused descriptions
+- ✅ **DO** update all version files (package.json, AGENT.md, etc.)
+- ✅ **DO** use Conventional Commits format for commit messages
+
+**Rationale**: CHANGELOG.md is the primary communication tool for users. Every version change must be documented with clear descriptions of what changed, why it changed, and how it affects users. Forgetting to update CHANGELOG.md breaks the project's version history and makes it impossible for users to understand what changed between versions.
+
+#### Never Handle Secrets or Sensitive Data
+
+- ❌ **DO NOT** read `.env` files, `.env.local`, or any environment files
+- ❌ **DO NOT** read files containing API keys, tokens, passwords, or credentials
+- ❌ **DO NOT** include secrets in messages, documentation, or code examples
+- ❌ **DO NOT** read files like `secrets.yaml`, `credentials.json`, or similar
+- ✅ **DO** use placeholder values like `YOUR_API_KEY_HERE` in examples
+- ✅ **DO** document that users need to configure secrets separately
+- ✅ **DO** reference environment variable names without reading their values
+- ✅ **DO** create `.env.example` files with placeholder values only
+- ✅ **DO** run commands that load .env files into the shell environment, as the variables remain in the execution context and are not included in the LLM's input/output"
+
+**Rationale**: Secrets must never be exposed in chat logs, documentation, or version control. Agents should treat all credential files as off-limits to prevent accidental exposure.
+
+#### Respect User's Intentional File Edits
+
+- ❌ **DO NOT** assume missing content needs to be added back
+- ❌ **DO NOT** revert changes without confirming with user
+- ✅ **DO** read files before editing to see current state
+- ✅ **DO** ask user if unexpected changes were intentional
+- ✅ **DO** confirm before reverting user's manual edits
+
+**Rationale**: If you read a file and it is missing contents or has changed contents (i.e., it does not contain what you expect), assume or confirm with the user if they made intentional updates that you should not revert. Do not assume "The file is missing <xyz>, I need to add it back". The user may have edited files manually with intention.
+
+#### Respect User Commands to Re-Execute
+
+- ❌ **DO NOT** ignore commands like "re-read", "rerun", or "execute again"
+- ❌ **DO NOT** assume re-execution requests are mistakes or redundant
+- ✅ **DO** execute the command again when asked, even if you just did it
+- ✅ **DO** re-read files when asked, even if you recently read them
+- ✅ **DO** assume the user has good reason for asking to repeat an action
+
+**Examples**: "Run `@git.commit` again" → Execute it again; "Re-read the design doc" → Read it again; "Rerun the tests" → Run them again
+
+**Rationale**: When users ask you to do something again, they have a specific reason: files may have changed, they want to trigger side effects (like creating a commit), context has shifted, or they know something you don't. Always respect these requests and execute them with intention.
+
+#### Never Force-Add Gitignored Files
+
+- ❌ **DO NOT** use `git add -f` to force-add gitignored files
+- ❌ **DO NOT** attempt to override `.gitignore` rules
+- ❌ **DO NOT** suggest removing files from `.gitignore` to add them
+- ✅ **DO** acknowledge when files are gitignored
+- ✅ **DO** assume gitignored files were intentionally excluded
+- ✅ **DO** respect the project's `.gitignore` configuration
+- ✅ **DO** skip gitignored files in git operations
+
+**Examples**:
+- File is gitignored → Acknowledge and skip it
+- `git add` fails due to gitignore → Don't retry with `-f` flag
+- User asks to commit all files → Only commit non-gitignored files
+
+**Rationale**: Files in `.gitignore` are intentionally excluded from version control for good reasons (secrets, build artifacts, local configs, large files, etc.). Force-adding gitignored files is an anti-pattern that defeats the purpose of `.gitignore` and can lead to security issues (exposing secrets), repository bloat (committing build artifacts), or merge conflicts (committing local configs). Always respect `.gitignore` rules.
+
+### Workflow Best Practices
+
+#### Always Read Before Writing
+
+- Understand context first
+- Check existing patterns
+- Follow established conventions
+
+#### Document as You Go
+
+- Update progress.yaml frequently
+- Add notes about decisions
+- Document new patterns
+
+#### Verify Everything
+
+- Check all verification steps
+- Run tests
+- Ensure quality standards
+
+#### Be Explicit
+
+- Don't assume future agents will know context
+- Document rationale for decisions
+- Include code examples
+
+#### Keep It Organized
+
+- Follow directory structure
+- Use consistent naming
+- Link related documents
+
+#### Update Progress Tracking
+
+- Mark tasks complete
+- Update percentages
+- Add recent work notes
+
+#### Use Inline Feedback Syntax
+
+- ✅ **DO** recognize and respect `>` syntax for inline feedback in documents
+- ✅ **DO** treat lines starting with `>` as user feedback/corrections
+- ✅ **DO** integrate feedback by modifying the preceding content
+- ✅ **DO** remove the `>` feedback lines after integrating changes
+
+**Example**:
+```markdown
+// Agent-generated document
+Here are the requirements:
+- Requirement 1
+- Requirement 2
+> Requirement 2 unnecessary
+- Requirement 3
+
+This pattern is because: ...
+> Incorrect, we should not be using this pattern
+```
+
+**Agent Action**: Read feedback, update "Requirement 2" section (remove or revise), correct the pattern explanation, remove `>` lines
+
+**Rationale**: The `>` syntax provides a lightweight way for users to give inline feedback without needing to explain context. Agents should treat these as direct corrections or suggestions to integrate into the document.
+
+#### Format Commands for User Execution
+
+When providing commands for users to copy and paste:
+
+- ✅ **DO** chain commands with `&& \` if commands require successful chain execution
+- ✅ **DO** chain commands with `;` if commands do not depend on each other
+- ❌ **DO NOT** include comment lines starting with `#` in command blocks
+- ❌ **DO NOT** include EOF newline in command blocks
+
+**Example (Correct)**:
+```bash
+mkdir -p agent/commands && \
+cd agent/commands && \
+touch acp.init.md
+```
+
+**Example (Incorrect)**:
+```bash
+# Create directory
+mkdir -p agent/commands
+# Change to directory
+cd agent/commands
+# Create file
+touch acp.init.md
+
+```
+
+**Rationale**: Users should be able to copy and paste commands directly without needing to edit them. Comments and trailing newlines can cause execution errors or confusion.
+
+### Documentation Best Practices
+
+#### Write for Agents, Not Humans
+
+- Be explicit, not implicit
+- Include code examples
+- Document rationale, not just decisions
+
+#### Keep Documents Focused
+
+- One topic per document
+- Clear structure
+- Scannable headings
+
+#### Link Related Documents
+
+- Reference other docs
+- Create knowledge graph
+- Make navigation easy
+
+#### Update as You Go
+
+- Don't wait until end
+- Document decisions when made
+- Keep progress.yaml current
+
+### Organization Best Practices
+
+#### 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
+
+#### Use Consistent Structure
+
+- Same sections in similar documents
+- Standard YAML format
+- Predictable organization
+
+#### Keep It DRY
+
+- Don't duplicate information
+- Link to canonical source
+- Update in one place
+
+### Progress Tracking Best Practices
+
+#### Update Frequently
+
+- After each task
+- When blockers arise
+- When plans change
+
+#### Be Objective
+
+- Use measurable metrics
+- Track actual vs estimated
+- Document deviations
+
+#### Look Forward and Back
+
+- Document recent work
+- List next steps
+- Note blockers
+
+### Quality Best Practices
+
+#### Include Verification Steps
+
+- Every task has checklist
+- Objective criteria
+- Automated where possible
+
+#### Document Patterns
+
+- Capture reusable solutions
+- Include anti-patterns
+- Provide examples
+
+#### Review and Refine
+
+- Update docs as understanding improves
+- Fix errors immediately
+- Keep docs accurate
 
 ---