---
name: eck:design
version: "0.7.4"
description: "Design orchestrator: research, discovery, architecture, solution design, specs, ADRs, QA plan, risk, and documentation. Reads FRD.md for requirements."
disable-model-invocation: false
---

# Design

Design a feature end-to-end: from research through documentation. Reads FRD.md for requirements and acceptance criteria. Dispatches to 9 design-\* sub-skills based on scope and configuration.

> **Plan mode required.** If not already in plan mode, use `EnterPlanMode` before proceeding.

Design feature: $ARGUMENTS

---

## Context Budget — Agent Dispatch Required

> **Stages 2–9 MUST dispatch their sub-skills via the Agent tool**, not inline invocation. The design orchestrator has 10 stages with 8 content-heavy stages that each produce design artifacts (RESEARCH.md, DESIGN-DISCOVERY.md, ARCHITECTURE.md, DESIGN.md, specs, QA-PLAN.md, RISK.md, docs). Inline execution risks exhausting the context window before reaching Stage 10 (Review). Each Agent dispatch returns only a compact summary, keeping the orchestrator lean enough to complete all stages.

---

## Sub-skill Dispatch Table

| Sub-skill        | Invocation                                  | Purpose                                                         |
| ---------------- | ------------------------------------------- | --------------------------------------------------------------- |
| design-research  | `/<PROJECT_KEY_LOWERCASE>:design-research`  | Online + KB research with heuristic consultation                |
| design-discovery | `/<PROJECT_KEY_LOWERCASE>:design-discovery` | Collaborative technical discovery for design-phase requirements |
| design-arch      | `/<PROJECT_KEY_LOWERCASE>:design-arch`      | System architecture, service decomposition, security arch       |
| design-solution  | `/<PROJECT_KEY_LOWERCASE>:design-solution`  | Component design, UI/UX patterns, state management              |
| design-specs     | `/<PROJECT_KEY_LOWERCASE>:design-specs`     | API contracts, DB schemas, sequence diagrams, NFRs              |
| design-adr       | `/<PROJECT_KEY_LOWERCASE>:design-adr`       | Architecture Decision Records                                   |
| design-qa        | `/<PROJECT_KEY_LOWERCASE>:design-qa`        | QA plan and test strategy                                       |
| design-risk      | `/<PROJECT_KEY_LOWERCASE>:design-risk`      | Risk assessment with GO/NO-GO gate                              |
| design-document  | `/<PROJECT_KEY_LOWERCASE>:design-document`  | BRD, PRD, technical documentation                               |
| design-review    | `/<PROJECT_KEY_LOWERCASE>:design-review`    | Review gate (mandatory)                                         |

> **Sub-skill invocation rule:** All sub-skills above MUST be invoked with the project key prefix derived from `PROJECT_KEY` in `.claude/project-constants.md`. For example, if `PROJECT_KEY=WA`, invoke `/wa:design-research`, not `/design-research`.

---

## Visual Framework

Follow the visual framework defined in the `output:visual-framework` primitive.

---

## Task Registration

| Stage | Subject               | Active Form            | Statusline      |
| ----- | --------------------- | ---------------------- | --------------- |
| 1     | Stage 1: Calibrate    | Calibrating session    | Calib (1/10)    |
| 2     | Stage 2: Research     | Running research       | Research (2/10) |
| 3     | Stage 3: Discovery    | Exploring requirements | Discov (3/10)   |
| 4     | Stage 4: Architecture | Designing architecture | Arch (4/10)     |
| 5     | Stage 5: Design       | Building design        | Design (5/10)   |
| 6     | Stage 6: Contracts    | Building contracts     | Ctrcts (6/10)   |
| 7     | Stage 7: Verify       | Verifying quality plan | Verify (7/10)   |
| 8     | Stage 8: Risk         | Assessing risk         | Risk (8/10)     |
| 9     | Stage 9: Documents    | Writing docs           | Docs (9/10)     |
| 10    | Stage 10: Review      | Reviewing design       | Review (10/10)  |

## Statusline Stage Updates

At the start of each stage:

```bash
bash $ECK_HOME/update-stage.sh "Name (N/10)"
```

At skill completion (success or error):

```bash
bash $ECK_HOME/update-stage.sh
```

## Usage

