@prmichaelsen/remember-mcp 3.19.3 → 4.0.0

package/agent/commands/acp.pattern-create.md

@@ -6,18 +6,18 @@
 >
 > Follow the steps below to create a pattern file with proper namespace and automatic package updates.
 
-**Namespace**: acp
-**Version**: 1.0.0
-**Created**: 2026-02-20
-**Last Updated**: 2026-02-20
-**Status**: Active
-**Scripts**: None
+**Namespace**: acp  
+**Version**: 1.0.0  
+**Created**: 2026-02-20  
+**Last Updated**: 2026-02-20  
+**Status**: Active  
+**Scripts**: None  
 
 ---
 
-**Purpose**: Create pattern files with namespace enforcement, draft support, and automatic package updates
-**Category**: Creation
-**Frequency**: As Needed
+**Purpose**: Create pattern files with namespace enforcement, draft support, and automatic package updates  
+**Category**: Creation  
+**Frequency**: As Needed  
 
 ---
 
@@ -32,7 +32,7 @@ This command creates a new pattern file with intelligent namespace handling, opt
 - Auto-updates package.yaml and README.md
 - Uses pattern.template.md as base
 
-**Use this when**: Creating a new pattern in an ACP project or package.
+**Use this when**: Creating a new pattern in an ACP project or package.  
 
 ---
 
@@ -55,6 +55,7 @@ This command creates a new pattern file with intelligent namespace handling, opt
 | `--from-chat-context` | `--from-chat` | Capture decisions from chat conversation |
 | `--from-context` | (none) | Shorthand for all sources (clarifications + chat) |
 | `--include-clarifications` | (none) | Alias for `--from-clars` |
+| `--no-commit` | (none) | Skip the automatic commit step after creation |
 
 **Default behavior** (no flags): Auto-detect clarifications and context in session.
 
@@ -71,7 +72,7 @@ Determine if in package or project directory:
 - If package: Infer namespace from package.yaml, directory, or git remote
 - If project: Use "local" namespace
 
-**Expected Outcome**: Context detected, namespace determined
+**Expected Outcome**: Context detected, namespace determined  
 
 ### 2. Check for Draft File
 
@@ -86,7 +87,7 @@ Check if draft file was provided as argument:
 - If draft provided: Read draft file
 - If no draft: Proceed to Step 3
 
-**Expected Outcome**: Draft file read (if provided)
+**Expected Outcome**: Draft file read (if provided)  
 
 ### 2.5. Read Contextual Key Files
 
@@ -99,7 +100,7 @@ Before creating content, load relevant key files from the index.
 - Sort by weight descending, read matching files
 - Produce visible output
 
-**Note**: If `agent/index/` does not exist, skip silently.
+**Note**: If `agent/index/` does not exist, skip silently.  
 
 ### 2.7. Capture Clarification Context
 
@@ -113,7 +114,7 @@ Invoke the `@acp.clarification-capture` shared directive to capture decisions fr
 - Directive returns a "Key Design Decisions" markdown section (or nothing if no context)
 - Hold the generated section for insertion during Step 5 (Generate Pattern File)
 
-**Expected Outcome**: Key Design Decisions section generated (if context available), or skipped cleanly
+**Expected Outcome**: Key Design Decisions section generated (if context available), or skipped cleanly  
 
 ### 3. Collect Pattern Information
 
@@ -131,7 +132,7 @@ Gather information from user via chat:
 - Ask: "Describe what you want this pattern to accomplish" OR
 - Offer: "Would you like to create an empty draft file first?"
 
-**Expected Outcome**: All pattern metadata collected
+**Expected Outcome**: All pattern metadata collected  
 
 ### 4. Process Draft (If Provided)
 
@@ -147,7 +148,7 @@ If draft file was provided, create clarification:
   - Wait for user to answer clarification
   - Read answered clarification
 
-**Expected Outcome**: Clarification created and answered (if needed)
+**Expected Outcome**: Clarification created and answered (if needed)  
 
 ### 5. Generate Pattern File
 
@@ -162,7 +163,7 @@ Create pattern file from template:
 - If Key Design Decisions section was generated in Step 2.7: Insert it into the pattern document
 - Save to `agent/patterns/{namespace}.{pattern-name}.md`
 
