docs: Enforce mandatory branch-first git workflow for all agents

[mvillmow]

Summary

This PR establishes a MANDATORY branch-first development workflow for all code-writing agents in ProjectKeystone.

Critical Policy Change

⚠️ ALL agents must create feature branches BEFORE committing code

This prevents direct commits to and ensures all changes go through Pull Request review.

---

Changes

1. CLAUDE.md - Project-Level Git Workflow Policy

Added comprehensive "Git Workflow" section with:

• ⚠️ MANDATORY: Branch-First Development requirement
• Step-by-step workflow: Branch → Commit → PR → Review → Merge
• Branch naming conventions with timestamps (e.g., feat/description-YYYYMMDD-HHMMSS)
• Commit message format (feat:, fix:, refactor:, etc.)
• What NOT to do (never git push origin main, etc.)
• Pre-commit checklist (tests, formatting, warnings)

2. .claude/agents/chief-architect.md

Added Git Workflow section for Level 0 strategic agent:

• Architecture-specific PR template
• Phase-based branch naming
• Architecture decision documentation requirements
• Extended verification checklist (E2E tests, architecture docs)
• Added Bash tool for git commands

3. .claude/agents/implementation-engineer.md

Added Git Workflow section for code implementation:

• Standard feature branch workflow
• Test-passing requirements before every commit
• Code formatting verification
• Added Bash tool for git commands

---

Rationale

This change addresses several critical issues:

1. Code Review: All changes must be reviewed before merge
2. CI/CD: Automated tests run before code reaches main
3. Main Branch Stability: Prevents breaking changes on main
4. Audit Trail: Pull Requests provide clear change history
5. Rollback Safety: Easy to revert PRs if issues found

---

Benefits

For Development Process

• ✅ Every change is reviewed before merge
• ✅ CI/CD runs on all PRs automatically
• ✅ Main branch always in stable state
• ✅ Clear documentation of what changed and why

For Agents

• ✅ Clear workflow: Branch → Code → Test → PR → Review
• ✅ No accidental main branch commits
• ✅ Timestamp-based branch names prevent conflicts
• ✅ Standardized PR format with test results

---

Implementation Notes

Branch Naming Format

feat/short-description-20251126-183834
fix/issue-description-20251126-183834
refactor/component-name-20251126-183834
docs/doc-description-20251126-183834

Timestamp ensures unique branch names across concurrent work.

What Agents Will Do Differently

Before this PR:

git checkout main
# make changes
git commit -m "feat: new feature"
git push origin main  # ❌ Direct push to main

After this PR:

git checkout -b feat/new-feature-20251126-183929
# make changes
just test-asan  # Verify tests pass
git commit -m "feat: new feature"
git push -u origin feat/new-feature-...
gh pr create  # ✅ Create PR for review

---

Testing

Documentation Changes Only

• ✅ No code changes
• ✅ Markdown formatting verified
• ✅ All tests still pass (466/466)

Verified Workflow

This PR itself demonstrates the new workflow:

1. ✅ Created feature branch: docs/git-workflow-mandatory-20251126-183834
2. ✅ Committed changes to feature branch
3. ✅ Pushed feature branch to remote
4. ✅ Creating this PR (not merging to main directly)

---

Future Work

Additional agents to update with this workflow:

• senior-implementation-engineer.md
• junior-implementation-engineer.md
• test-engineer.md
• junior-test-engineer.md
• documentation-engineer.md
• security-specialist.md
• performance-engineer.md

These will be updated in follow-up PRs to maintain focused changes.

---

Merge Instructions

After review and approval:

1. Merge this PR to main
2. All future agent work will follow new workflow
3. Document in team onboarding/README if needed

---

🤖 Generated with Claude Code implementing user-requested branch-first workflow policy