```bash
/eck:design <feature>                    # Full design pipeline (scope prompt)
/eck:design <feature> --full             # Run all 9 sub-skills
/eck:design <feature> --quick            # Research + discovery only
/eck:design <feature> design-solution    # Run a single named sub-skill
/eck:design <feature> design-research design-specs  # Run two named sub-skills
--force                                  # Override prerequisite gate check (not available at strict rigor)
--exit-plan-mode                         # Remove .planning-session marker without completing design
```

### Flags

| Flag               | Description                                                      |
| ------------------ | ---------------------------------------------------------------- |
| `--full`           | Run all 9 sub-skills in sequence                                 |
| `--quick`          | Run `design-research` and `design-discovery` only                |
| Sub-skill name     | Run only the named sub-skill(s)                                  |
| `--force`          | Override prerequisite gate check (not available at strict rigor) |
| `--exit-plan-mode` | Remove `.planning-session` marker without completing design      |

---

## Stage 0: Gate Check

> **Pre-execution prerequisite validation — does not appear in Task Registration.**

### Inputs

- Feature slug from `<FEATURE_SLUG>` or `$ARGUMENTS`
- `--force` flag (if present)

### Activities

1. Invoke `core/ops:gate-check` primitive with:
   - `feature_slug`: current feature
   - `required_step`: `spec`
   - `rigor`: current rigor level from `core/mode:read-dev-rigor`
2. If gate check passes: proceed to Stage 1.
3. If gate check fails:
   - **Without `--force`**: Display blocking reason and guidance. STOP.

     ```
     ⚠ Prerequisite not met: spec phase must be complete with passing review gate.
     Current status: <status> | Gate verdict: <verdict>

     Options:
     - Complete /eck:spec first
     - Re-run with --force to override (not available at strict rigor)
     ```

   - **With `--force`** (lite/standard only): Record override in lifecycle.json and proceed.
     At strict rigor, `--force` is rejected with: "Hard block at strict rigor — complete prerequisites first."

### Outputs

- Gate check result (pass/fail/forced)

### Exit Criteria

- Prerequisites verified OR override recorded

---

## Stage 1: Calibrate

```bash
bash $ECK_HOME/update-stage.sh "Calibrate (1/10)"
```

### Inputs

- `$ARGUMENTS` — feature description and flags
- `.claude/project-constants.md` — project key, paths
- `docs/{feature}/FRD.md` — requirements and AC-IDs (if exists)
- Development mode via `mode:read-dev-rigor` primitive

### Feature Resolution

Before proceeding, resolve the target <KEY>-XXX:

1. If `$ARGUMENTS` matches `FEAT-\d{3}` (case-insensitive) → normalize to uppercase, use directly
2. If `$ARGUMENTS` is non-empty text → `node $ECK_HOME/manage-features.js resolve "$ARGUMENTS"` → extract `id` from JSON output
3. If `$ARGUMENTS` is empty → read `active_feature` from session file:
   ```bash
   if [ -n "$CLAUDE_SESSION_ID" ]; then
     FEAT_ID=$(jq -r '.active_feature // empty' "$CLAUDE_PROJECT_DIR/.claude/sessions/${CLAUDE_SESSION_ID}.json" 2>/dev/null)
   fi
   ```
4. If still empty → read from lifecycle-state.json (fallback: lifecycle.json):
   ```bash
   FEAT_ID=$(jq -r '.active_feature // empty' "$CLAUDE_PROJECT_DIR/.claude/lifecycle-state.json" 2>/dev/null)
   [ -z "$FEAT_ID" ] && FEAT_ID=$(jq -r '.active_feature // empty' "$CLAUDE_PROJECT_DIR/.claude/lifecycle.json" 2>/dev/null)
   ```
5. If still empty → AskUserQuestion listing features from `node $ECK_HOME/manage-features.js list`
6. Validate <KEY>-XXX exists: `node $ECK_HOME/manage-features.js read "$FEAT_ID"`. If not found, STOP.
7. If not in lifecycle.json, auto-register: `node $ECK_HOME/update-lifecycle.js register "$FEAT_ID"`
8. Get slug: `FEATURE_SLUG=$(node $ECK_HOME/manage-features.js read "$FEAT_ID" | jq -r '.slug')`

Set `FEATURE_ID` to the <KEY>-XXX value. Use `FEATURE_ID` for all lifecycle calls.
Use `FEATURE_SLUG` only for docs folder paths: `docs/${FEATURE_ID}-${FEATURE_SLUG}/`

### Activities