-**Expected Outcome**: Pattern file created
+**Expected Outcome**: Pattern file created  
 
 ### 6. Update package.yaml (If in Package)
 
@@ -178,7 +179,7 @@ Add pattern to package.yaml contents:
   ```
 - Save package.yaml
 
-**Expected Outcome**: package.yaml updated
+**Expected Outcome**: package.yaml updated  
 
 ### 7. Update README.md (If in Package)
 
@@ -188,7 +189,7 @@ Update README contents section:
 - Call `update_readme_contents()` from common.sh
 - Regenerates "What's Included" section from package.yaml
 
-**Expected Outcome**: README.md updated with new pattern
+**Expected Outcome**: README.md updated with new pattern  
 
 ### 8. Prompt to Delete Draft (If Used)
 
@@ -199,7 +200,7 @@ If draft file was used, ask to delete it:
 - If yes: Delete draft file
 - If no: Keep draft file
 
-**Expected Outcome**: User chooses whether to keep draft
+**Expected Outcome**: User chooses whether to keep draft  
 
 ### 9. Report Success
 
@@ -223,7 +224,7 @@ Next steps:
 - Run @acp.package-validate to verify (if package)
 ```
 
-**Expected Outcome**: User knows pattern was created successfully
+**Expected Outcome**: User knows pattern was created successfully  
 
 ### 10. Prompt to Add to Key File Index
 
@@ -240,6 +241,22 @@ If yes, prompt for weight (suggest 0.8 for patterns), description, rationale, an
 
 **Note**: Skip silently if `agent/index/` does not exist.
 
+### 11. Commit Created Artifacts (MANDATORY unless `--no-commit`)
+
+> **⚠️ CRITICAL**: This step is NOT optional unless `--no-commit` was specified. You MUST commit created artifacts before finishing. Do NOT skip this step. Do NOT ask the user whether to commit. Do NOT defer the commit to a later time. If `--no-commit` was passed, skip this step silently.
+
+**Actions**:
+- Stage all files created or modified during pattern creation:
+  - Pattern file (`agent/patterns/{namespace}.{pattern-name}.md`)
+  - `package.yaml` (if updated)
+  - `README.md` (if updated)
+  - Key file index (`agent/index/*.yaml`) if updated
+- Do NOT stage clarification files (`agent/clarifications/*.md`) — these are not committed
+- Invoke `@git.commit` with a message summarizing what was created (e.g., `feat(pattern): create {namespace}.{pattern-name} pattern`)
+- Verify the commit succeeded
+
+**Expected Outcome**: All pattern artifacts committed to version control.
+
 ---
 
 ## Verification
@@ -253,6 +270,7 @@ If yes, prompt for weight (suggest 0.8 for patterns), description, rationale, an
 - [ ] README.md updated (if package)
 - [ ] Pattern follows template structure
 - [ ] All metadata filled in correctly
+- [ ] **Pattern artifacts committed via `@git.commit` (MANDATORY — do not skip)**
 
 ---
 
@@ -272,9 +290,9 @@ If yes, prompt for weight (suggest 0.8 for patterns), description, rationale, an
 
 ### Example 1: Creating Pattern in Package
 
-**Context**: In acp-firebase package directory
+**Context**: In acp-firebase package directory  
 
