xonecas.io
60255
Zn

Zoea-Nova / commit 60a12dd

docs: add multi-agent development workflow

Document the successful workflow used for the nudge system refactor:
- Phase 1: Create truth table and architecture docs
- Phase 2: Parallel agent implementation (minimum 3 agents)
- Phase 3: Integration review and test verification
- Phase 4: Regression analysis with review agents
- Phase 5: Fix implementation with multiple solution approaches
- Phase 6: User review and commit

This workflow coordinated 11 agents across 6 phases to complete a -785 line
refactor in ~2 hours (vs estimated 8-12 hours sequential work).

Key principles:
- Truth table before code (prevents scope creep)
- Minimum 3 agents for parallel work (4-6x speedup)
- Independent review agents catch critical bugs
- Multiple fix approaches reveal best solution
- User review at end prevents wasted work

Marked for future revision to refine agent counts, timing guidelines,
and decision trees for when to use each phase.

xonecas2026-02-07 60a12dd78b48e4f24427bcb4ed3929af1927dc5e parent 82df0ce

1 file changed

WORKFLOW.md+440−0
@@ -0,0 +1,440 @@
1+# Zoea Nova Development Workflow
2+
3+## Purpose
4+
5+This document defines the standard workflow for complex refactoring and architectural changes in Zoea Nova. It codifies the process used successfully for the nudge-to-encouragement system migration (commit 82df0ce, -785 lines, 11 agents coordinated).
6+
7+---
8+
9+## When to Use This Workflow
10+
11+Use this workflow for:
12+- **Architectural changes** - Replacing core systems or patterns
13+- **Large refactoring** - Changes spanning 10+ files or 500+ lines
14+- **API changes** - Modifications to core interfaces or contracts
15+- **System redesign** - Changing fundamental behavior or state machines
16+
17+Do NOT use for:
18+- Simple bug fixes (1-2 files, clear scope)
19+- Documentation-only changes
20+- Dependency updates
21+- Configuration tweaks
22+
23+---
24+
25+## Workflow Phases
26+
27+### Phase 1: Document the Truth
28+
29+**Goal:** Create single source of truth before touching code.
30+
31+**Steps:**
32+
33+1. **Analyze the problem**
34+ - What's broken or needs changing?
35+ - What's the root cause?
36+ - What are the constraints?
37+
38+2. **Create truth table**
39+ - Document all possible states
40+ - Document all transitions
41+ - Document trigger conditions
42+ - Document counter/flag behavior
43+
44+3. **Write architecture document**
45+ - Location: `documentation/architecture/`
46+ - Include:
47+ - Truth table (state × condition → action)
48+ - Message flow diagrams
49+ - Code location references
50+ - Design rationale (why this approach)
51+ - Migration path (current → target)
52+ - Format: Clear, specific, testable assertions
53+
54+4. **Review with user**
55+ - Present truth table
56+ - Verify assumptions
57+ - Get explicit approval before coding
58+
59+**Deliverable:** Architecture doc with truth table in `documentation/architecture/`
60+
61+**Example:** `MESSAGE_FORMAT_GUARANTEES.md` with state/message/counter truth table
62+
63+---
64+
65+### Phase 2: Parallel Agent Implementation
66+
67+**Goal:** Execute changes efficiently using coordinated agent fleet.
68+
69+**Minimum agents:** 3 (recommended: 5-6 for large changes)
70+
71+**Steps:**
72+
73+1. **Break work into independent tasks**
74+ - Each task should be:
75+ - Isolated (no dependencies on other agents)
76+ - Testable (can verify independently)
77+ - Bounded (clear start/end)
78+ - Example tasks:
79+ - Agent 1: Remove obsolete code (ticker, channels)
80+ - Agent 2: Remove provider fallbacks
81+ - Agent 3: Rename variables across codebase
82+ - Agent 4: Implement counter increment logic
83+ - Agent 5: Implement counter reset logic
84+ - Agent 6: Update tests
85+
86+2. **Launch agents in parallel**
87+ - Use task tool with clear instructions
88+ - Reference the truth table document
89+ - Specify what NOT to change (avoid conflicts)
90+ - Request specific deliverables (summary with line numbers)
91+
92+3. **Monitor agent completion**
93+ - Agents return task_id for resumption
94+ - Review each agent's summary as it completes
95+ - Note any unexpected issues
96+
97+**Deliverable:** All assigned tasks completed, summaries from each agent
98+
99+**Example:** 6 agents removed ticker code, renamed variables, updated tests in parallel (~15 min total vs ~90 min sequential)
100+
101+---
102+
103+### Phase 3: Integration Review
104+
105+**Goal:** Verify agent work integrates correctly and matches truth table.
106+
107+**Steps:**
108+
109+1. **Check for conflicts**
110+ - Review overlapping changes
111+ - Verify no duplicate edits
112+ - Check for missing dependencies
113+
114+2. **Verify truth table compliance**
115+ - For each row in truth table:
116+ - Find corresponding code
117+ - Verify behavior matches spec
118+ - Test the scenario
119+
120+3. **Build verification**
121+ - Run `make build`
122+ - Fix compilation errors
123+ - Check for LSP errors
124+
125+4. **Test verification**
126+ - Run `make test`
127+ - Review failures
128+ - Categorize: real bugs vs outdated tests
129+
130+5. **Fix integration issues**
131+ - Address conflicts between agents
132+ - Remove duplicate code
133+ - Fix broken tests
134+ - Handle edge cases
135+
136+**Deliverable:** Clean build, passing tests, truth table verified
137+
138+**Example:** Found and fixed encouragementCount reset in wrong location, removed duplicate test code, updated provider tests
139+
140+---
141+
142+### Phase 4: Regression Analysis
143+
144+**Goal:** Find issues the first agent pass missed.
145+
146+**Minimum review agents:** 3 (independent perspectives)
147+
148+**Steps:**
149+
150+1. **Launch review agents**
151+ - Each agent reviews different aspect:
152+ - Agent 1: State transition correctness
153+ - Agent 2: Trigger mechanisms and flow
154+ - Agent 3: Test coverage and edge cases
155+ - Reference truth table for verification
156+ - Request specific issue analysis format
157+
158+2. **Compare findings**
159+ - Look for consensus (all agents found same issue)
160+ - Look for unique findings (one agent caught something)
161+ - Prioritize by severity
162+
163+3. **Validate findings**
164+ - Check if issue is real or false positive
165+ - Verify against truth table
166+ - Test the scenario if unclear
167+
168+4. **Fix critical issues**
169+ - Use additional agents if fix is complex
170+ - Or fix manually if straightforward
171+ - Re-verify after fix
172+
173+**Deliverable:** All critical regressions found and fixed
174+
175+**Example:** 3 review agents found run() loop was empty (critical), Start() didn't reset counter (high), SendMessageFrom didn't auto-start idle myses (high)
176+
177+---
178+
179+### Phase 5: Fix Implementation
180+
181+**Goal:** Implement fixes for issues found in regression analysis.
182+
183+**Approach:** Multiple agents with different solutions (if complex)
184+
185+**Steps:**
186+
187+1. **For complex fixes:**
188+ - Launch 3 agents with same requirements
189+ - Each agent implements independent solution
190+ - Compare approaches:
191+ - Code simplicity
192+ - Performance
193+ - Maintainability
194+ - Risk level
195+ - Choose best solution or merge ideas
196+
197+2. **For simple fixes:**
198+ - Implement directly
199+ - Verify against truth table
200+ - Test immediately
201+
202+3. **Integration test**
203+ - Run full test suite
204+ - Verify all edge cases
205+ - Check performance
206+
207+**Deliverable:** Working implementation matching truth table
208+
209+**Example:** 3 agents proposed different run() loop fixes (direct call, extracted helper, polling), chose simplest working solution
210+
211+---
212+
213+### Phase 6: User Review and Commit
214+
215+**Goal:** Get user approval and create clean commit history.
216+
217+**Steps:**
218+
219+1. **Present summary**
220+ - What changed (high level)
221+ - What was removed (line counts)
222+ - What was added (new behavior)
223+ - Test status (coverage, pass rate)
224+ - Truth table compliance verification
225+
226+2. **User review**
227+ - User verifies changes match expectations
228+ - User tests manually if needed
229+ - User documents any unrelated issues found
230+
231+3. **Create commit**
232+ - Use conventional commits format
233+ - Include:
234+ - Type (refactor, feat, fix)
235+ - Short summary (what changed)
236+ - Detailed body (what/why for each area)
237+ - Statistics (lines changed, files affected)
238+ - Verification (tests passing, coverage)
239+ - Reference truth table document
240+
241+4. **Final verification**
242+ - `git show --stat HEAD`
243+ - Verify commit message accuracy
244+ - Verify all changes included
245+
246+**Deliverable:** Clean commit matching conventional commits style, user approval
247+
248+**Example:** Single comprehensive commit with detailed breakdown of all changes, +888 -1673 lines
249+
250+---
251+
252+## Success Metrics
253+
254+A successful workflow execution should achieve:
255+
256+1. **Correctness:** All truth table scenarios verified in code
257+2. **Completeness:** No missing edge cases or half-implemented features
258+3. **Test coverage:** All new behavior has tests, obsolete tests removed
259+4. **Documentation:** Truth table doc created, outdated comments cleaned
260+5. **Code quality:** Net negative lines (removed complexity)
261+6. **Build status:** All tests passing, clean compilation
262+7. **Efficiency:** Parallel agents complete in fraction of sequential time
263+
264+---
265+
266+## Anti-Patterns to Avoid
267+
268+**DON'T:**
269+- Code before documenting the truth table
270+- Use single agent for large multi-file changes
271+- Skip regression analysis phase
272+- Commit without user review
273+- Leave TODO comments for "later cleanup"
274+- Mix unrelated changes in one commit
275+- Write tests after implementation (write truth table first)
276+
277+**DO:**
278+- Document state machines and truth tables upfront
279+- Use minimum 3 agents for complex changes
280+- Review agent work before moving forward
281+- Get explicit user approval
282+- Clean up as you go (remove obsolete code immediately)
283+- Split commits by logical concern
284+- Write architecture docs that match implementation
285+
286+---
287+
288+## Tool Usage
289+
290+### Agent Coordination
291+
292+**Parallel execution:**
293+```
294+Agent 1: Remove subsystem A
295+Agent 2: Remove subsystem B
296+Agent 3: Rename variables
297+Agent 4: Implement new behavior X
298+Agent 5: Implement new behavior Y
299+Agent 6: Update tests
300+```
301+
302+**Sequential execution:**
303+```
304+Phase 1: Agents 1-6 (implementation)
305+Phase 2: Review integration
306+Phase 3: Agents 7-9 (regression review)
307+Phase 4: Agents 10-12 (fix implementation)
308+Phase 5: Final verification
309+```
310+
311+### Review Agents
312+
313+Always launch minimum 3 review agents with:
314+- Different focus areas (state, flow, tests)
315+- Independent analysis (no communication)
316+- Specific deliverables (issue list with line numbers)
317+- Truth table reference
318+
319+### Fix Agents
320+
321+For complex fixes, launch 3 agents with:
322+- Same requirements
323+- Different approaches encouraged
324+- Complete implementation expected
325+- Comparison matrix requested
326+
327+Choose best solution or merge ideas.
328+
329+---
330+
331+## Template Checklist
332+
333+Use this checklist for each workflow execution:
334+
335+- [ ] Phase 1: Truth table documented in `documentation/architecture/`
336+- [ ] Phase 1: User approved truth table
337+- [ ] Phase 2: Minimum 3 agents launched for implementation
338+- [ ] Phase 2: All agents completed and summarized work
339+- [ ] Phase 3: Build successful (`make build`)
340+- [ ] Phase 3: Initial test run completed
341+- [ ] Phase 3: Integration issues fixed
342+- [ ] Phase 4: Minimum 3 review agents launched
343+- [ ] Phase 4: All review findings documented
344+- [ ] Phase 4: Critical issues prioritized
345+- [ ] Phase 5: Fixes implemented (3 agents if complex)
346+- [ ] Phase 5: Final test run passing
347+- [ ] Phase 5: Truth table scenarios verified
348+- [ ] Phase 6: User reviewed changes
349+- [ ] Phase 6: Commit created with detailed message
350+- [ ] Phase 6: Commit verified with `git show --stat`
351+
352+---
353+
354+## Real-World Example: Nudge System Refactor
355+
356+**Phase 1:**
357+- Problem: Myses auto-idling after 90s despite processing broadcasts
358+- Truth table: Created MESSAGE_FORMAT_GUARANTEES.md with 7-row state table
359+- User approval: Confirmed new encouragement-based approach
360+
361+**Phase 2:**
362+- 6 agents launched in parallel
363+- Agent 1: Removed ticker (450 lines)
364+- Agent 2: Removed provider fallbacks (24 lines)
365+- Agent 3: Renamed variables (28 occurrences)
366+- Agent 4: Implemented counter increment
367+- Agent 5: Implemented counter reset
368+- Agent 6: Updated initial tests
369+
370+**Phase 3:**
371+- Build: Successful
372+- Tests: 88/91 passing (3 timeout failures)
373+- Integration: Fixed duplicate code, updated provider tests
374+- Time: ~30 minutes
375+
376+**Phase 4:**
377+- 3 review agents launched
378+- All found: run() loop empty (critical bug)
379+- Findings: 4 issues (1 critical, 2 high, 1 low)
380+- Prioritized: Fix run() loop immediately
381+
382+**Phase 5:**
383+- 3 fix agents launched (different approaches)
384+- Agent 1: Direct call (simple, working)
385+- Agent 2: Extracted helper (clean but complex)
386+- Agent 3: Polling loop (works but inefficient)
387+- Chose: Agent 1 solution (already tested)
388+
389+**Phase 6:**
390+- User review: Manual testing revealed unrelated issues (documented in TODO)
391+- Commit: Single comprehensive refactor commit
392+- Result: 21 files, -785 lines, all tests passing
393+
394+**Total time:** ~2 hours (vs estimated 8-12 hours sequential)
395+
396+---
397+
398+## Lessons Learned
399+
400+1. **Truth table prevents scope creep** - Clear boundaries for what changes
401+2. **Parallel agents are 4-6x faster** - Independent work, no blocking
402+3. **Review agents catch critical bugs** - Fresh perspective finds issues
403+4. **Multiple fix approaches reveal best solution** - Compare, don't guess
404+5. **User review at end prevents wasted work** - Manual testing finds real issues
405+6. **Single commit preferred for refactors** - Atomic, easy to revert
406+
407+---
408+
409+## Workflow Evolution
410+
411+This workflow will evolve based on experience. Future improvements:
412+
413+- [ ] Add metrics tracking (agent count, time per phase, bugs found)
414+- [ ] Refine agent task templates (reusable prompts)
415+- [ ] Optimize agent count (minimum effective team size)
416+- [ ] Improve review agent focus areas (coverage matrix)
417+- [ ] Streamline fix agent comparison (scoring rubric)
418+
419+---
420+
421+## Notes for Revision
422+
423+**User requested:** Review and refine this workflow for general use
424+
425+**Questions to address:**
426+- Optimal agent count per phase?
427+- How to handle mid-flight scope changes?
428+- When to abort and restart vs push through?
429+- How to handle conflicting agent solutions?
430+- Metrics for "is this working well"?
431+
432+**Future additions:**
433+- Phase timing guidelines (how long should each phase take?)
434+- Agent prompt templates for common tasks
435+- Decision tree for when to use which phase
436+- Rollback procedure if workflow fails mid-execution
437+
438+---
439+
440+Last updated: 2026-02-07