Add consolidated AGENT.md for faster AI agent onboarding

CLAUDE.md

@@ -0,0 +1,33 @@
+# 5DayDocs Development
+
+This repo builds 5DayDocs, a folder-based project management tool. It also dogfoods itself.
+
+## Architecture
+
+- `src/` — Source of truth for all distributed files. Edit here.
+- `docs/` — Dogfood: we use 5DayDocs to manage 5DayDocs. Synced from `src/` via `./setup.sh .`
+- `templates/` — GitHub/Bitbucket templates distributed to users
+- `setup.sh` — Installer/updater that copies `src/` to user projects
+
+Never edit `docs/5day/` directly — it's synced from `src/docs/5day/`.
+
+## Key files
+
+- `src/VERSION` — Current version
+- `docs/STATE.md` — Next task/bug IDs (check before creating tasks)
+- `src/docs/5day/AGENT.md` — Agent reference shipped to users
+- `src/docs/5day/scripts/5day.sh` — Main CLI (also copied to project root)
+- `src/DOCUMENTATION.md` — User-facing documentation
+
+## Commands
+
+```bash
+./setup.sh .              # Sync src/ to docs/ (dogfood)
+./5day.sh newtask "..."   # Create task
+./5day.sh status          # Pipeline overview
+./5day.sh help            # All commands
+```
+
+## Task conventions
+
+Read docs/5day/AGENT.md for the full reference (same file shipped to users).

docs/5day/AGENT.md

@@ -0,0 +1,85 @@
+# 5DayDocs — Agent Reference
+
+> One file. Everything an AI agent needs to work with 5DayDocs in this project.
+
+## What this is
+
+Folder-based project management. Tasks are markdown files that move through pipeline folders. No database, no app — just git.
+
+## Structure
+
+```
+docs/
+├── STATE.md              # Next IDs — read before creating tasks/bugs
+├── tasks/
+│   ├── backlog/          # Planned, not started
+│   ├── next/             # Sprint queue
+│   ├── working/          # In progress (max 1 at a time)
+│   ├── review/           # Done, awaiting approval
+│   └── live/             # Shipped
+├── features/             # Feature specifications
+├── ideas/                # Rough concepts (use Feynman protocol)
+├── bugs/                 # Bug reports
+├── guides/               # How-to docs, technical procedures
+├── examples/             # Code samples, configs
+└── 5day/                 # Framework (do NOT edit — overwritten on update)
+```
+
+## Rules
+
+1. **Check `docs/STATE.md` before creating tasks or bugs** — it has the next available ID
+2. **Folder = status** — move files between folders to change status
+3. **One task in `working/` at a time**
+4. **Never edit files in `docs/5day/`** — they're framework files, overwritten on update
+5. **Tasks describe outcomes, not implementation** — write "User can X" not "Add React component"
+6. **Technical details go in `docs/guides/` or `docs/features/`**, not in task files
+
+## File naming
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Task | `[ID]-[description].md` | `42-add-login-button.md` |
+| Bug | `BUG-[ID]-[description].md` | `BUG-3-login-fails.md` |
+| Feature | `[name].md` | `user-authentication.md` |
+| Idea | `[name].md` | `notification-system.md` |
+
+## Commands
+
+```bash
+./5day.sh newtask "Description"     # Create task (auto-increments ID)
+./5day.sh newbug "Description"      # Create bug report
+./5day.sh newfeature "Name"         # Create feature spec
+./5day.sh newidea "Name"            # Create idea for refinement
+./5day.sh status                    # Show pipeline overview
+./5day.sh help                      # All commands
+```
+
+## Task format
+
+```markdown
+# Task [ID]: [Short description]
+
+**Feature**: /docs/features/[name].md (or "none")
+**Created**: YYYY-MM-DD
+**Depends on**: Task [ID] (or "none")
+**Blocks**: Task [ID] (or "none")
+
+## Problem
+2-5 sentences. What's wrong and why it matters.
+
+## Success criteria
+- [ ] User can [do what]
+- [ ] System shows [result]
+- [ ] [Action] completes within [time]
+
+## Notes
+Links, dependencies, edge cases.
+```
+
+## Protocols (supplementary reading)
+
+For deeper guidance on specific workflows:
+
+- `docs/5day/ai/task-creation.md` — Interactive Q&A before writing tasks
+- `docs/5day/ai/task-writing-rules.md` — What goes where (tasks vs guides vs features)
+- `docs/5day/ai/feynman-method.md` — Breaking ideas into tasks (4-phase decomposition)

setup.sh

@@ -551,7 +551,12 @@ if [ -d "$FIVEDAY_SOURCE_DIR/src/docs/5day/scripts" ]; then
     done
 fi
 
