feat: /awos:flow — generates the project's /implement-feature delivery flow

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "AWOS plugins for AI-native development workflows",
-    "version": "2.1.0"
+    "version": "2.3.0"
   },
   "plugins": [
     {
       "name": "awos",
       "source": "./plugins/awos",
-      "description": "Comprehensive code quality audit framework with auto-discoverable dimensions",
-      "version": "2.1.0"
+      "description": "Extends AWOS core with AI-powered delivery automation: audits a project's AI-readiness across auto-discoverable quality dimensions (/awos:ai-readiness-audit) and sets up an end-to-end delivery flow — feature and optional bug-fix commands — tailored to the team (/awos:flow).",
+      "version": "2.3.0"
     }
   ]
 }

.gitignore

@@ -2,3 +2,7 @@ node_modules
 .idea
 .DS_Store
 docs/superpowers/
+tmp/
+
+# pr-review skill drafts (local, not committed)
+review/

CLAUDE.md

@@ -148,4 +148,5 @@ Non-obvious rules for this repo:
 - **Prefer the built-in `Explore` and `Plan` subagents** for read-heavy context-gathering. Don't have an orchestrator command read the whole codebase in its own context.
 - **Skip ceremonial preambles** like "Great!", "I will now…", "All done!" — modern models trim them naturally and AWOS prompts shouldn't fight that.
 - **`AskUserQuestion` belongs in core `commands/*.md`** under an `# INTERACTION` section. AWOS targets Claude Code only, so the tool is a framework default rather than a host-specific customization — don't duplicate it into the `claude/commands/*.md` wrappers.
+- **Prefer `AskUserQuestion` over plain prose for every fixed-choice ask, not just the interview.** The `# INTERACTION` bullet ("instead of plain text or numbered lists") states the rule, but it's easy to break in the `PROCESS` body: "list the spec directories and ask the user to choose" is a numbered-list question wearing prose, and a proceed/stop or keep/drop/merge decision is a two-to-three-option `AskUserQuestion`, not a sentence. `flow.md` is the reference — its interview, re-run reconciliation, and reuse tradeoffs are all `AskUserQuestion` calls. Reserve plain prose for interactions with no discrete options to enumerate: a hard stop with a single next action, a non-blocking recommendation the command then proceeds past, or open-ended "review this and tell me what to change".
 - **Do not hard-wrap markdown prose at 80 columns.** Let paragraphs and list items flow as a single line per logical unit. Markdown renderers reflow soft-wrapped text, and 80-col wrapping inflates diffs when prose is edited. Wrapping is fine only where the line is semantically a single token (a URL, a code identifier) or inside a fenced block whose literal line breaks matter.

claude/commands/spec.md

@@ -1,6 +1,6 @@
 ---
 description: Creates the Functional Spec — what the feature does for the user.
-argument-hint: '[topic, optional — defaults to next roadmap item]'
+argument-hint: '[topic for a new spec, or an existing spec to amend]'
 ---
 
 @.awos/commands/spec.md

commands/spec.md

@@ -45,6 +45,31 @@ Your primary task is to create a new functional specification file. You will det
 
 Follow this process precisely.
 
