owflow 0.1.10 → 0.3.0

package/dist/skills/dev-implement/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: owflow:dev-implement
+description: Development — execute the implementation plan via delegation, then the TDD Green Gate when a red gate exists. --quick selects the condensed direct path (bootstrap a task here when no state file exists; direct implementation when it does).
+argument-hint: "[task-path-or-identifier | \"description\"] [--quick]"
+user-invocable: true
+---
+
+# Dev Implement — Implementation & TDD Green Gate (implementation-done, tdd-green-proven)
+
+Work phase of the development workflow. Executes the implementation plan via delegation, then verifies the TDD red-gate test now passes when one exists.
+
+Supports a **quick mode** (`--quick`): a condensed path that implements **directly in the main agent** with the discovered standards — never routed through `implementation-plan-executor`. On a description argument with no existing task it first bootstraps a standard development task (state file, condensed spec + plan); on an existing task it applies `--quick` to the implementation itself (e.g., a quick plan). After the Exit Gate, the pipeline can either stop there or continue with `/owflow:dev-verify` — the task is a regular development task, resumable by any dev-* subskill.
+
+## Entry Gate
+
+Resolve the argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). The argument may be:
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/development/` (e.g., `2026-01-12-my-task`); resolve to its path.
+- **Description** — anything else (quoted free text, e.g. `"Add a logout button to the navbar"`) is treated as a new task description for quick bootstrap.
+
+Route by argument kind and flags:
+
+| Situation                                                        | Route                                        |
+| ---------------------------------------------------------------- | -------------------------------------------- |
+| Task path/identifier, no `--quick`, state + spec + plan exist (or only implementation pending) | Normal implementation below |
+| Task path/identifier, `--quick`, spec + plan exist               | Direct implementation (quick mode) — the flag selects the direct path over delegation |
+| Task path/identifier, `--quick`, spec or plan missing            | Quick prelude for the missing pieces, then direct implementation |
+| Task path/identifier of a dev-bugfix task (`entry_point: "dev-bugfix"`, implementation slugs complete, no spec/plan) | Normal implementation below — implement nothing; if `implementation-done` holds, run the green gate when a red gate exists, then Exit Gate (or suggest `/owflow:dev-verify <task-path>` for the verification pipeline) |
+| Description argument, `--quick` (or no argument after prompt)    | Quick bootstrap (create task + condensed prelude), then normal implementation |
+| Description argument, no `--quick`                               | Ask via `question`: quick condensed task / full pipeline (blocked block below) / cancel |
+| Missing argument                                                 | Prompt for input (path, identifier, or description), then re-route |
+
+If the path does **not exist** or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+
+1. Steps that must be completed first (in order), each with its command:
+   - Codebase & gap analysis (`codebase-analysed`, `gap-analysed`) → `/owflow:dev-analyze <task-path>`
+   - TDD red gate (`tdd-red-proven`) — only when a reproducible defect was detected → `/owflow:dev-tdd-red <task-path>`
+   - Requirements, specification & audit (`spec-written`, `spec-audited`) → `/owflow:dev-spec <task-path>`
+   - Implementation planning (`plan-created`) → `/owflow:dev-plan <task-path>`
+2. List available dev-task identifiers (directories under `.owflow/tasks/development/`) to resume from, if any.
+3. Hint: `Run /owflow:development <description> to start a task from scratch, /owflow:dev-implement --quick "<description>" for a condensed quick task, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill | Where verified                              | Produced by                      |
+| ----------------------- | ------------------------------------------- | -------------------------------- |
+| State file exists       | `<task-path>/orchestrator-state.yml`        | `/owflow:development <desc>` or quick bootstrap |
+| Spec approved           | `implementation/spec.md` exists             | `/owflow:dev-spec <task-path>` or quick prelude |
+| Plan approved           | `implementation/implementation-plan.md` exists | `/owflow:dev-plan <task-path>` or quick prelude |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → quick bootstrap (see Quick Mode), otherwise mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `implementation-done`): `question` — bootstrap a fresh standard task starting at this step, or decline → print: `No development task found at <path>. Run /owflow:development <description> to start a task from scratch.` and STOP.
+2. **Skip/resume**: if `implementation-done` is in `completed_phases`, skip to the TDD green gate.
+3. **Prerequisite check**: `implementation/spec.md` AND `implementation/implementation-plan.md` exist — **unless `implementation-done` is in `completed_phases`** (dev-bugfix task or re-run: spec/plan are not required; go straight to the skip/resume TDD green gate). If missing → run the Quick prelude for the missing pieces (`--quick` or user chooses quick), otherwise print the blocked block, then STOP:
+   - Steps that must be completed first: analysis (`codebase-analysed`, `gap-analysed`) → TDD red gate (`tdd-red-proven`, only when a reproducible defect was detected) → specification (`spec-written`) → implementation planning (`plan-created`).
+   - `Run /owflow:dev-spec and /owflow:dev-plan <task-path> first` (or `/owflow:dev-analyze <task-path>` / `/owflow:dev-spec <task-path>` for the missing earlier steps).
+   - If no task exists yet: `Run /owflow:development <description> to start a task from scratch, or /owflow:dev-implement --quick "<description>" for a condensed quick task.`
+
+## Quick Mode (condensed prelude → normal implementation)
+
+Quick mode produces the same artifacts as the early pipeline phases — just condensed into one pass inside this skill. It does NOT introduce a second state format: the task gets a standard `orchestrator-state.yml` and standard artifacts, so every other dev-* subskill can pick it up afterwards.
+
+### Quick bootstrap (no state file, description argument)
+
+1. **Create Task Directory**: `.owflow/tasks/development/YYYY-MM-DD-task-name/` (3–5 kebab-case words from the description).
+2. **Initialize State**: create `orchestrator-state.yml` from the development template with `task.title` / `task.description` from the description, `task.status: in_progress`, `orchestrator.entry_point: "dev-implement --quick"`, and `task_context.task_characteristics.has_reproducible_defect` set to `true` ONLY when the description is clearly bug-shaped (symptom + expected vs actual); otherwise `false`. Bug-shaped descriptions with a reproducible defect → suggest `/owflow:dev-bugfix` instead (TDD red gate discipline, same standard state) — `/owflow:dev-bugfix "<description>"` produces this same task shape under `.owflow/tasks/development/` — unless the user insists on proceeding here.
+   - **CRITICAL**: use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-development.yml`.
+3. **Discover project documentation**: read `.owflow/docs/INDEX.md` (if exists) and extract the Project Documentation file paths into `project_context.project_doc_paths` (matching the development dispatcher's initialization).
+4. If `.owflow/docs/` does not exist, proceed without standards and note the graceful-fallback hint in the completion message: `"No AI SDLC standards found. Consider running /owflow:flow-init to initialize project documentation and coding standards."`
+
+### Quick prelude (one condensed pass)
+
+**MANDATORY order — standards before analysis, analysis before spec/plan:**
+
+1. **Standards discovery**: identify applicable standards from INDEX.md by task keywords (e.g., "API" → api/error-handling, "form" → validation/accessibility) and **READ each applicable standard file** with the Read tool — reading INDEX.md alone is NOT sufficient. Record the paths in `project_context.standards_applied` (extra state field) and reference them in the spec.
+2. **Brief codebase analysis**: explore the affected areas (Glob, Grep, Read) — enough to identify affected files/modules, existing patterns, and test strategy. Write `analysis/quick-analysis.md` (affected files, approach sketch, standards referenced). Extract a 1–2 sentence summary into `phase_summaries.quick_analysis`.
+3. **Condensed spec**: write `implementation/spec.md` — goal, scope (in/out), requirements, applicable standards with key guidelines, verification criteria. Mark `spec-written` complete (`phase_summaries.specification` summary).
+4. **Condensed plan**: write `implementation/implementation-plan.md` — 1–3 task groups, each with concrete checkable steps and tests. Use the same on-the-fly plan shape as the dev-plan quick prelude: key discoveries with `file:line` references, a "What We're NOT Doing" out-of-scope list, intent + contract per step (no code snippets unless non-obvious), automated vs manual acceptance criteria, and no open questions (resolve before finalizing). Mark `plan-created` complete.
+5. **Approval gate** — use `question`: present the mini plan (goal, approach, affected files, task groups) and ask "Proceed with implementation?" Options: **Approve and implement** / **Adjust** (rework spec/plan, re-ask) / **Run full pipeline instead** (print `/owflow:development <task-path>` and STOP — do not implement) / **Cancel**.
+6. On approval: append `codebase-analysed` and `gap-analysed` to `completed_phases` (quick analysis covers both; note the condensation in `phase_summaries.codebase_analysis` / `phase_summaries.gap_analysis`), bump `orchestrator.updated`, re-run `verify_template` on the state file.
+
+The TDD red gate is SKIPPED in quick mode (no `tdd-red-proven`), and the green gate below is therefore skipped too. `spec-audited` is skipped — the approval gate in step 5 substitutes for the audit.
+
+Then continue with **Direct Implementation (quick mode)** below.
+
+### Direct implementation (quick mode, `implementation-done`)
+
+**Trigger**: quick mode selected for this run — the `--quick` flag on this invocation, or the task bootstrapped/prelude-run in quick mode this session (`orchestrator.entry_point: "dev-implement --quick"`). Quick mode NEVER routes to `implementation-plan-executor` — the main agent implements directly, applying the standards already read in prelude step 1 (for a pre-existing plan, apply the standards listed in its "Standards Compliance" section). (Normal full-pipeline runs always delegate — see Execute below.)
+
+1. **Work through the condensed plan's task groups in order**, following each step's intent and contract.
+2. **Apply standards**: for every code change, verify it follows the applicable standards from `project_context.standards_applied`. If implementation reveals new areas (auth, database, file handling, ...) whose standards were not read in the prelude, check `.owflow/docs/INDEX.md` and READ the applicable standard files before proceeding; append their paths to `project_context.standards_applied`.
+3. **Tests**: run the plan's tests as steps specify (test-driven order per group: tests → implementation → verify). Fix failures before moving on.
+4. **Mark checkboxes** in `implementation/implementation-plan.md` immediately after each step completes (main agent responsibility — same convention as implementation-plan-executor).
+5. **Work-log**: append per-group entries and a completion entry to `implementation/work-log.md` (files changed, standards applied — prelude-read and discovered, test results).
+
+## Execute (normal runs — full pipeline)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
+
+**Scope**: normal runs only — task created via the full pipeline, or a quick task resumed **without** `--quick` (e.g., a `/owflow:dev-plan --quick` task continued with `/owflow:dev-implement <task-path>`; the executor picks up uncompleted groups). Quick mode uses Direct implementation above instead of this section.
+
+### Implementation (`implementation-done`) — Skill tool
+
+**ANTI-PATTERN (normal runs) — never implement directly. "Simple enough to code inline" is NOT a reason to skip delegation.**
+
+Skill tool - `implementation-plan-executor`. Pass: task_path, task_description, task_characteristics, `phase_summaries`, research context if present in state. The skill manages its own subagents, incremental tests, and `implementation/work-log.md`.
+
+### TDD Green Gate (`tdd-green-proven`, conditional)
+
+**Skip if** `tdd-red-proven` is NOT in `completed_phases` (no red gate exists).
+
+1. Run the test written in the red gate (path recorded in `implementation/tdd-red-gate.md`).
+2. **It MUST pass** — proves the defect is fixed. On failure: fix implementation and retry (up to 5 attempts: syntax, imports, test alignment). Still failing → `question`: continue fixing, return to `/owflow:dev-implement` implementation work, or stop.
+3. Write results to `implementation/tdd-green-gate.md`; set `task_context.tdd_green_passed: true`.
+
+## State Update Convention (per step)
+
+Apply after EVERY phase/step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed plus that step's fields. Never batch multiple steps into one end-of-skill write:
+   - After implementation (direct quick implementation or plan execution complete): append `implementation-done` to `completed_phases`; extract 1-2 sentence summary to `phase_summaries.implementation` (task groups completed, files changed, test results, known issues); bump `orchestrator.updated`.
+   - After the green gate (only when it ran — no red gate ⇒ no `tdd-green-proven`): append `tdd-green-proven` to `completed_phases`; set `task_context.tdd_green_passed: true`; bump `orchestrator.updated`.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if the direct implementation or green gate ultimately fails (retries exhausted, user stops): do NOT append the corresponding slug to `completed_phases`; append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`. Partial progress stays documented in `phase_summaries.implementation` and `implementation/work-log.md`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-development.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ DEV IMPLEMENT COMPLETE — <task name>
+
+**Task groups** — [completed groups / total]
+**Files changed** — [count + key files, 1-3 lines]
+**Tests** — [incremental test results]
+**Green gate** — [✅ PASSED / not required (no red gate)]
+**Known issues** — [deferred items / "none"]
+**Entry point** — [quick bootstrap (direct implementation) / full pipeline (delegated)]
+
+**Artifacts**
+- implemented code
+- `implementation/work-log.md`
+- `implementation/tdd-green-gate.md` [conditional]
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — implementation matches the plan; continue.
+- **Adjust** — re-work the affected task groups (fix code, re-run their tests), update state and work-log, re-present the results box.
+- **Discuss** — walk through implementation details (decisions made, files changed, deferred items) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:dev-implement <task-path>`) and end. The task is a regular development task; `/owflow:dev-verify <task-path>` (or `/owflow:development <task-path>`) continues the pipeline later.
+
+### Next steps (after Accept)
+
+- `→ /owflow:dev-verify <task-path>` — `required` before commit: runs the verification pipeline (completeness, code review with a bounded fix loop) and must pass before finalization. Remaining after: finalize.
+
+**Other options**:
+
+- `/owflow:goal-development <task-path>` — `optional` shortcut: runs all remaining phases in one loop (verify → finalize)
+
+Then STOP.

package/dist/skills/dev-plan/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: owflow:dev-plan
+description: Development — break the approved specification into a grouped, dependency-ordered implementation plan. --quick starts a condensed task here when no state file exists.
+argument-hint: "[task-path-or-identifier | \"description\"] [--quick]"
+user-invocable: true
+---
+
+# Dev Plan — Implementation Planning (plan-created)
+
+Work phase of the development workflow. Delegates planning to break the specification into task groups with dependencies, then refines the plan with an execution diagram.
+
+Supports a **quick mode** (`--quick`, or any description argument with no existing task): a condensed prelude that bootstraps a standard development task (state file, standards discovery, quick analysis, condensed spec) and then writes the implementation plan directly on the fly — no planner subagent. After the Exit Gate, the pipeline can either stop there — the plan alone may be enough — or continue with `/owflow:dev-implement`. The task is a regular development task, resumable by any dev-* subskill.
+
+## Entry Gate
+
+Resolve the argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). The argument may be:
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/development/` (e.g., `2026-01-12-my-task`); resolve to its path.
+- **Description** — anything else (quoted free text, e.g. `"Add a logout button to the navbar"`) is treated as a new task description for quick bootstrap.
+
+Route by argument kind and flags:
+
+| Situation                                                        | Route                                        |
+| ---------------------------------------------------------------- | -------------------------------------------- |
+| Task path/identifier, state + spec exist                          | Normal planning below                        |
+| Task path/identifier, `--quick`, state or spec missing            | Quick bootstrap/prelude for the missing pieces, then normal planning |
+| Description argument, `--quick` (or no argument after prompt)     | Quick bootstrap (create task + condensed prelude), then normal planning |
+| Description argument, no `--quick`                                | Ask via `question`: quick plan-only task / full pipeline (blocked block below) / cancel |
+| Missing argument                                                  | Prompt for input (path, identifier, or description), then re-route |
+
+If the path does **not exist** or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+
+1. Steps that must be completed first (in order), each with its command:
+   - Codebase & gap analysis (`codebase-analysed`, `gap-analysed`) → `/owflow:dev-analyze <task-path>`
+   - TDD red gate (`tdd-red-proven`) — only when a reproducible defect was detected → `/owflow:dev-tdd-red <task-path>`
+   - Requirements, specification & audit (`spec-written`, `spec-audited`) → `/owflow:dev-spec <task-path>`
+2. List available dev-task identifiers (directories under `.owflow/tasks/development/`) to resume from, if any.
+3. Hint: `Run /owflow:development <description> to start a task from scratch, /owflow:dev-plan --quick "<description>" for a quick plan-only task, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill | Where verified                                       | Produced by                      |
+| ----------------------- | ---------------------------------------------------- | -------------------------------- |
+| State file exists       | `<task-path>/orchestrator-state.yml`                 | `/owflow:development <desc>` or quick bootstrap |
+| Spec approved           | `implementation/spec.md` exists                      | `/owflow:dev-spec <task-path>` or quick prelude |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → quick bootstrap (see Quick Mode), otherwise mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `plan-created`): `question` — bootstrap a fresh standard task starting at this step, or decline → print: `No development task found at <path>. Run /owflow:development <description> to start a task from scratch, or /owflow:dev-plan --quick "<description>" for a quick plan-only task.` and STOP.
+2. **Skip/resume**: if `plan-created` is in `completed_phases`, report the existing plan summary and route to the Exit Gate.
+3. **Prerequisite check**: `implementation/spec.md` exists (spec approved during `spec-written`). If missing → run the Quick prelude for the missing pieces (`--quick` or user chooses quick), otherwise print the blocked block, then STOP:
+   - Steps that must be completed first: analysis (`codebase-analysed`, `gap-analysed`) → TDD red gate (`tdd-red-proven`, only when a reproducible defect was detected) → specification (`spec-written`).
+   - `Run /owflow:dev-spec <task-path> first` (or `/owflow:dev-analyze <task-path>` if analysis is also missing).
+   - If no task exists yet: `Run /owflow:development <description> to start a task from scratch, or /owflow:dev-plan --quick "<description>" for a quick plan-only task.`
+
+## Quick Mode (condensed prelude → plan on the fly)
+
+Quick mode produces the same artifacts as the early pipeline phases — just condensed into one pass inside this skill. It does NOT introduce a second state format: the task gets a standard `orchestrator-state.yml` and standard artifacts, so every other dev-* subskill can pick it up afterwards.
+
+### Quick bootstrap (no state file, description argument)
+
+1. **Create Task Directory**: `.owflow/tasks/development/YYYY-MM-DD-task-name/` (3–5 kebab-case words from the description).
+2. **Initialize State**: create `orchestrator-state.yml` from the development template with `task.title` / `task.description` from the description, `task.status: in_progress`, and `orchestrator.entry_point: "dev-plan --quick"`.
+   - **CRITICAL**: use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-development.yml`.
+3. **Discover project documentation**: read `.owflow/docs/INDEX.md` (if exists) and extract the Project Documentation file paths into `project_context.project_doc_paths` (matching the development dispatcher's initialization).
+4. If `.owflow/docs/` does not exist, proceed without standards and note the graceful-fallback hint in the completion message: `"No AI SDLC standards found. Consider running /owflow:flow-init to initialize project documentation and coding standards."`
+
+### Quick prelude (one condensed pass)
+
+**MANDATORY order — standards before analysis, analysis before spec/plan:**
+
+1. **Standards discovery**: identify applicable standards from INDEX.md by task keywords (e.g., "API" → api/error-handling, "form" → validation/accessibility) and **READ each applicable standard file** with the Read tool — reading INDEX.md alone is NOT sufficient. Record the paths in `project_context.standards_applied` (extra state field).
+2. **Brief codebase analysis**: explore the affected areas (Glob, Grep, Read) — enough to identify affected files/modules, existing patterns, and constraints that inform the plan. Write `analysis/quick-analysis.md` (affected files, approach sketch, standards referenced). Extract a 1–2 sentence summary into `phase_summaries.quick_analysis`.
+3. **Condensed spec**: write `implementation/spec.md` — goal, scope (in/out), requirements, applicable standards with key guidelines, verification criteria. Mark `spec-written` complete (`phase_summaries.specification` summary).
+4. **Condensed plan — written directly, NO delegation**: write `implementation/implementation-plan.md` on the fly, keeping the executor-compatible shape (1–3 task groups, `Dependencies:` per group, `- [ ] N.1 / N.2 / …` steps, acceptance criteria per group) and applying these quality rules:
+   - **Key discoveries first** — open with 2–4 discoveries from the quick analysis, each with a `file:line` reference (pattern to follow, constraint to respect, existing component to reuse).
+   - **"What We're NOT Doing"** — an explicit out-of-scope list to fence scope creep.
+   - **Intent before implementation** — each step names WHAT and WHY (intent) plus the touched interface or invariant (contract: route, signature, schema field, invariant). No code snippets unless the change is genuinely non-obvious.
+   - **Verification split** — acceptance criteria distinguish automated checks (specific test commands) from manual checks.
+   - **No open questions** — every decision is made before the plan is final; resolve ambiguities during the quick analysis (decide, or ask via `question`), never write TBDs.
+   This REPLACES the `implementation-planner` delegation in Execute below (quick mode is the only exception to the delegation anti-pattern). Mark `plan-created` complete (`phase_summaries.planning` summary).
+
+The TDD red gate is SKIPPED in quick mode (no `tdd-red-proven`), and `spec-audited` is skipped — plan approval at the Exit Gate substitutes for the audit.
+
+Then continue with the **Post-Plan Diagram** gate below (both modes).
+
+## Execute (full pipeline — delegated planning)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
+
+**ANTI-PATTERN — never write implementation-plan.md yourself in the full pipeline. "This is simple enough to plan inline" is NOT a reason to skip delegation. (Quick mode is the ONLY exception — its prelude step 4 writes the plan directly and skips this section.)**
+
+Task tool - `implementation-planner`. Pass: task_path, task_description, task_characteristics, `phase_summaries` (specification, gap_analysis, codebase_analysis), research/quick context if present in state. Output: `implementation/implementation-plan.md`.
+
+## Post-Plan Diagram (optional — both modes)
+
+1. **Diagram gate** — use `question`: "Add an execution diagram to the implementation plan?" Options:
+   - **Add diagram** — run the refinement step below.
+   - **Skip diagram** — the plan stays as-is; neither choice affects plan approval.
+2. Only on **Add diagram** — Skill tool - `diagrams-mermaid` on `implementation/implementation-plan.md` (content-preserving): add a compact execution diagram (task-group dependency flow or phase/state view). Implementation steps remain authoritative; diagrams are explanatory. If refinement fails, note it and continue — the plan itself is unaffected.
+
+## State Update Convention (per step)
+
+1. **On success** (implementation-plan.md written — the diagram is optional and its absence does NOT block success): immediately append `plan-created` to `completed_phases`; write 1-2 sentence summary to `phase_summaries.planning`; bump `orchestrator.updated`.
+   - In quick mode, ALSO append the prelude slugs on their individual completions (never batched into one end-of-skill write): `codebase-analysed` and `gap-analysed` after the quick analysis (quick analysis covers both; note the condensation in `phase_summaries.codebase_analysis` / `phase_summaries.gap_analysis`), `spec-written` after the condensed spec (summary in `phase_summaries.specification`), and `plan-created` after the condensed plan (written directly — no delegation).
+2. **On failure** (planner fails in the full pipeline, or the quick-mode plan is incomplete): do NOT append to `completed_phases`; append `plan-created` to `orchestrator.failed_phases` and increment `auto_fix_attempts["plan-created"]`. A declined or failed diagram refinement is NOT a failure — note it in `phase_summaries.planning` and proceed.
+3. **Timestamp + validate** — set `orchestrator.updated` on every write; after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-development.yml`. Fix any reported issue immediately.
+4. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run.
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ DEV PLAN COMPLETE — <task name>
+
+**Task groups** — [N]
+**Total steps** — [M]
+**Dependencies** — [key ordering constraints, 1-2 lines]
+**Complexity** — [estimated complexity]
+**Entry point** — [quick bootstrap (`--quick`) / full pipeline]
+**Diagram** — [added / skipped (optional)]
+
+**Artifacts**
+- `implementation/implementation-plan.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the plan is good; continue.
+- **Adjust** — regenerate the plan with the user's corrections (grouping, ordering, scope), update state, re-present the results box.
+- **Discuss** — walk through the plan structure (task groups, dependencies, step breakdown) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:dev-plan <task-path>`) and end. The task is a regular development task; `/owflow:dev-implement <task-path>` (or `/owflow:development <task-path>`) continues the pipeline later.
+
+### Next steps (after Accept)
+
+- `→ /owflow:dev-implement <task-path>` — `required` next: executes the plan task group by task group via subagents (includes the TDD green gate when a red gate exists). Remaining after: verify → finalize. If the plan alone was the goal, stop here — the task stays resumable.
+- `/owflow:dev-implement --quick <task-path>` — `optional` condensed alternative: implements the plan directly in the main agent with standards instead of delegating to subagents.
+
+**Other options**:
+
+- `/owflow:goal-development <task-path>` — `optional` shortcut: runs all remaining phases in one loop (implement → verify → finalize)
+
+Then STOP.

package/dist/skills/dev-spec/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: owflow:dev-spec
+description: Development — technical approach, requirements gathering, specification creation, and optional specification audit. --quick starts a condensed spec task here when no state file exists (condensing the missing pieces on an existing task).
+argument-hint: "[task-path-or-identifier | \"description\"] [--quick]"
+user-invocable: true
+---
+
+# Dev Spec — Requirements, Specification & Audit (spec-written, spec-audited)
+
+Work phase of the development workflow. Resolves technical decisions, gathers requirements, creates the specification via delegation, refines it with diagrams, then offers an independent specification audit.
+
+Supports a **quick mode** (`--quick`, or any description argument with no existing task): a condensed prelude that bootstraps a standard development task (state file, standards discovery, quick analysis) and then writes the condensed specification directly on the fly — no specification-creator subagent. After the Exit Gate, the pipeline continues with `/owflow:dev-plan` (normal or `--quick`). The task is a regular development task, resumable by any dev-* subskill.
+
+## Entry Gate
+
+Resolve the argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). The argument may be:
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/development/` (e.g., `2026-01-12-my-task`); resolve to its path.
+- **Description** — anything else (quoted free text, e.g. `"Add a logout button to the navbar"`) is treated as a new task description for quick bootstrap.
+
+Route by argument kind and flags:
+
+| Situation                                                     | Route                                                                        |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Task path/identifier, no `--quick`, state + analysis exist    | Normal specification below                                                    |
+| Task path/identifier, `--quick`, analysis done (spec missing) | Quick prelude step 3 only (condensed spec), then audit offer / Exit Gate      |
+| Task path/identifier, `--quick`, analysis missing             | Quick bootstrap/prelude for the missing pieces, then condensed spec           |
+| Description argument, `--quick` (or no argument after prompt) | Quick bootstrap (create task + condensed prelude + condensed spec)            |
+| Description argument, no `--quick`                            | Ask via `question`: quick spec-only task / full pipeline (blocked block below) / cancel |
+| Missing argument                                              | Prompt for input (path, identifier, or description), then re-route            |
+
+If the path does **not exist** or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+
+1. Steps that must be completed first (in order), each with its command:
+   - Codebase & gap analysis (`codebase-analysed`, `gap-analysed`) → `/owflow:dev-analyze <task-path>`
+   - TDD red gate (`tdd-red-proven`) — only when a reproducible defect was detected during analysis → `/owflow:dev-tdd-red <task-path>`
+2. List available dev-task identifiers (directories under `.owflow/tasks/development/`) to resume from, if any.
+3. Hint: `Run /owflow:development <description> to start a task from scratch, /owflow:dev-spec --quick "<description>" for a quick spec-only task, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill    | Where verified                                                                              | Produced by                                        |
+| -------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| State file exists          | `<task-path>/orchestrator-state.yml`                                                        | `/owflow:development <desc>` or quick bootstrap    |
+| Analysis done              | `gap-analysed` in `completed_phases` + `analysis/gap-analysis.md` exists                    | `/owflow:dev-analyze <task-path>` or quick prelude |
+| TDD red gate (conditional) | `tdd-red-proven` in `completed_phases` — required only when `has_reproducible_defect: true` | `/owflow:dev-tdd-red <task-path>`                  |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → quick bootstrap when invoked with `--quick` or a description argument (see Quick Mode), otherwise mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `spec-written`): `question` — create a fresh standard development task starting at this step, or decline → print `No development task found at <path>. Run /owflow:development <description> to start a task from scratch, or /owflow:dev-spec --quick "<description>" for a quick spec-only task.` and STOP.
+2. **Skip/resume**: if both `spec-written` and `spec-audited` are in `completed_phases`, report existing results and route to the Exit Gate. If only `spec-written` is complete: when `options.spec_audit_enabled: false` (quick task — audit skipped by design), report the existing spec summary and route to the Exit Gate; otherwise skip to the spec audit.
+3. **Conditional activation (routing guard — both modes)**: if `task_context.task_characteristics.has_reproducible_defect` is `true` AND `tdd-red-proven` is NOT in `completed_phases` → print the blocked block, then STOP (quick mode does NOT bypass a proven-defect red gate; the quick TDD lane for bug-shaped work is `/owflow:dev-bugfix`):
+   - Steps that must be completed first: TDD red gate (`tdd-red-proven` — required because a reproducible defect was detected); if analysis (`codebase-analysed`, `gap-analysed`) is also missing, start there.
+   - `Run /owflow:dev-tdd-red <task-path> first (or /owflow:dev-analyze <task-path> if analysis is also missing).`
+4. **Prerequisite check**: `gap-analysed` in `completed_phases` and `analysis/gap-analysis.md` exists. If missing → run the Quick prelude for the missing pieces (when `--quick` or the user chooses quick), otherwise print the blocked block, then STOP:
+   - Steps that must be completed first: codebase & gap analysis (`codebase-analysed`, `gap-analysed`).
+   - `Run /owflow:dev-analyze <task-path> first.`
+   - If no task exists yet: `Run /owflow:development <description> to start a task from scratch, or /owflow:dev-spec --quick "<description>" for a quick spec-only task.`
+
+## Quick Mode (condensed prelude → spec on the fly)
+
+Quick mode produces the same artifacts as the early pipeline phases — just condensed into one pass inside this skill. It does NOT introduce a second state format: the task gets a standard `orchestrator-state.yml` and standard artifacts, so every other dev-* subskill can pick it up afterwards.
+
+### Quick bootstrap (no state file, description argument)
+
+1. **Create Task Directory**: `.owflow/tasks/development/YYYY-MM-DD-task-name/` (3–5 kebab-case words from the description).
+2. **Initialize State**: create `orchestrator-state.yml` from the development template with `task.title` / `task.description` from the description, `task.status: in_progress`, and `orchestrator.entry_point: "dev-spec --quick"`. Bug-shaped descriptions (symptom + expected vs actual) → suggest `/owflow:dev-bugfix "<description>"` instead (TDD red gate discipline, same standard state) — unless the user insists on proceeding here.
+   - **CRITICAL**: use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-development.yml`.
+3. **Discover project documentation**: read `.owflow/docs/INDEX.md` (if exists) and extract the Project Documentation file paths into `project_context.project_doc_paths` (matching the development dispatcher's initialization).
+4. If `.owflow/docs/` does not exist, proceed without standards and note the graceful-fallback hint in the completion message: `"No AI SDLC standards found. Consider running /owflow:flow-init to initialize project documentation and coding standards."`
+
+### Quick prelude (one condensed pass)
+
+**MANDATORY order — standards before analysis, analysis before spec:**
+
+1. **Standards discovery** (skip when `project_context.standards_applied` already lists the applicable standards): identify applicable standards from INDEX.md by task keywords (e.g., "API" → api/error-handling, "form" → validation/accessibility) and **READ each applicable standard file** with the Read tool — reading INDEX.md alone is NOT sufficient. Record the paths in `project_context.standards_applied` (extra state field).
+2. **Brief codebase analysis** (skip when `gap-analysed` is already in `completed_phases`): explore the affected areas (Glob, Grep, Read) — enough to identify affected files/modules, existing patterns, and constraints that inform the spec. Write `analysis/quick-analysis.md` (affected files, approach sketch, standards referenced). Extract a 1–2 sentence summary into `phase_summaries.quick_analysis`.
+3. **Condensed requirements pass (gap-driven — no fixed question rounds)**: extract the REQUIRED spec topics from evidence first — **User Journey** (discovery/access, personas, workflow fit), **Existing Code Reuse** (similar features, UI components, backend patterns — found during the brief analysis), **Visual Assets** (check `analysis/visuals/` regardless of the answer; skip visual processing for non-UI tasks when none found). On an existing task, reuse the analysis clarifications (`analysis/clarifications.md`, gap-analysis scope decisions) as already-gathered evidence. Only where a genuine gap or ambiguity would change the spec's scope or architecture, ask ONE consolidated `question` round (2–4 targeted questions, confirmable-assumption framing "I assume X — is that correct?", multi-select where positions co-exist); when multiple valid architectural approaches surface, present them in the same round and record the choice in `task_context.architecture_decision`. Never write TBDs or open questions into the condensed spec — decide, or ask; anything unresolvable is recorded as an explicit assumption in the spec's scope section. Save the gathered context to `analysis/requirements.md` (condensed: description, evidence-based journey/reuse/visuals findings, any Q&A, requirements, scope boundaries, standards referenced).
+4. **Condensed spec — written directly, NO delegation**: write `implementation/spec.md` — goal, scope (in/out), requirements, applicable standards with key guidelines, verification criteria. Then run the Quick diagram gate below. This REPLACES the `specification-creator` delegation in Execute below (quick mode is the only exception to the delegation anti-pattern). Mark `spec-written` complete (`phase_summaries.specification` summary).
+
+### Quick diagram gate (optional — part of the condensed spec)
+
+1. Use `question`: "Add diagrams to the condensed spec?" Options:
+   - **Add diagrams** — Skill tool - `diagrams-mermaid` on `implementation/spec.md` (content-preserving, same rules as the normal Diagram Refinement).
+   - **Skip** — the spec stays prose-only.
+2. A declined or failed diagram refinement is NOT a failure — note it in `phase_summaries.specification` and continue.
+
+The TDD red gate is NOT bypassed by quick mode: when `has_reproducible_defect: true` and `tdd-red-proven` is missing, the routing guard in the Entry Gate fires in both modes — the quick TDD lane for bug-shaped work is `/owflow:dev-bugfix`, not a silent skip. `spec-audited` is SKIPPED in quick mode — set `options.spec_audit_enabled: false`; Exit Gate acceptance substitutes for the audit, and `/owflow:reviews-spec-audit <task-path>` remains available as a standalone later option.
+
+Then continue with the **Exit Gate** below.
+
+## Execute (normal runs — delegated specification)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
+
+**Scope**: normal runs only — quick mode writes the condensed spec directly (see Quick Mode) and skips this section.
+
+### Technical & Architecture Clarification (before `spec-written`, inline, conditional)
+
+- Complex task with multiple approaches → `question` for 3-5 technical questions.
+- Multiple valid architectural approaches → present 2-3 via `question`; the chosen approach is passed to specification-creator.
+- Save to `analysis/technical-clarifications.md` (conditional).
+- Skip if: simple task, `risk_level: low`, no multiple approaches detected.
+
+### Requirements Gathering (part of `spec-written`, inline)
+
+1. `question` for specification requirements — adaptive count based on description length: brief (<30 words) 6-8; standard (30-100 words) 4-6; detailed (>100 words) 2-3. Frame as confirmable assumptions ("I assume X, is that correct?").
+2. REQUIRED questions (always include): **User Journey** (discovery/access, personas, workflow fit), **Existing Code Reuse** (similar features, UI components, backend patterns), **Visual Assets** (mockups/wireframes → `analysis/visuals/`).
+3. Check `analysis/visuals/` for assets regardless of the answer; note findings for subagent context (skip visual processing for non-UI tasks when none found).
+4. Save to `analysis/requirements.md`: initial description, all Q&A rounds, similar features, visual insights, functional requirements, reusability opportunities, scope boundaries, technical considerations.
+
+### Specification Creation (part of `spec-written`, subagent)
+
+**ANTI-PATTERN — never write spec.md yourself in a normal run. "The task is simple" is NOT a reason to skip delegation. (Quick mode is the ONLY exception — its prelude step 4 writes the condensed spec directly and skips this section.)**
+
+Task tool - `specification-creator`. Pass: task_path, task_description, task_characteristics, requirements_path (`analysis/requirements.md`), project_context_paths (INDEX.md + `project_doc_paths` from state), risk_level, relevant `phase_summaries`, research/quick context if present in state. Output: `implementation/spec.md`.
+
+### Diagram Refinement (part of `spec-written`, Skill, content-preserving)
+
+Skill tool - `diagrams-mermaid` on `implementation/spec.md`. Add diagrams that clarify scope and communication without replacing prose: `flowchart` (primary functional path), `sequenceDiagram` (key interaction), optional `C4Component` (if module structure is in scope). Missing context → add an explicit open questions section instead of inventing entities.
+
+### Specification Audit (`spec-audited`, recommended)
+
+1. `question` — "Run specification audit? (Recommended)" with "Yes, run audit (Recommended)" first. User may skip.
+2. If yes: Task tool - `spec-auditor`. Pass: task_path, spec_path. Output: `verification/spec-audit.md`. Display verdict (pass/pass-with-concerns/fail), issue counts by severity, top critical findings.
+
+## State Update Convention (per step)
+
+Apply after EVERY phase/step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed plus that step's fields. Never batch multiple steps into one end-of-skill write:
+   - After Part A (if it ran): set `task_context.tech_clarified`, `task_context.architecture_decision`.
+   - After Parts B–D (`spec-written` complete): append `spec-written` to `completed_phases`; set `phase_summaries.specification`; bump `orchestrator.updated`.
+   - After Part E (only when the audit ran): append `spec-audited` to `completed_phases`; set `options.spec_audit_enabled: true` and the audit verdict in `phase_summaries.specification`; bump `orchestrator.updated`. When the user skipped the audit, set `options.spec_audit_enabled: false` — no `spec-audited` entry.
+   - In quick mode, ALSO append the prelude slugs on their individual completions (never batched): `codebase-analysed` and `gap-analysed` after the quick analysis (quick analysis covers both; note the condensation in `phase_summaries.codebase_analysis` / `phase_summaries.gap_analysis`), then `spec-written` after the condensed spec (summary in `phase_summaries.specification`). The audit skip sets `options.spec_audit_enabled: false` — no `spec-audited` entry.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if the spec creation or audit fails and cannot be recovered, do NOT append to `completed_phases`; append the corresponding step slug (`spec-written` or `spec-audited`) to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-development.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ DEV SPEC COMPLETE — <spec title>
+
+**Approach** — [architecture approach in 1 line]
+**Scope** — [N included / M excluded]
+**Audit** — [✅ pass / ⚠ pass-with-concerns / ❌ fail / skipped]: [0 critical / N major / N minor]
+**Entry point** — [quick bootstrap (`--quick`) / full pipeline]
+
+**Artifacts**
+
+- `analysis/requirements.md`
+- `implementation/spec.md`
+- `verification/spec-audit.md` [conditional]
+```
+
+In quick mode the audit line reads `skipped (quick mode)` and `/owflow:reviews-spec-audit <task-path>` is the standalone later option.
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the specification is good; continue.
+- **Adjust** — regenerate the spec with the user's corrections (clarifications, scope boundaries, requirements), update state, re-present the results box.
+- **Discuss** — walk through a specific part of the spec (scope boundaries, architecture approach, audit findings) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:dev-spec <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:dev-plan <task-path>` — `required` next: breaks the approved spec into grouped, dependency-ordered task groups with test-driven steps. Remaining after: implement → verify → finalize.
+- `/owflow:dev-plan --quick <task-path>` — `optional` condensed alternative: writes the implementation plan directly on the fly instead of delegating to the planner subagent.
+
+**Other options**:
+
+- `/owflow:reviews-spec-audit <task-path>` — `optional` — standalone spec re-audit; does not advance phases (verify results, then re-run `/owflow:dev-spec` adjustments if needed)
+- `/owflow:goal-development <task-path>` — `optional` shortcut: runs all remaining phases in one loop (plan → implement → verify → finalize)
+
+Then STOP.

package/dist/skills/dev-tdd-red/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: owflow:dev-tdd-red
+description: Development — TDD Red Gate. Write a failing test that reproduces the defect before any implementation work.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Dev TDD Red — TDD Red Gate (tdd-red-proven)
+
+Work phase of the development workflow. Writes a failing test proving the defect exists, before any implementation. Only runs when the gap analysis detected a reproducible defect.
+
+## Entry Gate
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/development/` (e.g., `2026-01-12-my-task`); resolve to its path.
+- If the argument is **missing**, the path does **not exist**, or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+  1. Steps that must be completed first (in order), each with its command:
+     - Codebase & gap analysis (`codebase-analysed`, `gap-analysed`) → `/owflow:dev-analyze <task-path>`
+  2. List available dev-task identifiers (directories under `.owflow/tasks/development/`) to resume from, if any.
+  3. Hint: `Run /owflow:development <description> to start a task from scratch, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill        | Where verified                                                                                         | Produced by                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------ | -------------------------------- |
+| State file exists              | `<task-path>/orchestrator-state.yml`                                                                   | `/owflow:development <desc>`     |
+| Analysis done                  | `gap-analysed` in `completed_phases`                                                                   | `/owflow:dev-analyze <task-path>`|
+| Defect is reproducible         | `task_context.task_characteristics.has_reproducible_defect: true`                                      | `/owflow:dev-analyze <task-path>`|
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `tdd-red-proven`): `question` — create a fresh standard development task starting at this step, or decline → print `No development task found at <path>. Run /owflow:development <description> to start a task from scratch.` and STOP.
+2. **Skip/resume**: if `tdd-red-proven` is in `completed_phases`, report the existing `implementation/tdd-red-gate.md` results and route to the Exit Gate.
+3. **Conditional activation**: read `task_context.task_characteristics.has_reproducible_defect`. If `false` → print `No reproducible defect detected — TDD red gate not required.` and suggest `→ /owflow:dev-spec <task-path>` (required next phase: turns analysis into a user-approved specification; remaining plan plan → implement → verify → finalize), then STOP.
+4. **Prerequisite check**: `gap-analysed` must be in `completed_phases`. If not → print the blocked block, then STOP:
+   - Steps that must be completed first: codebase & gap analysis (`codebase-analysed`, `gap-analysed`).
+   - Run `/owflow:dev-analyze <task-path> first.`
+   - If no task exists yet: `Run /owflow:development <description> to start a task from scratch.`
+
+## Execute
+
+Direct execution (no delegation — this is a targeted, single-test task):
+
+1. Read `analysis/clarifications.md`, `analysis/gap-analysis.md`, and the affected files identified by the analysis to understand the defect.
+2. Write ONE focused test that reproduces the defect (correct test framework for the project — check existing test setup).
+3. Run the test. **It MUST fail** — a failing result proves the defect exists. If it passes unexpectedly, the defect is not reproduced: revise the test or report the mismatch via `question`.
+
+**Critical**: Do NOT fix anything. Do NOT write implementation code. The test failing is the deliverable.
+
+## State Update Convention (per step)
+
+1. **On success** (test fails as expected, red gate proven): immediately append `tdd-red-proven` to `completed_phases` and set `task_context.tdd_red_passed: true`; bump `orchestrator.updated`.
+2. **On failure or abandoned retries** (test framework issues, imports that could not be resolved): do NOT append to `completed_phases`; append `tdd-red-proven` to `orchestrator.failed_phases` and increment `auto_fix_attempts["tdd-red-proven"]`; document the blocker in `task_context.gaps`.
+3. **On user-chosen skip** (via `question` after repeated failures): record the skip with the failure reason in `task_context.gaps` and set `task_context.tdd_red_passed: false` — no `completed_phases` entry, no `failed_phases` entry (it was a deliberate decision, not a failure).
+4. **Timestamp + validate** — set `orchestrator.updated` on every write; after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-development.yml`. Fix any reported issue immediately.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run.
+
+Retry rule: on repeated failures (test framework issues, imports) retry up to 2 times (rewrite test, fix setup). Still failing → `question`: continue trying, or skip TDD with the failure documented in state (per rule 3).
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ TDD RED GATE COMPLETE — <task name>
+
+**Test** — <test name> (`<test file path>`)
+**Result** — ❌ FAILED as expected — defect reproduced
+**Failure** — <1-line key failure output proving the defect>
+
+**Artifacts**
+- `implementation/tdd-red-gate.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the failing test faithfully reproduces the defect; continue.
+- **Adjust** — revise the test (different conditions, better assertion), re-run, re-present the results box.
+- **Discuss** — walk through the reproduction reasoning (defect path, why the test fails) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:dev-tdd-red <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:dev-spec <task-path>` — `required` next: turns analysis plus this red test into a user-approved specification (the test becomes the acceptance criterion for the fix). Remaining after: plan → implement → verify → finalize.
+
+**Other options**:
+
+- `/owflow:goal-development <task-path>` — `optional` shortcut: runs all remaining phases in one loop (spec → plan → implement → verify → finalize)
+
+Then STOP.