# 147 Workflow 1c449525 > Multi-Agent Development Workflow - Skill: `tools-only/147-workflow-1c449525` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/147-workflow-1c449525` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/147-workflow-1c449525/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tools-only/147-workflow-1c449525 --- # Multi-Agent Development Workflow > **⚠️ ADVANCED WORKFLOW - FOR REFERENCE ONLY** > > This document describes the **worktree isolation model** with separate branches per agent. The standard `/encode-policy` workflow now uses a **simple branch model** where all agents work on the same branch (`-`) in different folders. > > Use this advanced workflow only if you need strict isolation between test-creator and rules-engineer. ## Architecture Overview This workflow ensures complete isolation between agents during development, preventing any agent from seeing another's work until the appropriate phase. ## Branch and Worktree Isolation ### Initial Setup (Supervisor Agent) ```bash # Create base branch git checkout master git pull origin master git checkout -b feature/-base # Create isolated branches for each agent git checkout -b feature/-docs git checkout -b feature/-tests git checkout -b feature/-rules # Create separate worktrees for complete isolation git worktree add ../pe--docs feature/-docs git worktree add ../pe--tests feature/-tests git worktree add ../pe--rules feature/-rules ``` ### Agent Isolation Rules 1. **Document Collector** - Works in: `../pe--docs/` - Branch: `feature/-docs` - Can see: Only base PolicyEngine code - Creates: Documentation in `docs/agents/sources//` 2. **Test Creator** - Works in: `../pe--tests/` - Branch: `feature/-tests` - Can see: Only base PolicyEngine code (NOT the implementation) - Receives: Document files via supervisor (copied to their worktree) - Creates: Integration tests 3. **Rules Engineer** - Works in: `../pe--rules/` - Branch: `feature/-rules` - Can see: Only base PolicyEngine code (NOT the tests) - Receives: Document files via supervisor (copied to their worktree) - Creates: Parameters and variables with unit tests 4. **Reviewer** (acting as verifier) - Works in: Main repository after merge - Branch: `feature/-verify` - Can see: Everything after supervisor merges - Validates: All components together ## Workflow Phases ### Phase 1: Document Collection ```bash # Supervisor starts Document Collector in isolated environment cd ../pe--docs # Document Collector works here, creates documents git add docs/agents/sources// git commit -m "Add documentation" git push origin feature/-docs ``` ### Phase 2: Parallel Development Supervisor distributes documents WITHOUT merging branches: ```bash # Copy documents to Test Creator worktree cp -r ../pe--docs/docs/agents/sources// \ ../pe--tests/docs/agents/sources// # Copy documents to Rules Engineer worktree cp -r ../pe--docs/docs/agents/sources// \ ../pe--rules/docs/agents/sources// ``` **Test Creator** (in isolated worktree): ```bash cd ../pe--tests # Creates tests based ONLY on documents # CANNOT see any implementation in feature/-rules git add policyengine_us/tests/ git commit -m "Add integration tests" git push origin feature/-tests ``` **Rules Engineer** (in isolated worktree): ```bash cd ../pe--rules # Creates implementation based ONLY on documents # CANNOT see any tests in feature/-tests git add policyengine_us/parameters/ policyengine_us/variables/ git commit -m "Implement rules" git push origin feature/-rules ``` ### Phase 3: Integration and Verification Only now does Supervisor merge everything: ```bash # Create verification branch git checkout master git checkout -b feature/-verify # Merge all work (first time components see each other) git merge --no-ff feature/-docs git merge --no-ff feature/-rules git merge --no-ff feature/-tests # Now Reviewer can see everything and validate ``` ### Phase 4: Verification Reviewer works on the merged branch: - Validates documentation compliance - Runs all tests - Checks references - **Can now see both tests and implementation together** ### Phase 5: Iteration (Multiple Rounds Expected) The development process is inherently iterative. Expect 3-5 rounds of verification and fixes for complex programs. #### Iteration Round Structure: ```bash # Round 1: Initial Verification git checkout feature/-verify git merge --no-ff feature/-docs git merge --no-ff feature/-rules git merge --no-ff feature/-tests # Reviewer finds 15 issues # Round 1: Fixes cd ../pe--rules # Rules Engineer fixes 10 issues based on document references git add -A && git commit -m "Round 1: Fix parameter values and calculation logic" git push cd ../pe--tests # Test Creator fixes 5 issues based on document references git add -A && git commit -m "Round 1: Add missing test cases and fix calculations" git push # Round 2: Re-verification git checkout feature/-verify git reset --hard origin/master git merge --no-ff feature/-docs git merge --no-ff feature/-rules # Updated git merge --no-ff feature/-tests # Updated # Reviewer finds 3 issues # Round 2: Fixes cd ../pe--rules # Rules Engineer fixes remaining issues git add -A && git commit -m "Round 2: Handle edge cases" git push # Round 3: Final Verification git checkout feature/-verify git reset --hard origin/master git merge --no-ff feature/-docs git merge --no-ff feature/-rules # Final git merge --no-ff feature/-tests # Final # Reviewer confirms: ALL TESTS PASS ✓ ``` #### Maintaining Isolation During Iterations: Each agent continues working in their isolated worktree: - Rules Engineer never sees test expectations, even during fixes - Test Creator never sees implementation, even during fixes - Supervisor translates issues into document-based fix requests #### Example Fix Request Translation: ```markdown ❌ WRONG (breaks isolation): "The test expects $450 but implementation returns $500" ✅ CORRECT (maintains isolation): "Review the shelter deduction calculation in 7 CFR 273.9(d)(6)(ii), particularly the order of applying the cap versus the 50% calculation" ``` ## Information Flow Control ### What Each Agent Receives | Agent | Receives | Never Sees (Until Verification) | |-------|----------|----------------------------------| | Document Collector | Program requirements | Tests, Implementation | | Test Creator | Documents only | Implementation, Parameters | | Rules Engineer | Documents only | Integration tests, Expected values | | Reviewer | Everything (after merge) | N/A | ### Supervisor's Role in Isolation The Supervisor must: 1. **Never** share test values with Rules Engineer 2. **Never** share implementation with Test Creator 3. **Only** share documents between agents 4. Manage all branch merging 5. Route fix requests without revealing why ### Example Fix Request Routing ❌ **Wrong** (reveals test information): ``` "Rules Engineer: The benefit calculation returns $450 but should return $500" ``` ✅ **Correct** (references documentation only): ``` "Rules Engineer: Please review the shelter deduction calculation against 7 CFR 273.9(d)(6)(ii). Ensure the excess shelter amount is calculated as specified in the regulation." ``` ## Audit Trail Supervisor maintains audit log: ```markdown # Development Audit Log ## Phase 1: Documents - Collector started: 2024-01-10 09:00 - Documents completed: 2024-01-10 11:00 - Files created: 6 documents ## Phase 2: Parallel Development - Documents distributed: 2024-01-10 11:30 - Test Creator started: 2024-01-10 11:35 - Rules Engineer started: 2024-01-10 11:35 - Tests completed: 2024-01-10 14:00 - Rules completed: 2024-01-10 15:00 ## Information Isolation Verified: - Test Creator worktree never had access to rules branch ✓ - Rules Engineer worktree never had access to tests branch ✓ - Only documents were shared between agents ✓ ## Phase 3: Verification - Branches merged: 2024-01-10 15:30 - Reviewer started: 2024-01-10 15:35 - Issues found: 3 - All issues resolved: 2024-01-10 17:00 ``` ## Technical Implementation ### Using Git Worktrees for Isolation ```bash # Setup script for Supervisor #!/bin/bash PROGRAM=$1 # Create branches git checkout -b feature/${PROGRAM}-docs git checkout -b feature/${PROGRAM}-tests git checkout -b feature/${PROGRAM}-rules # Create isolated worktrees git worktree add ../pe-${PROGRAM}-docs feature/${PROGRAM}-docs git worktree add ../pe-${PROGRAM}-tests feature/${PROGRAM}-tests git worktree add ../pe-${PROGRAM}-rules feature/${PROGRAM}-rules echo "Isolated environments created:" echo " Docs: ../pe-${PROGRAM}-docs/" echo " Tests: ../pe-${PROGRAM}-tests/" echo " Rules: ../pe-${PROGRAM}-rules/" ``` ### Cleanup After Development ```bash # Remove worktrees git worktree remove ../pe--docs git worktree remove ../pe--tests git worktree remove ../pe--rules # Delete branches after PR is merged git branch -d feature/-docs git branch -d feature/-tests git branch -d feature/-rules ``` ## Benefits of This Approach 1. **True Isolation**: Physical separation via worktrees 2. **Parallel Development**: Test and rules developed simultaneously 3. **No Contamination**: Impossible for agents to see each other's work 4. **Audit Trail**: Clear record of isolation maintained 5. **Quality Assurance**: Independent development ensures accuracy ## Summary This workflow ensures that: - Test Creator never sees implementation until verification - Rules Engineer never sees expected test values until verification - Both work from the same authoritative documents - Reviewer validates everything works together correctly - Complete audit trail proves isolation was maintained The physical separation through git worktrees makes it technically impossible for agents to violate isolation rules.