# Unified Agentic Workflow

## Overview

This project uses a three-layer agentic development stack:

- **Design OS** — product vision and UI design (Phase A)
- **Spec-Kit** — requirements and governance (Phase B–C)
- **Superpowers** — execution, TDD, and verification (Phase D–E)

---

## Non-Negotiables

These rules apply to every task, regardless of size:

- **Always read `.constitution.md`** before starting any task. Constitutional principles are IMMUTABLE — they override all other decisions.
- **All code changes use TDD.** Write the failing test first. Verify it fails. Implement minimally. Verify it passes. Commit. No exceptions.
- **No claims without evidence.** Run the full verification suite (tests, lint, type-check, build). Read the actual output. Check exit codes. "I think it should work" is not verification.
- **No performative language in reviews.** Instead of "Great point!" write "Fixed. [description of what changed]."
- **No PRs without human-approved diffs.** Show the complete diff and wait for explicit approval before merging.
- **No generic AI aesthetics.** No Inter + purple gradient + gray card layout. All UI work must follow Design OS design tokens (`colors.json`, `typography.json`).
- **No "TBD" or vague references in task descriptions.** Every task must include exact file paths, code samples, and verification commands.

---

## Phase Selection — Right-Sizing the Workflow

Choose the appropriate entry point based on the scope of work:

| Work Type          | Estimated Effort | Entry Point        | What to Skip                                 |
| ------------------ | ---------------- | ------------------ | -------------------------------------------- |
| New product        | > 1 week         | Phase A (Step 1)   | Nothing                                      |
| New epic / feature | 1–4 hours       | Phase A or B       | Phase A if design system already exists      |
| Medium feature     | 30 min–1 hour   | Phase C (Step 7)   | Formal spec — rely on existing constitution |
| Bug fix            | < 30 min         | Phase D (debug)    | Phases A, B, C                               |
| UI-only change     | Any              | Phase A → D       | Spec-Kit unless behaviour changes            |
| Refactor           | Any              | Phase C (Step 7)   | Phases A, B — plan from existing code       |
| Documentation      | Any              | Spec-Kit templates | Phases A, D                                  |

---

## Phase A — Envision (Design OS)

**Use when:** Starting a new product, epic, or feature area that needs UI design.

**Commands (in order):**

1. `/product-vision` — Capture product concept, problems solved, key features, roadmap areas (3–5 sections). Output: `product/product-overview.md`, `product/product-roadmap.md`, `product/data-shape.md`
2. `/design-tokens` — Select colour palette and typography. Output: `product/colors.json`, `product/typography.json`
3. `/design-shell` — Establish app layout pattern (sidebar nav / top nav / minimal). Output: `product/shell/spec.md`, shell components
4. `/shape-section` — Define user flows and UI requirements per roadmap section. Output: `product/sections/{id}/spec.md`, `data.json`, `types.ts`
5. `/design-screen` — Generate production-grade React components per section. All components must be props-based. Output: React components with light/dark mode and mobile responsiveness
6. `/screenshot-design` — (Optional) Capture visual reference screenshots

**Human gate:** Review and approve all designs before moving to Phase B.

---

## Phase B — Specify (Spec-Kit)

**Use when:** You have a product vision (from Phase A or otherwise) and need formal requirements.

**Commands (in order):**

1. `speckit.constitution` — **(One-time per project)** Define immutable architectural principles. Output: `.constitution.md`
2. `speckit.specify` — Write formal specification using Design OS outputs as context. Capture: user stories (Given/When/Then), functional requirements (FR-###), success criteria (SC-###), key entities, assumptions. Output: formal spec with FR-### identifiers
3. `speckit.analyze` — Validate spec against constitutional principles. Must pass before proceeding.

**Integration note:** Pass Design OS's `product-overview.md`, `data-shape.md`, and section `spec.md` files as context when running `speckit.specify`. These become the UI/UX foundation; the formal spec adds backend requirements, API contracts, business logic, and data validation.

**Human gate:** Review and approve the formal specification before planning.

---

## Phase C — Plan (Spec-Kit + Superpowers)

**Commands (in order):**

1. `speckit.plan` — Define technical architecture: language/framework, data models, storage, testing framework, performance constraints. Include a constitution-check validation gate. Reference Design OS components as the frontend foundation.
2. `speckit.tasks` — Decompose the plan into granular tasks. Each task MUST include:
   - Unique ID and priority (e.g., `[T005] [P2]`)
   - Story-group tracing (e.g., `[S2]` for Section 2)
   - Parallelisation marker `[P]` if the task can run concurrently
   - **Exact file paths** — no "the relevant file" or "the component"
   - **Code samples** where implementation decisions are non-obvious
   - Testing command and verification step
   - Dependency ordering for sequential tasks
   - Target: 2–5 minutes of agent work per task

---

## Phase D — Execute (Superpowers)

**Skills to use:** `using-git-worktrees`, `subagent-driven-development`, `test-driven-development`, `systematic-debugging`, `executing-plans`

**Steps:**

1. Create a git worktree for the feature branch using `using-git-worktrees` skill
2. Run baseline tests — confirm green state before any changes
3. Import Design OS components into the project if not already present
4. For each task (respecting `[P]` markers and dependency order):
   - Dispatch a **fresh subagent** with: task text, relevant FR-### from spec, constitutional principles, design tokens, and any Design OS components needed
   - Subagent follows **Red-Green-Refactor**: write failing test → verify it fails → implement minimally → verify it passes → commit
   - Parallel `[P]` tasks may run concurrently
5. If tests fail after 3+ fix attempts: use `systematic-debugging` skill (investigate → pattern analysis → hypothesis testing → fix). If root cause is unclear, escalate to human — do not symptom-patch.

---

## Phase E — Verify & Ship (Superpowers + Spec-Kit)

**Skills to use:** `requesting-code-review`, `receiving-code-review`, `verification-before-completion`, `finishing-a-development-branch`

**Steps:**

1. **Stage 1 — Spec compliance review:** Does every change satisfy its FR-### and SC-### requirements? Does it use Design OS design tokens correctly? Does it comply with the constitution? Critical violations block progression.
2. **Stage 2 — Code quality review:** Implementation patterns, naming, performance, security. Severity: Critical (blocks merge) / Major (should fix) / Minor (nit).
3. **Verification gate:** Run full suite — unit tests, integration tests, linter, type-checker, build. Read actual output. Check exit codes. Then run `speckit.analyze` to confirm spec–code alignment post-implementation.
4. **Human approval:** Present the complete diff with traceability (which FR-### each change addresses, which Design OS section it implements). Wait for explicit approval before merging.
5. Clean up the git worktree after merge.

---

## Repo References

- **Design OS:** https://github.com/buildermethods/design-os
- **Spec-Kit:** https://github.com/github/spec-kit — install via `uv tool install specify-cli`
- **Superpowers:** https://github.com/obra/superpowers — install per platform plugin instructions