Create or reorganize project documentation with structured /docs hierarchy
Create or reorganize /docs following a 5-tier hierarchy:
/docs
├── 00-context/ # WHY and WHAT EXISTS RIGHT NOW
├── 01-product/ # WHAT the product must do
├── 02-features/ # HOW features are designed & built
├── 03-logs/ # MEMORY (what changed over time)
├── 04-process/ # HOW to work with this system
├── archive/ # Old/unclear docs preserved here
└── README.md # Navigation guide
Check if /docs exists and has content:
find docs -name "*.md" 2>/dev/null | wc -l
List all markdown files:
find docs -name "*.md" -exec wc -l {} \; | sort -n
For each file, read first 50-100 lines and categorize:
| Category | Criteria | Action |
|---|---|---|
| KEEP | Evergreen guides, references, architecture, troubleshooting | Move to appropriate tier |
| CONSOLIDATE | Duplicate/overlapping content | Merge into one, originals to archive |
| ARCHIVE | Work logs, status reports, old phase docs, unclear purpose | Move to /docs/archive/ |
Likely KEEP/MOVE:
Likely ARCHIVE:
When uncertain → ARCHIVE (can always recover later)
Before making changes, show categorization:
KEEP → Move to new structure (X files):
- guides/COMMANDS.md → 02-features/cli/COMMANDS.md
- reference/CONFIG.md → 04-process/reference/CONFIG.md
...
CONSOLIDATE (X groups):
- architecture.md + ARCHITECTURE.md → 00-context/system-state.md
...
ARCHIVE (X files):
- PHASE1_STATUS.md
- FIX_SUMMARY_2024.md
- reports/old-metrics.md
...
Wait for user approval before proceeding.
mkdir -p docs/{00-context,01-product,02-features,03-logs,04-process,archive}
mv docs/old-file.md docs/archive/
Move KEEP files to appropriate tiers
For CONSOLIDATE: read both files, merge content into new file, move originals to archive
Remove empty old directories
mkdir -p docs/{00-context,01-product,02-features,03-logs,04-process,archive}
Create these files (see references/templates.md for content):
00-context/ (4 files):
blueprint.md - Overarching project artifact (see below)vision.md - Product purpose & boundariesassumptions.md - Constraints, risks, unknownssystem-state.md - What's currently built01-product/ (1 file):
prd.md - Product requirements02-features/ (per feature):
feature-<name>/ subdirectories as needed03-logs/ (5 files):
implementation-log.mddecisions-log.mdbug-log.mdvalidation-log.mdinsights.md04-process/ (3+ files):
dev-workflow.mddefinition-of-done.mdllm-prompts.mdRoot:
README.md - Navigation guidePull content from:
When moving files:
If CLAUDE.md exists: Add or update documentation pointer:
## Documentation
See `docs/README.md` for full documentation structure.
If KNOWLEDGE_BASE.md exists: Update to reference new structure with quick links.
# Check structure exists
ls -la docs/{00-context,01-product,02-features,03-logs,04-process,archive}
# Verify minimum files
test -f docs/00-context/blueprint.md && echo "✓ blueprint.md"
test -f docs/00-context/vision.md && echo "✓ vision.md"
test -f docs/00-context/system-state.md && echo "✓ system-state.md"
test -f docs/01-product/prd.md && echo "✓ prd.md"
test -f docs/README.md && echo "✓ README.md"
# Count files per tier
find docs/00-context -name "*.md" | wc -l # >= 4
find docs/03-logs -name "*.md" | wc -l # >= 5
find docs/04-process -name "*.md" | wc -l # >= 3
docs/00-context/blueprint.md is the one and only high-level project document. It answers: what is this project, what's built, what's planned, where is it headed.
When to create: Always. blueprint.md is the first file created in 00-context/. It is required for both Fresh and Existing modes.
Content sources:
README.md — project identity, purpose, statspackage.json / pyproject.toml — tech stack, dependenciesStructure:
# [Project Name] Blueprint
## Identity
[What this project IS in 2-3 sentences. Sourced from README.]
## Status
| Area | Status | Notes |
|------|--------|-------|
| [feature/module] | implemented / in-progress / planned | [brief] |
## Architecture
[High-level structure: packages, modules, entry points. No ASCII trees — use tables or flat lists.]
## Implemented
[What works today. Group by feature area. Be specific.]
## Planned
[What's next. Ordered by priority. Include design docs if they exist.]
## Future Direction
[Where does this project want to be? North star. 3-5 bullets max.]
## Key Decisions
[Major architectural choices already made. Link to decisions-log if it exists.]
Rules for blueprint.md:
DO:
DON'T:
✅ Mode correctly detected (fresh vs existing) ✅ For existing: categorization presented and approved ✅ All 5 tier directories created (+ archive) ✅ Minimum files in each tier ✅ Files populated with project-specific content ✅ Archive contains old/unclear docs (not deleted) ✅ docs/README.md with navigation ✅ Validation checks pass
| Old Location | New Location |
|---|---|
| guides/, howto/ | 02-features/ or 04-process/ |
| reference/, api/ | 04-process/reference/ |
| architecture/ | 00-context/ |
| commands/ | 02-features/cli/ |
| development/ | 04-process/development/ |
| troubleshooting/ | 04-process/troubleshooting/ |
| reports/, status/, phases/ | archive/ |
See: references/templates.md