block · mpawliszyn · Mar 14, 2026
@@ -0,0 +1,2 @@
+# Private research and working documents
+docs/private/
@@ -25,13 +25,22 @@ scripts/
   coverage-report.sh        # Coverage summary from tree
   check-tree-quality.sh     # Structural quality validation
 
+templates/
+  review-tree.md            # Format spec: the tree IS the state
+  review-comments.md        # Format spec: comment store
+
+troubleshoot/
+  agent-struggling.md       # Diagnostic guide loaded on agent failure
+
 tests/
   scripts/                  # bats-core tests for shell scripts
   formats/                  # Sample format files for validation
 
 docs/
-  templates/                # Format templates (review-tree, review-comments, user-hints)
-  troubleshoot/             # Diagnostic guides loaded only on failure
+  guides/                   # Version-independent development guidance
+  hackweek/                 # Feb 23-26 2026 sprint archive
+  v1/                       # Active V1 work: plans, designs, decision records
+  private/                  # Investigation workbench (scratch and reconstruction work)
 ```
 
 ## Conventions
@@ -81,10 +90,23 @@ Files in this repo are loaded into LLM context windows during operation. Stale r
 When adding forward-looking version notes to files, add an entry here so future agents know to clean them up.
 
 **Known examples:**
-- `docs/templates/review-comments.md` has a **V1.1 Posting Compatibility** section (~50 lines) with GitHub API mapping, GraphQL recommendations, and graceful degradation strategy. This is forward-looking spec commentary for V1.0. When V1.1 posting is implemented, replace this section with actual implementation docs.
+- `templates/review-comments.md` has a **V1.1 Posting Compatibility** section (~50 lines) with GitHub API mapping, GraphQL recommendations, and graceful degradation strategy. This is forward-looking spec commentary for V1.0. When V1.1 posting is implemented, replace this section with actual implementation docs.
 
 ### Commits
 
 - One logical change per commit
 - Descriptive messages explaining why, not just what
 - Every task ends with: verify, document, commit
+
+### Doc File Routing
+
+Working files go to predictable locations based on their type:
+
+- **Workbench files** (scratch, investigation, drafts) go in `docs/private/`
+- **Designs, specs, plans, and decision records** go in the current version folder (e.g., `docs/v1/`). Examples: implementation plans, design-decisions docs, reorg specs.
+- **Curated research** goes in the current version's `research/` subfolder (e.g., `docs/v1/research/`). Research starts in `docs/private/` and gets promoted when it's high-signal enough to keep.
+- **Version-independent guides** stay in `docs/guides/`
+
+The current version is declared in `docs/README.md`.
+
+Tools may try to write specs or plans to their own default locations (e.g., `docs/superpowers/specs/`). Redirect these to the appropriate folder.
@@ -132,10 +132,18 @@ scripts/
   coverage-report.sh        # Coverage summary from tree
   check-tree-quality.sh     # Structural quality validation
 
+templates/
+  review-tree.md            # Format spec: the tree IS the state
+  review-comments.md        # Format spec: comment store, V1.1 posting
+
+troubleshoot/
+  agent-struggling.md       # Diagnostic guide loaded on agent failure
+
 docs/
-  templates/
-    review-tree.md          # Format spec: the tree IS the state
-    review-comments.md      # Format spec: comment store, V1.1 posting
+  guides/                   # Version-independent development guidance
+  hackweek/                 # Feb 23-26 2026 sprint archive
+  v1/                       # Active V1 plans, designs, decision records
+  private/                  # Investigation workbench (gitignored)
 
 tests/
   formats/                  # Parsing tests for format specs (bats-core)

@@ -0,0 +1,24 @@
+# Docs
+
+**Current version: V1**
+
+Plans, designs, decision records, and curated research for V1 go in `v1/`.
+
+## Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| `guides/` | Version-independent development guidance (prompt principles, design guide) |
+| `hackweek/` | Archive of the Feb 23-26 2026 sprint that created Fowlcon's foundation |
+| `v1/` | Active V1 work: plans, designs, decision records, promoted research |
+| `private/` | Investigation workbench: scratch files, drafts, reconstruction work |
+
+Future versions (v1.001/, v1.01/, v1.1/) get their own directories as work begins.
+
+## Where files go
+
+- **Plans, designs, specs, decision records** go directly in the current version folder
+- **Research** starts in `private/` and gets promoted to the version's `research/` subfolder when it's high-signal enough to keep
+- **Scratch work and investigation** stays in `private/`
+
+See AGENTS.md (repo root) for the full file routing conventions.
@@ -29,7 +29,7 @@ Format designed and approved. Key decisions:
 - Dot-separated numeric IDs with no depth limit
 - Description verification as table only, not tree nodes
 
-**Files:** `docs/templates/review-tree.md`, `tests/formats/sample-tree-hawksbury.md`
+**Files:** `templates/review-tree.md`, `tests/formats/sample-tree-hawksbury.md`
 
 ---
 
@@ -42,7 +42,7 @@ Format designed and approved. Key decisions:
 - Source provenance field, soft deletion via status, tree revision tracking
 - 43 tests across 2 suites
 
-**Files:** `docs/templates/review-comments.md`, `tests/formats/sample-comments-hawksbury.md`, `tests/formats/sample-comments-edge-cases.md`
+**Files:** `templates/review-comments.md`, `tests/formats/sample-comments-hawksbury.md`, `tests/formats/sample-comments-edge-cases.md`
 
 ---
 
@@ -192,7 +192,7 @@ YAML frontmatter: name (review-pr), description, model (opus). The prompt covers
 - Startup: read user-hints.md, check for existing per-PR data
 - Fetch PR diff + description + metadata
 - Spawn concept-researchers (as few passes as needed, maximum 3)
-- Build the review tree using the format from `docs/templates/review-tree.md`
+- Build the review tree using the format from `templates/review-tree.md`
 - Verify description against tree
 - Run coverage checker
 - Evaluate complexity (7 top-level threshold, based on Miller's 7±2)

@@ -0,0 +1,145 @@
+# Docs Reorganization Design
+
+**Date:** 2026-03-14
+**Status:** Approved
+
+## Goal
+
+Reorganize the docs/ folder and repo structure so that:
+- App runtime artifacts (templates, troubleshoot guides) live alongside other runtime directories at repo root
+- Hackweek sprint output is archived separately from ongoing version work
+- Each version has a clear home for plans, design, and promoted research
+- The current active version is immediately obvious
+- Version-independent development guides have a permanent home
+- AGENTS.md documents where working files go so all tools route correctly
+
+## Current Structure (Before)
+
+```
+docs/
+  templates/
+    review-tree.md
+    review-comments.md
+  troubleshoot/
+    agent-struggling.md
+  guides/
+    agent-prompt-design.md
+  design/
+    agent-prompt-design-decisions.md
+  research/
+    agent-memory-systems.md
+    agentic-restart-patterns.md
+    github-pr-review-api.md
+    tui-frameworks-comparison.md
+  plans/
+    v1-implementation.md
+    2026-02-26-pr-test-corpus-design.md
+  agent-prompt-principles.md
+  research-summary.md
+  private/
+    prompts/
+    reconstruction/
+  superpowers/
+    specs/
+```
+
+## Target Structure (After)
+
+```
+templates/                               # PROMOTED to root
+  review-tree.md
+  review-comments.md
+
+troubleshoot/                            # PROMOTED to root
+  agent-struggling.md
+
+docs/
+  README.md                              # NEW — current version + structure scheme
+  guides/                                # permanent, version-independent
+    agent-prompt-principles.md           # MOVED from docs/ root
+    agent-prompt-design.md               # stays (was docs/guides/)
+  hackweek/                              # NEW — Feb 23-26 sprint archive
+    research-summary.md                  # MOVED from docs/
+    v1-implementation.md                 # MOVED from docs/plans/
+    pr-test-corpus-design.md             # MOVED from docs/plans/ (renamed)
+    agent-prompt-design-decisions.md     # MOVED from docs/design/
+    research/                            # MOVED from docs/research/
+      agent-memory-systems.md
+      agentic-restart-patterns.md
+      github-pr-review-api.md
+      tui-frameworks-comparison.md
+  v1/                                    # NEW — active version work (created on first use)
+    research/                            # promoted high-signal research
+  private/                               # unchanged — scratch/investigation
+    prompts/
+    reconstruction/
+```
+
+## File Moves
+
+| Source | Destination |
+|---|---|
+| `docs/templates/review-tree.md` | `templates/review-tree.md` |
+| `docs/templates/review-comments.md` | `templates/review-comments.md` |
+| `docs/troubleshoot/agent-struggling.md` | `troubleshoot/agent-struggling.md` |
+| `docs/agent-prompt-principles.md` | `docs/guides/agent-prompt-principles.md` |
+| `docs/research-summary.md` | `docs/hackweek/research-summary.md` |
+| `docs/plans/v1-implementation.md` | `docs/hackweek/v1-implementation.md` |
+| `docs/plans/2026-02-26-pr-test-corpus-design.md` | `docs/hackweek/pr-test-corpus-design.md` |
+| `docs/design/agent-prompt-design-decisions.md` | `docs/hackweek/agent-prompt-design-decisions.md` |
+| `docs/research/agent-memory-systems.md` | `docs/hackweek/research/agent-memory-systems.md` |
+| `docs/research/agentic-restart-patterns.md` | `docs/hackweek/research/agentic-restart-patterns.md` |
+| `docs/research/github-pr-review-api.md` | `docs/hackweek/research/github-pr-review-api.md` |
+| `docs/research/tui-frameworks-comparison.md` | `docs/hackweek/research/tui-frameworks-comparison.md` |
+| `docs/superpowers/specs/2026-03-14-docs-reorganization-design.md` | `docs/v1/2026-03-14-docs-reorganization-design.md` |
+| `docs/superpowers/plans/2026-03-14-docs-reorganization.md` | `docs/v1/2026-03-14-docs-reorganization-plan.md` |
+
+## New Files
+
+| File | Purpose |
+|---|---|
+| `docs/README.md` | Current version declaration + docs structure explanation |
+| `docs/private/reconstruction/07-docs-reorganization-decision.md` | Decision record for this reorg (already created) |
+
+## Removed Directories
+
+These become empty after moves and should be deleted (including any `.gitkeep` files):
+- `docs/templates/`
+- `docs/troubleshoot/`
+- `docs/plans/`
+- `docs/design/`
+- `docs/research/`
+- `docs/superpowers/`
+
+## Files Requiring Path Updates
+
+These files reference paths that will change:
+
+| File | References to update |
+|---|---|
+| `AGENTS.md` | Repo structure section, context window hygiene section, NEW file routing convention |
+| `README.md` | Architecture section |
+| `docs/hackweek/v1-implementation.md` | Internal references to docs/templates/ paths |
+| `docs/private/**/*.md` | References to old doc paths (leave as-is — historical artifacts) |
+
+Note: `CLAUDE.md` is a symlink to `AGENTS.md` — updating AGENTS.md covers both.
+
+## AGENTS.md Additions
+
+Add a **File Routing** subsection under Conventions in AGENTS.md covering where working files go:
+
+- **Workbench files** (scratch, investigation, drafts) go in `docs/private/`
+- **Designs, specs, plans, and decision records** go in the current version folder (e.g., `docs/v1/`)
+- **Curated research** goes in the current version's research subfolder (e.g., `docs/v1/research/`)
+- **Example:** Superpowers brainstorming specs go to the current version folder, not `docs/superpowers/specs/`
+- **Decision record examples:** design-decisions.md (architecture choices), docs-reorganization-design.md (structural decisions)
+
+The current version is declared in `docs/README.md`.
+
+## Principles
+
+1. **Only high-signal stuff gets checked into version folders.** Private/ is the workbench.
+2. **Version folders are the curated gallery.** Plans go directly there. Research gets promoted when it earns its place.
+3. **Hackweek files are hackweek files.** Produced during the sprint, archived there. Superseded by new docs.
+4. **docs/ root is directories only** (plus README.md). Version folders stand out as obvious destinations.
+5. **docs/README.md signals the current version.** The orientation document for anyone opening docs/.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# Private research and working documents
		docs/private/