Engineer Phase

The Engineer agent designs the technical architecture and selects technologies based on the PRD and design specifications. It produces a technical specification and a structured set of technology decisions.

What the Engineer agent does

The Engineer agent acts as a senior engineer with architecture experience. It reads all previous outputs (PRD, acceptance criteria, design brief, screens), then:

1. Scans the codebase — A high-level scan (not deep analysis) to understand existing tech stack, frameworks, and patterns
2. Asks constraint questions — Focused on non-technical constraints that affect architecture
3. Designs architecture — System components, data models, API design, security
4. Evaluates technologies — For each decision category, presents options with trade-offs
5. Produces recommendations — Marks recommended options with rationale

The questions

The Engineer agent asks 2-4 questions focused on constraints, not implementation details:

• Performance — Expected traffic, latency requirements, concurrent users?
• Security — Compliance requirements, data sensitivity, auth patterns?
• Cost — Infrastructure budget, managed services vs self-hosted?
• Scale — Growth expectations, data volume, geographic distribution?
• Reliability — Uptime requirements, failover needs, backup strategy?

Like the Designer phase, questions reference your previous answers to avoid repetition.

Outputs

Technical specification (technical_specification.md)

A Markdown document covering:

• Architecture overview — System components and how they interact
• Data models — Entity relationships, storage approach
• API design — Endpoints, request/response formats, authentication
• Security architecture — Auth flow, data protection, threat mitigation
• Performance considerations — Caching strategy, query optimization
• Deployment strategy — Infrastructure, CI/CD, environments
• Monitoring — Logging, metrics, alerting approach

Technology choices (technology_choices.json)

Structured technology decisions where each category presents multiple options:

{
  "technology_decisions": [
    {
      "category": "Database",
      "decision_needed": true,
      "options": [
        {
          "name": "PostgreSQL",
          "description": "Relational database with JSON support",
          "version": "14+",
          "recommended": true,
          "recommendation_reason": "Best fit for relational data with ACID guarantees",
          "pros": ["ACID compliance", "Rich JSON support", "Proven at scale"],
          "cons": ["Operational overhead vs managed options"],
          "trade_offs": ["Higher memory usage", "Schema migrations required"],
          "maturity": "stable",
          "implementation_complexity": "medium",
          "documentation_url": "https://www.postgresql.org/docs/",
          "github_url": "https://github.com/postgres/postgres"
        }
      ]
    }
  ]
}

Technology choices viewer

In the Web UI, technology decisions are displayed in a tab-based interface. For each decision category:

• All options are shown with their pros, cons, and trade-offs
• The recommended option is highlighted
• Maturity level is color-coded: stable (green), emerging (blue), beta (amber)
• Implementation complexity is color-coded: low (green), medium (amber), high (red)
• Documentation and GitHub links are provided where available
• A dropdown lets you select your preferred option

You must make a selection for each category before the technology choices can be approved. Progress tracking shows how many decisions you've made out of the total.

The Engineer agent evaluates options across: scalability, performance, reliability, security, maintainability, cost, complexity, team fit, time to market, and vendor lock-in risk.

Review and refinement

After generation, you review the technical spec and technology choices in the Web UI:

• Technical specification — Edit inline, refine with AI feedback and reference images, or approve
• Technology choices — Review each category, select your preferred option, then approve once all selections are made

What's next?

• Issue Breakdown — Implementation tasks built from all three specs
• Output Files — Full file format for technology_choices.json