1. Read project constants from `.claude/project-constants.md`.
2. Resolve development mode using the `mode:read-dev-rigor` primitive.
3. Create `.planning-session` marker via:
   ```bash
   node $ECK_HOME/update-lifecycle.js plan-mode "$FEATURE_ID" on
   ```
4. Check for existing state file:

   ```bash
   cat "$CLAUDE_PROJECT_DIR/docs/${FEATURE_ID}-${FEATURE_SLUG}/DESIGN-STATE.md" 2>/dev/null || echo "No state file"
   ```

   If found, offer resume via AskUserQuestion:

   ```
   Found DESIGN-STATE.md from a previous session.
   Options:
     1 - Resume from where you left off
     2 - Start fresh (discard previous state)
   ```

   If resume: load state, skip completed sub-skills, resume from the last incomplete stage.

5. Load `docs/{feature}/FRD.md` if it exists. Extract:
   - Problem statement and goals (as research/design brief)
   - Acceptance criteria (AC-IDs) for artifact mapping
   - Open questions (for research prioritization in Stage 2)
6. If FRD.md is not found, display notice:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${YELLOW}[>]${RESET} No FRD.md found — using feature description as fallback"
printf '%b\n' "    ${DIM}Run /eck:spec first for spec-driven design.${RESET}"
```

7. Determine the design scope from `$ARGUMENTS`:

| Scope           | Detection                                | Dispatch                              |
| --------------- | ---------------------------------------- | ------------------------------------- |
| **Feature**     | Default, or `--feature` flag             | Full sub-skill pipeline               |
| **Epic/Sprint** | `--epic` flag or epic key pattern        | `design-research` → `design-document` |
| **Task**        | `--task` flag or single task description | `design-research` + single task       |

8. Parse `$ARGUMENTS` for pipeline flags:

| Flag / Token                             | Behavior                                          |
| ---------------------------------------- | ------------------------------------------------- |
| `--full`                                 | Run all 9 sub-skills in sequence                  |
| `--quick`                                | Run `design-research` and `design-discovery` only |
| Sub-skill name (e.g., `design-solution`) | Run only the named sub-skill(s)                   |
| None                                     | Prompt user (step 9)                              |

9. If no pipeline flag or sub-skill name is found, use AskUserQuestion:

```
What design depth do you need?

Options:
  1 - Full (all stages: research, discovery, architecture, design, specs, QA, risk, docs)
  2 - Quick (research + discovery only)
  3 - Custom (select sub-skills)
```

If **Custom**, present a follow-up multiselect:

```
Select sub-skills to run:
  [ ] design-research
  [ ] design-discovery
  [ ] design-arch
  [ ] design-solution
  [ ] design-specs
  [ ] design-adr
  [ ] design-qa
  [ ] design-risk
  [ ] design-document
```

### Outputs

- Resolved pipeline configuration
- FRD.md context (if loaded)
- Scope summary displayed to user

### Exit Criteria

- Project constants loaded
- Development mode resolved
- FRD.md loaded (or fallback acknowledged)
- Pipeline sub-skills selected

### Display Scope Summary

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Design Scope${RESET}"
echo ""
printf '%b\n' "Feature: {FEATURE_NAME}"
printf '%b\n' "Mode: {DEV_RIGOR}"
printf '%b\n' "FRD.md: {LOADED | not found}"
printf '%b\n' "AC-IDs: {COUNT} criteria loaded"
printf '%b\n' "Sub-skills: {COUNT} selected"
printf '%b\n' "Pipeline: {LIST_OF_SUB_SKILLS}"
echo ""
```

---

## Stage 2: Research

```bash
bash $ECK_HOME/update-stage.sh "Research (2/10)"
```

**Skip this stage if `design-research` is not in the selected scope.**

Display skip notice when not in scope:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${DIM}[-]${RESET} Research — skipped (not in scope)"
```

### Inputs

- `$ARGUMENTS` — feature description
- FRD.md open questions (prioritized for research)
- Project codebase context

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:design-research $ARGUMENTS` via the **Agent tool** to keep orchestrator context lean.

   The Agent prompt should instruct the subagent to:
   - Run the design-research sub-skill, passing FRD.md open questions as priority research targets
   - Write `docs/{feature}/RESEARCH.md` to disk
   - Return a **compact summary only**: key findings per dimension, one line each
   - Do NOT return full research content

