How griv32/agentic-proposal-generator works
Project Type and Purpose
• This is a Python-based, CLI-driven multi-agent AI orchestration tool (not a web app).
• Purpose: Ingest a discovery call transcript → run specialist AI agents in parallel → synthesize and self-correct → emit a business proposal.
File Structure
Top-level directories:
• .claude/agents: human-readable agent definitions (markdown)
• src/agentic_proposal_generator/
– agents/: Python implementations of each specialist agent
– mcp/: “MCP Tools” library (business heuristics & utilities)
– parallel_orchestrator.py: core engine for parallel execution
– events.py: pub/sub or event system for agent coordination
– output_parser.py: formatting & streaming CLI output
– cli.py: entry point / argument parsing
• example_usage.py: sample script for end-user
• sample_data/: demonstration transcript
• tests/: unit, integration, manual/live tests
• CI config, packaging (pyproject.toml), linting, security, docs
README for Additional Insights
• Three-phase workflow:
Phase 1: Solutions Engineer, Solution Architect, Commercial Analyst (parallel)
Phase 2: Proposal Writer (synthesis)
Phase 3: Quality Reviewer (self-correction loop & human review)
• MCP Tools (six utility functions available to all agents)
• Async/await patterns for concurrency
• Human-in-the-loop optional via CLI flag
Main Components & Their Interactions
a. Components
– CLI Interface (cli.py / example_usage.py)
– Orchestrator (parallel_orchestrator.py + events.py)
– Agent Workers (solutions_engineer, solution_architect, commercial_analyst, proposal_writer, quality_reviewer)
– MCP Tools Library (mcp/tools.py)
– Output Parser / Formatter (output_parser.py)
– External API: Anthropic Claude via Claude Agent SDK
– Optional Human Review (HUMAN_REVIEW.md flow)
– Data Store: local file system for .md/.json outputs
b. Relationships & Data Flow
1. User invokes CLI → loads transcript.
2. CLI calls Orchestrator → emits events to spin up three parallel agents.
3. Each Agent: receives transcript, optionally calls MCP Tools, returns structured output.
4. Orchestrator collects parallel outputs → fires Proposal Writer agent.
5. Proposal Writer calls MCP Tools, merges data → produces draft proposal.
6. Orchestrator invokes Quality Reviewer → scores draft.
7. If score < threshold → feedback loop → re-emit events to revise prior agents.
8. Once approved, orchestrator writes final proposal to disk/CLI stream.
9. If human review not skipped → pause for user approval before finalizing.
c. Architectural Patterns
– Event-driven, pub/sub coordination between orchestrator and agents
– Parallel execution using asyncio
– Self-correction loop (feedback cycle) as a control flow
– Modular “tool” library for separation of concerns (MCP Tools)
d. Key Technologies & Frameworks
– Python 3.10+ (asyncio, type hints)
– Claude Agent SDK (Anthropic)
– UV for dependency management
– pytest (unit, integration, live tests)
– GitHub Actions (CI/CD workflows)
Detail Level & Scope
– Capture each agent as its own component even if they live in the same directory
– Include the event bus or orchestration mechanism explicitly
– Show both programmatic (API calls to Claude) and human (CLI prompt) interactions
– Don’t forget the Output Parser/Formatter step before writing the final file