xonecas.io
60255
Zn

Zoea-Nova / commit da4af0f

docs: complete and polish WORKFLOW.md agent best practices

- Add comprehensive git command templates for agents
- Add mandatory verification checklist with 9 checkpoints
- Add detailed commit message requirements with examples
- Add 6-step branch verification protocol
- Add decision tree for handling previous commits
- Add evidence-based completion report template
- Add 5 examples of good vs bad agent behavior
  - Making changes without committing
  - Reverting correct implementations
  - Vague commit messages
  - Incomplete verification
  - Testing without truth table
- Make Action Items concrete with immediate/short/medium/long-term goals
- Update version to 1.1 and date to 2026-02-08

Focus: Actionable steps, clear examples, concrete commands, measurable outcomes

xonecas2026-02-08 da4af0fa1446a7661aed020aaceeff7f35c76b0b parent 7799e98

1 file changed

WORKFLOW.md+472−4
@@ -1,7 +1,35 @@
11 # Zoea Nova Development Workflow
22
3-**Version:** 1.0
4-**Last updated:** 2026-02-07
3+**Version:** 1.1
4+**Last updated:** 2026-02-08
5+
6+---
7+
8+## Quick Reference
9+
10+**When to use:** Architectural changes, large refactors (10+ files), API changes, system redesigns
11+
12+**Don't use for:** Simple bugs (1-2 files), docs-only, dependency updates, config tweaks
13+
14+**Time budget:** 2-4 hours for medium refactors
15+
16+**Minimum requirements:**
17+- Phase 1: Truth table document (abort if >90 min)
18+- Phase 2: 3+ agents for implementation
19+- Phase 4: 3+ agents for review
20+- Phase 6: User approval before commit
21+
22+**Emergency stops:**
23+- Phase 1: Can't define truth table after 90 min
24+- Phase 2: >50% agents report blocking dependencies
25+- Phase 3: >20 compilation errors
26+- Phase 4: Review finds architectural flaws (not bugs)
27+- Phase 5: All 3 fix agents fail
28+- Phase 6: User finds critical missing functionality
29+
30+**Quick links:** [Decision Tree](#decision-tree) | [Troubleshooting](#troubleshooting) | [Checklist](#template-checklist)
31+
32+---
533
634 ## Purpose
735
@@ -26,6 +54,21 @@ Do NOT use for:
2654
2755 ---
2856
57+## Decision Tree
58+
59+Use this flowchart to decide whether and how to proceed:
60+
61+```
62+Phase 1: Can define truth table <90 min? → YES → Phase 2
63+Phase 2: 3+ independent tasks identified? → YES → Phase 3
64+Phase 3: <20 compilation errors? → YES → Phase 4
65+Phase 4: Only bugs found (no arch flaws)? → YES → Phase 5
66+Phase 5: At least 1 solution works? → YES → Phase 6
67+Phase 6: User approved changes? → YES → Commit
68+```
69+
70+---
71+
2972 ## Workflow Phases
3073
3174 ### Phase 1: Document the Truth
@@ -511,5 +554,430 @@ This workflow will evolve based on experience. After using this workflow multipl
511554
512555 ---
513556
514-**Version:** 1.0
515-**Last updated:** 2026-02-07
557+## Agent Best Practices and Git Workflow
558+
559+### Recommendations for Agent Prompts
560+
561+**Phase 5 agent instructions must explicitly include:**
562+
563+#### 1. Git Command Templates
564+
565+**After making ANY code changes:**
566+```bash
567+# Stage changes
568+git add internal/path/to/changed_file.go internal/path/to/test_file.go
569+
570+# Commit with descriptive message
571+git commit -m "fix(mysis): implement autonomous turn loop in run()
572+
573+- Added select loop listening to nudgeChan in internal/mysis/mysis.go:234
574+- Loop calls handleNextTurn() when nudged
575+- Added test coverage in internal/mysis/mysis_test.go:456
576+- Tests: 91/91 passing"
577+
578+# VERIFY commit was created
579+git log --oneline -1
580+# Expected output: <hash> fix(mysis): implement autonomous turn loop in run()
581+```
582+
583+**Before reporting completion:**
584+```bash
585+# Verify commits exist on your branch
586+git log main..$(git branch --show-current) --oneline
587+# Expected output: One or more commit hashes with messages
588+
589+# Verify changes are committed (should be empty if all committed)
590+git status
591+# Expected output: "nothing to commit, working tree clean"
592+
593+# Verify diff exists between your branch and main
594+git diff main --stat
595+# Expected output: List of files with +/- line counts
596+```
597+
598+#### 2. Mandatory Verification Checklist
599+
600+**Every agent MUST complete this checklist before reporting "done":**
601+
602+```markdown
603+- [ ] Created branch: `git branch --show-current` shows correct branch name
604+- [ ] Made code changes: Files modified in editor/IDE
605+- [ ] Staged changes: `git status` shows "Changes to be committed" OR already committed
606+- [ ] Created commit: `git log -1` shows my commit with correct message
607+- [ ] Verified commit exists on branch: `git log main..HEAD` shows my commit(s)
608+- [ ] Tests passing: `make test` output shows 0 failures
609+- [ ] Clean working tree: `git status` shows "nothing to commit, working tree clean"
610+- [ ] Changes visible in diff: `git diff main` shows my changes
611+- [ ] Commit hash reported: Included 7-char hash in completion message
612+```
613+
614+#### 3. Commit Message Requirements
615+
616+**Structure:**
617+```
618+<type>(<scope>): <summary>
619+
620+<body with specifics>
621+<test results>
622+```
623+
624+**Example (GOOD):**
625+```
626+fix(mysis): add autonomous turn loop in run() method
627+
628+- Modified internal/mysis/mysis.go:234-256
629+- Added select{} loop with nudgeChan listener
630+- Calls handleNextTurn() on each nudge
631+- Updated internal/mysis/mysis_test.go:456-478
632+- Added TestRunMethodNudgeHandling test case
633+
634+Tests: 91/91 passing (0.847s)
635+Coverage: internal/mysis 87.3% (+2.1%)
636+```
637+
638+**Example (BAD - DO NOT USE):**
639+```
640+fix: implement feature
641+
642+- Made changes to mysis
643+- Added tests
644+- Everything works now
645+```
646+
647+**Rules:**
648+- Describe what code ACTUALLY does (not aspirational goals)
649+- Reference specific files and line numbers
650+- Include test results
651+- Use present tense ("add", "fix", "remove", not "added", "fixed", "removed")
652+- Be specific about behavior change
653+
654+#### 4. Branch Verification Protocol
655+
656+**Step-by-step verification (run ALL commands):**
657+
658+```bash
659+# 1. Verify you're on correct branch
660+git branch --show-current
661+# Must output: Your expected branch name (e.g., "fix/autonomous-loop")
662+
663+# 2. Verify commit exists
664+git log -1 --format="%H %s"
665+# Must output: Full hash + your commit message
666+
667+# 3. Verify commit is on current branch (not on main)
668+git log main..HEAD --oneline
669+# Must output: One or more commits (NOT empty)
670+
671+# 4. Verify changes are committed (not just staged)
672+git diff --cached
673+# Must output: Empty (no staged changes) if all committed
674+
675+# 5. Verify working tree is clean
676+git status --short
677+# Must output: Empty (no uncommitted changes)
678+
679+# 6. Verify diff against main
680+git diff main --stat
681+# Must output: File list with +/- counts
682+```
683+
684+**If ANY check fails, DO NOT report completion. Fix the issue first.**
685+
686+#### 5. Never Revert Previous Commits
687+
688+**Before making changes, ALWAYS check history:**
689+
690+```bash
691+# Check what commits exist on this branch
692+git log main..HEAD --oneline
693+
694+# For each commit, check what it changed
695+git show <commit-hash> --stat
696+
697+# Read the actual code changes
698+git show <commit-hash>
699+```
700+
701+**Decision tree:**
702+
703+```
704+Found previous commit with the fix?
705+├─ YES
706+│ ├─ Tests pass? → Keep the fix, report it works
707+│ └─ Tests fail?
708+│ ├─ Code matches truth table? → Fix the tests
709+│ └─ Code doesn't match? → Fix the code
710+└─ NO → Implement the fix
711+```
712+
713+**Example (GOOD behavior):**
714+```bash
715+$ git log main..HEAD --oneline
716+788254c fix(mysis): add autonomous turn loop
717+$ git show 788254c | grep -A 10 "select {"
718+# See the loop exists
719+$ make test
720+# Tests fail
721+$ # Decision: Loop matches truth table, fix the tests
722+$ vim internal/mysis/mysis_test.go # Fix test expectations
723+```
724+
725+**Example (BAD behavior - DO NOT DO THIS):**
726+```bash
727+$ make test
728+# Tests fail
729+$ # Decision: Remove the loop to make tests pass
730+$ vim internal/mysis/mysis.go # Delete the loop
731+# ❌ WRONG: Reverted correct implementation
732+```
733+
734+#### 6. Evidence-Based Completion Reports
735+
736+**When reporting completion, MUST include:**
737+
738+1. **Branch name** (verified with `git branch --show-current`)
739+2. **Commit hash** (verified with `git log -1 --format="%h"`)
740+3. **Commit message** (first line of `git log -1 --format="%s"`)
741+4. **Files changed** (verified with `git diff main --stat`)
742+5. **Test results** (verified with `make test`)
743+6. **Verification commands** (paste output of checklist commands)
744+
745+**Example (GOOD report):**
746+```
747+Completion Report:
748+
749+Branch: fix/autonomous-loop-v2
750+Commit: a3f7c89
751+Message: fix(mysis): add autonomous turn loop in run()
752+
753+Files changed:
754+ internal/mysis/mysis.go | 23 +++++++++++++++++++++
755+ internal/mysis/mysis_test.go | 18 +++++++++++++++++
756+ 2 files changed, 41 insertions(+)
757+
758+Test results:
759+=== RUN TestRunMethodNudgeHandling
760+--- PASS: TestRunMethodNudgeHandling (0.02s)
761+PASS
762+ok github.com/example/zoea-nova/internal/mysis 0.847s
763+
764+Verification:
765+$ git log main..HEAD --oneline
766+a3f7c89 fix(mysis): add autonomous turn loop in run()
767+
768+$ git status
769+On branch fix/autonomous-loop-v2
770+nothing to commit, working tree clean
771+
772+$ git diff main --stat
773+ internal/mysis/mysis.go | 23 +++++++++++++++++++++
774+ internal/mysis/mysis_test.go | 18 +++++++++++++++++
775+ 2 files changed, 41 insertions(+)
776+```
777+
778+**Example (BAD report - DO NOT USE):**
779+```
780+Done! Created branch fix/autonomous-loop. All tests pass. Ready for review.
781+
782+# ❌ Missing: commit hash, verification output, files changed, evidence
783+```
784+
785+---
786+
787+### Examples of Good vs Bad Agent Behavior
788+
789+#### Example 1: Making Changes Without Committing
790+
791+**BAD:**
792+```
793+Agent: "I've implemented the autonomous turn loop on branch fix/autonomous-loop.
794+All tests pass. Ready for review."
795+
796+User: "Show me the commit"
797+Agent: "Oh, I didn't commit yet. Let me do that now..."
798+```
799+
800+**GOOD:**
801+```
802+Agent: "Completion Report:
803+
804+Branch: fix/autonomous-loop-v2
805+Commit: a3f7c89
806+Message: fix(mysis): add autonomous turn loop in run()
807+
808+Verification:
809+$ git log main..HEAD --oneline
810+a3f7c89 fix(mysis): add autonomous turn loop in run()
811+
812+$ git status
813+On branch docs/workflow-completion-agent4
814+nothing to commit, working tree clean"
815+```
816+
817+#### Example 2: Reverting Correct Implementations
818+
819+**BAD:**
820+```
821+Agent 1: Commits working loop (788254c)
822+Agent 2: "Tests fail. Removing the loop to fix tests." (d2146af)
823+
824+Result: Branch HEAD has no loop, fix is lost
825+```
826+
827+**GOOD:**
828+```
829+Agent 2:
830+$ git log main..HEAD --oneline
831+788254c fix(mysis): add autonomous turn loop
832+
833+$ git show 788254c
834+# ... sees the loop exists and matches truth table
835+
836+$ make test
837+# Tests fail with "unexpected goroutine running"
838+
839+Analysis: Loop is correct per truth table. Tests have wrong expectations.
840+Action: Updating test to expect autonomous behavior.
841+
842+$ git diff
843+# ... shows test changes, not code reversion
844+```
845+
846+#### Example 3: Vague Commit Messages
847+
848+**BAD:**
849+```
850+fix: implement feature
851+
852+- Made changes
853+- Everything works
854+```
855+
856+**GOOD:**
857+```
858+fix(mysis): add autonomous turn loop in run() method
859+
860+- Modified internal/mysis/mysis.go:234-256
861+- Added select{} loop with nudgeChan listener
862+- Calls handleNextTurn() on each nudge
863+- Updated internal/mysis/mysis_test.go:456-478
864+- Added TestRunMethodNudgeHandling test case
865+
866+Tests: 91/91 passing (0.847s)
867+Coverage: internal/mysis 87.3% (+2.1%)
868+```
869+
870+#### Example 4: Incomplete Verification
871+
872+**BAD:**
873+```
874+Agent: "Tests pass, so the implementation is correct!"
875+
876+(Didn't verify:
877+- Commit exists
878+- Changes are on correct branch
879+- Working tree is clean
880+- Diff shows expected changes)
881+```
882+
883+**GOOD:**
884+```
885+Agent: "Running verification checklist:
886+
887+✓ Branch: git branch --show-current → fix/autonomous-loop-v2
888+✓ Commit: git log -1 --format='%h' → a3f7c89
889+✓ Commits on branch: git log main..HEAD --oneline → 1 commit found
890+✓ Tests: make test → 91/91 passing
891+✓ Clean tree: git status → nothing to commit, working tree clean
892+✓ Diff exists: git diff main --stat → 2 files, 41 insertions
893+
894+All checks passed. Implementation complete."
895+```
896+
897+#### Example 5: Testing Without Truth Table
898+
899+**BAD:**
900+```
901+Agent: "Tests pass, so it must be correct!"
902+
903+(Didn't check:
904+- Does behavior match truth table?
905+- Are tests encoding the right behavior?
906+- Did previous agent already fix this?)
907+```
908+
909+**GOOD:**
910+```
911+Agent: "Verifying against truth table (MESSAGE_FORMAT_GUARANTEES.md):
912+
913+Row 3: 'Running + no messages in 90s → Idle'
914+Expected: Mysis should NOT idle (encouragementCount prevents it)
915+Code: run() loop checks encouragementCount before idling ✓
916+Test: TestRunningWithRecentEncouragement passes ✓
917+
918+Truth table compliance: VERIFIED
919+Tests encode correct behavior: VERIFIED"
920+```
921+
922+---
923+
924+### Action Items for Workflow Improvement
925+
926+**Immediate (Before Next Workflow Execution):**
927+
928+- [x] Document git command templates in this section
929+- [x] Create mandatory verification checklist
930+- [x] Add good vs bad behavior examples
931+- [ ] Create agent prompt template file (`templates/agent-prompt-fix-implementation.md`)
932+- [ ] Add pre-launch checklist for coordinators (`templates/coordinator-checklist.md`)
933+- [ ] Create post-completion verification script (`scripts/verify-agent-work.sh`)
934+
935+**Short-term (After 2-3 Workflow Executions):**
936+
937+- [ ] Build automated agent verification tool
938+ - Checks: branch exists, commits exist, tests pass, clean tree
939+ - Output: Pass/fail with specific failures highlighted
940+ - Integration: Run before accepting agent work
941+- [ ] Create agent performance metrics tracking
942+ - Track: completion rate, revert rate, verification pass rate
943+ - Report: Per-agent and aggregate statistics
944+ - Use: Identify agents needing prompt improvements
945+- [ ] Develop commit message linter for CI
946+ - Check: includes file paths, line numbers, test results
947+ - Enforce: conventional commits format
948+ - Reject: vague messages like "fix: implement feature"
949+
950+**Medium-term (After 5+ Workflow Executions):**
951+
952+- [ ] Build agent prompt library with versioning
953+ - Templates: implementation agents, review agents, fix agents
954+ - Includes: embedded checklists, command templates, examples
955+ - Versioned: track prompt effectiveness over time
956+- [ ] Create truth table compliance checker tool
957+ - Parse: truth table from architecture docs
958+ - Verify: each row has corresponding test
959+ - Report: coverage gaps and missing scenarios
960+- [ ] Develop agent coordination dashboard
961+ - Status: which agents running, completed, blocked
962+ - Conflicts: detect overlapping file changes early
963+ - Timeline: visualize parallel execution progress
964+
965+**Long-term (Continuous Improvement):**
966+
967+- [ ] Machine learning for agent prompt optimization
968+ - Train on: successful vs failed agent executions
969+ - Identify: patterns in prompt structure that correlate with success
970+ - Suggest: prompt improvements based on historical data
971+- [ ] Automated workflow phase detection system
972+ - Monitor: git state, test results, agent reports
973+ - Detect: current phase without manual declaration
974+ - Alert: when workflow deviates from standard path
975+- [ ] CI/CD integration for agent work
976+ - Hook: run verification on agent branch creation
977+ - Block: merges that fail verification checklist
978+ - Report: verification results in PR comments
979+
980+---
981+
982+**Version:** 1.1
983+**Last updated:** 2026-02-08