From cb18a2aa31533c87735bc02e6a73288518479d54 Mon Sep 17 00:00:00 2001
From: marcusquinn <6428977+marcusquinn@users.noreply.github.com>
Date: Sun, 11 Jan 2026 04:52:04 +0000
Subject: [PATCH] docs(loops): add README and changelog guidance to loop agents

- Add 'Documentation Updates' section to ralph-loop.md with README and
  conventional commit guidance
- Add 'Documentation & Changelog' section to full-loop.md with commit
  prefix table
- Update completion criteria to include README updates
- Add changelog.md to related workflows
- Clarify that changelog is auto-generated from conventional commits
---
 .agent/scripts/commands/full-loop.md | 34 +++++++++++++++++++++
 .agent/workflows/ralph-loop.md       | 45 ++++++++++++++++++++++++++--
 2 files changed, 77 insertions(+), 2 deletions(-)

diff --git a/.agent/scripts/commands/full-loop.md b/.agent/scripts/commands/full-loop.md
index 59a4d4272..76407fea5 100644
--- a/.agent/scripts/commands/full-loop.md
+++ b/.agent/scripts/commands/full-loop.md
@@ -55,6 +55,8 @@ The AI will iterate on the task until outputting:
 - All requirements implemented
 - Tests passing (if applicable)
 - Code quality acceptable
+- README.md updated (if adding features/APIs)
+- Conventional commits used (for auto-changelog)
 
 ### Step 4: Automatic Phase Progression
 
@@ -134,9 +136,41 @@ Pass options after the prompt:
 /full-loop "Refactor database layer" --no-auto-pr
 ```
 
+## Documentation & Changelog
+
+### README Updates
+
+When implementing features or APIs, include README updates in your task:
+
+```bash
+/full-loop "Add user authentication with JWT tokens and update README"
+```
+
+The task development phase should update README.md with:
+- New feature documentation
+- Usage examples
+- API endpoint descriptions
+- Configuration options
+
+### Changelog (Auto-Generated)
+
+The release workflow auto-generates CHANGELOG.md from conventional commits. Use proper commit prefixes during task development:
+
+| Prefix | Changelog Section | Example |
+|--------|-------------------|---------|
+| `feat:` | Added | `feat: add JWT authentication` |
+| `fix:` | Fixed | `fix: resolve token expiration bug` |
+| `docs:` | Changed | `docs: update API documentation` |
+| `perf:` | Changed | `perf: optimize database queries` |
+| `refactor:` | Changed | `refactor: simplify auth middleware` |
+| `chore:` | (excluded) | `chore: update dependencies` |
+
+See `workflows/changelog.md` for format details.
+
 ## Related
 
 - `workflows/ralph-loop.md` - Ralph loop technique details
 - `workflows/preflight.md` - Pre-commit quality checks
 - `workflows/pr.md` - PR creation workflow
 - `workflows/postflight.md` - Post-release verification
+- `workflows/changelog.md` - Changelog format and validation
diff --git a/.agent/workflows/ralph-loop.md b/.agent/workflows/ralph-loop.md
index b8416e2e8..f59803ad8 100644
--- a/.agent/workflows/ralph-loop.md
+++ b/.agent/workflows/ralph-loop.md
@@ -227,7 +227,36 @@ Implement feature X following TDD:
 7. Output: <promise>COMPLETE</promise>
 ```
 
-### 4. Escape Hatches
+### 4. Documentation Updates
+
+Include documentation requirements in your completion criteria:
+
+**README updates** - When adding features, APIs, or changing behavior:
+
+```text
+Implement feature X.
+
+When complete:
+- Feature working with tests
+- README.md updated with usage examples
+- Output: <promise>COMPLETE</promise>
+```
+
+**Changelog via commits** - Use conventional commit messages for auto-generated changelogs:
+
+```text
+# Good commit messages (auto-included in changelog)
+feat: add user authentication
+fix: resolve memory leak in connection pool
+docs: update API documentation
+
+# Excluded from changelog
+chore: update dependencies
+```
+
+The release workflow auto-generates CHANGELOG.md from conventional commits. See `workflows/changelog.md`.
+
+### 5. Escape Hatches
 
 Always use `--max-iterations` as a safety net:
 
@@ -542,13 +571,25 @@ The loop is designed for maximum AI autonomy while preserving human control at s
 
 | Phase | AI Autonomous | Human Required |
 |-------|---------------|----------------|
-| Task Development | Code changes, iterations, fixes | Initial task definition, scope decisions |
+| Task Development | Code changes, iterations, fixes, README updates | Initial task definition, scope decisions |
 | Preflight | Auto-fix, re-run checks | Override to skip (emergency only) |
 | PR Creation | Auto-create with `--fill` | Custom title/description if needed |
 | PR Review | Address feedback, push fixes | Approve/merge (if required by repo) |
 | Postflight | Monitor, report issues | Rollback decision if issues found |
 | Deploy | Run `setup.sh` | None (fully autonomous) |
 
+### Documentation in Loops
+
+**README updates**: Include in task development phase when adding features/APIs.
+
+**Changelog**: Auto-generated from conventional commits during release. Use proper prefixes:
+- `feat:` → Added section
+- `fix:` → Fixed section
+- `docs:` → Changed section
+- `chore:` → Excluded from changelog
+
+See `workflows/changelog.md` for details.
+
 ### Options
 
 ```bash