2. Verify `docs/{feature}/RESEARCH.md` exists after agent returns. If missing, treat as failure.

### Outputs

- `docs/{feature}/RESEARCH.md` written to the feature docs directory

### Exit Criteria

- Research sub-skill completed (or skipped/failed with logged reason)
- RESEARCH.md exists at expected path (when sub-skill succeeds)

### Display Result

On success:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${GREEN}[x]${RESET} Research complete"
printf '%b\n' "    ${DIM}Output: docs/{feature}/RESEARCH.md${RESET}"
```

On failure:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} design-research failed — skipping stage"
printf '%b\n' "    ${DIM}Check sub-skill output for details.${RESET}"
```

---

## Stage 3: Discovery

```bash
bash $ECK_HOME/update-stage.sh "Discovery (3/10)"
```

**Skip this stage if `design-discovery` is not in the selected scope.**

Display skip notice when not in scope:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${DIM}[-]${RESET} Discovery — skipped (not in scope)"
```

### Inputs

- `$ARGUMENTS` — feature description
- FRD.md open questions (if loaded in Stage 1)
- RESEARCH.md (if produced in Stage 2)

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:design-discovery $ARGUMENTS` via the **Agent tool** to keep orchestrator context lean. Pass FRD.md and RESEARCH.md summary as context.

   The Agent prompt should instruct the subagent to:
   - Run the design-discovery sub-skill
   - Write `docs/{feature}/DESIGN-DISCOVERY.md` to disk
   - Return a **compact summary only**: decisions made, constraints identified, and key technical findings (one line each)
   - Do NOT return full discovery content

2. Verify `docs/{feature}/DESIGN-DISCOVERY.md` exists after agent returns. If missing, treat as failure.

### Outputs

- `docs/{feature}/DESIGN-DISCOVERY.md` — technical decisions, constraints, and findings

### Exit Criteria

- Discovery sub-skill completed (or skipped/failed with logged reason)

### Display Result

On success:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${GREEN}[x]${RESET} Technical discovery complete"
printf '%b\n' "    ${DIM}Output: docs/{feature}/DESIGN-DISCOVERY.md${RESET}"
```

On failure:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} design-discovery failed — skipping stage"
printf '%b\n' "    ${DIM}Check sub-skill output for details.${RESET}"
```

### Stage Exit Verification

Before proceeding to Stage 4, **MUST** verify:

- [ ] `docs/{feature}/RESEARCH.md` exists and is non-empty (from Stage 2)
- [ ] `docs/{feature}/DESIGN-DISCOVERY.md` exists and is non-empty (from Stage 3)

**Rigor behavior:**

- **strict**: STOP on failure, no override
- **standard**: STOP on failure, `--force` available
- **lite**: Warn and continue

If verification fails at current rigor level (read via `mode:read-dev-rigor`): apply rigor behavior above.

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} Stage exit verification failed: research artifacts not written"
```

---

## Stage 4: Architecture

```bash
bash $ECK_HOME/update-stage.sh "Architecture (4/10)"
```

**Skip this stage if `design-arch` is not in the selected scope.**

Display skip notice when not in scope:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${DIM}[-]${RESET} Architecture — skipped (not in scope)"
```

### Inputs

- `$ARGUMENTS` — feature description
- FRD.md requirements and AC-IDs
- RESEARCH.md (if produced in Stage 2)
- DESIGN-DISCOVERY.md (if produced in Stage 3)

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:design-arch $ARGUMENTS` via the **Agent tool** to keep orchestrator context lean. Pass FRD.md and prior stage summaries as context.

   The Agent prompt should instruct the subagent to:
   - Run the design-arch sub-skill
   - Write `docs/{feature}/ARCHITECTURE.md` to disk
   - Return a **compact summary only**: architecture style, component count, key decisions (one line each)
   - Do NOT return full architecture content

2. Verify `docs/{feature}/ARCHITECTURE.md` exists after agent returns. If missing, treat as failure.

### Outputs

- `docs/{feature}/ARCHITECTURE.md` — system architecture document

### Exit Criteria

- Architecture sub-skill completed (or skipped/failed with logged reason)

### Display Result

On success:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${GREEN}[x]${RESET} System architecture complete"
printf '%b\n' "    ${DIM}Output: docs/{feature}/ARCHITECTURE.md${RESET}"
```

