Architecture Orchestrator

Overview

Turn a raw product brief into a consistent, implementation-ready spec pack under specs/ by coordinating specialist agents and enforcing a project's preferred stack (frontend, backend, and AI).

When to Use

• User provides a software brief and wants full project architecture/spec docs
• User wants "screen-by-screen + backend + API + AI" markdown files
• User says "create architecture", "generate specs", "turn my brief into documentation"
• User wants an opinionated stack (design system + deployment platform) applied consistently across the whole spec pack

When NOT to Use

• Simple one-off questions about architecture patterns
• When user already has spec files and just needs edits
• Code implementation tasks (use after specs are approved)

Preference System (SOURCE OF TRUTH)

1) Preference File Search Order

1. specs/preferences.yaml (recommended)
2. specs/preferences.json
3. .arch-orchestrator/preferences.yaml
4. .arch-orchestrator/preferences.json

If none exist, create specs/preferences.yaml using the default template (see templates/preferences.example.yaml), and record this in specs/decisions.md.

2) Design System Sources Search Order

1. design-system/ folder (any of: README.md, tokens.*, components.*, patterns.*, a11y.*)
2. specs/design-system-source.md
3. docs/design-system.md

If none exist, generate specs/design-system.md as a "Design system not provided" doc.

3) How Preferences Are Applied

• Treat preferences as hard constraints unless explicitly marked as optional
• Every generated spec must include:
  • The chosen packages/libraries and why they exist in the architecture
  • How they are wired into the repo
  • Any constraints they impose (build/deploy/runtime limits)
• Subagents must be instructed to read and comply with specs/preferences.yaml first, then the brief

Output Contract (MUST)

Create (or update) these files in specs/:

Workflow

Phase 0: Load Preferences + Design System

1. Load preferences

   • Find and parse a preference file using the search order above
   • If missing, create specs/preferences.yaml using the default template
   • Normalize into a short "Stack Summary" section for all specs

2. Load design system sources

   • If design-system/ exists, summarize it into specs/design-system.md
   • If only a doc exists, consolidate it
   • If nothing exists, produce a default DS doc matching chosen UI libraries

3. Propagate constraints

   • Every Task prompt must include: "Follow specs/preferences.yaml as hard constraints."

Phase 1: Normalize the Brief

1. Locate the brief

   • Look for: brief.md, spec.md, requirements.md, product-brief.md
   • If not found, ask user where it is

2. Extract and structure

   • Project name and purpose
   • Goals and non-goals
   • User roles and personas
   • Key workflows and user journeys
   • Technical constraints (merge with preferences; preferences win)
   • Required integrations
   • Success metrics

3. Write specs/brief-normalized.md

Phase 2: Define Shared Foundations (Backend First)

Write specs/backend-specs.md first with:

1. Canonical domain model (SOURCE OF TRUTH)

   • Core entities with fields, types, constraints
   • Relationships between entities

2. Platform blueprint (from preferences)

   • Compute layer selection rationale
   • Storage selection (D1 vs KV vs R2 vs Durable Objects)
   • Deployment model and environment separation

3. Auth/authz model (from preferences)

   • Authentication approach (JWT, session, OAuth)
   • Authorization model (RBAC, ABAC)
   • Multi-tenancy strategy

4. Error conventions

   • Standard error envelope format
   • HTTP status code usage
   • Error code taxonomy

5. Observability + operations (from preferences)

   • Logging, error tracking, metrics
   • Analytics approach

6. Complete the backend spec

   • Services architecture
   • Database schema with indexes
   • Background jobs and queues
   • Security and rate limiting

Phase 3: Spawn Specialist Agents (Preference-Aware)

Use the Task tool to spawn agents in parallel:

API Documentation Agent:

Task tool with:
- subagent_type: "general-purpose"
- prompt: "Create comprehensive API documentation in specs/api-docs.md.
          HARD CONSTRAINTS: Follow specs/preferences.yaml.
          Reference the canonical domain model from specs/backend-specs.md.
          Include all endpoints with request/response schemas, auth requirements,
          error handling, and pagination conventions."

Frontend Specs Agent:

Task tool with:
- subagent_type: "general-purpose"
- prompt: "Create granular frontend specifications in specs/frontend-specs.md.
          HARD CONSTRAINTS: Follow specs/preferences.yaml and specs/design-system.md.
          Use the preferred UI component source and icon strategy.
          Reference entities from specs/backend-specs.md and endpoints from specs/api-docs.md.
          Provide screen-by-screen breakdown with component-level detail."

AI Services Agent (ONLY if AI features mentioned or ai.enabled=true):

Task tool with:
- subagent_type: "general-purpose"
- prompt: "Create AI services architecture in specs/ai-services.md.
          HARD CONSTRAINTS: Follow specs/preferences.yaml.
          Include AI feature inventory, model gateway, prompt management, RAG strategy,
          safety guardrails, evaluation framework, and cost controls."

Phase 4: Create Index and Decision Logs

1. Index (specs/index.md)

   • Navigation hub with links to all specs
   • One-paragraph summary per document
   • "Stack Summary" pulled from preferences

2. Decisions (specs/decisions.md)

   • All assumptions made
   • Rationale for key architectural choices
   • Stack choices (must match preferences)

3. Open questions (specs/open-questions.md)

   • Uncertainties needing clarification
   • Trade-offs to discuss with team

Phase 5: Consistency Validation

Before finishing, verify:

• Preferences applied across FE/BE/API/AI specs
• Entity names identical across all specs
• API routes in frontend-specs.md exist in api-docs.md
• Permissions consistent (screen access = endpoint access)
• Data schemas match between FE/BE/API
• All agent tasks completed successfully
• All open questions captured

Assumptions + Questions

Ask at most 5 critical questions only if blockers exist:

• Must choose between fundamentally different approaches (e.g., session vs jwt)
• Must know tenancy model for multi-tenant apps
• Must clarify data residency / compliance requirements

Otherwise, proceed with explicit assumptions and document in specs/decisions.md.

Error Handling