@prmichaelsen/reddit-mcp 0.1.0

package/agent/commands/acp.index.md

@@ -0,0 +1,423 @@
+# Command: index
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp-index` has been invoked. Follow the steps below to execute this command.
+> Pretend this command was entered with this additional context: "Execute directive `@acp-index` 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-02
+**Last Updated**: 2026-03-02
+**Status**: Active
+**Scripts**: None
+
+---
+
+**Purpose**: Manage the key file index — list, add, remove, explore, and show indexed key files
+**Category**: Maintenance
+**Frequency**: As Needed
+
+---
+
+## Arguments
+
+This command supports both CLI-style subcommands and natural language arguments.
+
+### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| (none) / `list` | List all indexed key files (default) |
+| `add <path>` | Add a file to `agent/index/local.main.yaml` |
+| `remove <path>` | Remove a file from `agent/index/local.main.yaml` |
+| `explore` | Scan codebase and suggest key files to add |
+| `show` | Show full metadata for all entries |
+
+### Natural Language (Fuzzy Matching)
+
+| Example | Detected Subcommand |
+|---------|---------------------|
+| `@acp.index` | list |
+| `@acp.index show all files` | show |
+| `@acp.index add the testing pattern` | add (infer path from "testing pattern") |
+| `@acp.index remove requirements.md` | remove |
+| `@acp.index what should I add?` | explore |
+| `@acp.index suggest key files` | explore |
+
+**Matching rules**:
+- Look for keywords: `add`, `remove`, `delete`, `explore`, `suggest`, `scan`, `show`, `detail`, `list`
+- If a path is provided after `add`/`remove`, use it directly
+- If a description is given instead of path (e.g., "the testing pattern"), search the codebase for matching files
+- Default to `list` if no subcommand detected
+
+---
+
+## What This Command Does
+
+This command manages the ACP Key File Index system. The key file index is a weighted list of critical project files stored in `agent/index/` that agents must read before taking action. This command provides a convenient interface for viewing, adding, removing, and discovering index entries without manually editing YAML.
+
+Use this when you want to see what files are indexed, add newly created files, remove stale entries, or discover files that should be indexed based on codebase analysis.
+
+See also: `agent/design/local.key-file-index-system.md`
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/index/` directory exists (created by `acp.install.sh` or Task 99)
+
+---
+
+## Steps
+
+### 1. Check Index Directory
+
+**Actions**:
+- Check if `agent/index/` directory exists
+- If not: warn user and suggest running `mkdir -p agent/index`
+- List all `*.yaml` files (excluding `*.template.yaml`)
+
+**Expected Outcome**: Index directory confirmed, files discovered
+
+### 2. Parse Arguments
+
+**Actions**:
+- Detect subcommand from flags or natural language (see Arguments section)
+- If ambiguous, default to `list`
+- If `add`/`remove` with natural language path description, search codebase to resolve to actual path
+
+**Expected Outcome**: Subcommand and arguments determined
+
+### 3. Execute Subcommand
+
+Branch to the appropriate subcommand handler below.
+
+---
+
+### Subcommand: `list` (Default)
+
+List all indexed key files across all namespaces in a compact table.
+
+**Actions**:
+- Parse all index YAML files in `agent/index/`
+- Group entries by namespace
+- Sort within each namespace by weight descending
+
+**Display format**:
+```
+📑 Key File Index (7 entries across 2 namespaces)
+
+local (4 entries):
+  1.0  requirements  agent/design/requirements.md
+  0.8  pattern       agent/patterns/local.e2e-testing.md
+  0.7  design        agent/design/local.architecture.md
+  0.6  design        src/core/state-machine.ts
+
+core-sdk (3 entries):
+  0.5  pattern       agent/patterns/core-sdk.service-base.md
+  0.4  pattern       agent/patterns/core-sdk.testing-unit.md
+  0.3  design        agent/design/core-sdk.architecture.md
+```
+
+**If no index files found**:
+```
+📑 Key File Index: Empty
+
+No index files found in agent/index/.
+Run @acp.index explore to discover key files, or @acp.index add <path> to add one.
+```
+
+---
+
+### Subcommand: `add <path>`
+
+Add a file to `agent/index/local.main.yaml`.
+
+**Actions**:
+1. Validate the file exists at the given path
+2. Check if it's already in any index file (warn if duplicate)
+3. Prompt for required metadata:
+   - **weight** (suggest based on kind: 0.9 for requirements, 0.8 for patterns, 0.7 for designs)
+   - **kind** (pattern, command, design, requirements)
+   - **description** (what the file contains)
+   - **rationale** (why it should be in the index)
+   - **applies** (comma-separated fully qualified command names)
+4. Append entry to `agent/index/local.main.yaml`
+   - If file doesn't exist, create it from `local.main.template.yaml`
+5. Check recommended limits:
+   - Warn if local namespace exceeds 10 entries
+   - Warn if total across namespaces exceeds 20 entries
+
+**Display on success**:
+```
+✅ Added to key file index:
+
+  path: agent/patterns/local.my-pattern.md
+  weight: 0.8
+  kind: pattern
+  applies: acp.proceed, acp.task-create
+
+  Local namespace: 5 entries (within limits)
+```
+
+---
+
+### Subcommand: `remove <path>`
+
+Remove a file from `agent/index/local.main.yaml`.
+
+**Actions**:
+1. Find entry by path in `agent/index/local.main.yaml`
+2. If not found: report error, suggest checking `@acp.index list`
+3. If found: show the entry and confirm removal
+4. Remove entry from YAML file
+
+**Note**: Only entries in `local.*.yaml` can be removed via this command. Package index entries should be managed via package updates.
+
+**Display on success**:
+```
+✅ Removed from key file index:
+
+  path: agent/patterns/local.old-pattern.md
+  was: weight 0.8, pattern
+
+  Local namespace: 3 entries remaining
+```
+
+---
+
+### Subcommand: `explore`
+
+Scan the codebase and suggest files that should be indexed.
+
+**Actions**:
+1. List all files in `agent/design/` (excluding templates)
+2. List all files in `agent/patterns/` (excluding templates)
+3. Check for `requirements.md`, `architecture` design docs
+4. Cross-reference with all existing index entries
+5. Present un-indexed files as suggestions with recommended metadata
+
+**Display format**:
+```
+🔍 Exploring codebase for key files...
+
+Found 4 un-indexed files:
+
+  1. agent/design/requirements.md
+     Suggested: weight 1.0, kind: requirements
+     Applies: acp.init, acp.design-create, acp.task-create, acp.plan, acp.proceed
+
+  2. agent/patterns/local.library-services.md
+     Suggested: weight 0.7, kind: pattern
+     Applies: acp.proceed, acp.task-create
+
+  3. agent/design/yaml-parser-design.md
+     Suggested: weight 0.6, kind: design
+     Applies: acp.proceed
+
+  4. agent/design/acp-package-development-system.md
+     Suggested: weight 0.6, kind: design
+     Applies: acp.design-create, acp.plan
+
+Would you like to add any of these? (enter numbers, "all", or "none")
+```
+
+If user selects entries:
+- Prompt for confirmation/adjustment of suggested metadata
+- Add selected entries to `agent/index/local.main.yaml`
+
+---
+
+### Subcommand: `show`
+
+Show full metadata for all index entries across all namespaces.
+
+**Actions**:
+- Parse all index YAML files
+- Display every field for every entry
+- Group by namespace and qualifier
+
+**Display format**:
+```
+📑 Key File Index — Full Details
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  local.main.yaml (4 entries)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  path:        agent/design/acp-commands-design.md
+  weight:      0.9
+  kind:        design
+  description: Core design document for the ACP command system.
+  rationale:   Essential context for creating or modifying any ACP command.
+  applies:     acp.command-create, acp.design-create, acp.plan
+
+  ─────────────────────────────────────────
+
+  path:        agent/patterns/local.e2e-testing.md
+  weight:      0.8
+  kind:        pattern
+  description: E2E testing pattern used across all test suites.
+  rationale:   Prevents agents from writing tests that don't follow conventions.
+  applies:     acp.task-create, acp.proceed
+
+  [... more entries ...]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  core-sdk.main.yaml (3 entries)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  [... entries ...]
+```
+
+---
+
+## Verification
+
+- [ ] `agent/index/` directory checked
+- [ ] Subcommand detected from arguments or NLP
+- [ ] `list`: All entries displayed grouped by namespace
+- [ ] `add`: File validated, metadata collected, entry appended, limits checked
+- [ ] `remove`: Entry found, confirmed, removed from YAML
+- [ ] `explore`: Un-indexed files discovered and presented with suggestions
+- [ ] `show`: Full metadata displayed for all entries
+
+---
+
+## Expected Output
+
+### Files Modified
+- `agent/index/local.main.yaml` — Modified by `add` and `remove` subcommands
+
+### Console Output
+See display formats for each subcommand above.
+
+---
+
+## Examples
+
+### Example 1: Listing Indexed Files
+
+**Context**: Want to see what's currently indexed
+
+**Invocation**: `@acp.index`
+
+**Result**: Displays compact table of all indexed files grouped by namespace
+
+### Example 2: Adding a New Pattern
+
+**Context**: Just created a new pattern and want to index it
+
+**Invocation**: `@acp.index add agent/patterns/local.api-conventions.md`
+
+**Result**: Prompts for weight/kind/description/rationale/applies, adds to local.main.yaml
+
+### Example 3: Exploring for Missing Files
+
+**Context**: Want to discover what files should be indexed
+
+**Invocation**: `@acp.index explore`
+
+**Result**: Scans agent/design/ and agent/patterns/, shows un-indexed files with suggestions
+
+### Example 4: Natural Language Add
+
+**Context**: Want to add a file using description instead of path
+
+**Invocation**: `@acp.index add the e2e testing pattern`
+
+**Result**: Agent searches for matching file, finds `agent/patterns/local.e2e-testing.md`, proceeds with add flow
+
+### Example 5: Removing a Stale Entry
+
+**Context**: A file was deleted but still in the index
+
+**Invocation**: `@acp.index remove agent/design/old-feature.md`
+
+**Result**: Finds entry, confirms removal, updates local.main.yaml
+
+---
+
+## Related Commands
+
+- [`@acp.init`](acp.init.md) - Reads key files during initialization (step 2.8)
+- [`@acp.proceed`](acp.proceed.md) - Reads contextual key files before task execution
+- [`@acp.validate`](acp.validate.md) - Validates index file paths and schema
+- [`@acp.design-create`](acp.design-create.md) - Prompts to add new designs to index
+- [`@acp.pattern-create`](acp.pattern-create.md) - Prompts to add new patterns to index
+
+---
+
+## Troubleshooting
+
+### Issue 1: No agent/index/ directory
+
+**Symptom**: Warning "agent/index/ directory not found"
+
+**Cause**: ACP installed before key file index system was available
+
+**Solution**: Run `mkdir -p agent/index` to create the directory
+
+### Issue 2: File not found when adding
+
+**Symptom**: Error "File does not exist: <path>"
+
+**Cause**: Path is incorrect or file was deleted
+
+**Solution**: Verify the file path. Use `@acp.index explore` to discover files automatically.
+
+### Issue 3: Cannot remove package index entry
+
+**Symptom**: Error "Entry is in package index, not local"
+
+**Cause**: Trying to remove an entry from a package-shipped index file
+
+**Solution**: Package index entries are managed by the package. Use `@acp.package-update` or `@acp.package-remove` to modify package indices.
+
+### Issue 4: Exceeding recommended limits
+
+**Symptom**: Warning about too many entries
+
+**Cause**: Index has more than 10 entries per namespace or 20 total
+
+**Solution**: Review entries and remove lower-priority ones. The index should focus on truly critical files.
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `agent/index/*.yaml`, `agent/design/*`, `agent/patterns/*`
+- **Writes**: `agent/index/local.main.yaml` (add/remove operations)
+- **Executes**: None
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Never includes secrets in index entries
+- **Credentials**: Does not access credentials
+
+---
+
+## Notes
+
+- This is an LLM-based command — no shell scripts, the agent interprets and executes directly
+- Only `local.*.yaml` files can be modified by this command; package indices are read-only
+- The `explore` subcommand uses heuristics to suggest files, not exhaustive analysis
+- Entries are YAML — the agent must maintain valid YAML when adding/removing
+- Recommended limits are advisory, not enforced: 5-10 per namespace, 15-20 total
+- The `applies` field should use fully qualified command names (e.g., `acp.init`, `core-sdk.bootstrap`)
+
+---
+
+**Namespace**: acp
+**Command**: index
+**Version**: 1.0.0
+**Created**: 2026-03-02
+**Last Updated**: 2026-03-02
+**Status**: Active
+**Compatibility**: ACP 5.10.0+
+**Author**: ACP Project