304 lines
12 KiB
Markdown
304 lines
12 KiB
Markdown
---
|
|
description: Orchestrates multi-agent workflow to implement new government benefit programs
|
|
---
|
|
|
|
# Implementing $ARGUMENTS in PolicyEngine
|
|
|
|
Coordinate the multi-agent workflow to implement $ARGUMENTS as a complete, production-ready government benefit program.
|
|
|
|
## Program Type Detection
|
|
|
|
This workflow adapts based on the type of program being implemented:
|
|
|
|
**TANF/Benefit Programs** (e.g., state TANF, SNAP, WIC):
|
|
- Phase 4: test-creator creates both unit and integration tests
|
|
- Phase 7: Uses specialized @complete:country-models:tanf-program-reviewer agent in parallel validation
|
|
- Optional phases: May be skipped for simplified implementations
|
|
|
|
**Other Government Programs** (e.g., tax credits, deductions):
|
|
- Phase 4: test-creator creates both unit and integration tests
|
|
- Phase 7: Uses general @complete:country-models:implementation-validator agent in parallel validation
|
|
- Optional phases: Include based on production requirements
|
|
|
|
## Phase 0: Implementation Approach (TANF Programs Only)
|
|
|
|
**For TANF programs, detect implementation approach from $ARGUMENTS:**
|
|
|
|
**Auto-detect from user's request:**
|
|
- If $ARGUMENTS contains "simple" or "simplified" → Use **Simplified** approach
|
|
- If $ARGUMENTS contains "full" or "complete" → Use **Full** approach
|
|
- If unclear → Default to **Simplified** approach
|
|
|
|
**Simplified Implementation:**
|
|
- Use federal baseline for gross income, demographic eligibility, immigration eligibility
|
|
- Faster implementation
|
|
- Suitable for most states that follow federal definitions
|
|
- Only creates state-specific variables for: income limits, disregards, benefit amounts, final calculation
|
|
|
|
**Full Implementation:**
|
|
- Create state-specific income definitions, eligibility criteria
|
|
- More detailed implementation
|
|
- Required when state has unique income definitions or eligibility rules
|
|
- Creates all state-specific variables
|
|
|
|
**Record the detected approach and pass it to Phase 4 (rules-engineer).**
|
|
|
|
## Phase 1: Issue and PR Setup
|
|
|
|
Invoke @complete:country-models:issue-manager agent to:
|
|
- Search for existing issue or create new one for $ARGUMENTS
|
|
- Create draft PR immediately in PolicyEngine/policyengine-us repository (NOT personal fork)
|
|
- Return issue number and PR URL for tracking
|
|
|
|
## Phase 2: Variable Naming Convention
|
|
Invoke @complete:country-models:naming-coordinator agent to:
|
|
- Analyze existing naming patterns in the codebase
|
|
- Establish variable naming convention for $ARGUMENTS
|
|
- Analyze existing folder structure patterns in the codebase
|
|
- Post naming decisions and folder structure to GitHub issue for all agents to reference
|
|
|
|
**Quality Gate**: Naming convention and folder structure must be documented before proceeding to ensure consistency across parallel development.
|
|
|
|
## Phase 3: Document Collection
|
|
|
|
**Phase 3A: Initial Document Gathering**
|
|
|
|
Invoke @complete:country-models:document-collector agent to gather official $ARGUMENTS documentation, save as `working_references.md` in the repository, and post to GitHub issue
|
|
|
|
**After agent completes:**
|
|
1. Check the agent's report for "📄 PDFs Requiring Extraction" section
|
|
2. **Decision Point:**
|
|
- **If PDFs are CRITICAL** (State Plans with benefit formulas, calculation methodology):
|
|
- Ask the user: "Please send me these PDF URLs so I can extract their content:"
|
|
- List each PDF URL on a separate line
|
|
- Wait for user to send the URLs (they will auto-extract)
|
|
- Proceed to Phase 3B
|
|
- **If PDFs are SUPPLEMENTARY** (additional reference, not essential):
|
|
- Note them for future reference
|
|
- Proceed directly to Phase 4 with current documentation
|
|
|
|
3. **If no PDFs listed:**
|
|
- Skip to Phase 4 (documentation complete)
|
|
|
|
**Phase 3B: PDF Extraction & Complete Documentation** (Only if CRITICAL PDFs found)
|
|
|
|
1. After receiving extracted PDF content from user:
|
|
2. Relaunch @complete:country-models:document-collector agent with:
|
|
- Original task description
|
|
- Extracted PDF content included in prompt
|
|
- Instruction: "You are in Phase 2 - integrate this PDF content with your HTML research"
|
|
3. Agent creates complete documentation
|
|
|
|
**Quality Gate**: Documentation must include:
|
|
- Official program guidelines or state plan
|
|
- Income limits and benefit schedules
|
|
- Eligibility criteria and priority groups
|
|
- Seasonal/temporal rules if applicable
|
|
- ✅ All critical PDFs extracted and integrated (if applicable)
|
|
|
|
## Phase 4: Development (Parallel on Same Branch)
|
|
|
|
Run both agents IN PARALLEL - they work on different folders so no conflicts:
|
|
|
|
**@complete:country-models:test-creator** → works in `tests/` folder:
|
|
- Create comprehensive INTEGRATION tests from documentation
|
|
- Create UNIT tests for each variable that will have a formula
|
|
- Both test types created in ONE invocation
|
|
- Use only existing PolicyEngine variables
|
|
- Test realistic calculations based on documentation
|
|
|
|
**@complete:country-models:rules-engineer** → works in `variables/` + `parameters/` folders:
|
|
- **Implementation Approach:** [Pass the decision from Phase 0: "simplified" or "full"]
|
|
- **If Simplified TANF:** Do NOT create state-specific gross income variables - use federal baseline (`tanf_gross_earned_income`, `tanf_gross_unearned_income`)
|
|
- **If Full TANF:** Create complete state-specific income definitions as needed
|
|
- **Step 1:** Create all parameters first using embedded parameter-architect patterns
|
|
- Complete parameter structure with all thresholds, amounts, rates
|
|
- Include proper references from documentation
|
|
- **Step 2:** Implement variables using the parameters
|
|
- Zero hard-coded values
|
|
- Complete implementations only
|
|
- Follow simplified/full approach from Phase 0
|
|
|
|
**Quality Requirements**:
|
|
- rules-engineer: ZERO hard-coded values, parameters created before variables
|
|
- test-creator: All tests (unit + integration) created together, based purely on documentation
|
|
|
|
## Phase 5: Pre-Push Validation
|
|
Invoke @complete:country-models:pr-pusher agent to:
|
|
- Ensure changelog entry exists
|
|
- Run formatters (black, isort)
|
|
- Fix any linting issues
|
|
- Run local tests for quick validation
|
|
- Push branch and report initial CI status
|
|
|
|
**Quality Gate**: Branch must be properly formatted with changelog before continuing.
|
|
|
|
## Optional Enhancement Phases
|
|
|
|
**These phases are OPTIONAL and should be considered based on implementation type:**
|
|
|
|
### For Production-Ready Implementations:
|
|
The following enhancements may be applied to ensure production quality:
|
|
|
|
1. **Cross-Program Validation**
|
|
- @complete:country-models:cross-program-validator: Check interactions with other benefits
|
|
- Prevents benefit cliffs and unintended interactions
|
|
|
|
2. **Documentation Enhancement**
|
|
- @complete:country-models:documentation-enricher: Add examples and regulatory citations
|
|
- Improves maintainability and compliance verification
|
|
|
|
3. **Performance Optimization**
|
|
- @complete:country-models:performance-optimizer: Vectorize and optimize calculations
|
|
- Ensures scalability for large-scale simulations
|
|
|
|
**Decision Criteria:**
|
|
- **Simplified/Experimental TANF**: Skip these optional phases
|
|
- **Production TANF**: Include based on specific requirements
|
|
- **Full Production Deployment**: Include all enhancements
|
|
|
|
## Phase 6: Validation
|
|
|
|
**Run validators to check implementation quality:**
|
|
|
|
**@complete:country-models:implementation-validator:**
|
|
- Check for hard-coded values in variables
|
|
- Verify placeholder or incomplete implementations
|
|
- Check federal/state parameter organization
|
|
- Assess test quality and coverage
|
|
- Identify performance and vectorization issues
|
|
|
|
**For TANF/Benefit Programs, also run @complete:country-models:tanf-program-reviewer:**
|
|
- Learn from PA TANF and OH OWF reference implementations first
|
|
- Validate code formulas against regulations
|
|
- Verify test coverage with manual calculations
|
|
- Check parameter structure and references
|
|
- Focus on: eligibility rules, income disregards, benefit formulas
|
|
|
|
**Quality Gate:** Review validator reports before proceeding
|
|
|
|
## Phase 7: Local Testing & Fixes
|
|
**CRITICAL: ALWAYS invoke @complete:country-models:ci-fixer agent - do NOT manually fix issues**
|
|
|
|
Invoke @complete:country-models:ci-fixer agent to:
|
|
- Run all tests locally: `policyengine-core test policyengine_us/tests/policy/baseline/gov/states/[STATE]/[PROGRAM] -c policyengine_us -v`
|
|
- Identify ALL failing tests
|
|
- For each failing test:
|
|
- Read the test file to understand expected values
|
|
- Read the actual test output to see what was calculated
|
|
- Determine root cause: incorrect test expectations OR bug in implementation
|
|
- Fix the issue:
|
|
- If test expectations are wrong: update the test file with correct values
|
|
- If implementation is wrong: fix the variable/parameter code
|
|
- Re-run tests to verify fix
|
|
- Iterate until ALL tests pass locally
|
|
- **Reference Verification**
|
|
- Verify all parameters have reference metadata
|
|
- Verify all variables have reference fields
|
|
- Keep `sources/` folder files for future reference
|
|
- If references missing: Create todos for adding them
|
|
- Run `make format` before committing fixes
|
|
- Push final fixes to PR branch
|
|
|
|
**Success Metrics**:
|
|
- All tests pass locally (green output)
|
|
- All references embedded in code metadata
|
|
- `sources/` folder kept for future reference
|
|
- Code properly formatted
|
|
- Implementation complete and working
|
|
- Clean commit history
|
|
|
|
## Phase 8: Final Summary
|
|
|
|
After all tests pass and references are embedded:
|
|
- Update PR description with final implementation status
|
|
- Add summary of what was implemented
|
|
- Report completion to user
|
|
- **Keep PR as draft** - user will mark ready when they choose
|
|
- **WORKFLOW COMPLETE**
|
|
|
|
## Anti-Patterns This Workflow Prevents
|
|
|
|
1. **Hard-coded values**: Rules-engineer enforces parameterization
|
|
2. **Incomplete implementations**: Validator catches before PR
|
|
3. **Federal/state mixing**: Proper parameter organization enforced
|
|
4. **Non-existent variables in tests**: Test creator uses only real variables
|
|
5. **Missing edge cases**: Edge-case-generator covers all boundaries
|
|
6. **Benefit cliffs**: Cross-program-validator identifies interactions
|
|
7. **Poor documentation**: Documentation-enricher adds examples
|
|
8. **Performance issues**: Performance-optimizer ensures vectorization
|
|
9. **Review delays**: Most issues caught and fixed automatically
|
|
|
|
## Execution Instructions
|
|
|
|
**YOUR ROLE**: You are an orchestrator ONLY. You must:
|
|
1. Invoke agents using the Task tool
|
|
2. Wait for their completion
|
|
3. Check quality gates
|
|
4. **PAUSE and wait for user confirmation before proceeding to next phase**
|
|
|
|
**YOU MUST NOT**:
|
|
- Write any code yourself
|
|
- Fix any issues manually
|
|
- Run tests directly
|
|
- Edit files
|
|
|
|
**Execution Flow (ONE PHASE AT A TIME)**:
|
|
|
|
Execute each phase sequentially and **STOP after each phase** to wait for user instructions:
|
|
|
|
0. **Phase 0**: Implementation Approach (TANF Programs Only)
|
|
- Auto-detect from $ARGUMENTS ("simple"/"simplified" vs. "full"/"complete")
|
|
- Default to Simplified if unclear
|
|
- Inform user of detected approach
|
|
- **STOP - Wait for user to say "continue" or provide adjustments**
|
|
|
|
1. **Phase 1**: Issue and PR Setup
|
|
- Complete the phase
|
|
- Report results
|
|
- **STOP - Wait for user to say "continue" or provide adjustments**
|
|
|
|
2. **Phase 2**: Variable Naming Convention
|
|
- Complete the phase
|
|
- Report results
|
|
- **STOP - Wait for user to say "continue" or provide adjustments**
|
|
|
|
3. **Phase 3**: Document Collection
|
|
- Complete the phase
|
|
- Report results
|
|
- **STOP - Wait for user to say "continue" or provide adjustments**
|
|
|
|
4. **Phase 4**: Development (Test + Implementation)
|
|
- Pass simplified/full decision to rules-engineer
|
|
- Run test-creator and rules-engineer in parallel (different folders)
|
|
- Report results
|
|
- **STOP - Wait for user to say "continue" or provide adjustments**
|
|
|
|
5. **Phase 5**: Pre-Push Validation
|
|
- Complete the phase
|
|
- Report results
|
|
- **STOP - Wait for user to say "continue" or provide adjustments**
|
|
|
|
6. **Phase 6**: Validation
|
|
- Run validators
|
|
- Report results
|
|
- **STOP - Wait for user to say "continue" or provide adjustments**
|
|
|
|
7. **Phase 7**: Local Testing & Fixes (Including Reference Verification)
|
|
- Complete the phase
|
|
- Report results
|
|
- **STOP - Wait for user to say "continue" or provide adjustments**
|
|
|
|
8. **Phase 8**: Final Summary
|
|
- Update PR description
|
|
- Report final results (keep PR as draft)
|
|
- **WORKFLOW COMPLETE**
|
|
|
|
**CRITICAL RULES**:
|
|
- Do NOT proceed to the next phase until user explicitly says to continue
|
|
- After each phase, summarize what was accomplished
|
|
- If user provides adjustments, incorporate them before continuing
|
|
- All 8 phases are REQUIRED - pausing doesn't mean skipping
|
|
|
|
If any agent fails, report the failure but DO NOT attempt to fix it yourself. Wait for user instructions.
|