[stefanfisk]

I totally understand that this is not really a small ask, but if you could put together some sort of example repo of this setup I and probably a lot of people with me would be most grateful! I don't mean with running code or anything, just the doc structure for Claude.

[bonsai_spool]

No problem! I recommend asking Claude for these sorts of things so they can better match your own processes.

----

New session:

     ## Prompt
     
     Set up project documentation structure for this new project.
     
     Create the following:
     
     1. \*CLAUDE.md\* (project root) - Concise (<40 lines) entry point with:
         - One-line hypothesis/goal
         - "Start Here" pointing to docs/ROADMAP.md
         - Quick Reference (key commands)
         - Key Files table
         - Documentation links
         - "End of Session" protocol (append to docs/session_log.md)
     
     2. \*docs/ROADMAP.md\* - Status dashboard:
         - Current state table (what exists)
         - Blockers table (with links to plans)
         - Priority actions table (with links to plans)
         - Success criteria (minimum + publishable)
     
     3. \*docs/plans/\* directory with plan templates:
         - Each plan: Priority, Status, Depends on, Problem, Goal, Steps, Success Criteria
         - Name format: plan_descriptive_name.md (not numbered)
     
     4. \*docs/runbook.md\* - Common operations:
         - How to add new data sources
         - How to run analysis
         - How to run tests
     
     5. \*docs/session_log.md\* - Work history:
         - Template for session entries
         - "Prior Sessions" section for context
     
     6. \*docs/archive/\* - For completed/old docs
     
     If this is a data pipeline project, also set up:
      - SQLAlchemy + Pydantic architecture (see sqlalchemy_pydantic_template.zip)
      - tests/ directory with pytest structure
     - you can copy the file from ./generic_claude_project_src.zip to the current folder and unzip the copy. DO NOT modify the original file or try to move the original file
     
     Keep all docs concise. Link between docs rather than duplicating.
     
     ---
     
     ## After Setup Checklist
     
     - [ ] CLAUDE.md is <50 lines
      - [ ] ROADMAP.md fits on one screen
      - [ ] Each plan has clear success criteria
      - [ ] runbook.md has actual commands (not placeholders)
      - [ ] session_log.md has first entry from setup session
     
     ---
     
     ## python
     
     use the py-PROJECT pyenv
     
     ensure pyenv is installed
     
     ## Example Structure
     
     project/
      ├── CLAUDE.md                    # Entry point (<50 lines)
      ├── docs/
      │   ├── ROADMAP.md              # Status + plan links
      │   ├── runbook.md              # Common operations
      │   ├── session_log.md          # Work history
      │   ├── plans/
      │   │   ├── plan_data_loading.md
      │   │   ├── plan_analysis.md
      │   │   └── plan_validation.md
      │   └── archive/
      │       └── plans/              # Old plans with date prefix
      ├── src/ or project_name_src/   # Code
      └── tests/
          └── test_*.py
     
     ## Session log example
     
     ## YYYY-MM-DD: Brief Title
       \*Goal\*: What you aimed to do
     
       **Done**: What was accomplished (be specific)
     
       **Discovered**: Non-obvious findings about codebase/data/tools
     
       **Decisions**: Choices made and brief rationale
     
       **Deferred**: Work skipped and why (not just "next steps")
     
       **Blockers**: Issues preventing progress (or "None")
     
       The key shift: less about tasks completed, more about knowledge gained that isn't captured elsewhere.
     
     
     

Continuation prompt

     Review the project state and tell me what to work on:
       1. Read docs/ROADMAP.md
       2. Read docs/session_log.md (last entry)
       3. Read the highest-priority plan in docs/plans/
     
       Then summarize:
       - Last session (1 line)
       - Current blockers
       - Recommended next step
     
       Ask if I'm ready to proceed.
     

The zip archive above is just a standard Python module with __init__ and hints at how I'd like things to be named.