@prmichaelsen/reddit-mcp 0.1.0

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

@@ -0,0 +1,432 @@
+# Command: command-create
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.command-create` has been invoked.
+>
+> **This is a CREATION command - you will create files directly, no shell scripts needed.**
+>
+> Follow the steps below to create a command file 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
+
+---
+
+**Purpose**: Create command files with namespace enforcement, draft support, and automatic package updates
+**Category**: Creation
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command creates a new command file with intelligent namespace handling, optional draft file support, and automatic updates to package.yaml and README.md. It provides a guided workflow for creating well-structured commands that follow ACP conventions.
+
+**Key Features**:
+- Context-aware (detects if in package vs project)
+- Automatic namespace enforcement
+- Draft file support with clarification workflow
+- Auto-updates package.yaml and README.md
+- Uses command.template.md as base
+- Collects command-specific metadata (category, frequency)
+
+**Use this when**: Creating a new command in an ACP project or package.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in current directory
+- [ ] Command template exists (agent/commands/command.template.md)
+- [ ] (Optional) Draft file prepared if using draft workflow
+
+---
+
+## Arguments
+
+**Context Capture Arguments** (optional — passed to `@acp.clarification-capture` directive):
+
+| Argument | Alias | Behavior |
+|---|---|---|
+| `--from-clarification <file>` | `--from-clar` | Capture decisions from a specific clarification file |
+| `--from-clarifications` | `--from-clars` | Capture from all recent clarifications |
+| `--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` |
+
+**Default behavior** (no flags): Auto-detect clarifications and context in session.
+
+---
+
+## Steps
+
+### 1. Detect Context
+
+Determine if in package or project directory:
+
+**Actions**:
+- Check if package.yaml exists
+- If package: Infer namespace from package.yaml, directory, or git remote
+- If project: Use "local" namespace
+
+**Expected Outcome**: Context detected, namespace determined
+
+### 2. Check for Draft File
+
+Check if draft file was provided as argument:
+
+**Syntax**:
+- `@acp.command-create @my-draft.md` (@ reference)
+- `@acp.command-create agent/drafts/my-draft.md` (path)
+- `@acp.command-create` (no draft)
+
+**Actions**:
+- If draft provided: Read draft file
+- If no draft: Proceed to Step 3
+
+**Expected Outcome**: Draft file read (if provided)
+
+### 2.5. Read Contextual Key Files
+
+Before creating content, load relevant key files from the index.
+
+**Actions**:
+- Check if `agent/index/` directory exists
+- If exists, scan for all `*.yaml` files (excluding `*.template.yaml`)
+- Filter entries where `applies` includes `acp.command-create`
+- Sort by weight descending, read matching files
+- Produce visible output
+
+**Note**: If `agent/index/` does not exist, skip silently.
+
+### 2.7. Capture Clarification Context
+
+Invoke the `@acp.clarification-capture` shared directive to capture decisions from clarifications and/or chat context.
+
+**Actions**:
+- Read and follow the directive in [`agent/commands/acp.clarification-capture.md`](acp.clarification-capture.md)
+- Pass through any `--from-*` arguments from this command's invocation
+- If no `--from-*` flags specified: auto-detect clarifications in session (default behavior)
+- If uncaptured clarifications detected, show warning and ask user whether to include
+- Directive returns a "Key Design Decisions" markdown section (or nothing if no context)
+- Hold the generated section for insertion during Step 5 (Generate Command File)
+
+**Expected Outcome**: Key Design Decisions section generated (if context available), or skipped cleanly
+
+### 3. Collect Command Information
+
+Gather information from user via chat:
+
+**Information to Collect**:
+- **Command name** (without namespace prefix)
+  - Example: "deploy" (not "firebase.deploy")
+  - Validation: lowercase, alphanumeric, hyphens
+- **Command description** (one-line summary)
+  - Example: "Deploy Firebase functions to production"
+- **Command category**:
+  - Workflow
+  - Documentation
+  - Maintenance
+  - Creation
+  - Custom
+- **Command frequency**:
+  - Once
+  - Per Session
+  - As Needed
+  - Continuous
+- **Command arguments** (optional):
+  - Ask: "Does this command accept arguments? (yes/no)"
+  - If yes: Collect CLI-style flags and natural language mappings
+  - If no: Skip Arguments section in generated command
+- **Command version** (default: 1.0.0)
+
+**If no draft provided**:
+- Ask: "Describe what you want this command to accomplish" OR
+- Offer: "Would you like to create an empty draft file first?"
+
+**Expected Outcome**: All command 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)
+
+### 5. Generate Command File
+
+Create command file from template:
+
+**Actions**:
+- Determine full filename: `{namespace}.{command-name}.md`
+- Copy from command.template.md
+- **CRITICAL**: Copy the exact directive header from template (lines 3-5)
+  - Replace `@{namespace}-{command-name}` with actual values (e.g., `@firebase-deploy`)
+  - Do NOT modify the directive text itself
+  - This header is required for agents to recognize and execute the command
+  - Example: `> **🤖 Agent Directive**: If you are reading this file, the command @firebase-deploy has been invoked.`
+- Fill in metadata (name, version, date, description, category, frequency)
+- If command has arguments: Fill in Arguments section (before Prerequisites)
+- If no arguments: Remove Arguments section from template
+- If draft/clarification provided: Incorporate content
+- If no draft: Create from template with user-provided description
+- If Key Design Decisions section was generated in Step 2.7: Insert it into the command document
+- Save to `agent/commands/{namespace}.{command-name}.md`
+
+**Expected Outcome**: Command file created with proper directive header
+
+### 6. Update package.yaml (If in Package)
+
+Add command to package.yaml contents:
+
+**Actions**:
+- Read package.yaml
+- Add entry to contents.commands array:
+  ```yaml
+  - name: {namespace}.{command-name}.md
+    version: 1.0.0
+    description: {description}
+  ```
+- Save package.yaml
+
+**Expected Outcome**: package.yaml updated
+
+### 7. Update README.md (If in Package)
+
+Update README contents section:
+
+**Actions**:
+- Call `update_readme_contents()` from common.sh
+- Regenerates "What's Included" section from package.yaml
+
+**Expected Outcome**: README.md updated with new command
+
+### 8. Prompt to Delete Draft (If Used)
+
+If draft file was used, ask to delete it.
+
+**Expected Outcome**: User chooses whether to keep draft
+
+### 9. Report Success
+
+Display what was created:
+
+**Output**:
+```
+✅ Command Created Successfully!
+
+File: agent/commands/{namespace}.{command-name}.md
+Namespace: {namespace}
+Category: {category}
+Frequency: {frequency}
+Version: 1.0.0
+
+✓ Command file created
+✓ package.yaml updated (if package)
+✓ README.md updated (if package)
+
+Next steps:
+- Edit the command file to add detailed steps
+- Run @acp.package-validate to verify (if package)
+```
+
+**Expected Outcome**: User knows command was created successfully
+
+### 10. Prompt to Add to Key File Index
+
+After successful creation, offer to add the new file to the index (if `agent/index/` exists).
+
+**Display**:
+```
+Would you like to add this to the key file index?
+  - Yes, add to agent/index/local.main.yaml
+  - No, skip
+```
+
+If yes, prompt for weight (suggest 0.6 for commands), description, rationale, and applies values. Add entry to `agent/index/local.main.yaml`.
+
+**Note**: Skip silently if `agent/index/` does not exist.
+
+---
+
+## Verification
+
+- [ ] Context detected correctly (package vs project)
+- [ ] Namespace inferred or determined
+- [ ] Command information collected
+- [ ] Draft processed (if provided)
+- [ ] Command file created with correct namespace
+- [ ] **Directive header copied exactly from template**
+- [ ] **Namespace and command name replaced in directive**
+- [ ] **Directive text not modified**
+- [ ] package.yaml updated (if package)
+- [ ] README.md updated (if package)
+- [ ] Command follows template structure
+- [ ] All metadata filled in correctly
+
+---
+
+## Expected Output
+
+### Files Created
+- `agent/commands/{namespace}.{command-name}.md` - Command file
+- `agent/clarifications/clarification-{N}-command-{name}.md` - Clarification (if draft was ambiguous)
+
+### Files Modified
+- `package.yaml` - Command added to contents (if package)
+- `README.md` - Contents section updated (if package)
+
+### Example Command File Structure
+
+```markdown
+# Command: deploy
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@firebase-deploy` has been invoked.
+> Pretend this command was entered with this additional context: "Execute directive `@firebase-deploy 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**: firebase
+**Version**: 1.0.0
+**Created**: 2026-02-22
+**Last Updated**: 2026-02-22
+**Status**: Active
+
+---
+
+**Purpose**: Deploy Firebase functions to production
+**Category**: Workflow
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+[Command description...]
+
+## Prerequisites
+[Prerequisites...]
+
+## Steps
+[Implementation steps...]
+```
+
+---
+
+## Examples
+
+### Example 1: Creating Command in Package
+
+**Context**: In acp-firebase package directory
+
+**Invocation**: `@acp.command-create`
+
+**Interaction**:
+```
+Agent: Detected package context. Namespace: firebase
+
+Agent: What would you like to name your command? (without namespace prefix)
+User: deploy
+
+Agent: Provide a one-line description:
+User: Deploy Firebase functions to production
+
+Agent: Command category? (Workflow/Documentation/Maintenance/Creation/Custom)
+User: Workflow
+
+Agent: Command frequency? (Once/Per Session/As Needed/Continuous)
+User: As Needed
+
+Agent: Command version? (default: 1.0.0)
+User: [Enter]
+
+✅ Command Created Successfully!
+
+File: agent/commands/firebase.deploy.md
+Namespace: firebase
+Category: Workflow
+Frequency: As Needed
+Version: 1.0.0
+
+✓ Command file created
+✓ package.yaml updated
+✓ README.md updated
+```
+
+### Example 2: Creating Command in Project
+
+**Context**: In regular project (no package.yaml)
+
+**Invocation**: `@acp.command-create`
+
+**Result**: Uses "local" namespace, creates `agent/commands/local.my-command.md`, no package updates
+
+---
+
+## Related Commands
+
+- [`@acp.pattern-create`](acp.pattern-create.md) - Create patterns
+- [`@acp.design-create`](acp.design-create.md) - Create designs
+- [`@acp.package-validate`](acp.package-validate.md) - Validate package after creation
+
+---
+
+## Troubleshooting
+
+### Issue 1: Namespace inference failed
+
+**Symptom**: Cannot determine namespace
+
+**Solution**: Provide namespace manually when prompted, or check package.yaml exists and has name field
+
+### Issue 2: Invalid command name
+
+**Symptom**: Command name rejected
+
+**Solution**: Use lowercase, alphanumeric, and hyphens only. No spaces or special characters.
+
+### Issue 3: package.yaml update failed
+
+**Symptom**: Error updating package.yaml
+
+**Solution**: Verify package.yaml exists and is valid YAML. Run @acp.package-validate to check.
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: package.yaml, draft files, command templates
+- **Writes**: agent/commands/{namespace}.{name}.md, package.yaml, README.md
+- **Executes**: None
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Never include secrets in commands
+- **Credentials**: Never include credentials
+
+---
+
+## Notes
+
+- Command name should be descriptive and action-oriented
+- Namespace is automatically added to filename
+- Draft files can be any format (free-form markdown)
+- Clarifications are created only if draft is ambiguous
+- package.yaml and README.md updates are automatic in packages
+- In non-package projects, uses "local" namespace
+- Category and frequency help users understand command purpose
+
+---
+
+**Namespace**: acp
+**Command**: command-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-create.md

@@ -0,0 +1,286 @@
+# Command: design-create
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.design-create` has been invoked.
+>
+> **This is a CREATION command - you will create files directly, no shell scripts needed.**
+>
+> 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
+
+---
+
+**Purpose**: Create design documents with namespace enforcement, draft support, and automatic package updates
+**Category**: Creation
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command creates a new design document with intelligent namespace handling, optional draft file support, and automatic updates to package.yaml and README.md. It provides a guided workflow for creating well-structured design documents that follow ACP conventions.
+
+**Key Features**:
+- Context-aware (detects if in package vs project)
+- Automatic namespace enforcement
+- Draft file support with clarification workflow
+- 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.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in current directory
+- [ ] Design template exists (agent/design/design.template.md)
+- [ ] (Optional) Draft file prepared if using draft workflow
+
+---
+
+## Arguments
+
+**Context Capture Arguments** (optional — passed to `@acp.clarification-capture` directive):
+
+| Argument | Alias | Behavior |
+|---|---|---|
+| `--from-clarification <file>` | `--from-clar` | Capture decisions from a specific clarification file |
+| `--from-clarifications` | `--from-clars` | Capture from all recent clarifications |
+| `--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` |
+
+**Default behavior** (no flags): Auto-detect clarifications and context in session.
+
+---
+
+## Steps
+
+### 1. Detect Context
+
+Determine if in package or project directory:
+
+**Actions**:
+- Check if package.yaml exists
+- If package: Infer namespace from package.yaml, directory, or git remote
+- If project: Use "local" namespace
+
+**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)
+
+### 2.5. Read Contextual Key Files
+
+Before creating content, load relevant key files from the index.
+
+**Actions**:
+- Check if `agent/index/` directory exists
+- If exists, scan for all `*.yaml` files (excluding `*.template.yaml`)
+- Filter entries where `applies` includes `acp.design-create`
+- Sort by weight descending, read matching files
+- Produce visible output
+
+**Note**: If `agent/index/` does not exist, skip silently.
+
+### 2.7. Capture Clarification Context
+
+Invoke the `@acp.clarification-capture` shared directive to capture decisions from clarifications and/or chat context.
+
+**Actions**:
+- Read and follow the directive in [`agent/commands/acp.clarification-capture.md`](acp.clarification-capture.md)
+- Pass through any `--from-*` arguments from this command's invocation
+- If no `--from-*` flags specified: auto-detect clarifications in session (default behavior)
+- If uncaptured clarifications detected, show warning and ask user whether to include
+- 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
+
+### 3. Collect Design Information
+
+Gather information from user via chat:
+
+**Information to Collect**:
+- **Design name** (without namespace prefix)
+  - Example: "architecture" (not "firebase.architecture")
+  - Validation: lowercase, alphanumeric, hyphens
+- **Design description** (one-line summary)
+  - Example: "Firebase integration architecture and patterns"
+- **Design version** (default: 1.0.0)
+
+**If no draft provided**:
+- 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
+
+### 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)
+
+### 5. Generate Design File
+
+Create design file from template:
+
+**Actions**:
+- Determine full filename: `{namespace}.{design-name}.md`
+- Copy from design.template.md
+- Fill in metadata (name, version, date, description)
+- If draft/clarification provided: Incorporate content
+- If no draft: Create from template with user-provided description
+- 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
+
+### 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
+
+### 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
+
+### 8. Prompt to Delete Draft (If Used)
+
+If draft file was used, ask to delete it.
+
+**Expected Outcome**: User chooses whether to keep draft
+
+### 9. Report Success
+
+Display what was created.
+
+**Expected Outcome**: User knows design was created successfully
+
+### 10. Prompt to Add to Key File Index
+
+After successful creation, offer to add the new file to the index.
+
+**Display**:
+```
+Would you like to add this to the key file index?
+  - Yes, add to agent/index/local.main.yaml
+  - No, skip
+```
+
+If yes:
+- Prompt for weight (suggest 0.7 for designs), description, rationale, and applies values
+- Add entry to `agent/index/local.main.yaml` (create file from template if it doesn't exist)
+
+**Note**: If `agent/index/` does not exist, skip this step.
+
+---
+
+## Verification
+
+- [ ] Context detected correctly (package vs project)
+- [ ] Namespace inferred or determined
+- [ ] Design information collected
+- [ ] Draft processed (if provided)
+- [ ] Design file created with correct namespace
+- [ ] package.yaml updated (if package)
+- [ ] README.md updated (if package)
+- [ ] Design follows template structure
+- [ ] All metadata filled in correctly
+
+---
+
+## Expected Output
+
+### Files Created
+- `agent/design/{namespace}.{design-name}.md` - Design file
+- `agent/clarifications/clarification-{N}-design-{name}.md` - Clarification (if draft was ambiguous)
+
+### Files Modified
+- `package.yaml` - Design added to contents (if package)
+- `README.md` - Contents section updated (if package)
+
+---
+
+## Examples
+
+### Example 1: Creating Design in Package
+
+**Context**: In acp-firebase package directory
+
+**Invocation**: `@acp.design-create`
+
+**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)
+
+**Invocation**: `@acp.design-create`
+
+**Result**: Uses "local" namespace, creates `agent/design/local.my-design.md`, no package updates
+
+---
+
+## Related Commands
+
+- [`@acp.pattern-create`](acp.pattern-create.md) - Create patterns
+- [`@acp.command-create`](acp.command-create.md) - Create commands
+- [`@acp.package-validate`](acp.package-validate.md) - Validate package after creation
+
+---
+
+## Troubleshooting
+
+Same as @acp.pattern-create and @acp.command-create.
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: package.yaml, draft files, design templates
+- **Writes**: agent/design/{namespace}.{name}.md, package.yaml, README.md
+- **Executes**: None
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Never include secrets in designs
+- **Credentials**: Never include credentials
+
+---
+
+## Notes
+
+- Design name should be descriptive and specific
+- Namespace is automatically added to filename
+- Draft files can be any format (free-form markdown)
+- Clarifications are created only if draft is ambiguous
+- package.yaml and README.md updates are automatic in packages
+- In non-package projects, uses "local" namespace
+
+---
+
+**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