On failure:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} design-arch failed — skipping stage"
printf '%b\n' "    ${DIM}Check sub-skill output for details.${RESET}"
```

---

## Stage 5: Design

```bash
bash $ECK_HOME/update-stage.sh "Design (5/10)"
```

**Skip this stage if `design-solution` is not in the selected scope.**

Display skip notice when not in scope:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${DIM}[-]${RESET} Design — skipped (not in scope)"
```

### Inputs

- `$ARGUMENTS` — feature description
- FRD.md — requirements
- ARCHITECTURE.md (if produced in Stage 4)

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:design-solution $ARGUMENTS` via the **Agent tool** to keep orchestrator context lean. Pass FRD.md and architecture summary as context.

   The Agent prompt should instruct the subagent to:
   - Run the design-solution sub-skill
   - Write `docs/{feature}/DESIGN.md` to disk
   - Return a **compact summary only**: component count, patterns used, state management approach (one line each)
   - Do NOT return full design content

2. Verify `docs/{feature}/DESIGN.md` exists after agent returns. If missing, treat as failure.

### Outputs

- `docs/{feature}/DESIGN.md` — component design document

### Exit Criteria

- Design sub-skill completed (or skipped/failed with logged reason)

### Display Result

On success:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${GREEN}[x]${RESET} Component design complete"
printf '%b\n' "    ${DIM}Output: docs/{feature}/DESIGN.md${RESET}"
```

On failure:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} design-solution failed — skipping stage"
printf '%b\n' "    ${DIM}Check sub-skill output for details.${RESET}"
```

---

## Stage 6: Contracts

```bash
bash $ECK_HOME/update-stage.sh "Contracts (6/10)"
```

**Skip this stage if `design-specs` is not in the selected scope.**

Display skip notice when not in scope:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${DIM}[-]${RESET} Contracts — skipped (not in scope)"
```

### Inputs

- `$ARGUMENTS` — feature description
- FRD.md — requirements
- ARCHITECTURE.md (if produced in Stage 4)
- DESIGN.md (if produced in Stage 5)

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:design-specs $ARGUMENTS` via the **Agent tool** to keep orchestrator context lean. Pass architecture and design summaries as context.

   The Agent prompt should instruct the subagent to:
   - Run the design-specs sub-skill
   - Write API contracts, DB schemas, sequence diagrams, NFRs to disk
   - Return a **compact summary only**: artifact count, API endpoint count, schema count
   - Do NOT return full spec content

2. If `design-adr` is in the selected scope, **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:design-adr $ARGUMENTS` via the **Agent tool** immediately after design-specs completes. The agent should write ADR files and return only ADR IDs and titles.

### Outputs

- API contracts, DB schemas, sequence diagrams, NFRs
- `docs/adrs/ADR-<NNN>-{title}.md` — ADR(s) if `design-adr` ran

### Exit Criteria

- Specs sub-skill completed (or skipped/failed with logged reason)
- ADR sub-skill completed if in scope

### Display Result

On success:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${GREEN}[x]${RESET} Specification artifacts complete"
printf '%b\n' "    ${DIM}Output: API contracts, DB schemas, NFRs${RESET}"
```

On failure:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} {design-specs|design-adr} failed — skipping"
printf '%b\n' "    ${DIM}Check sub-skill output for details.${RESET}"
```

### Stage Exit Verification

Before proceeding to Stage 7, **MUST** verify:

- [ ] `docs/{feature}/ARCHITECTURE.md` exists and is non-empty
- [ ] `docs/{feature}/DESIGN.md` exists and is non-empty

**Rigor behavior:**

- **strict**: STOP on failure, no override
- **standard**: STOP on failure, `--force` available
- **lite**: Warn and continue

If verification fails at current rigor level (read via `mode:read-dev-rigor`): apply rigor behavior above.

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} Stage exit verification failed: ARCHITECTURE.md or DESIGN.md missing"
```

---

## Stage 7: Verify

```bash
bash $ECK_HOME/update-stage.sh "Verify (7/10)"
```

**Skip this stage if `design-qa` is not in the selected scope.**

Display skip notice when not in scope:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${DIM}[-]${RESET} Verify — skipped (not in scope)"
```

### Inputs

