@prmichaelsen/remember-mcp 3.19.3 → 4.0.0

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

@@ -6,18 +6,18 @@
 >
 > Follow the steps below to create a design document with proper namespace and automatic package updates.
 
-**Namespace**: acp
-**Version**: 1.0.0
-**Created**: 2026-02-21
-**Last Updated**: 2026-02-21
-**Status**: Active
-**Scripts**: None
+**Namespace**: acp  
+**Version**: 1.0.0  
+**Created**: 2026-02-21  
+**Last Updated**: 2026-02-21  
+**Status**: Active  
+**Scripts**: None  
 
 ---
 
-**Purpose**: Create design documents with namespace enforcement, draft support, and automatic package updates
-**Category**: Creation
-**Frequency**: As Needed
+**Purpose**: Create design documents with namespace enforcement, draft support, and automatic package updates  
+**Category**: Creation  
+**Frequency**: As Needed  
 
 ---
 
@@ -32,7 +32,7 @@ This command creates a new design document with intelligent namespace handling,
 - Auto-updates package.yaml and README.md
 - Uses design.template.md as base
 
-**Use this when**: Creating a new design document in an ACP project or package.
+**Use this when**: Creating a new design document in an ACP project or package.  
 
 ---
 
@@ -55,6 +55,7 @@ This command creates a new design document with intelligent namespace handling,
 | `--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,13 +72,13 @@ 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
 
 Check if draft file was provided as argument (same as pattern-create and command-create).
 
-**Expected Outcome**: Draft file read (if provided)
+**Expected Outcome**: Draft file read (if provided)  
 
 ### 2.5. Read Contextual Key Files
 
@@ -90,7 +91,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
 
@@ -104,7 +105,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 Design 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 Design Information
 
@@ -122,13 +123,13 @@ Gather information from user via chat:
 - Ask: "Describe what you want this design document to cover" OR
 - Offer: "Would you like to create an empty draft file first?"
 
-**Expected Outcome**: All design metadata collected
+**Expected Outcome**: All design metadata collected  
 
 ### 4. Process Draft (If Provided)
 
 If draft file was provided, create clarification if needed (same as pattern-create).
 
-**Expected Outcome**: Clarification created and answered (if needed)
+**Expected Outcome**: Clarification created and answered (if needed)  
 
 ### 5. Generate Design File
 
@@ -143,31 +144,31 @@ Create design file from template:
 - If Key Design Decisions section was generated in Step 2.7: Insert it into the design document
 - Save to `agent/design/{namespace}.{design-name}.md`
 
-**Expected Outcome**: Design file created
+**Expected Outcome**: Design file created  
 
 ### 6. Update package.yaml (If in Package)
 
 Add design to package.yaml contents (same as pattern-create and command-create).
 
-**Expected Outcome**: package.yaml updated
+**Expected Outcome**: package.yaml updated  
 
 ### 7. Update README.md (If in Package)
 
 Update README contents section (same as pattern-create and command-create).
 
-**Expected Outcome**: README.md updated with new design
+**Expected Outcome**: README.md updated with new design  
 
 ### 8. Prompt to Delete Draft (If Used)
 
 If draft file was used, ask to delete it.
 
-**Expected Outcome**: User chooses whether to keep draft
+**Expected Outcome**: User chooses whether to keep draft  
 
 ### 9. Report Success
 
 Display what was created.
 
-**Expected Outcome**: User knows design was created successfully
+**Expected Outcome**: User knows design was created successfully  
 
 ### 10. Prompt to Add to Key File Index
 
@@ -186,6 +187,22 @@ If yes:
 
 **Note**: If `agent/index/` does not exist, skip this step.
 
+### 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 design creation:
+  - Design file (`agent/design/{namespace}.{design-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(design): create {namespace}.{design-name} design document`)
+- Verify the commit succeeded
+
+**Expected Outcome**: All design artifacts committed to version control.
+
 ---
 
 ## Verification
@@ -199,6 +216,7 @@ If yes:
 - [ ] README.md updated (if package)
 - [ ] Design follows template structure
 - [ ] All metadata filled in correctly
+- [ ] **Design artifacts committed via `@git.commit` (MANDATORY — do not skip)**
 
 ---
 
@@ -218,19 +236,19 @@ If yes:
 
 ### Example 1: Creating Design in Package
 
-**Context**: In acp-firebase package directory
+**Context**: In acp-firebase package directory  
 
-**Invocation**: `@acp.design-create`
+**Invocation**: `@acp.design-create`  
 
-**Result**: Creates `agent/design/firebase.architecture.md`, updates package.yaml and README.md
+**Result**: Creates `agent/design/firebase.architecture.md`, updates package.yaml and README.md  
 
 ### Example 2: Creating Design in Project
 
-**Context**: In regular project (no package.yaml)
+**Context**: In regular project (no package.yaml)  
 
-**Invocation**: `@acp.design-create`
+**Invocation**: `@acp.design-create`  
 
-**Result**: Uses "local" namespace, creates `agent/design/local.my-design.md`, no package updates
+**Result**: Uses "local" namespace, creates `agent/design/local.my-design.md`, no package updates  
 
 ---
 
@@ -276,11 +294,11 @@ Same as @acp.pattern-create and @acp.command-create.
 
 ---
 
-**Namespace**: acp
-**Command**: design-create
-**Version**: 1.0.0
-**Created**: 2026-02-21
-**Last Updated**: 2026-02-21
-**Status**: Active
-**Compatibility**: ACP 2.2.0+
-**Author**: ACP Project
+**Namespace**: acp  
+**Command**: design-create  
+**Version**: 1.0.0  
+**Created**: 2026-02-21  
+**Last Updated**: 2026-02-21  
+**Status**: Active  
+**Compatibility**: ACP 2.2.0+  
+**Author**: ACP Project  

package/agent/commands/acp.design-reference.md

@@ -7,18 +7,18 @@
 >
 > If you are a command reading this file, follow the steps below to discover relevant design documents, extract actionable elements, and return them to the calling command.
 
-**Namespace**: acp
-**Version**: 1.0.0
-**Created**: 2026-03-07
-**Last Updated**: 2026-03-07
-**Status**: Active
-**Scripts**: None
+**Namespace**: acp  
+**Version**: 1.0.0  
+**Created**: 2026-03-07  
+**Last Updated**: 2026-03-07  
+**Status**: Active  
+**Scripts**: None  
 
 ---
 
-**Purpose**: Discover and cross-reference design documents to ensure tasks have complete implementation detail
-**Category**: Workflow (Internal Directive)
-**Frequency**: Called by task-create and proceed when design context is needed
+**Purpose**: Discover and cross-reference design documents to ensure tasks have complete implementation detail  
+**Category**: Workflow (Internal Directive)  
+**Frequency**: Called by task-create and proceed when design context is needed  
 
 ---
 
@@ -76,7 +76,7 @@ Extract topic keywords from the calling context to form a search query.
 - Combine into a search query (e.g., `clarification capture system directive`)
 - Strip common ACP terms that would match too broadly (`acp`, `command`, `task`, `system`, `implement`, `create`, `update`)
 
-**Expected Outcome**: Set of topic keywords for search
+**Expected Outcome**: Set of topic keywords for search  
 
 ### 2. Search for Design Documents
 
@@ -94,7 +94,7 @@ Search `agent/design/` for documents matching the topic.
 - Read all relevant documents in full
 - Sort by relevance score (filename matches > content matches)
 
-**Expected Outcome**: List of relevant design documents read and scored
+**Expected Outcome**: List of relevant design documents read and scored  
 
 ### 3. Report Findings
 
@@ -116,7 +116,7 @@ Design Reference: No design documents found for topic "{topic keywords}"
   Tasks will be created from available context only.
 ```
 
-**Expected Outcome**: User informed of which designs were found/skipped
+**Expected Outcome**: User informed of which designs were found/skipped  
 
 ### 4. Extract Design Elements
 
@@ -142,7 +142,7 @@ Parse the relevant design document(s) and extract all actionable elements organi
   - Which design section it came from
   - Which category it belongs to
 
-**Expected Outcome**: Complete inventory of design elements organized by category
+**Expected Outcome**: Complete inventory of design elements organized by category  
 
 ### 5. Flag Design Gaps
 
@@ -167,7 +167,7 @@ Suggest creating a clarification? (yes/no)
 - If user says **yes**: Suggest invoking `@acp.clarification-create` targeting the specific gaps. Halt the directive and let the user address gaps first.
 - If user says **no**: Proceed with available detail. Include a note about gaps in the returned data so the calling command can mention them in the task.
 
-**Expected Outcome**: Design gaps identified and user informed; decision made on whether to address them
+**Expected Outcome**: Design gaps identified and user informed; decision made on whether to address them  
 
 ### 6. Return Elements to Calling Command
 
@@ -183,7 +183,7 @@ Pass the extracted data back to the calling command.
 - **task-create**: Expand task steps with implementation detail from design elements; add verification items for each design requirement; set Design Reference metadata field; carry Key Design Decisions into the task
 - **proceed**: Load design context as supplementary "why" information during implementation; consult when ambiguity or edge cases arise
 
-**Expected Outcome**: Calling command receives structured design data for integration
+**Expected Outcome**: Calling command receives structured design data for integration  
 
 ---
 
@@ -247,33 +247,33 @@ design_names:
 
 ### Example 1: task-create finds relevant design
 
-**Context**: User invokes `@acp.task-create` for a task about "clarification capture"
+**Context**: User invokes `@acp.task-create` for a task about "clarification capture"  
 
-**Flow**: Directive searches `agent/design/`, matches `local.clarification-capture-system.md` by filename keywords, reads it, extracts 8-step directive flow + argument table + UX warning format + affected commands table + lifecycle rules. Returns all to task-create. Task is generated with full implementation detail.
+**Flow**: Directive searches `agent/design/`, matches `local.clarification-capture-system.md` by filename keywords, reads it, extracts 8-step directive flow + argument table + UX warning format + affected commands table + lifecycle rules. Returns all to task-create. Task is generated with full implementation detail.  
 
 ### Example 2: No design document exists
 
-**Context**: User invokes `@acp.task-create` for a task about "user preferences"
+**Context**: User invokes `@acp.task-create` for a task about "user preferences"  
 
-**Flow**: Directive searches `agent/design/`, no filenames match "preferences" (M6 has no design doc yet). Reports "No design documents found." Task is created from available context only (user input, draft, clarifications).
+**Flow**: Directive searches `agent/design/`, no filenames match "preferences" (M6 has no design doc yet). Reports "No design documents found." Task is created from available context only (user input, draft, clarifications).  
 
 ### Example 3: Multiple relevant designs
 
-**Context**: User invokes `@acp.task-create` for a task about "package validation"
+**Context**: User invokes `@acp.task-create` for a task about "package validation"  
 
-**Flow**: Directive finds both `acp-package-management-system.md` and `local.experimental-features-system.md` as relevant. Reads both. Extracts elements from each. Returns combined elements to task-create.
+**Flow**: Directive finds both `acp-package-management-system.md` and `local.experimental-features-system.md` as relevant. Reads both. Extracts elements from each. Returns combined elements to task-create.  
 
 ### Example 4: Design has gaps
 
-**Context**: User invokes `@acp.task-create` for a feature whose design has a TBD Testing Strategy
+**Context**: User invokes `@acp.task-create` for a feature whose design has a TBD Testing Strategy  
 
-**Flow**: Directive reads design, extracts elements, flags "Testing Strategy: marked TBD". Asks user whether to create clarification. User says no. Task is created with a note about the gap.
+**Flow**: Directive reads design, extracts elements, flags "Testing Strategy: marked TBD". Asks user whether to create clarification. User says no. Task is created with a note about the gap.  
 
 ### Example 5: proceed loads design context
 
-**Context**: Agent runs `@acp.proceed` on a task with `Design Reference: [Clarification Capture System](../design/local.clarification-capture-system.md)`
+**Context**: Agent runs `@acp.proceed` on a task with `Design Reference: [Clarification Capture System](../design/local.clarification-capture-system.md)`  
 
-**Flow**: Proceed reads the linked design document. Uses it as supplementary context during implementation — consulting it when the task step is ambiguous or when an unlisted edge case arises.
+**Flow**: Proceed reads the linked design document. Uses it as supplementary context during implementation — consulting it when the task step is ambiguous or when an unlisted edge case arises.  
 
 ---
 
@@ -291,27 +291,27 @@ design_names:
 
 ### Issue 1: Wrong design document matched
 
-**Symptom**: Directive loads an unrelated design document
+**Symptom**: Directive loads an unrelated design document  
 
-**Cause**: Keyword overlap on generic terms (e.g., "system", "command")
+**Cause**: Keyword overlap on generic terms (e.g., "system", "command")  
 
-**Solution**: Step 1 strips overly common terms. If false matches persist, the user can indicate which design is relevant when the report is displayed.
+**Solution**: Step 1 strips overly common terms. If false matches persist, the user can indicate which design is relevant when the report is displayed.  
 
 ### Issue 2: Design document not found despite existing
 
-**Symptom**: Directive reports "no design documents found" but one exists
+**Symptom**: Directive reports "no design documents found" but one exists  
 
-**Cause**: Filename keywords don't overlap with topic keywords
+**Cause**: Filename keywords don't overlap with topic keywords  
 
-**Solution**: User can provide additional context (mention the design doc name) or use a more specific task/milestone name. The calling command can also pass the design path explicitly if known.
+**Solution**: User can provide additional context (mention the design doc name) or use a more specific task/milestone name. The calling command can also pass the design path explicitly if known.  
 
 ### Issue 3: Too many elements extracted
 
-**Symptom**: Returned elements are overwhelming for a single task
+**Symptom**: Returned elements are overwhelming for a single task  
 
-**Cause**: Design document covers a broad feature with many tasks
+**Cause**: Design document covers a broad feature with many tasks  
 
-**Solution**: The calling command (task-create) filters elements by relevance to the specific task being created. Not all elements from the design need to appear in every task — only those relevant to the task's scope.
+**Solution**: The calling command (task-create) filters elements by relevance to the specific task being created. Not all elements from the design need to appear in every task — only those relevant to the task's scope.  
 
 ---
 
@@ -345,11 +345,11 @@ design_names:
 
 ---
 
-**Namespace**: acp
-**Command**: design-reference
-**Version**: 1.0.0
-**Created**: 2026-03-07
-**Last Updated**: 2026-03-07
-**Status**: Active
-**Compatibility**: ACP 5.13.1+
-**Author**: ACP Project
+**Namespace**: acp  
+**Command**: design-reference  
+**Version**: 1.0.0  
+**Created**: 2026-03-07  
+**Last Updated**: 2026-03-07  
+**Status**: Active  
+**Compatibility**: ACP 5.13.1+  
+**Author**: ACP Project  

package/agent/commands/acp.handoff.md

@@ -4,18 +4,18 @@
 > Pretend this command was entered with this additional context: "Execute directive `@acp-handoff 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-03-13
-**Last Updated**: 2026-03-13
-**Status**: Active
-**Scripts**: None
+**Namespace**: acp  
+**Version**: 1.0.0  
+**Created**: 2026-03-13  
+**Last Updated**: 2026-03-13  
+**Status**: Active  
+**Scripts**: None  
 
 ---
 
-**Purpose**: Generate a context-aware handoff report for transferring work to an agent in a different context (different repository, provider, etc.)
-**Category**: Workflow
-**Frequency**: As Needed
+**Purpose**: Generate a context-aware handoff report for transferring work to an agent in a different context (different repository, provider, etc.)  
+**Category**: Workflow  
+**Frequency**: As Needed  
 
 ---
 
@@ -66,7 +66,7 @@ Determine where the handoff is going.
 - Check `~/.acp/projects.yaml` to resolve project names to paths
 - If inference fails, ask the user: "Which project should this handoff target?"
 
-**Expected Outcome**: Target project identified (name and/or path)
+**Expected Outcome**: Target project identified (name and/or path)  
 
 ### 2. Gather Context from Conversation
 
@@ -80,7 +80,7 @@ Extract relevant information from the current chat session.
 - Note environment or dependency details only if they add necessary context
 - Optionally check `agent/progress.yaml` if task context is relevant
 
-**Expected Outcome**: Core handoff content gathered from conversation
+**Expected Outcome**: Core handoff content gathered from conversation  
 
 ### 3. Identify Source Project
 
@@ -91,7 +91,7 @@ Determine the source project details for back-reference.
 - Get the git remote URL if available
 - Include source project path/repo URL in the report so the receiving agent can reference back
 
-**Expected Outcome**: Source project location captured
+**Expected Outcome**: Source project location captured  
 
 ### 4. Generate Handoff Report
 
@@ -107,7 +107,7 @@ Write the handoff report in freeform markdown, shaped by the specific need.
 - If the target project is ACP-aware, suggest relevant files to read (e.g., `AGENT.md`), but keep the report generic enough for any agent
 - Do NOT include specific implementation steps — describe the problem and request, let the receiving agent decide how to solve it
 
-**Expected Outcome**: Handoff report generated
+**Expected Outcome**: Handoff report generated  
 
 ### 5. Deliver Handoff
 
@@ -118,7 +118,7 @@ Ask the user how they want to receive the report.
 - If **chat**: Output the full report directly in the conversation
 - If **disk**: Save to `agent/reports/handoff-{target-name}-{date}.md` (create `agent/reports/` if it doesn't exist)
 
-**Expected Outcome**: Handoff report delivered to user in their preferred format
+**Expected Outcome**: Handoff report delivered to user in their preferred format  
 
 ---
 
@@ -156,27 +156,27 @@ Paste the contents of this file into your agent session in the target project.
 
 ### Example 1: Cross-Repo Migration Handoff
 
-**Context**: Working in REST server project, discovered Weaviate schema needs a new field
+**Context**: Working in REST server project, discovered Weaviate schema needs a new field  
 
-**Invocation**: `@acp.handoff --to weaviate-schema`
+**Invocation**: `@acp.handoff --to weaviate-schema`  
 
-**Result**: Generates a report explaining that the REST server needs a new `embedding_model` field on the `Document` class, references the source project path, and describes the data model expectations — without prescribing how to write the migration.
+**Result**: Generates a report explaining that the REST server needs a new `embedding_model` field on the `Document` class, references the source project path, and describes the data model expectations — without prescribing how to write the migration.  
 
 ### Example 2: Inferred Target
 
-**Context**: Conversation mentions "the frontend repo needs to update its API client types"
+**Context**: Conversation mentions "the frontend repo needs to update its API client types"  
 
-**Invocation**: `@acp.handoff`
+**Invocation**: `@acp.handoff`  
 
-**Result**: Agent infers the target is the frontend project, checks `~/.acp/projects.yaml` for a match, generates the handoff report describing the API contract changes.
+**Result**: Agent infers the target is the frontend project, checks `~/.acp/projects.yaml` for a match, generates the handoff report describing the API contract changes.  
 
 ### Example 3: Output to Chat
 
-**Context**: Quick handoff, user doesn't need a file
+**Context**: Quick handoff, user doesn't need a file  
 
-**Invocation**: `@acp.handoff --to ~/projects/infra`
+**Invocation**: `@acp.handoff --to ~/projects/infra`  
 
-**Result**: Agent generates the report and outputs it directly in chat. User copies it into their next agent session.
+**Result**: Agent generates the report and outputs it directly in chat. User copies it into their next agent session.  
 
 ---
 
@@ -191,15 +191,15 @@ Paste the contents of this file into your agent session in the target project.
 
 ### Issue 1: Cannot infer target project
 
-**Symptom**: Agent asks "Which project should this handoff target?"
+**Symptom**: Agent asks "Which project should this handoff target?"  
 
-**Solution**: Provide the target explicitly with `--to` or `--target`, or register the project in `~/.acp/projects.yaml`.
+**Solution**: Provide the target explicitly with `--to` or `--target`, or register the project in `~/.acp/projects.yaml`.  
 
 ### Issue 2: Handoff report is too broad
 
-**Symptom**: Report includes too much session context
+**Symptom**: Report includes too much session context  
 
-**Solution**: The handoff should be narrow — focused on the specific problem and request, not a full session summary. If the report is too broad, re-invoke with more specific conversation context.
+**Solution**: The handoff should be narrow — focused on the specific problem and request, not a full session summary. If the report is too broad, re-invoke with more specific conversation context.  
 
 ---
 
@@ -260,11 +260,11 @@ Paste the contents of this file into your agent session in the target project.
 
 ---
 
-**Namespace**: acp
-**Command**: handoff
-**Version**: 1.0.0
-**Created**: 2026-03-13
-**Last Updated**: 2026-03-13
-**Status**: Active
-**Compatibility**: ACP 5.15.0+
-**Author**: ACP Project
+**Namespace**: acp  
+**Command**: handoff  
+**Version**: 1.0.0  
+**Created**: 2026-03-13  
+**Last Updated**: 2026-03-13  
+**Status**: Active  
+**Compatibility**: ACP 5.15.0+  
+**Author**: ACP Project