Real issues found:
1. Daily review script bugs (checker needed checking)
2. Tea CLI auth not documented (had to describe commands)
3. Go module structure confusing (telemetry standalone)
4. Done signal ambiguous (had to ask permission)
5. Build tags not in QUICKSTART
6. Issue state machine undocumented (who closes?)
7. No task pickup skill (had to guess priority)
Biggest: Agents can't fully query/modify Gitea programmatically.
Options: A) Full autonomy (skills needed), B) Assisted (current), C) Hybrid.
Immediate fixes needed in QUICKSTART.md and handbook documentation.
1. Created QUICKSTART.md (60 second read vs 1295 line handbook)
- Who you are, 4 session-start actions, critical rules
- All CLAUDE.md files now reference QUICKSTART first
2. Created scripts/daily-review.sh (automates Part 4 checks)
- Runs Section A, F, G checks automatically
- Reports PASS/FAIL with colors
- Fails fast on foundation violations
3. Added workflow section to handbook
- Where to find tasks (git.clavitor.ai)
- Priority order (CRITICAL > HIGH > MEDIUM)
- Engineer vs Reviewer responsibilities
4. Created tasks skill (.claude/skills/tasks/SKILL.md)
- For querying Gitea issues programmatically
- Will integrate with agent workflow
5. Updated all 11 CLAUDE.md files with concise headers
- Quickstart link (60s)
- Deep reference link (handbook Section V)
- Agent identity + daily script command
Hans' feedback addressed:
- ✅ Handbook too long → QUICKSTART.md
- ✅ Daily review manual → automated script
- ✅ Vague instructions → specific script + task query
- ✅ No task queue → skill created
- Documented monorepo structure (use johan/clavitor, not sub-repos)
- Added --assignees plural flag (not --assignee)
- Added Known Limitations section:
* Labels don't show in list view (workaround: tea issues view)
* User discovery is hard (provided valid usernames)
* 'no gitea login' noise (safe to ignore)
- Added file paths in descriptions (clavis/clavis-telemetry/main.go)
- Added curl command to list labels via API
James