From 0780b4c17d19f43e7f8abf906cb0fde1429b75b9 Mon Sep 17 00:00:00 2001
From: OpenCode Test <test@opencode.ai>
Date: Wed, 7 Jan 2026 11:28:56 -0800
Subject: [PATCH] Document plans index in CLAUDE.md and plans/README.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add plans/ to directory structure
- Add plans/index.json to shared state files table
- Add Plans row to component formats table
- Create plans/README.md with schema and query examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md       |  4 +++
 plans/README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 plans/README.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 227b36f..4697e0e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -45,6 +45,8 @@ See `agents/README.md` for details on agent files and execution.
 ├── commands/                    # Slash command definitions
 ├── workflows/                   # Workflow definitions (design docs)
 │   └── README.md
+├── plans/                       # Implementation plans
+│   └── index.json               # Plan status registry
 ├── state/                       # Shared state files (JSON)
 │   ├── sysadmin/
 │   ├── programmer/
@@ -67,6 +69,7 @@ All agents MUST read and follow the processes defined in these files:
 | `state/personal-assistant-preferences.json` | PA persistent config | personal-assistant |
 | `state/personal-assistant/general-instructions.json` | User memory | personal-assistant |
 | `state/kb.json` | Shared knowledge base | personal-assistant |
+| `plans/index.json` | Plan status registry | any agent |
 
 ## Key Processes
 
@@ -126,6 +129,7 @@ curl -s -X PATCH \
 | **Skills** | SKILL.md + scripts/ + references/ | `skills/` |
 | **Commands** | Markdown + YAML frontmatter | `commands/` |
 | **Workflows** | YAML (design docs, not auto-executed) | `workflows/` |
+| **Plans** | Markdown + index.json | `plans/` |
 | **State** | JSON | `state/` |
 | **Hooks** | JSON | `hooks/` |
 
diff --git a/plans/README.md b/plans/README.md
new file mode 100644
index 0000000..28ec973
--- /dev/null
+++ b/plans/README.md
@@ -0,0 +1,74 @@
+# Plans
+
+Implementation plans for features, enhancements, and investigations.
+
+## Structure
+
+```
+plans/
+├── index.json              # Status registry (source of truth)
+├── README.md               # This file
+└── *.md                    # Individual plan files
+```
+
+## Plan Naming
+
+- **Dated plans**: `YYYY-MM-DD-descriptive-name.md` (design docs)
+- **Generated names**: `adjective-verb-scientist.md` (brainstorming outputs)
+
+## Status Registry (index.json)
+
+Central tracking for all plans:
+
+```json
+{
+  "plan-name": {
+    "title": "Human readable title",
+    "status": "pending|implemented|partial|abandoned|superseded",
+    "created": "YYYY-MM-DD",
+    "implemented": "YYYY-MM-DD",
+    "category": "feature|enhancement|bugfix|diagnostic|design",
+    "notes": "Optional notes"
+  }
+}
+```
+
+### Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Not yet implemented |
+| `implemented` | Fully implemented |
+| `partial` | Partially implemented |
+| `abandoned` | Decided not to implement |
+| `superseded` | Replaced by another plan |
+
+### Categories
+
+| Category | Meaning |
+|----------|---------|
+| `feature` | New capability |
+| `enhancement` | Improve existing feature |
+| `bugfix` | Fix an issue |
+| `diagnostic` | One-time investigation |
+| `design` | Design document for reference |
+
+## Querying Plans
+
+```bash
+# List pending plans
+jq -r '.plans | to_entries[] | select(.value.status == "pending") | .key' index.json
+
+# List by category
+jq '.plans | to_entries[] | select(.value.category == "feature")' index.json
+
+# Count by status
+jq '.plans | to_entries | group_by(.value.status) | map({status: .[0].value.status, count: length})' index.json
+```
+
+## Workflow
+
+1. **Create plan**: Write `plans/plan-name.md`
+2. **Register**: Add entry to `index.json` with `status: "pending"`
+3. **Implement**: Execute the plan
+4. **Update**: Set `status: "implemented"` and add `implemented` date