# Phase 07: Story Seed Generation

## Entry Gate

```bash
devforgeai-validate phase-check ${DEVARCH_ID} --workflow=development-architecture --from=06 --to=07 --project-root=. 2>&1
```

| Exit Code | Action |
|-----------|--------|
| 0 | Proceed to Phase 07 |
| 127 | CLI not installed — proceed without enforcement |
| Other | HALT — previous phase not complete |

---

## Contract

| Attribute | Value |
|-----------|-------|
| **PURPOSE** | Submit the whole assembled development design to an independent `architect-reviewer` BLOCKING design review — the review gate Gap E identified as absent — then derive the `SEED-NNN` story seeds that `/create-story` consumes. A story seed is an implementable unit of work carrying enough design to author a story; it is NOT a story file and carries no final acceptance criteria. **The architect-reviewer design review is BLOCKING.** |
| **REFERENCE** | `.claude/skills/spec-driven-development-architecture/references/development-architecture-output.schema.json` |
| **SUBAGENT** | `architect-reviewer` (design review of the whole Development Architecture design — BLOCKING) |
| **STEP COUNT** | 5 mandatory steps |

## Phase Exit Criteria

Before this phase can complete, ALL of the following MUST be true:

- [ ] `architect-reviewer` invoked; it returned a verdict per reviewed design element
- [ ] Every `BLOCKING` review finding resolved with the user; every `NEEDS_REVISION` finding recorded
- [ ] `story_seeds` enumerated — ≥ 1 `SEED-NNN`, each with a `title` and a `summary`
- [ ] Every seed's `components` resolve to feature components; every seed `id` matches `^SEED-[0-9]{3,}$`

**IF any criterion is unmet: HALT. Do NOT proceed to Phase 08.**

---

## Reference Loading

```
Read(file_path=".claude/skills/spec-driven-development-architecture/references/development-architecture-output.schema.json")
```

The `$defs.story_seed` shape (`id`, `title`, `summary`, `feature_ref`, `components`,
`acceptance_hint`, `estimated_complexity`) is exactly what this phase produces. IF
the Read fails: HALT — "Phase 07 output contract not loaded."

Do NOT rely on memory of previous reads. Load fresh every time this phase executes.

---

## Mandatory Steps

### Step 7.1: Invoke architect-reviewer for the Design Review (BLOCKING)

**EXECUTE:**
```
Task(
  subagent_type="architect-reviewer",
  prompt="Review the assembled Development Architecture design for feature
    ${feature_ref} of this project. This is the implementation-ready design that
    /create-story and /dev will build against — review it before it is committed.

    Inputs:
    - Feature: ${feature}  (name, description, feasibility, risk)
    - Layer placement map (Phase 03): ${layer_placement_map}
    - Design patterns (Phase 04): ${design_patterns}
    - Module structure (Phase 05): ${module_structure}
    - Dependency wiring (Phase 05): ${dependency_wiring}
    - Test strategy hooks (Phase 06): ${test_strategy_hooks}
    - Solution Architecture handoff + constraints: ${sol_handoff}
    - The 6 constitutional context files in devforgeai/specs/context/

    Review the design as a whole — layer placement, pattern selection, module
    structure, dependency wiring, and test-strategy hooks. For EACH design element
    return a verdict:
    { verdicts: [ { element: '<layer_placement | design_patterns | module_structure |
        dependency_wiring | test_strategy_hooks | overall>',
        verdict: 'SOUND' | 'NEEDS_REVISION' | 'BLOCKING',
        rationale: '<why>',
        evidence: '<file:line or design reference>' } ] }

    SOUND          — the element is implementation-ready as designed.
    NEEDS_REVISION — the element works but has a non-blocking weakness to record.
    BLOCKING       — the element cannot go to /create-story as designed; it must
                     change before story seeds are generated."
)
```
This is a BLOCKING task. Wait for the result before proceeding.

**VERIFY:**
- Task returned a `verdicts` array with ≥ 1 entry covering the design elements
- Every verdict has `element`, `verdict`, `rationale`
- Every `verdict` is one of `SOUND` / `NEEDS_REVISION` / `BLOCKING`

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=07 --step=7.1 --project-root=. 2>&1
```
```json
{ "phase": "07", "step": "7.1", "review_verdicts": [ ... ],
  "verdict_summary": { "SOUND": 0, "NEEDS_REVISION": 0, "BLOCKING": 0 } }
