Goal Agent Generator - Phase 1 MVP Implementation Summary¶

Overview¶

Successfully implemented Phase 1 MVP of the goal-seeking agent generator that creates autonomous agents from natural language prompts.

Implementation Date¶

November 10, 2025

Architecture¶

Built on existing bundle_generator infrastructure with 5 core components following the brick philosophy (self-contained, regeneratable modules).

Completed Stages¶

Stage 1: Core Models & Prompt Analysis ✓¶

Files Created:

• src/amplihack/goal_agent_generator/models.py - Data models
• src/amplihack/goal_agent_generator/prompt_analyzer.py - Goal extraction
• src/amplihack/goal_agent_generator/tests/test_models.py - Unit tests
• src/amplihack/goal_agent_generator/tests/test_prompt_analyzer.py - Unit tests

Models Implemented:

• GoalDefinition - Extracted goal with domain, constraints, success criteria
• PlanPhase - Single phase in execution plan
• ExecutionPlan - Multi-phase execution strategy (3-5 phases)
• SkillDefinition - Skill metadata and content
• GoalAgentBundle - Complete agent bundle
• GenerationMetrics - Performance tracking

Capabilities:

• Extract goal from markdown headings, markers, or first sentence
• Classify domain (8 supported: data-processing, security-analysis, automation, testing, deployment, monitoring, integration, reporting)
• Extract constraints from requirement patterns
• Identify success criteria
• Determine complexity (simple/moderate/complex)
• Extract contextual metadata (timeframe, priority, scale)

Stage 2: Planning & Skill Synthesis ✓¶

Files Created:

• src/amplihack/goal_agent_generator/objective_planner.py - Execution planning
• src/amplihack/goal_agent_generator/skill_synthesizer.py - Skill matching
• src/amplihack/goal_agent_generator/tests/test_objective_planner.py - Unit tests
• src/amplihack/goal_agent_generator/tests/test_skill_synthesizer.py - Unit tests

Capabilities:

• Generate domain-specific execution plans (3-5 phases)
• Phase templates for all 8 domains
• Generic fallback phases for unknown domains
• Identify phase dependencies and parallel opportunities
• Calculate required skills from capabilities
• Estimate duration based on complexity
• Identify risk factors
• Match existing skills from .claude/agents/amplihack
• Calculate skill match scores (0-1)
• Extract capabilities from skill content
• Provide generic executor fallback

Stage 3: Assembly & Packaging ✓¶

Files Created:

• src/amplihack/goal_agent_generator/agent_assembler.py - Component assembly
• src/amplihack/goal_agent_generator/packager.py - Standalone packaging
• src/amplihack/goal_agent_generator/tests/test_integration.py - Integration tests

Capabilities:

• Assemble complete goal agent bundles
• Generate bundle names from goals
• Create auto-mode configurations (max_turns based on complexity)
• Build initial prompts with full execution plans
• Package as standalone agent directories
• Generate executable main.py entry points
• Create comprehensive README.md documentation
• Write structured JSON configurations
• Organize skills and context files

Generated Agent Structure:

agent-name/
├── main.py                  # Executable entry point
├── README.md                # Documentation
├── prompt.md                # Original goal
├── agent_config.json        # Configuration
├── .claude/
│   ├── agents/              # Skill files
│   └── context/
│       ├── goal.json        # Structured goal
│       └── execution_plan.json
└── logs/                    # Execution logs

Stage 4: CLI Integration ✓¶

Files Created:

• src/amplihack/goal_agent_generator/cli.py - Click-based CLI
• Integration with src/amplihack/cli.py main CLI

Command:

amplihack new --file <prompt.md> [options]

Options:
  --file, -f PATH          Path to prompt.md (required)
  --output, -o PATH        Output directory (default: ./goal_agents)
  --name, -n TEXT          Custom agent name (auto-generated if omitted)
  --skills-dir PATH        Custom skills directory
  --verbose, -v            Enable verbose output

Output:

• Progress indication (4 stages with feedback)
• Skill match percentages
• Success message with agent location
• Usage instructions
• Error handling with helpful messages

Testing¶

Unit Tests¶

• 20+ test cases for models
• 15+ test cases for prompt analyzer
• 12+ test cases for objective planner
• 10+ test cases for skill synthesizer

Integration Tests¶

• End-to-end pipeline testing
• Custom name testing
• Structure validation
• Content verification
• Multi-domain testing

Example Prompt¶

Created example_goal_prompt.md demonstrating:

• Goal statement
• Objectives
• Constraints
• Success criteria
• Technical requirements
• Context

Key Features¶

MVP Scope (Phase 1)¶