- `$ARGUMENTS` — feature description
- FRD.md — acceptance criteria
- ARCHITECTURE.md and DESIGN.md (if produced in prior stages)

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:design-qa $ARGUMENTS` via the **Agent tool** to keep orchestrator context lean. Pass prior stage summaries as context.

   The Agent prompt should instruct the subagent to:
   - Run the design-qa sub-skill
   - Write `docs/{feature}/QA-PLAN.md` to disk
   - Return a **compact summary only**: test scope, coverage targets, environment count
   - Do NOT return full QA plan content

2. Verify `docs/{feature}/QA-PLAN.md` exists after agent returns. If missing, treat as failure.

### Outputs

- `docs/{feature}/QA-PLAN.md` — QA plan and test strategy

### Exit Criteria

- QA sub-skill completed (or skipped/failed with logged reason)

### Display Result

On success:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${GREEN}[x]${RESET} QA plan complete"
printf '%b\n' "    ${DIM}Output: docs/{feature}/QA-PLAN.md${RESET}"
```

On failure:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} design-qa failed — skipping stage"
printf '%b\n' "    ${DIM}Check sub-skill output for details.${RESET}"
```

---

## Stage 8: Risk

```bash
bash $ECK_HOME/update-stage.sh "Risk (8/10)"
```

**Skip this stage if `design-risk` is not in the selected scope.**

Display skip notice when not in scope:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${DIM}[-]${RESET} Risk — skipped (not in scope)"
```

### Inputs

- All prior stage artifacts
- FRD.md — acceptance criteria for risk evaluation

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:design-risk $ARGUMENTS` via the **Agent tool** to keep orchestrator context lean.

   The Agent prompt should instruct the subagent to:
   - Run the design-risk sub-skill
   - Write `docs/{feature}/RISK.md` to disk
   - Return a **compact summary only**: GO/NO-GO verdict, risk count by category, top risk one-liner
   - Do NOT return full risk assessment content

2. Verify `docs/{feature}/RISK.md` exists after agent returns. If missing, treat as failure and STOP.
3. Evaluate gate result:

| Result | Action                       |
| ------ | ---------------------------- |
| GO     | Continue to Stage 9          |
| NO-GO  | Display risk report and STOP |

### Outputs

- `docs/{feature}/RISK.md` — risk assessment
- GO/NO-GO decision

### Exit Criteria

- Risk gate decision made
- If NO-GO: statusline reset and execution halted

### Display Result

**GO path:**

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${GREEN}[x]${RESET} Risk gate: GO"
printf '%b\n' "    ${DIM}Continuing to Stage 9.${RESET}"
```

**NO-GO path:**

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Gate: Risk NO-GO${RESET}"
echo ""
printf '%b\n' "${RED}[!]${RESET} design-risk returned NO-GO"
printf '%b\n' "    ${DIM}Design halted. Review the risk report before${RESET}"
printf '%b\n' "    ${DIM}proceeding. Address blockers and re-run /eck:design.${RESET}"
```

Then reset statusline and STOP:

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Stage 9: Documents

```bash
bash $ECK_HOME/update-stage.sh "Documents (9/10)"
```

**Skip this stage if `design-document` is not in the selected scope.**

Display skip notice when not in scope:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${DIM}[-]${RESET} Documents — skipped (not in scope)"
```

### Inputs

- All prior stage artifacts (FRD.md, RESEARCH.md, DESIGN-DISCOVERY.md, ARCHITECTURE.md, DESIGN.md, QA-PLAN.md, RISK.md, ADRs)

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:design-document $ARGUMENTS` via the **Agent tool** to keep orchestrator context lean. Pass prior stage summaries as context.

   The Agent prompt should instruct the subagent to:
   - Run the design-document sub-skill
   - Write BRD, PRD, and technical documentation to disk
   - Return a **compact summary only**: documents created, page count
   - Do NOT return full document content

### Outputs

- BRD, PRD, technical documentation (project-level docs)

### Exit Criteria

- Document sub-skill completed (or skipped/failed with logged reason)

### Display Pre-Review Summary

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Design Summary${RESET}"
echo ""
printf '%b\n' "Feature: {FEATURE_NAME}"
printf '%b\n' "Sub-skills run: {COUNT} of 9"
printf '%b\n' "AC coverage: {N} of {TOTAL} AC-IDs mapped"
echo ""

printf '%b\n' "${BOLD}Sub-skills Executed${RESET}"
# For each sub-skill that ran successfully:
printf '%b\n' "${GREEN}[x]${RESET} {sub-skill-name}"
# For each sub-skill that was skipped (not in scope):
printf '%b\n' "${DIM}[-]${RESET} {sub-skill-name} (skipped)"
# For each sub-skill that failed:
printf '%b\n' "${RED}[!]${RESET} {sub-skill-name} (failed)"
echo ""
```

