Design

---
description: Start a standard or deep-tier task. Produces PRD → PLAN → (REVIEW loop if --deep) → EXECUTE → VERIFY.
argument-hint: "[--deep] <title>"
---

# `/ark:design $ARGUMENTS`

Create a **standard**-tier task (default) or **deep**-tier task (if `--deep` is in `$ARGUMENTS`).

- **Standard** — feature work with testable scope. Single PLAN, no REVIEW loop, single VERIFY gate.
- **Deep** — architectural / cross-cutting work. Iterated PLAN ⇄ REVIEW loop, VERIFY gate, SPEC extracted on commit.

Parse `$ARGUMENTS`: if it contains `--deep`, tier = deep, title = remainder; else tier = standard, title = `$ARGUMENTS`.

Structural ops (task dirs, phase transitions, SPEC extraction, INDEX upserts) are owned by `ark agent`. Artifact bodies (PRD prose, PLAN sections, REVIEW findings) are yours to write.

## Preconditions

- `.ark/` is initialized.
- **Standard:** scope is feature-shaped, testable, doesn't break APIs/architecture. If it does, use `--deep`.
- **Deep:** scope is architectural, cross-cutting, or introduces a new subsystem.

## Phase 1 — DESIGN

### Step 1.1: Pull design-phase context `[AI]`

```bash
ark context --scope phase --for design --format json

See workflow.md §4 for the projection contract. Read every SPEC under specs.project and any specs.features rows that look related.

Step 1.2: Brainstorm [AI] [USER]

• Standard: ≤3 clarifying questions on what's ambiguous in the title (observable outcome? constraints? existing patterns to follow?).
• Deep: thorough brainstorm — problem framing, non-goals, performance/security/compat boundaries, alternatives + why rejected, risks/assumptions, interaction with existing feature SPECs.

Do not proceed until the user confirms direction.

Step 1.3: Create the task [AI]

Slugify the title (lowercase, hyphen-separated, ASCII, ≤40 chars).

# standard tier — opt in to --worktree only if work would collide with in-flight changes
ark agent task new --slug <slug> --title "<title>" --tier standard

# deep tier — --worktree is REQUIRED
ark agent task new --slug <slug> --title "<title>" --tier deep --worktree

Scaffolds .ark/tasks/<slug>/{PRD.md, task.toml}, registers the slug, sets this session's focus. Deep tier: cd .ark/worktrees/<branch>/ and run all subsequent steps from there.

Step 1.4: Fill the PRD [AI] [USER]

Edit .ark/tasks/<slug>/PRD.md: What, Why, Outcome, Related Specs (one bullet per touched feature SPEC + how it interacts).

Deep — STOP and ask the user before drafting if any topic needs research (third-party library, prior art, cross-cutting pattern). Offer ark-researcher and wait for their answer; do not decide silently. On dispatch, findings land at <task>/research/<topic>.md. After: git status, git restore out-of-scope edits, git clean -fd out-of-scope new files.

Gate: PRD complete → Phase 2.

Phase 2 — PLAN

Step 2.1: Refresh phase context [AI]

ark context --scope phase --for plan --format json

Step 2.2: Advance phase [AI]

ark agent task plan

Transitions to Plan and seeds PLAN.md (standard) or 00_PLAN.md (deep).

Step 2.3: Fill the PLAN [AI]

Per the template: ## Summary, ## Log (None in 00_PLAN), ## Spec (Goals/NG/Architecture/Data Structure/API Surface/Constraints), ## Runtime, ## Implementation, ## Trade-offs, ## Validation with Acceptance Mapping.

Spec discipline (the ## Spec section is what gets promoted to a feature SPEC verbatim on deep commit — write it like a contract, not a narrative):

• Goals: one line each, ≤80 chars, verb-led (the what). Soft cap of 5.
• Non-goals: list only when a reader would assume in-scope. Soft cap of 3.
• Constraints: one declarative sentence each, ≤120 chars. The why goes in Trade-offs, not the Constraint body.
• If a goal sounds like a procedure ("Two flags control X..."), it is a Constraint, not a Goal.

Deep — STOP and ask the user before drafting if PLAN authoring needs library/API or pattern comparison research. Offer ark-researcher and wait. Same post-check: git status, git restore out-of-scope edits, git clean -fd out-of-scope new files.

Gate: every Goal G-N mapped to ≥1 Validation V-*-N in the Acceptance Mapping table.

Step 2.4: Advance [AI]

# standard
ark agent task execute   # → Phase 4

# deep
ark agent task review    # → Phase 3

Phase 3 — REVIEW (deep only, looped)

Step 3.1: Refresh phase context [AI]

ark context --scope phase --for review --format json

Step 3.2: Pick the reviewer [AI] [USER]

STOP. Ask the user: ark-reviewer subagent, a different model, or self-review? Wait for the answer; do not pick.

• ark-reviewer: dispatch it. git status after; git restore edits outside NN_REVIEW.md and git clean -fd any new files.
• Self-review: switch framing — you are now the reviewer. Read the latest NN_PLAN.md against the PRD and project specs; fill NN_REVIEW.md with verdict, findings (R-NNN), trade-off advice (TR-N).

Reject (HIGH) if the latest PLAN's ## Spec references prior iterations instead of restating in full.

Step 3.3: Loop if revisions needed [AI]

If verdict is Rejected or Approved with Revisions:

1. Copy .ark/templates/PLAN.md → (NN+1)_PLAN.md; copy .ark/templates/REVIEW.md → (NN+1)_REVIEW.md.
2. Edit task.toml: bump iteration to NN+1, set phase = "plan", refresh updated_at.
3. Fill (NN+1)_PLAN.md's ## Log Response Matrix — every prior CRITICAL/HIGH finding listed with Accepted/Rejected/Deferred + reasoning. ## Spec stays self-contained.
4. ark agent task review → fill (NN+1)_REVIEW.md.
5. Repeat until verdict is Approved with zero open CRITICAL.

task.toml.max_iterations (typically 3–5 for deep). If exhausted without approval, halt and ask the user.

Step 3.4: Advance [AI]

ark agent task execute

Phase 4 — EXECUTE