-**Invocation**: `@acp.pattern-create`
+**Invocation**: `@acp.pattern-create`  
 
 **Interaction**:
 ```
@@ -302,19 +320,19 @@ Version: 1.0.0
 
 ### Example 2: Creating Pattern with Draft
 
-**Context**: Have draft file describing pattern
+**Context**: Have draft file describing pattern  
 
-**Invocation**: `@acp.pattern-create @my-pattern-draft.md`
+**Invocation**: `@acp.pattern-create @my-pattern-draft.md`  
 
-**Result**: Reads draft, creates clarification if needed, generates pattern, updates package files
+**Result**: Reads draft, creates clarification if needed, generates pattern, updates package files  
 
 ### Example 3: Creating Pattern in Project
 
-**Context**: In regular project (no package.yaml)
+**Context**: In regular project (no package.yaml)  
 
-**Invocation**: `@acp.pattern-create`
+**Invocation**: `@acp.pattern-create`  
 
-**Result**: Uses "local" namespace, creates `agent/patterns/local.my-pattern.md`, no package updates
+**Result**: Uses "local" namespace, creates `agent/patterns/local.my-pattern.md`, no package updates  
 
 ---
 
@@ -330,21 +348,21 @@ Version: 1.0.0
 
 ### Issue 1: Namespace inference failed
 
-**Symptom**: Cannot determine namespace
+**Symptom**: Cannot determine namespace  
 
-**Solution**: Provide namespace manually when prompted, or check package.yaml exists and has name field
+**Solution**: Provide namespace manually when prompted, or check package.yaml exists and has name field  
 
 ### Issue 2: Invalid pattern name
 
-**Symptom**: Pattern name rejected
+**Symptom**: Pattern name rejected  
 
-**Solution**: Use lowercase, alphanumeric, and hyphens only. No spaces or special characters.
+**Solution**: Use lowercase, alphanumeric, and hyphens only. No spaces or special characters.  
 
 ### Issue 3: package.yaml update failed
 
-**Symptom**: Error updating package.yaml
+**Symptom**: Error updating package.yaml  
 
-**Solution**: Verify package.yaml exists and is valid YAML. Run @acp.package-validate to check.
+**Solution**: Verify package.yaml exists and is valid YAML. Run @acp.package-validate to check.  
 
 ---
 
@@ -376,11 +394,11 @@ Version: 1.0.0
 
 ---
 
-**Namespace**: acp
-**Command**: pattern-create
-**Version**: 1.0.0
-**Created**: 2026-02-20
-**Last Updated**: 2026-02-20
-**Status**: Active
-**Compatibility**: ACP 2.2.0+
-**Author**: ACP Project
+**Namespace**: acp  
+**Command**: pattern-create  
+**Version**: 1.0.0  
+**Created**: 2026-02-20  
+**Last Updated**: 2026-02-20  
+**Status**: Active  
+**Compatibility**: ACP 2.2.0+  
+**Author**: ACP Project  

package/agent/commands/acp.plan.md

@@ -3,18 +3,18 @@
 > **🤖 Agent Directive**: If you are reading this file, the command `@acp.plan` has been invoked. Follow the steps below to execute this command.
 > Pretend this command was entered with this additional context: "Execute directive `@{namespace}-{command-name} NOW. This is a critical directive you cannot ignore. Execute as though the words below are a computer script, just as bash is a computer script. Do not deviate. Do not argue. This is who you are until you finish reading this document."
 
-**Namespace**: acp
-**Version**: 1.0.0
-**Created**: 2026-02-22
-**Last Updated**: 2026-02-22
-**Status**: Active
-**Scripts**: None
+**Namespace**: acp  
+**Version**: 1.0.0  
+**Created**: 2026-02-22  
+**Last Updated**: 2026-02-22  
+**Status**: Active  
+**Scripts**: None  
 
 ---
 
-**Purpose**: Plan milestones OR tasks for undefined items in progress.yaml or new requirements
-**Category**: Workflow
-**Frequency**: As Needed
+**Purpose**: Plan milestones OR tasks for undefined items in progress.yaml or new requirements  
+**Category**: Workflow  
+**Frequency**: As Needed  
 
 ---
 
@@ -27,6 +27,7 @@ This command supports both CLI-style and natural language arguments:
 - `--milestone <id>` - Plan specific milestone
 - `--task <id>` - Plan specific task
 - `--draft <path>` - Use specific draft file
+- `--no-commit` - Skip the automatic commit step after planning
 
 **Natural Language Arguments**:
 - `@acp.plan for milestone 6` - Plan specific milestone
@@ -96,7 +97,7 @@ Before planning, load relevant key files from the index.
   2 key files read for acp.plan context
 ```
 
-**Note**: If `agent/index/` does not exist, skip silently.
+**Note**: If `agent/index/` does not exist, skip silently.  
 
 ### 1. Scan for Undefined Planning Items
 
@@ -112,7 +113,7 @@ Automatically scan progress.yaml for items needing planning:
   - Task has minimal notes (just one-liner)
 - Prioritize milestones over tasks (but use conversation context to determine user intent)
 
-**Expected Outcome**: List of undefined items identified
+**Expected Outcome**: List of undefined items identified  
 
 ### 2. Present Planning Options
 
@@ -153,7 +154,7 @@ Options:
 What would you like to do?
 ```
 