-# Copy AI context files
+# Copy AGENT.md (consolidated agent reference)
+if safe_copy "$FIVEDAY_SOURCE_DIR/src/docs/5day/AGENT.md" "docs/5day/AGENT.md" "AGENT.md (agent reference)"; then
+    ((FILES_COPIED++))
+fi
+
+# Copy AI protocol files (supplementary reading)
 if [ -d "$FIVEDAY_SOURCE_DIR/src/docs/5day/ai" ]; then
     for ai_file in "$FIVEDAY_SOURCE_DIR/src/docs/5day/ai"/*.md; do
         if [ -f "$ai_file" ]; then
@@ -723,6 +728,44 @@ else
     fi
 fi
 
+# ============================================================================
+# AI AGENT INTEGRATION (CLAUDE.md)
+# ============================================================================
+
+CLAUDE_SNIPPET="Read docs/5day/AGENT.md for 5DayDocs conventions (task management, file structure, commands)."
+
+if [ -f "CLAUDE.md" ]; then
+    if grep -q "5day" CLAUDE.md 2>/dev/null || grep -q "5DayDocs" CLAUDE.md 2>/dev/null || grep -q "AGENT.md" CLAUDE.md 2>/dev/null; then
+        msg_step "CLAUDE.md already references 5DayDocs"
+    else
+        echo ""
+        echo "CLAUDE.md found. Add a one-liner so AI agents auto-discover 5DayDocs conventions? (y/n)"
+        read -r CLAUDE_CHOICE
+        if [[ "$CLAUDE_CHOICE" =~ ^[Yy]$ ]]; then
+            if { echo ""; echo "$CLAUDE_SNIPPET"; } >> CLAUDE.md 2>/dev/null; then
+                msg_success "Added 5DayDocs reference to CLAUDE.md"
+            else
+                msg_error "Failed to update CLAUDE.md"
+            fi
+        else
+            msg_step "Skipped CLAUDE.md update"
+        fi
+    fi
+else
+    echo ""
+    echo "No CLAUDE.md found. Create one so AI agents (Claude Code, etc.) auto-discover 5DayDocs? (y/n)"
+    read -r CLAUDE_CHOICE
+    if [[ "$CLAUDE_CHOICE" =~ ^[Yy]$ ]]; then
+        if echo "$CLAUDE_SNIPPET" > CLAUDE.md 2>/dev/null; then
+            msg_success "Created CLAUDE.md"
+        else
+            msg_error "Failed to create CLAUDE.md"
+        fi
+    else
+        msg_step "Skipped CLAUDE.md creation"
+    fi
+fi
+
 # ============================================================================
 # CLEANUP LEGACY FILES
 # ============================================================================

src/docs/5day/AGENT.md

@@ -0,0 +1,85 @@
+# 5DayDocs — Agent Reference
+
+> One file. Everything an AI agent needs to work with 5DayDocs in this project.
+
+## What this is
+
+Folder-based project management. Tasks are markdown files that move through pipeline folders. No database, no app — just git.
+
+## Structure
+
+```
+docs/
+├── STATE.md              # Next IDs — read before creating tasks/bugs
+├── tasks/
+│   ├── backlog/          # Planned, not started
+│   ├── next/             # Sprint queue
+│   ├── working/          # In progress (max 1 at a time)
+│   ├── review/           # Done, awaiting approval
+│   └── live/             # Shipped
+├── features/             # Feature specifications
+├── ideas/                # Rough concepts (use Feynman protocol)
+├── bugs/                 # Bug reports
+├── guides/               # How-to docs, technical procedures
+├── examples/             # Code samples, configs
+└── 5day/                 # Framework (do NOT edit — overwritten on update)
+```
+
+## Rules
+
+1. **Check `docs/STATE.md` before creating tasks or bugs** — it has the next available ID
+2. **Folder = status** — move files between folders to change status
+3. **One task in `working/` at a time**
+4. **Never edit files in `docs/5day/`** — they're framework files, overwritten on update
+5. **Tasks describe outcomes, not implementation** — write "User can X" not "Add React component"
+6. **Technical details go in `docs/guides/` or `docs/features/`**, not in task files
+
+## File naming
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Task | `[ID]-[description].md` | `42-add-login-button.md` |
+| Bug | `BUG-[ID]-[description].md` | `BUG-3-login-fails.md` |
+| Feature | `[name].md` | `user-authentication.md` |
+| Idea | `[name].md` | `notification-system.md` |
+
+## Commands
+
+```bash
+./5day.sh newtask "Description"     # Create task (auto-increments ID)
+./5day.sh newbug "Description"      # Create bug report
+./5day.sh newfeature "Name"         # Create feature spec
+./5day.sh newidea "Name"            # Create idea for refinement
+./5day.sh status                    # Show pipeline overview
+./5day.sh help                      # All commands
+```
+
+## Task format
+
+```markdown
+# Task [ID]: [Short description]
+
+**Feature**: /docs/features/[name].md (or "none")
+**Created**: YYYY-MM-DD
+**Depends on**: Task [ID] (or "none")
+**Blocks**: Task [ID] (or "none")
+
+## Problem
+2-5 sentences. What's wrong and why it matters.
+
+## Success criteria
+- [ ] User can [do what]
+- [ ] System shows [result]
+- [ ] [Action] completes within [time]
+
+## Notes
+Links, dependencies, edge cases.
+```
+
+## Protocols (supplementary reading)
+
+For deeper guidance on specific workflows:
+
+- `docs/5day/ai/task-creation.md` — Interactive Q&A before writing tasks
+- `docs/5day/ai/task-writing-rules.md` — What goes where (tasks vs guides vs features)
+- `docs/5day/ai/feynman-method.md` — Breaking ideas into tasks (4-phase decomposition)