From e48105f98aec203b8285d3a11aaa1b55f70c5c0a Mon Sep 17 00:00:00 2001
From: Patrick Singletary <PSingletary@users.noreply.github.com>
Date: Fri, 14 Aug 2026 07:42:46 -0400
Subject: [PATCH] Add plan intake: docs/plans/ drop zone, REGISTRY.md, archive;
 no auto-pickup

---
 AGENTS.md                    | 17 +++++++++++++++++
 docs/plans/README.md         | 20 ++++++++++++++++++++
 docs/plans/REGISTRY.md       | 28 ++++++++++++++++++++++++++++
 docs/plans/archive/README.md |  4 ++++
 4 files changed, 69 insertions(+)
 create mode 100644 docs/plans/README.md
 create mode 100644 docs/plans/REGISTRY.md
 create mode 100644 docs/plans/archive/README.md

diff --git a/AGENTS.md b/AGENTS.md
index 5202403..0e8e68f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,3 +3,20 @@
 Conventions: AGENTS.md is the primary agent instructions file; .hermes.md (if present) is secondary.
 
 For any frontend/UI design, redesign, critique, audit, polish, or visual work, load the `impeccable` skill first (skill_view name='impeccable') and follow it.
+
+## Plan intake (docs/plans/)
+
+Claude-generated PLAN-*.md files (from Kagi discussions) are dropped in
+`docs/plans/`. Rules:
+
+- NEVER auto-pick-up or auto-build. No cron, no watchers, no automatic
+  processing. Plans are picked up ONLY on explicit user request
+  ("pick up PLAN-x.md").
+- Pickup flow: read plan -> create ~/dev/<slug> via ~/scripts/project-init.sh
+  (scaffold only, zero features) -> write TODO.md breakdown -> report project ID
+  to the user.
+- Build starts ONLY after explicit user approval (every build step consumes
+  Nous credits; user curates all projects).
+- After pickup: move the PLAN file to docs/plans/archive/ and add a row to
+  docs/plans/REGISTRY.md (plan -> project ID -> status).
+
diff --git a/docs/plans/README.md b/docs/plans/README.md
new file mode 100644
index 0000000..73ecc26
--- /dev/null
+++ b/docs/plans/README.md
@@ -0,0 +1,20 @@
+# docs/plans — Plan intake
+
+Drop Claude-generated PLAN-*.md files here (from Kagi discussions). Nothing
+happens automatically. To pick one up, tell Hermes: "pick up PLAN-<name>.md".
+
+## Workflow
+
+1. User drops PLAN-*.md in this folder (committed to Tangled).
+2. User explicitly asks Hermes to pick up a plan.
+3. Hermes: reads plan -> creates ~/dev/<slug> via ~/scripts/project-init.sh
+   (scaffold only, zero features) -> writes TODO.md breakdown -> reports the
+   project ID.
+4. Plan file moves to archive/ + REGISTRY.md updated.
+5. Building starts ONLY on explicit user approval (cost control — every build
+   step consumes Hermes/Nous credits; user curates everything).
+
+## Files
+
+- REGISTRY.md — plan -> project ID -> status tracker
+- archive/ — processed plans, kept for provenance
diff --git a/docs/plans/REGISTRY.md b/docs/plans/REGISTRY.md
new file mode 100644
index 0000000..478441a
--- /dev/null
+++ b/docs/plans/REGISTRY.md
@@ -0,0 +1,28 @@
+# Plans Registry
+
+Track Claude-generated PLAN-*.md files dropped in this folder, the project IDs
+created from them, and their status. One row per plan.
+
+## Status values
+
+| Status    | Meaning                                             |
+|-----------|-----------------------------------------------------|
+| inbox     | Dropped in docs/plans/, not yet picked up           |
+| scaffold  | Project dir created (scaffold only, no features)    |
+| building  | Actively building, user-approved                    |
+| done      | Shipped / parked                                    |
+
+## Rules (hard)
+
+- NEVER auto-pick-up or auto-build. Plans are processed only on explicit
+  user request ("pick up PLAN-x.md").
+- Pickup = read plan -> create ~/dev/<slug> via project-init.sh (scaffold
+  only, zero features) -> write TODO.md breakdown -> report project ID.
+- Build starts ONLY after the user explicitly approves.
+- After pickup: move PLAN file to docs/plans/archive/ and update this file.
+
+## Registry
+
+| Plan file | Project ID | Project dir  | Status  | Picked up  | Notes |
+|-----------|------------|--------------|---------|------------|-------|
+|           |            |              |         |            |       |
diff --git a/docs/plans/archive/README.md b/docs/plans/archive/README.md
new file mode 100644
index 0000000..eed87c9
--- /dev/null
+++ b/docs/plans/archive/README.md
@@ -0,0 +1,4 @@
+# Archive for processed PLAN-*.md files.
+
+Processed plans move here from docs/plans/ after pickup; see REGISTRY.md for
+the plan -> project ID mapping.
-- 
2.51.2