zhongwei/gh-policyengine-policyengine-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:47:43 +08:00
commit 2e8d89fca3
41 changed files with 14051 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

303
commands/encode-policy.md Normal file
View File

@@ -0,0 +1,303 @@
---
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.