@prmichaelsen/acp-visualizer 0.1.0 → 0.1.2

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

@@ -1,432 +0,0 @@
-# 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

@@ -1,286 +0,0 @@
-# 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