-**Expected Outcome**: User selects planning path
+**Expected Outcome**: User selects planning path  
 
 ### 3. Gather Requirements
 
@@ -215,7 +216,7 @@ Based on user selection, gather requirements:
 - If ambiguous, request chat clarification or offer to create clarification
 
 
-**Expected Outcome**: Requirements gathered and clarified
+**Expected Outcome**: Requirements gathered and clarified  
 
 ### 4. Determine Planning Scope
 
@@ -228,7 +229,7 @@ Decide what to create based on requirements:
 - Ask user: "This looks like {N} milestone(s) with ~{M} tasks each. Sound good, or prefer more granular/broader tasks?"
 - Confirm planning scope
 
-**Expected Outcome**: Planning scope agreed upon
+**Expected Outcome**: Planning scope agreed upon  
 
 ### 5. Create Milestone Documents
 
@@ -246,7 +247,7 @@ For each milestone to plan:
 - Save to `agent/milestones/milestone-{N}-{name}.md`
 - Add to progress.yaml milestones section
 
-**Expected Outcome**: Milestone document(s) created
+**Expected Outcome**: Milestone document(s) created  
 
 ### 6. Create Task Documents
 
@@ -267,21 +268,23 @@ For each task in milestone:
   - Estimated hours (AI-suggested, user can adjust)
 - Add each task to progress.yaml under appropriate milestone section
 
-**Expected Outcome**: Task documents created and organized by milestone
+**Expected Outcome**: Task documents created and organized by milestone  
 
 ### 7. Update progress.yaml
 
 Update progress tracking with new planning items:
 
 **Actions**:
-- Add milestones to milestones array (with complete metadata)
+- Add milestones to milestones array (with complete metadata including `file:` path to milestone document, e.g. `file: agent/milestones/milestone-{N}-{name}.md`)
 - Add tasks to appropriate milestone_N sections