---

## Stage 10: Review (10/10)

> **Mandatory — cannot be skipped or deselected.**

```bash
bash $ECK_HOME/update-stage.sh "Review (10/10)"
```

### Inputs

- All stage artifacts produced by prior stages
- Feature slug
- Rigor level

### Activities

1. **MUST** dispatch to `<PK>:design-review` sub-skill. Do NOT skip the review gate.
2. Review skill validates mandatory artifacts, runs quality checks, computes verdict.
3. Review skill **MUST** record verdict via `update-lifecycle.js gate-verdict`.
4. On PASS or CONDITIONAL:
   - Call `update-lifecycle.js plan-mode "$FEATURE_ID" off` to remove `.planning-session` marker.
   - Call `update-lifecycle.js done "$FEATURE_ID" design`
   - Display: "✓ Design gate PASSED. Next: /eck:develop"
5. On FAIL:
   - Step status set to "gated" (yellow in statusline)
   - Display: "✗ Design gate FAILED. Fix issues and re-run /eck:design."
   - STOP (do not display next-stage guidance)

### Outputs

- `docs/{feature}/DESIGN-REVIEW.md` verdict artifact
- lifecycle.json updated with gate verdict

### Exit Criteria

- Review gate verdict recorded
- `.planning-session` marker removed (on PASS)
- Step marked "done" (on PASS) or "gated" (on FAIL)

### Reset Statusline

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Lifecycle Integration

### Entry Protocol (Stage 1)

At the start of Stage 1, after feature resolution, run:

```bash
echo "$(date +%s)" > /tmp/eck-skill-start-$$

node $ECK_HOME/update-lifecycle.js register "$FEATURE_ID" --branch "$(git branch --show-current 2>/dev/null)"
node $ECK_HOME/update-lifecycle.js start "$FEATURE_ID" "design"
node $ECK_HOME/update-lifecycle.js activate "$FEATURE_ID"
```

### Exit Protocol (after Review Gate)

```bash
START_TS=$(cat /tmp/eck-skill-start-$$ 2>/dev/null || echo "0")
END_TS=$(date +%s)
DURATION=$((END_TS - START_TS))

node $ECK_HOME/update-lifecycle.js done "$FEATURE_ID" "design"

node $ECK_HOME/log-activity.js \
  --skill "eck:design" --feature "$FEATURE_ID" --outcome "success" \
  --duration "$DURATION" --summary "{SUMMARY_TEXT}" --step "design"

```

On failure, replace `done` with `fail` and outcome with `"failed"`.

---

## Error Handling

| Condition                                  | Behavior                                                              |
| ------------------------------------------ | --------------------------------------------------------------------- |
| Sub-skill fails (non-risk)                 | Log the error, mark stage as failed, continue                         |
| Risk gate returns NO-GO                    | Display risk report and STOP — do not proceed                         |
| All sub-skills fail                        | Complete Stage 9 with available context, note failures in summary     |
| Unexpected failure or user-initiated pause | Write state to `DESIGN-STATE.md` using the `ops:state-save` primitive |

On unexpected failure or user-initiated pause (`/eck:pause`), write stage state to `docs/{feature}/DESIGN-STATE.md`. The `/eck:pause` command will write this state file automatically when invoked during a design session.

### Error Display Pattern

Use this pattern for any sub-skill failure:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} {sub-skill-name} failed — continuing to next stage"
printf '%b\n' "    ${DIM}Failed stages will appear in the final summary.${RESET}"
```

The final summary always lists which stages passed, were skipped, and failed.
At completion (success or error), reset the statusline:

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Related Documents

- `/eck:spec` — previous orchestrator in the lifecycle
- `/eck:develop` — next orchestrator in the lifecycle
- `design-research` — online + KB research with heuristic consultation
- `design-discovery` — collaborative technical discovery
- `design-arch` — system architecture, service decomposition
- `design-solution` — component design, UI/UX patterns
- `design-specs` — API contracts, DB schemas, sequence diagrams, NFRs
- `design-adr` — Architecture Decision Records
- `design-qa` — QA plan and test strategy
- `design-risk` — risk assessment with GO/NO-GO gate
- `design-document` — BRD, PRD, technical documentation
