Crystal Agentic Team - Implementation Roadmap

This roadmap turns the PRD into a build sequence that starts with the smallest useful system and expands only after each layer is stable.

Guiding Principles

• Start with a CLI-first MVP.
• Keep the first version workflow-driven, not autonomous.
• Use small, specialized agents with narrow tool access.
• Add human approval gates before any risky action.
• Prefer simple storage and file-based artifacts before introducing heavier infrastructure.

Target Architecture

• Runtime: Python
• Execution: Docker Compose on a single VPS
• Entry point: Orchestrator
• Control plane: Workflow engine
• Intelligence layer: Specialized agents
• Capability layer: Tools
• State layer: Simple memory files and run artifacts
• Interface: CLI first, web dashboard later

Milestone 0 - Project Skeleton

Goal: establish the repo, runtime shape, and base conventions before any agent logic.

Tasks

1. Create the project structure.

   • orchestrator/
   • agents/
   • workflows/
   • tools/
   • memory/
   • runs/
   • logs/

2. Define the core interfaces.

   • task input format
   • workflow definition format
   • agent request/response schema
   • tool invocation schema
   • run artifact structure

3. Set up the execution environment.

   • Python project scaffolding
   • Dockerfile(s)
   • Docker Compose
   • environment variable handling for secrets

4. Create the base observability layer.

   • structured run logs
   • per-run output folders
   • error capture and status tracking

Deliverables

• A runnable empty system that can accept a task and produce a logged run.
• A repo layout ready for incremental development.

Exit Criteria

• A basic CLI command can start a run and record its result.
• Run artifacts are written to disk with a predictable structure.

Milestone 1 - Core Orchestration MVP

Goal: prove the system can route work through the orchestrator and one workflow end to end.

Scope

• Orchestrator
• CEO agent
• Developer agent
• Tester agent
• Research agent
• Content agent

Tasks

1. Implement the orchestrator.

   • receive a user task
   • classify the task
   • select a workflow
   • route work to agents
   • collect outputs

2. Implement a minimal workflow engine.

   • sequential workflow steps
   • simple branching on success/failure
   • run state persistence

3. Implement the first agent set.

   • CEO: task routing and high-level planning
   • Developer: code or spec drafting
   • Tester: test case generation and validation
   • Research: information gathering
   • Content: writing and editing outputs

4. Implement the first tools.

   • repository reader
   • repository writer
   • test runner
   • web search
   • file writer for logs and outputs

5. Define the first memory files.

   • memory/company.md
   • memory/product.md
   • memory/pricing.md
   • memory/coding_standards.md

6. Create two starter workflows.

   • feature spec generation
   • content drafting

Deliverables

• A request can flow from orchestrator to agents and produce saved outputs.
• Two workflows run consistently with logged steps.

Exit Criteria

• A single command can generate a feature spec or content draft.
• Outputs are readable, stored per run, and easy to review manually.
• Tool access is limited by agent role.

Milestone 2 - Approval and Safety Controls

Goal: make the system safe enough to use with real company assets.

Tasks

1. Add tool permissions per agent.

   • allowlist tools by role
   • deny all unspecified tools

2. Add approval gates for risky actions.

   • deploy code
   • send email
   • launch ads
   • modify database records

3. Add audit logging.

   • who requested the action
   • which agent decided it
   • which tools were called
   • whether approval was granted

4. Add safer tool execution boundaries.

   • containerized execution
   • restricted filesystem access
   • env-based secret injection

Deliverables

• A permission model enforced at runtime.
• Approval-required actions block until explicitly approved.

Exit Criteria

• A blocked action cannot execute without approval.
• Every tool call is traceable in logs.

Milestone 3 - Operational Workflows

Goal: expand from demo workflows to practical business automation.

Scope

• Reviewer
• DevOps
• Ads Manager
• Sales Assistant
• SEO
• Analytics

Tasks

1. Add the new agents.

   • Reviewer for quality checks
   • DevOps for release-related tasks
   • Ads Manager for campaign operations
   • Sales Assistant for lead and follow-up tasks
   • SEO for search-focused content
   • Analytics for reporting and insights

2. Add business tools.

   • CRM update
   • email send
   • calendar scheduling
   • ad platform integration
   • product usage stats
   • demo tenant creation
   • report generation

3. Add operational workflows.

   • lead follow-up
   • campaign creation
   • bug triage
   • release preparation
   • customer reporting
   • proposal generation

4. Introduce simple workflow templates.

   • reusable step definitions
   • consistent output formats
   • shared validation rules

Deliverables

• The system handles real company operational tasks, not just examples.

Exit Criteria

• At least one workflow from sales, one from marketing, and one from ops runs end to end.
• Outputs can be reviewed and approved before execution.

Milestone 4 - Visibility and Operator Experience

Goal: reduce friction for day-to-day use.

Tasks

1. Add a web dashboard.

   • task submission
   • run status
   • output review
   • approval queue

2. Add run history browsing.

   • filter by workflow
   • filter by agent
   • filter by status

3. Add summaries and reporting.

   • daily run summary
   • weekly activity summary
   • failure summary

4. Add better observability.

   • structured events
   • step timing
   • error grouping

Deliverables

• Non-technical users can submit, review, and approve tasks through a UI.

Exit Criteria

• Common tasks can be tracked without reading raw logs.
• Approval and run status are visible in one place.

Milestone 5 - Smarter Routing and Memory

Goal: improve quality and reuse without making the system complex.

Tasks

1. Add model routing by task type.

   • stronger reasoning model for planning
   • cheaper model for content drafts
   • code-focused model for development tasks

2. Improve memory handling.

   • task history by run
   • historical campaign storage
   • customer feedback storage

3. Add optional retrieval search.

   • search past runs
   • reuse prior outputs
   • surface relevant artifacts during planning

Deliverables

• The system becomes more efficient and more consistent over time.

Exit Criteria

• New tasks can reference prior runs and reuse useful artifacts.
• Model selection is explicit and configurable.

Recommended Build Order

1. Project skeleton
2. Orchestrator and workflow engine
3. Tool layer with permissions
4. Logging and run artifacts
5. CEO, Developer, Tester, Research, Content agents
6. First two workflows
7. Approval gates and audit logs
8. Sales, marketing, and ops agents
9. Dashboard and run history
10. Smarter memory and model routing

Definition of Done for the MVP

The MVP is done when:

• one CLI command can start a run
• the orchestrator routes the request to the right workflow
• at least two workflows complete successfully
• outputs are written to run folders
• tool access is restricted by role
• risky actions require approval
• logs clearly show the path of execution

Suggested First Sprint

• Finalize the repo structure.
• Implement the orchestrator shell.
• Implement the workflow runner.
• Add logging and run artifacts.
• Add repository read/write tools.
• Add the Research and Content agents.
• Ship one workflow: content drafting.