# Arch Orchestrator

> Use when the user says "create architecture plan/specs", "turn this brief into docs", "generate frontend/backend/api specs", or "write the spec markdown files". Triggers on requests for end-to-end software architecture documentation from a product brief.

- Skill: `majiayu000/arch-orchestrator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/arch-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/arch-orchestrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/arch-orchestrator

---


# 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/`:

| File | Purpose |
|------|---------|
| `specs/index.md` | Navigation hub with links to all specs |
| `specs/brief-normalized.md` | Structured extraction of the product brief |
| `specs/preferences.yaml` | Stack preferences (create if missing) |
| `specs/design-system.md` | Design tokens, components, a11y rules |
| `specs/frontend-specs.md` | Screen-by-screen UI specifications |
| `specs/backend-specs.md` | Domain model, services, database schema |
| `specs/api-docs.md` | Endpoint documentation with schemas |
| `specs/ai-services.md` | AI/LLM features (or "Not in scope") |
| `specs/decisions.md` | Architectural decisions and rationale |
| `specs/open-questions.md` | Uncertainties needing clarification |

---

## 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

| Condition | Action |
|-----------|--------|
| Preferences missing | Create defaults, record in decisions.md |
| Design system missing | Generate default DS doc, record assumptions |
| Brief missing | Ask user where it is |
| Brief vague | Proceed with assumptions, document in decisions.md |
| AI features unclear | Default to ai.enabled preference; otherwise "not in scope" |
| Agent fails | Document issue in open-questions.md, continue with other specs |