```

---

### Step 7.2: Reconcile the Review

**EXECUTE:**
```
FOR each verdict:
  IF verdict == "BLOCKING":
    AskUserQuestion — the design element cannot go to /create-story as designed.
    Options:
      - Revise the design (return to the relevant phase with user consent — Deviation Protocol)
      - Override with justification (record the user's reasoning)
    A BLOCKING finding MUST NOT remain unresolved.

  IF verdict == "NEEDS_REVISION":
    Record the weakness. Either apply the revision now (if it is within this
    phase's scope) or carry it as an open question into the Phase 08 handoff.
    This is non-blocking.
```

**VERIFY:**
- No `BLOCKING` verdict remains unresolved
- Every `NEEDS_REVISION` verdict is recorded (applied or carried as an open question)

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=07 --step=7.2 --project-root=. 2>&1
```
```json
{ "step": "7.2", "blocking_resolutions": [ ... ], "review_open_questions": [ ... ] }
```

---

### Step 7.3: Generate the Story Seeds

**EXECUTE:**

From the reviewed design — the modules (Phase 05), the components (Phase 02), the
patterns (Phase 04), and the test hooks (Phase 06) — derive the `SEED-NNN` story
seeds. A seed is an independently implementable slice of the feature:

```
story_seed = {
  id: "SEED-001",                  # ^SEED-[0-9]{3,}$ — numbered from 001 within THIS document
  title: "<short imperative title of the unit of work>",
  summary: "<what this seed delivers and the design it builds on — modules,
            components, patterns involved>",
  feature_ref: "${feature_ref}",   # F-NN
  components: [ "COMP-NNN", ... ],  # the feature components this seed touches
  acceptance_hint: [ "<suggested acceptance-criterion seed for /create-story to
                       formalize>", ... ],
  estimated_complexity: "Low" | "Medium" | "High"
}
```

Guidance:
- `SEED-NNN` ids are scoped to THIS Development Architecture Document — number from
  `SEED-001`. Do NOT glob prior `DEVARCH` outputs; seeds are per-document, the way
  `F-NN` features are per-Solution-Architecture.
- A seed should be a coherent, independently valuable unit — typically one module
  group or one component slice, sized so `/create-story` can author one story from
  it. Split a seed whose `summary` needs the word "and" to describe two jobs.
- `acceptance_hint` entries are HINTS — `/create-story` owns the final acceptance
  criteria. Phrase them as suggestions, not mandates.
- The union of all seeds MUST cover the feature's design — every module in
  `module_structure` must be touched by ≥ 1 seed. At least one seed MUST be
  produced (the output contract requires `handoff.recommended_build_order` to be
  non-empty).

**VERIFY:**
- ≥ 1 `story_seed` generated
- Every seed has a unique `id` matching `^SEED-[0-9]{3,}$`, a `title`, and a `summary`
- Every `components[]` id resolves to a feature component
- Every module in `module_structure` is touched by ≥ 1 seed

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=07 --step=7.3 --project-root=. 2>&1
```
```json
{ "step": "7.3", "story_seeds": [ ... ], "module_coverage_gaps": [ ... ] }
```

---

### Step 7.4: Validate the Story Seeds

**EXECUTE:**
```
Confirm the seed set is internally consistent:
  - Every seed id is unique and matches ^SEED-[0-9]{3,}$.
  - Every seed feature_ref equals ${feature_ref}.
  - Every seed component resolves to a Phase 02 feature component.
  - Every estimated_complexity (if set) is Low / Medium / High.
  - module_coverage_gaps from Step 7.3 is empty — an uncovered module is a
    decomposition gap: add a seed or record the gap as a handoff open question.
```

**VERIFY:**
- The `story_seeds` array is non-empty and every seed is schema-conformant
- No module-coverage gap remains unaddressed

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=07 --step=7.4 --project-root=. 2>&1
```
```json
{ "step": "7.4", "seeds_validated": true }
```

---

### Step 7.5: Record the Story Seeds

**EXECUTE:**
```
Assemble the story_seeds array — each entry a full story_seed object — and retain
the review outcome (review_verdicts, blocking_resolutions, review_open_questions)
for the Phase 08 handoff.
```

**VERIFY:**
- `story_seeds` is a non-empty array; every seed has `id`, `title`, `summary`

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=07 --step=7.5 --project-root=. 2>&1
```
```json
checkpoint.phases["07"] = {
  "status": "completed",
  "review_verdicts": [ ... ],
  "blocking_resolutions": [ ... ],
  "review_open_questions": [ ... ],
  "story_seeds": [
    { "id": "SEED-001", "title": "...", "summary": "...", "feature_ref": "F-NN",
      "components": [ "COMP-NNN", ... ], "acceptance_hint": [ ... ],
      "estimated_complexity": "Medium" }, ...
  ]
}
```

---

## Exit Gate

```bash
devforgeai-validate phase-complete ${DEVARCH_ID} --workflow=development-architecture --phase=07 --checkpoint-passed --project-root=. 2>&1
```

| Exit Code | Action |
|-----------|--------|
| 0 | Phase 07 complete — proceed to next phase |
| 127 | CLI not installed — proceed without enforcement |
| Other | HALT — checkpoint/step validation failed |

---

## Phase Transition Display

```
Display:
  "Phase 07 Complete: Story Seed Generation"
  "Design review: {n} SOUND, {n} NEEDS_REVISION, {n} BLOCKING (all resolved)"
  "Story seeds: {count}  |  Proceeding to Phase 08: Development Architecture Document"
```
