Claude/update readme documentation 011 cuke4vw4w m dkh r1u7 e4g q

[kieranklaassen]

No description provided.

[xshaheen]

100% Compliance Achieved

Added optional metadata enhancements (M1, M2, L2, L3):

M1 - brainstorm: Research metadata in frontmatter (repo_patterns, learnings_applied, timestamp)
M2 - deepen-plan: Enhancement metadata in frontmatter (skills_applied, agents_consulted)
L2 - code-review: Review summary file at docs/reviews/YYYY-MM-DD-pr-NNN-review.md
L3 - compound: Research provenance in solution frontmatter (agents, documented_at)

Final Compliance:

• Main branch: 65%
• After US-001 to US-015: 95%
• After metadata enhancements: 100%

All 7 workflow commands now have complete metadata for transparency, resumability, and audit trails.

Commit: 57ea389

[xshaheen]

Architecture Compliance Fixes Applied

Addressed critical and high-priority issues from workflow command architecture review:

Issue 1: Missing allowed-tools (CRITICAL - Security)

All 7 commands now have explicit tool permissions:

• ✅ brainstorm.md: Read, Grep, Glob, Write, Bash(git *), Bash(mkdir *), Task, AskUserQuestion
• ✅ plan.md: Broad research access (gh, git, jq, WebSearch, MCP)
• ✅ code.md: Full execution access (Read, Write, Edit, Bash, Task)
• ✅ swarm.md: Orchestration tools (jq, git, gh, SendMessage, TeamCreate)
• ✅ code-review.md: Review tools (Read, Write, gh, git, Task)
• ✅ compound.md: Documentation tools (Read, Write, git, Task)
• ✅ deepen-plan.md: Discovery tools (ls, find, cat, git, WebSearch, MCP)

Security improvement: No blanket Bash access, specific patterns only

Issue 2: Context Budget Management (CRITICAL - Reliability)

4 high-context commands now check budget:

• ✅ code.md: Warns at 70% usage, offers checkpoint every 5 tasks
• ✅ swarm.md: Pre-loop assessment, checkpoint every 5 stories for PRDs with 10+ stories
• ✅ code-review.md: Warns if >15 agents or >500 lines changed
• ✅ deepen-plan.md: User choice before launching 30+ agents, estimates context usage

Reliability improvement: Prevents context exhaustion mid-workflow

Issue 4: Model Selection (HIGH - Performance)

All 7 commands specify model:

• ✅ All set to model: sonnet for balanced orchestration/reasoning
• Consistent model usage improves performance and cost predictability

Commit

• Hash: a2fd146
• Files changed: 7 (all dev workflow commands)
• Lines changed: +90 additions

Next Steps

These fixes address the most critical architecture issues. Remaining enhancements (low priority) can be addressed in follow-up PRs if needed.

[xshaheen]

Additional Workflow Improvements

Progress File Location Fix (d8a9480)

Issue: Progress files created in current directory (progress.txt)
Fix: Progress files now created alongside plan files

• Pattern: ${PLAN_FILE%.md}.progress.txt
• Example: docs/plans/feat-auth-plan.md → docs/plans/feat-auth-plan.progress.txt
• Removed lock file coordination section (never implemented)

Benefit: Progress logs stay with plan artifacts, easy to find

Context Management Removal (6beae9a)

Rationale: Simplify workflow commands by removing context budget checks

Removed from:

• ✅ code.md: Context Budget Management section
• ✅ swarm.md: Pre-loop context check + teammate template awareness
• ✅ code-review.md: Pre-launch context check
• ✅ deepen-plan.md: Agent discovery context check + user choices

Impact: -81 lines of complexity, cleaner command instructions

Result: Commands now focus on core workflow without decision fatigue