+### Mode Detection (do this first)
+
+Before determining a topic, decide whether this run **creates** a new spec or **amends** an existing one. Parse `<user_prompt>` for a reference to an existing spec — a spec number (`002`), a spec directory name (`002-task-scheduling`), or an explicit "amend/update spec NNN: \<what changed\>" phrasing (how the generated `fix-bug` command's `amend-spec` stage invokes this command after a behavior-changing fix).
+
+- If the prompt names a spec whose `context/spec/[index]-[short-name]/functional-spec.md` exists, go to **Update Mode** below.
+- Otherwise, fall through to **Creation Mode** (Step 1 onward) — today's flow.
+
+Only an explicit reference to an existing spec routes to Update Mode; a fresh topic — even one adjacent to an existing feature — is Creation Mode. When the reference is ambiguous, confirm with the user via `AskUserQuestion` rather than guessing.
+
+### Update Mode
+
+Amend the named spec **in place**. This mode never runs `create-spec-directory.sh` and never allocates a new index — it edits the existing directory.
+
+1.  Read the named spec's `functional-spec.md`.
+2.  Identify the acceptance criteria (and any parent requirement statements) the change affects. Edit them to match the corrected behavior, holding to the same non-technical, user-facing Language Rules above. Leave untouched criteria as they are.
+3.  Append a dated entry under a `## Change Log` heading (add the heading if the spec predates it): the date, the source reference (e.g. the bug id or the fix description passed in), and what behavior changed and why.
+4.  **Status:** do not force a transition. A spec amended after an already-verified fix stays `Completed` — the Change Log records the amendment. Only move Status back (e.g. to `In Review`) when the user is amending a spec that was not yet verified.
+5.  Save in the same directory under the same index. Report the amended path, which criteria changed, and the new Change Log entry. The amendment is complete — do not run the directory script or the Creation-Mode steps.
+
+If the prompt referenced a spec that does not exist (no matching `functional-spec.md`), do not fabricate one in Update Mode — tell the user, and offer to create it fresh via Creation Mode instead.
+
+---
+
+The steps below are **Creation Mode** — reached when Mode Detection finds no existing spec to amend.
+
 ### Step 1: Determine the Specification Topic
 
 Your first goal is to determine the **topic** - the single, specific feature or capability that this specification will define. To determine the topic, follow these steps:

commands/verify.md

@@ -37,7 +37,7 @@ Verify a specification's implementation against its acceptance criteria. For eac
 - **`/awos:verify` is a look-and-feel + spec-freshness check, not a test runner.** Generated test suites belong in the Feature Testing & Regression slice produced by `/awos:tasks` and executed by `/awos:implement`. This command verifies that the implementation matches the spec's acceptance criteria from a user's perspective and that downstream documentation has not drifted.
 - **Step 3 still requires evidence.** Do not mark an acceptance criterion `[x]` without confirming it — either by driving the UI/API yourself or by getting an explicit user confirmation via `AskUserQuestion`. "The user can verify this manually" without a check is not acceptable.
 - **For non-visual criteria, pick the tool by fit.** APIs, data, CLI, and business-logic criteria can be confirmed with whatever proves them fastest and most reliably — `curl`, shell, log/database inspection, a browser-automation tool, or direct user confirmation. Do not assume any specific tool is available; if none work, fall back to `AskUserQuestion`. The one exception is look-and-feel, covered next.
-- **Look-and-feel means real rendering, with screenshots kept as evidence.** For any acceptance criterion describing something a user sees or does in a UI — a rendered page, a control, a state change, a redirect — in-process or component tests are **not** sufficient: they confirm logic, not look-and-feel. Start the app if it isn't running, drive the actual UI through whatever browser-automation tool the project ships (Playwright MCP/CLI, Cypress, the chrome MCP, etc.), and capture screenshots of the states the criteria describe. Save them to `docs/screenshots/` — the same evidence folder the `testing-expert` agent writes E2E captures to — naming each file so it sorts by spec: `docs/screenshots/<spec-directory>-<short-state>.png` (e.g. `docs/screenshots/011-scheduled-tasks-amber-pill.png`). The browser tool creates the folder on first write; do not edit `.gitignore` — git-ignoring `docs/screenshots/` is a one-time project setup, not part of verification. Reference the saved paths in the report — they are what the human reviews.
+- **Look-and-feel means real rendering, with screenshots kept as evidence.** For any acceptance criterion describing something a user sees or does in a UI — a rendered page, a control, a state change, a redirect — in-process or component tests are **not** sufficient: they confirm logic, not look-and-feel. Start the app if it isn't running, drive the actual UI through whatever browser-automation tool the project ships (Playwright MCP/CLI, Cypress, the chrome MCP, etc.), and capture screenshots of the states the criteria describe. **Running the app is your job, not the user's.** A shared resource the app normally binds — a port already held by a running service, a single database, a device — is not a reason to hand a `run` command to the user: reclaim it (stop the service, use an alternate port, spin a throwaway instance) or drive the project's own deploy/run step yourself, then verify against it. Only after every agent-driven way to render the behavior is genuinely unavailable does manual confirmation apply. Save them to `docs/screenshots/` — the same evidence folder the `testing-expert` agent writes E2E captures to — naming each file so it sorts by spec: `docs/screenshots/<spec-directory>-<short-state>.png` (e.g. `docs/screenshots/011-scheduled-tasks-amber-pill.png`). The browser tool creates the folder on first write; do not edit `.gitignore` — git-ignoring `docs/screenshots/` is a one-time project setup, not part of verification. Reference the saved paths in the report — they are what the human reviews.
 - **Honour the `skip-tests` mode.** If the spec's `tasks.md` carries the `<!-- skip-tests: true -->` marker (set by `/awos:tasks` when the user opted out of test generation), perform Step 3 as a look-and-feel walk-through only — do not run or generate test suites, and treat missing test tooling as expected rather than as a verification failure. Visual criteria are still verified by rendering the UI and capturing screenshots; skip-tests suppresses test suites, not look-and-feel.
 - **Session length does not excuse skipping.** Even in long sessions, Step 3 must run.
 
@@ -65,7 +65,7 @@ For each acceptance criterion in `functional-spec.md`:
    - **Visual / UI criterion** (anything a user sees or does in a browser): start the app if needed (per `technical-considerations.md`), drive the running UI through the project's browser-automation tool, observe the actual rendered behavior, and save a screenshot of the verified state to `docs/screenshots/<spec-directory>-<short-state>.png` (the shared screenshot folder; see CONSTRAINTS). A passing component/test-client test does not satisfy a visual criterion — render it for real.
 2. **If met:** mark it `[x]` and record the evidence — the command output for non-visual criteria, or the screenshot path for visual ones (e.g. "verified via curl /api/health", "see docs/screenshots/011-scheduled-tasks-amber-pill.png").
 3. **If NOT met:** report which criterion failed and what's missing, then stop.
-4. **If no tool can verify the criterion in this environment:** ask the user via `AskUserQuestion` — "I can't verify [criterion] automatically because [reason]. Verify manually and confirm, or stop here?" Options: "I verified manually — mark as done" / "Stop — I'll fix the tooling first". Never mark criteria `[x]` without evidence from one of the paths above.
+4. **If no tool can verify the criterion in this environment:** ask the user via `AskUserQuestion` — "I can't verify [criterion] automatically because [reason]. Verify manually and confirm, or stop here?" Options: "I verified manually — mark as done" / "Stop — I'll fix the tooling first". This is a last resort: it means no agent-driven render path exists (no browser tooling, the app genuinely cannot be started here) — not that the normal run path is temporarily reserved. Starting the app on an alternate port, reclaiming a shared resource, or driving the project's deploy step are all agent-driven paths; try them before deferring. Never hand the user a `run` command to execute for you, and never mark criteria `[x]` without evidence from one of the paths above.
 
 ### Step 4: Mark as Completed
 

plugins/awos/.claude-plugin/plugin.json

@@ -1,10 +1,10 @@
 {
   "name": "awos",
-  "version": "2.1.0",
-  "description": "AWOS code quality audit framework",
+  "version": "2.3.0",
+  "description": "Extends AWOS core with AI-powered delivery automation: audits a project's AI-readiness across quality dimensions (/awos:ai-readiness-audit) and sets up an end-to-end delivery flow — feature and optional bug-fix commands — tailored to the team (/awos:flow).",
   "author": {
     "name": "Provectus"
   },
   "license": "MIT",
-  "keywords": ["audit", "code-quality", "dimensions"]
+  "keywords": ["audit", "code-quality", "dimensions", "delivery-flow", "bug-fix"]
 }

plugins/awos/README.md

@@ -1,4 +1,6 @@
-# AWOS Audit Plugin
+# AWOS Plugin
+
+Two AI-powered capabilities for AWOS projects: an extensible AI-readiness audit (`/awos:ai-readiness-audit`) and a delivery-flow generator (`/awos:flow`). The audit is documented below; the delivery flow has its own section near the end.
 
 Extensible, dimension-based code quality audit for Claude Code. Each dimension runs in its own context window for thorough analysis. Run `/awos:ai-readiness-audit` and get a scored report with actionable recommendations.
 
@@ -86,12 +88,27 @@ context/audits/YYYY-MM-DD/
 
 When a previous audit exists, the report includes score deltas per dimension.
 
+## Delivery Flow
+
+`/awos:flow` interviews the team and investigates the repo, then writes a decision record (`context/product/delivery-flow.md`) and generates one or two project-specific commands in `.claude/commands/`:
+
+- **`/implement-feature <feature>`** — drives one feature end to end through the AWOS chain (`spec → tech → tasks → implement → verify`) and the team's delivery steps (branch, review, change request, merge, deploy, close).
+- **`/fix-bug <bug>`** — generated only when the team opts in. The lighter sibling: its middle is `diagnose → fix → scoped re-verify → targeted spec amendment` instead of the full feature pipeline. It classifies each bug as a _conformance_ fix (code violated a correct spec → fix + regression test) or a _divergence_ (the spec was wrong or behavior intentionally changed → also amend the owning `functional-spec.md` via `/awos:spec` in update mode), so a behavior-changing fix never silently drifts the spec.
+
+Both commands are user-owned and generated outside `.claude/commands/awos/`, so framework updates never touch them; re-running `/awos:flow` reconciles each stage and preserves manual edits. The generated commands are derived from the same flow-agnostic decision record, so they share the team's git flow, review gates, merge policy, and notifications.
+
 ## Plugin Structure
 
 ```
 plugins/awos/
 ├── .claude-plugin/
 │   └── plugin.json              # plugin manifest
+├── commands/
+│   └── flow.md                  # /awos:flow — delivery-flow generator
+├── templates/
+│   ├── delivery-flow-template.md      # decision-record scaffold
+│   ├── implement-feature-template.md  # generated feature command
+│   └── fix-bug-template.md            # generated bug-fix command
 ├── skills/
 │   └── ai-readiness-audit/
 │       ├── SKILL.md             # orchestrator skill