aw-spec-cli 0.1.21 → 0.1.23

package/assets/.appweaver/orchestrator/workflows/aw-spec-ui-prototype.orch.yaml

@@ -0,0 +1,386 @@
+# =============================================================================
+# aw-spec-ui-prototype (orchestrator) — Next.js UI prototype per domain
+#
+# Scaffolds a single shared Next.js prototype app per domain (prototypes/<domain>/),
+# then on every subsequent run adds or regenerates just the active feature's screen/route inside it,
+# driven by that feature's spec.md (+ any active delta-spec.md).
+#
+# Launch:
+#   /appweaver ui-prototype [strategy] [guidance]
+# =============================================================================
+
+name: aw-spec-ui-prototype
+description: Generate or update a single screen/route inside a domain Next.js UI prototype, driven by the active feature's specification (referencing workflow-model.md and ui-model.md if available, or directly from spec.md).
+version: 3.7.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional UI styling or behavior preferences (e.g. dark mode, Tailwind aesthetic, specific mock data).
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+vars:
+  feature: ""
+  feature_dir: ""
+  feature_slug: ""
+  spec_file: ""
+  spec_exists: "false"
+  context: ""
+  context_dir: ""
+  domain_model: ""
+  domain_model_exists: "false"
+  active_change: ""
+  has_change: "false"
+  domain: ""
+  prototype_root: "prototype"
+  project_exists: "false"
+
+workflow:
+
+  # 1. Resolve active feature and its spec directly from .appweaver/feature.json
+  #    which points to the bounded context directory and then the feature (specs/<BoundedContext>/<Feature>/)
+  - id: feature_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: feature-paths
+    outputs:
+      - { name: feature,        from: "$.feature" }
+      - { name: feature_slug,   from: "$.feature_slug" }   # kebab-case route segment
+      - { name: feature_dir,    from: "$.feature_dir" }
+      - { name: spec_file,      from: "$.spec_file" }
+      - { name: spec_exists,    from: "$.spec_exists" }
+
+  - id: require_feature
+    action: verify_context
+    require_non_empty: feature_dir
+    on_empty: stop
+    on_empty_message: "No active feature. Run /appweaver select-feature first, then re-run ui-prototype."
+
+  - id: require_spec
+    action: verify_context
+    require_true: spec_exists
+    on_false: stop
+    on_false_message: "No specification found for this feature at {{spec_file}}. Run /appweaver specify first to create spec.md."
+
+  # 2. Resolve the bounded context containing this feature and its canonical domain model
+  - id: context_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: context-paths
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: context,             from: "$.context" }
+      - { name: context_dir,         from: "$.context_dir" }
+      - { name: domain_model,        from: "$.domain_model" }
+      - { name: domain_model_exists, from: "$.domain_model_exists" }
+
+  # 3. Resolve active domain
+  - id: resolve_domain
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: resolve-domain
+    args: ["--command", "/aw-spec-ui-prototype"]
+    outputs:
+      - { name: domain, from: "$.domain" }
+
+  # 4. Resolve prototype root from stacks declaration (.appweaver/stacks.json)
+  - id: resolve_prototype_lane
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: prototype_root, from: "$.prototype.root" }
+
+  # 5. Check for active change requests (feature-level)
+  - id: version_read
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: version-read
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: active_change, from: "$.active_change" }
+      - { name: has_change,    from: "$.has_change" }
+
+  # 6. Check whether the domain prototype project already exists at prototype_root
+  - id: check_project
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: path-exists
+    args: ["--path", "{{prototype_root}}/package.json"]
+    outputs:
+      - { name: project_exists, from: "$.exists" }
+
+  # 7. Assemble specification, bounded context domain model, optional UI artifacts, and rules context
+  - id: ctx_prototype
+    action: build_context
+    vars:
+      feature_name: "{{feature}}"
+      feature_slug: "{{feature_slug}}"
+      feature_dir: "{{feature_dir}}"
+      context_name: "{{context}}"
+      context_dir: "{{context_dir}}"
+      domain: "{{domain}}"
+      prototype_root: "{{prototype_root}}"
+      project_exists: "{{project_exists}}"
+      user_preferences: "{{USER_INPUT}}"
+    context:
+      - "{{spec_file}}"
+      - { path: "{{domain_model}}", optional: true }
+      - { path: "{{feature_dir}}/ui/workflow-model.md", optional: true }
+      - { path: "{{feature_dir}}/ui/ui-model.md", optional: true }
+      - { path: ".appweaver/memory/constitution.domain.md", optional: true }
+      - { path: ".appweaver/memory/constitution.ui.md", optional: true }
+      - { path: "{{feature_dir}}/changes/{{active_change}}/delta-spec.md", optional: true }
+      - { path: "{{prototype_root}}/screens.json", optional: true }
+
+  # 5a. First run only: scaffold the domain Next.js prototype shell if missing
+  - id: scaffold_project
+    action: agent_generate
+    condition: "{{project_exists}} == false"
+    tools: "Read,Write,Edit,Bash"
+    permission_mode: acceptEdits
+    task: |
+      There is no prototype project for domain `{{domain}}` yet. Scaffold ONE reusable Next.js application
+      shell for domain `{{domain}}` at `{{prototype_root}}/`. This project will be reused and extended by every
+      subsequent feature run for `{{domain}}` — do not build any single feature's screen content here.
+
+      Build only the shared shell:
+      1. `package.json`, Next.js App Router baseline (`app/layout.tsx`), global styles/design
+         tokens, and client-side state/provider pattern screens will share
+         (e.g. a lightweight context for active persona/role).
+      2. A shared nav/shell component (sidebar or top nav) that lists available screens by
+         reading dynamically from `lib/screens-registry.ts`. It renders each entry's
+         `title` field verbatim as the visible label — later screen runs are responsible for
+         putting a natural, product-appropriate name there (see the per-screen task), not
+         a raw spec title.
+      3. A shared persona/role-switcher component — its initial role and persona options
+         are populated directly from the actors/personas specified in `spec.md` (under `Actors` /
+         `Experience Scope` / `User Stories`) and `ui-model.md`, and registered in `lib/screens-registry.ts`.
+      4. `lib/screens-registry.ts` — an empty typed registry (array of
+         `{ slug, title, route, specVersion, roles }`) plus a `screens.json` mirror for
+         non-JS tooling. This file is APPENDED TO by screen runs.
+      5. A clean, production-feeling home page (`app/page.tsx`) for the domain application —
+         shared nav and an overview relevant to the domain — using the domain's real product
+         name (derive one from `{{domain}}`/spec/constitution, e.g. "Acme" not "Acme Prototype").
+         This home page is the app's actual dashboard/landing experience — the entry point a
+         real user of this product would land on — not a menu of "screens" or a list mirroring
+         spec structure.
+
+      Do not create the route for `{{feature_name}}` yet — that happens in the next step.
+      Ensure `npm install && npm run dev` works with just this shell.
+
+      **This must read as one coherent real application, never as a list of specs:**
+      - Never render the words "prototype", "mock", "demo", "scaffold", "shell", "sample",
+        or similar anywhere a user can see them — not in the page title, `<title>`/metadata,
+        headers, nav labels, empty states, placeholder copy, button text, or console-visible
+        UI. Those words are fine in code comments, filenames, or `PROTOTYPE_NOTES.md`, but
+        never in rendered UI.
+      - Never render raw spec/traceability identifiers anywhere in the UI — no `REQ-###`,
+        `SPEC-SCREEN-###`, `SPEC-COMP-###`, `MOCKDATA-###`, `FEEDBACK-###`, `CHANGE-###`, or
+        literal spec section titles/filenames. Those are internal authoring artifacts, not
+        product language a real user would ever see.
+      - The home page, nav, and browser tab title should use the actual product/domain name
+        as if this were the shipping application, not a label describing what this project is.
+      - The persona/role switcher must be styled and framed as a normal in-app affordance
+        (e.g. an account/role menu a real user of this kind of app would plausibly have),
+        not as an obvious dev/testing control bolted onto the UI.
+
+      **Styling must actually render — this is not optional:**
+      - Install and fully configure **Tailwind CSS** (latest stable version, matching whatever
+        the installed Next.js version's official setup docs specify — App Router's Tailwind
+        setup has changed across versions, e.g. `tailwind.config.ts`/PostCSS config differs
+        between Tailwind v3 and v4). Do not stop at `npm install tailwindcss` — verify the
+        PostCSS config, content globs, and `@tailwind base/components/utilities` (or v4's
+        `@import "tailwindcss"`) directives are all present and correct for the version installed.
+      - Create `app/globals.css` with the Tailwind directives plus any design-token CSS
+        variables (colors, spacing, radii, fonts), and **explicitly `import "./globals.css"`
+        at the top of `app/layout.tsx`.** A missing import here is the most common cause of
+        a fully unstyled app — verify it's present before finishing.
+      - After scaffolding, actually run `npm run dev` (or `next build`) and confirm no
+        Tailwind/PostCSS errors appear in the output before ending this step. Don't just
+        assume the config is correct because the files exist.
+      - If `constitution.ui.md` or USER_INPUT specifies a different styling approach
+        (CSS Modules, a specific component library with its own styling, styled-components,
+        etc.), follow that instead of Tailwind — but whichever system is chosen, the same
+        rule applies: install it fully, wire it into the root layout, and verify it actually
+        renders styled output, not just that the packages are present in `package.json`.
+
+      **Always use the latest versions and current best practices:**
+      - Scaffold against the latest stable Next.js (App Router) and React releases available
+        at the time of this run — do not pin to or reproduce an older remembered baseline.
+        Resolve versions with `npm view <package> version` (or `npm install <package>@latest`)
+        rather than assuming a version from memory.
+      - Use current, non-deprecated APIs and patterns for whatever is scaffolded (routing,
+        data fetching, styling setup). If a pattern you'd default to has since been superseded
+        (e.g. an older config format, a deprecated hook/API), use the current replacement.
+      - If a UI/component library or design-token approach is implied by
+        `constitution.ui.md`, USER_INPUT, or the spec, install its latest published version
+        and use its current component APIs — check the library's current docs/changelog
+        rather than relying on a possibly-stale remembered API surface.
+      - Note the resolved major versions of Next.js/React and any UI library in a short
+        comment at the top of `package.json` or in a `PROTOTYPE_NOTES.md`, so later screen
+        runs and reviewers know what "latest" resolved to at scaffold time.
+
+  # 5b. Every run: generate/update this feature's screen inside the existing domain prototype
+  - id: generate_screen
+    action: agent_generate
+    tools: "Read,Write,Edit,Bash"
+    permission_mode: acceptEdits
+    task: |
+      You are adding or regenerating ONE screen inside the existing Next.js prototype for domain `{{domain}}`
+      at `{{prototype_root}}/`. Do NOT touch project scaffolding, `package.json`, shared layout,
+      or other features' routes/components except where explicitly instructed below.
+
+      The feature specification is taken directly from the bounded context directory and feature path defined in `.appweaver/feature.json`:
+      `{{spec_file}}` (Bounded Context: `{{context_name}}`, Feature: `{{feature_name}}`).
+      Read this specification strictly from `{{spec_file}}`, along with the bounded context's canonical domain model (`{{domain_model}}`),
+      and when available, the Workflow Model (`{{feature_dir}}/ui/workflow-model.md`) and UI Model (`{{feature_dir}}/ui/ui-model.md`), plus `{{prototype_root}}/lib/screens-registry.ts` / `screens.json`.
+      If `workflow-model.md` and `ui-model.md` are not provided, derive all UI surfaces, workflows, and interaction states directly from `{{spec_file}}`.
+
+      **SPEC-DRIVEN PROTOTYPE GENERATION (STAGE 4 EXECUTION)**:
+      Your goal is to build the executable Next.js application surfaces defined in the spec and UI/workflow models (when available):
+      - Implement ALL UI surfaces (Primary Page `/{{feature_slug}}`, sub-routes, modal dialogs, drawers, forms, data grids/cards).
+      - Realize all user workflows (`WF-1`, `WF-2`, `WF-3`...) with realistic interactive behavior, persona role-switching, and surface navigation transitions.
+      - Handle all specified UI states (`Loading`, `Empty`, `Populated`, `Filtered / Searched`, `Validation Error`, `Submitting`, `Success`, `Error`).
+
+      1. **Multi-Surface & Route Implementation**:
+         - Create or fully regenerate `{{prototype_root}}/app/{{feature_slug}}/page.tsx`
+           (and any screen-scoped components under
+           `{{prototype_root}}/app/{{feature_slug}}/components/`).
+         - Treat this route as regenerated wholesale each run — don't hand-patch it.
+         - Build the full, finished screen the spec describes — not a wireframe, stub,
+           "coming soon," or reduced placeholder version. A user landing on this route should
+           see the actual working application screen, fully styled and populated, matching
+           spec.md as if it shipped this way.
+         - Never surface "prototype/mock/demo/sample" language, or raw spec/traceability IDs
+           (`REQ-###`, `SPEC-SCREEN-###`, etc.) anywhere in this screen's rendered UI (titles,
+           headers, empty states, tooltips, button copy). Keep all such labeling out of
+           user-visible text entirely.
+
+      2. **Integrate this screen into the app like a real feature, not a spec entry**:
+         - `{{feature_name}}` and any spec title/ID are internal identifiers for you to read —
+           never repeat them verbatim as the nav label, page heading, or route's display name.
+           Derive a natural, user-facing name the way a real product would phrase it (e.g. a
+           spec called "Project Creation Screen" surfaces as a "Projects" nav entry whose
+           content includes creating a project — not a nav item literally labeled
+           "Project Creation Screen").
+         - Decide where this screen naturally belongs in the app's information architecture
+           based on what the spec describes, the same way a product designer would: a
+           top-level nav item, a sub-page reached by an action on another already-generated
+           screen (e.g. a "New Project" button on the dashboard or on a "Projects" list),
+           or an entry point added to the shared dashboard — whichever fits how a real user
+           would discover and reach this functionality. Don't default to "flat nav item per
+           spec" if the spec's own content implies a more natural entry point (e.g. reached
+           via a button/action from another screen rather than the top-level nav).
+         - If the natural entry point is from another already-generated screen or the
+           dashboard, update that screen/dashboard minimally to add the real link/button/card
+           that leads here — don't leave this screen orphaned and reachable only by URL.
+
+      3. **Specification-driven behavior**:
+         - Derive all behavior exclusively from the active specification for this feature.
+         - Implement all functional requirements, business rules, invariants, validations,
+           constraints, state transitions, and workflows explicitly defined in spec.md.
+         - Do not invent business rules absent from the spec. Use reasonable UI defaults only
+           for presentation/interaction mechanics.
+
+      4. **Roles, personas, and permission rules from spec**:
+         - Derive all roles/personas directly from `spec.md` (under `Actors` / `Experience Scope` / `User Stories`) and `ui-model.md`.
+         - Ensure every role defined in the specification exists in the SHARED persona/role-switcher context.
+         - Wire the UI controls dynamically so switching persona demonstrates role-based visibility, disabled inputs, and permission workflows (e.g. PM vs PMO vs Delivery Head) strictly as specified.
+
+      5. **Mock data**:
+         - Place this feature's mock data under
+           `{{prototype_root}}/lib/mock-data/{{feature_slug}}.ts`, isolated from other screens.
+         - Data values should read as realistic, plausible content for this domain (real-sounding
+           names, dates, amounts, statuses) — not "Lorem ipsum," "Test User 1," "Sample Item,"
+           or other obviously-fake placeholder text. The screen should look fully populated and
+           real, even though the data behind it is static.
+
+      6. **Reuse, don't duplicate**:
+         - Reuse existing shared components (nav shell, buttons, layout primitives, design
+           tokens) from the shell in the project.
+
+      7. **Styling must render on this screen too**:
+         - Before writing this screen, confirm the shell's styling setup is actually wired
+           up — `app/globals.css` exists and is imported in `app/layout.tsx`, and the
+           Tailwind/CSS config from the shell is intact. If it's missing or broken, fix it
+           as part of this run and note that in your final summary; don't build a styled-looking
+           screen on top of a broken/absent styling pipeline.
+         - Use the shell's existing design tokens and Tailwind utility classes (or whatever
+           styling system the shell uses) rather than inline style objects or
+           ad-hoc CSS that bypasses the shared system — inline styles that "look fine" in
+           isolation are usually the sign the shared pipeline isn't actually being used.
+         - If this screen needs a component from a UI library not yet installed in the shell
+           (e.g. a data table, date picker), install it into the shell's `package.json` (latest
+           version, per below) and ensure its required CSS/theme setup is added to
+           `app/globals.css` or its own import — a component library added without its styles
+           wired in is another common source of unstyled output.
+
+      8. **Always use the latest UI, components, and libraries**:
+         - Any new dependency added for this screen (UI library, icon set, chart/table/form
+           component, date picker, etc.) must be the latest stable published version —
+           resolve it with `npm view <package> version` or install via `@latest` rather than
+           writing a version from memory.
+         - When reusing shared components from the shell, check whether the shell's installed
+           versions are current; if `{{prototype_root}}/PROTOTYPE_NOTES.md` or `package.json`
+           indicates they're stale relative to what's now available, flag it in your final
+           summary rather than silently building on outdated components — don't upgrade
+           shared/shell dependencies yourself from a screen run.
+         - Prefer each library's current, non-deprecated component API and patterns
+           (e.g. current shadcn/ui component structure, current Next.js Image/Link/Font APIs)
+           over older remembered forms of the same API.
+         - Do not introduce a second library that duplicates something the shell or an
+           earlier screen already standardized on — "latest" applies to versions, not to
+           swapping in a different library each run.
+
+      9. **Registry update**:
+         - Add or update this feature's entry in `lib/screens-registry.ts` and `screens.json`:
+           `{ slug: "{{feature_slug}}", title: "<natural product-facing name from step 2, NOT
+           the raw spec title>", route: "/{{feature_slug}}", specVersion: <from spec.md if
+           present>, roles: [...] }`.
+         - `title` here drives the visible nav label — it must be the naturalized name from
+           step 2, never `{{feature_name}}` or a spec ID verbatim. If you need to retain the
+           original spec title/ID for traceability, add it as a separate non-rendered field
+           (e.g. `specRef`) rather than reusing `title` for it.
+
+      User Preferences / Guidance:
+      {{user_preferences}}
+
+      End your final reply with a summary of what was added/changed and a ```json code block:
+      ```json
+      {
+        "status": "ok",
+        "domain": "{{domain}}",
+        "feature": "{{feature_name}}",
+        "slug": "{{feature_slug}}",
+        "route": "/{{feature_slug}}",
+        "prototype_root": "{{prototype_root}}",
+        "launch_command": "cd {{prototype_root}} && npm run dev"
+      }
+      ```
+    outputs:
+      - { name: result, from: "$" }
+
+outputs:
+  domain: "{{domain}}"
+  context: "{{context}}"
+  context_dir: "{{context_dir}}"
+  feature: "{{feature}}"
+  spec_file: "{{spec_file}}"
+  route: "/{{feature_slug}}"
+  prototype_root: "{{prototype_root}}"
+  launch_hint: "First time: cd {{prototype_root}} && npm install && npm run dev — after that, just rerun ui-prototype per feature and refresh the browser."
+  next: "Visit http://localhost:3000/{{feature_slug}} to review this screen, or / for the full screen list."

package/assets/.appweaver/orchestrator/workflows/aw-spec-workflow-model.orch.yaml

@@ -0,0 +1,153 @@
+# =============================================================================
+# aw-spec-workflow-model (orchestrator) — Derive Workflow Model from Feature Spec
+#
+# Stage 2 of the 4-Stage Spec-Driven UI Generation Pipeline.
+# Consumes active feature's spec.md (+ active delta-spec.md) and derives user-oriented
+# workflows (Actors, Goals, Primary Steps, Decisions, Alt Paths, Validation Failures, State Transitions).
+# Writes output artifact to `specs/<Feature>/ui/workflow-model.md`.
+#
+# Launch:
+#   /appweaver workflow-model [strategy] [guidance]
+# =============================================================================
+
+name: aw-spec-workflow-model
+description: Derive the Workflow Model (specs/<Feature>/ui/workflow-model.md) from the active feature's spec.md, describing user goals, interaction steps, decision branches, validation rules, and state transitions.
+version: 1.0.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional guidance or specific workflow emphasis.
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+vars:
+  feature: ""
+  feature_dir: ""
+  feature_slug: ""
+  spec_file: ""
+  spec_exists: "false"
+  active_change: ""
+  has_change: "false"
+  domain: ""
+  prototype_root: ""
+
+workflow:
+
+  # 1. Resolve active feature and paths
+  - id: feature_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: feature-paths
+    outputs:
+      - { name: feature,        from: "$.feature" }
+      - { name: feature_dir,    from: "$.feature_dir" }
+      - { name: feature_slug,   from: "$.feature_slug" }   # kebab-case route segment
+      - { name: spec_file,      from: "$.spec_file" }
+      - { name: spec_exists,    from: "$.spec_exists" }
+
+  # domain and prototype_root have their OWN resolvers — feature-paths answers for the
+  # feature's documents and nothing else, so binding them here left both empty and the
+  # emptiness reached the prompts as a blank path segment rather than an error.
+  - id: resolve_domain
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: resolve-domain
+    args: ["--command", "/aw-spec-workflow-model"]
+    outputs:
+      - { name: domain, from: "$.domain" }
+
+  - id: resolve_prototype_lane
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: prototype_root, from: "$.prototype.root" }
+
+  - id: require_feature
+    action: verify_context
+    require_non_empty: feature_dir
+    on_empty: stop
+    on_empty_message: "No active feature selected. Run /appweaver select-feature first."
+
+  - id: require_spec
+    action: verify_context
+    require_true: spec_exists
+    on_false: stop
+    on_false_message: "No specification found for this feature. Run /appweaver specify first."
+
+  # 2. Check active change requests
+  - id: version_read
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: version-read
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: active_change, from: "$.active_change" }
+      - { name: has_change,    from: "$.has_change" }
+
+  # 3. Assemble specification & template context
+  - id: ctx_workflow
+    action: build_context
+    vars:
+      feature_name: "{{feature}}"
+      feature_dir: "{{feature_dir}}"
+      user_preferences: "{{USER_INPUT}}"
+    context:
+      - "{{spec_file}}"
+      - { path: "{{feature_dir}}/changes/{{active_change}}/delta-spec.md", optional: true }
+      - { path: ".appweaver/templates/workflow-model-template.md", optional: true }
+      - { path: ".appweaver/memory/constitution.ui.md", optional: true }
+
+  # 4. Generate Workflow Model Artifact (specs/<Feature>/ui/workflow-model.md)
+  - id: generate_workflow_model
+    action: agent_generate
+    tools: "Read,Write,Edit,Bash"
+    permission_mode: acceptEdits
+    task: |
+      You are authoring Stage 2 (Workflow Model) of the 4-Stage Spec-Driven UI Pipeline for feature `{{feature_name}}`.
+
+      Target Artifact Path: `{{feature_dir}}/ui/workflow-model.md`
+
+      Instructions:
+      1. Read the feature specification (`spec.md` + active `delta-spec.md`) in context.
+      2. Identify ALL discrete user workflows required to fulfill the feature's capabilities, functional requirements (FRs), business rules (BRs), and user personas.
+      3. For EACH user workflow (WF-1, WF-2, ...), detail:
+         - **Actor / Persona**: Which role executes this flow (e.g. Project Manager, Delivery Head).
+         - **Goal**: Clear statement of user goal.
+         - **Preconditions**: Initial system state, permissions, or prerequisite conditions.
+         - **Primary Flow**: Step-by-step numbered interaction steps from start to completion.
+         - **Decision Points & Alternative Paths**: Clear branch logic (e.g. If user cancels, If user requests correction).
+         - **Validation Failures & Error Handling**: Inline system reaction when business rules or validations fail.
+         - **State Transitions**: `[Initial State]` → `[Resulting State]`.
+      4. Format the output according to `.appweaver/templates/workflow-model-template.md`.
+      5. Create the directory `{{feature_dir}}/ui/` if it does not exist, and write the authored markdown content to `{{feature_dir}}/ui/workflow-model.md`.
+
+      User Guidance:
+      {{user_preferences}}
+
+      End your final reply with a summary and a ```json fence:
+      ```json
+      {
+        "status": "ok",
+        "feature": "{{feature_name}}",
+        "workflow_model_path": "{{feature_dir}}/ui/workflow-model.md"
+      }
+      ```
+    outputs:
+      - { name: result, from: "$" }
+
+outputs:
+  feature: "{{feature}}"
+  workflow_model_path: "{{feature_dir}}/ui/workflow-model.md"
+  next: "Run /appweaver ui-model to derive the UI Model surfaces and interaction structure."