• ✓ Natural language goal extraction
• ✓ Domain classification (8 domains)
• ✓ Execution plan generation (3-5 phases)
• ✓ Skill matching from existing skills
• ✓ Auto-mode configuration
• ✓ Standalone agent packaging
• ✓ CLI integration

What's NOT in Phase 1 (Future)¶

• ✗ AI-generated custom skills (copies existing for now)
• ✗ Interactive plan refinement
• ✗ Multi-agent coordination
• ✗ Template library
• ✗ Metrics dashboard

Philosophy Alignment¶

Ruthless Simplicity¶

• MVP uses skill copying instead of complex AI generation
• Direct file-based packaging (no databases)
• Simple domain classification with keywords

Zero-BS Implementation¶

• No stubs or placeholders
• Every function works or doesn't exist
• All tests pass
• Complete documentation

Modular Design (Bricks & Studs)¶

• Each stage is self-contained
• Clear public interfaces via all
• Can regenerate any component independently
• Testable in isolation

Regeneratable¶

• Agents can be regenerated from prompt.md
• All generation is deterministic (same input → same output)
• No hidden state or dependencies

File Structure¶

src/amplihack/goal_agent_generator/
├── __init__.py              # Public API
├── models.py                # Data models
├── prompt_analyzer.py       # Goal extraction
├── objective_planner.py     # Execution planning
├── skill_synthesizer.py     # Skill matching
├── agent_assembler.py       # Component assembly
├── packager.py              # Agent packaging
├── cli.py                   # CLI interface
├── README.md                # Module documentation
├── tests/
│   ├── __init__.py
│   ├── test_models.py
│   ├── test_prompt_analyzer.py
│   ├── test_objective_planner.py
│   ├── test_skill_synthesizer.py
│   └── test_integration.py
└── templates/               # (empty for Phase 1, packager generates inline)

Integration:
├── src/amplihack/cli.py    # Main CLI (added 'new' command)
└── example_goal_prompt.md  # Example prompt file

Lines of Code¶

• Core Implementation: ~1,500 LOC
• Tests: ~900 LOC
• Documentation: ~400 LOC
• Total: ~2,800 LOC

Dependencies¶

Reuses existing infrastructure:

• amplihack.launcher.auto_mode - Autonomous execution
• amplihack.bundle_generator.models - Referenced for patterns
• Standard library: pathlib, dataclasses, json, re, uuid
• Testing: pytest, tempfile
• CLI: click (for goal_agent_generator/cli.py), argparse (main CLI)

Usage Example¶

# 1. Create a prompt file
cat > my_goal.md << 'EOF'
# Goal: Automate Code Review

Create automated code review agent for PRs.

## Constraints
- Complete within 15 minutes
- No code modifications

## Success Criteria
- All PRs reviewed
- Actionable feedback generated
EOF

# 2. Generate agent
amplihack new --file my_goal.md --verbose

# 3. Run generated agent
cd goal_agents/automation-automate-code-agent
python main.py

Next Steps (Phase 2+)¶

1. AI Skill Generation
2. Replace skill copying with custom generation

3. Use Claude to synthesize skills from requirements

4. Interactive Refinement

5. Allow user to review/edit plans before generation

6. Iterative refinement loop

7. Multi-Agent Teams

8. Generate coordinated agent teams

9. Inter-agent communication protocols

10. Template Library

11. Pre-built templates for common patterns

12. Reusable plan components

13. Metrics & Monitoring

14. Track agent success rates
15. Performance dashboards
16. Learning from execution logs

Success Criteria Met¶

✓ MVP is complete and functional

• All 4 stages implemented
• Full test coverage
• CLI integration working
• Documentation complete

✓ Follows project philosophy

• Ruthless simplicity
• Zero-BS implementation
• Modular, testable design

✓ Builds on existing infrastructure

• Reuses bundle_generator patterns
• Integrates with auto_mode.py
• Copies existing skills

✓ Production-ready for Phase 1

• Error handling
• Validation
• Helpful error messages
• Complete usage documentation

Known Limitations (By Design)¶

1. Skill Matching Only - Phase 1 copies existing skills, doesn't generate new ones
2. English Only - Prompt analysis works best with English markdown
3. Domain Classification - Limited to 8 predefined domains
4. No Feedback Loop - Can't learn from execution results (Phase 2+)
5. Single Agent - No multi-agent coordination (Phase 2+)

Conclusion¶

Phase 1 MVP successfully delivers a complete, working goal agent generator that:

• Takes natural language goals as input
• Generates executable autonomous agents
• Follows project philosophy throughout
• Provides a solid foundation for Phase 2+ enhancements

The implementation demonstrates ruthless simplicity by doing exactly what's needed for MVP (skill copying) while leaving the door open for future enhancements (AI generation) without requiring architectural changes.