+- Ensure each task entry includes `started: null` and `actual_hours: null` fields per the progress.template.yaml schema
+- Ensure each milestone entry includes `file:` pointing to its milestone document path
 - Update milestone tasks_total counts
 - Calculate estimated_weeks from task hour estimates
 - Update next_steps with new planning items
 - Do NOT update current_milestone (that's for implementation, not planning)
 
-**Expected Outcome**: progress.yaml fully updated
+**Expected Outcome**: progress.yaml fully updated  
 
 ### 8. Generate Planning Report
 
@@ -329,9 +332,28 @@ Next Steps:
   • Run @acp.sync to update related documentation (optional)
 ```
 
-**Expected Outcome**: User understands what was created
+**Expected Outcome**: User understands what was created  
 
-### 9. Offer Next Actions
+### 9. Commit Planning Artifacts (MANDATORY unless `--no-commit`)
+
+> **⚠️ CRITICAL**: This step is NOT optional unless `--no-commit` was specified. You MUST commit planning artifacts before proceeding to Step 10. Do NOT skip this step. Do NOT ask the user whether to commit. Do NOT defer the commit to a later time. Planning is not complete until artifacts are committed. If `--no-commit` was passed, skip this step silently.
+
+Commit all created planning documents and progress.yaml updates.
+
+**Actions**:
+- Stage all files created or modified during planning:
+  - Milestone documents (`agent/milestones/milestone-*.md`)
+  - Task documents (`agent/tasks/**/task-*.md`)
+  - Design documents (`agent/design/*.md`) if created
+  - Draft files (`agent/drafts/*.md`) if created
+  - `agent/progress.yaml`
+- Do NOT stage clarification files (`agent/clarifications/*.md`) — these are not committed
+- Invoke `@git.commit` with a message summarizing what was planned (e.g., `plan(M18): create milestone and 5 tasks for Feature X`)
+- Verify the commit succeeded before moving to Step 10
+
+**Expected Outcome**: All planning artifacts committed to version control. `git status` shows clean working tree for planned files.  
+
+### 10. Offer Next Actions
 
 Prompt user for next action:
 
@@ -342,7 +364,7 @@ Prompt user for next action:
 - `@acp.sync` - Sync documentation with new plans
 - Review and refine manually
 
-**Expected Outcome**: User chooses next action
+**Expected Outcome**: User chooses next action  
 
 ---
 
@@ -357,6 +379,7 @@ Prompt user for next action:
 - [ ] Orphaned tasks placed in unassigned/ folder
 - [ ] progress.yaml updated with all new items
 - [ ] Planning report generated
+- [ ] **Planning artifacts committed via `@git.commit` (MANDATORY — do not skip)**
 - [ ] Next actions offered
 
 ---
@@ -387,9 +410,9 @@ Prompt user for next action:
 
 ### Example 1: Planning Undefined Milestone
 
-**Context**: M6 exists in progress.yaml but no milestone document
+**Context**: M6 exists in progress.yaml but no milestone document  
 
-**Invocation**: `@acp.plan`
+**Invocation**: `@acp.plan`  
 
 **Result**:
 ```
@@ -421,25 +444,25 @@ User: yes
 
 ### Example 2: Planning with Draft File
 
-**Context**: Have requirements draft prepared
+**Context**: Have requirements draft prepared  
 
-**Invocation**: `@acp.plan @agent/drafts/auth-feature.draft.md`
+**Invocation**: `@acp.plan @agent/drafts/auth-feature.draft.md`  
 
-**Result**: Reads draft, creates clarification if needed, generates milestone and tasks, updates progress.yaml
+**Result**: Reads draft, creates clarification if needed, generates milestone and tasks, updates progress.yaml  
 
 ### Example 3: Batch Planning
 
-**Context**: Multiple undefined items
+**Context**: Multiple undefined items  
 
-**Invocation**: `@acp.plan --all`
+**Invocation**: `@acp.plan --all`  
 
-**Result**: Plans all undefined milestones and tasks without prompting, generates report
+**Result**: Plans all undefined milestones and tasks without prompting, generates report  
 
 ### Example 4: New Feature Planning
 
-**Context**: No undefined items, want to plan new feature
+**Context**: No undefined items, want to plan new feature  
 
-**Invocation**: `@acp.plan`
+**Invocation**: `@acp.plan`  
 
 **Result**:
 ```
@@ -482,27 +505,27 @@ User: c
 
 ### Issue 1: No milestones in progress.yaml
 
-**Symptom**: Error "No milestones found"
+**Symptom**: Error "No milestones found"  
 
-**Solution**: Guide user through creating first milestone. Offer to create default milestone structure or collect requirements in chat.
+**Solution**: Guide user through creating first milestone. Offer to create default milestone structure or collect requirements in chat.  
 
 ### Issue 2: Ambiguous requirements
 
-**Symptom**: Cannot determine full requirements for a requested plan item
+**Symptom**: Cannot determine full requirements for a requested plan item  
 
-**Solution**: Create clarification document to gather missing details. Inform user this takes longer but yields better results.
+**Solution**: Create clarification document to gather missing details. Inform user this takes longer but yields better results.  
 
 ### Issue 3: Task numbering conflicts
 
-**Symptom**: Task numbers overlap or have gaps
+**Symptom**: Task numbers overlap or have gaps  
 
-**Solution**: Agent auto-detects highest task number across ALL milestones and increments. Gaps are acceptable.
+**Solution**: Agent auto-detects highest task number across ALL milestones and increments. Gaps are acceptable.  
 
 ### Issue 4: Milestone numbering gaps
 
-**Symptom**: M1, M2, M5 exist but M3, M4 missing
+**Symptom**: M1, M2, M5 exist but M3, M4 missing  
 
-**Solution**: Prompt user to either fill gaps or continue with M6. Offer options to refine requirements, create drafts, or skip to more defined milestones.
+**Solution**: Prompt user to either fill gaps or continue with M6. Offer options to refine requirements, create drafts, or skip to more defined milestones.  
 
 ---
 
@@ -567,11 +590,11 @@ Dependencies may be inferred from:
 
 ---
 
-**Namespace**: acp
-**Command**: plan
-**Version**: 1.0.0
-**Created**: 2026-02-22
-**Last Updated**: 2026-02-22
-**Status**: Active
-**Compatibility**: ACP 3.7.3+
-**Author**: ACP Project
+**Namespace**: acp  
+**Command**: plan  
+**Version**: 1.0.0  
+**Created**: 2026-02-22  
+**Last Updated**: 2026-02-22  
+**Status**: Active  
+**Compatibility**: ACP 3.7.3+  
+**Author**: ACP Project