aw-spec-cli 0.1.8 → 0.1.9

package/assets/.appweaver/orchestrator/workflows/aw-spec-select-feature.orch.yaml

@@ -0,0 +1,128 @@
+# =============================================================================
+# aw-spec-select-feature (orchestrator) — pick or create the active FEATURE
+#
+# feature = AGGREGATE (e.g. Order). This is the FIRST step of the spec-anchored
+# pipeline: it fixes the aggregate boundary BEFORE any spec/design exists, so the
+# feature's single spec.md + design.md and every command (CreateOrder/UpdateOrder =
+# user stories) hang off one directory. It replaces guessing the aggregate out of prose in
+# `specify` — that is why finding #1 (feature=aggregate) is enforced here, not hoped for.
+#
+# The pickable list is TWO merged sources (deduped by name): specs/ sub-folders
+# (features already scaffolded/adopted) AND the OKF bundle's Aggregate concepts —
+# the brownfield feature map `/appweaver onboard` reverse-engineers. So in a
+# brownfield repo you pick a real discovered code feature BEFORE anything is under
+# specs/; on greenfield (no bundle) the list is specs-only, exactly as before.
+#
+# ZERO LLM: only scripts + one select + (conditionally) one ask. No generation,
+# no standards, no domain-select. Pure, deterministic orchestration/governance.
+#
+#   list-features (specs/ ∪ OKF aggregates) → user_select (existing | "+ create new") → [ask name] → set-feature
+#
+# Persists .appweaver/feature.json {"feature_directory":"specs/<Feature>"} so every
+# later command operates on it: the forward loop (specify/design/analyze-design/implement/
+# build/analyze-slice/run/deploy) and the CR loop (analyze-delta-design/implement-delta/
+# finalize-delta/close-delta — the standalone `cr` is retired; specify and design author
+# the delta docs themselves).
+#
+# Launch:
+#   /appweaver select-feature                 # interactive: list + add-new
+#   /appweaver select-feature Order           # direct: create-or-select Order
+# =============================================================================
+
+name: aw-spec-select-feature
+description: Pick an existing feature (aggregate) or create a new one, and store it in .appweaver/feature.json so every AW-Spec command operates on it. Zero LLM — scripts + one selection only.
+version: 1.0.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional feature (aggregate) name to create or select directly, e.g. Order.
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+vars:
+  new_sentinel: "+ Create a new feature"   # source of truth is list-features $.sentinel; overwritten below
+  typed_name: ""
+  target_name: ""
+  bundle_dir: "knowledge"                   # where /appweaver onboard writes the OKF feature map (repo-root default)
+
+workflow:
+
+  # 1. Enumerate selectable aggregates from TWO merged sources (deduped by name):
+  #    specs/ sub-folders (already scaffolded/adopted) AND the OKF bundle's
+  #    Aggregate concepts — the brownfield feature map onboard reverse-engineers,
+  #    so a not-yet-adopted code feature is pickable before its specs/ dir exists.
+  #    On greenfield (no bundle) the OKF source is empty → specs-only, as before.
+  #    `select_options` carries the "+ create new" sentinel and (when USER_INPUT
+  #    names a not-yet feature) that name injected — a direct arg is one-list select.
+  - id: list_features
+    action: execute_script
+    script: { ref: actions }
+    subcommand: list-features
+    args: ["--preselect", "{{USER_INPUT}}", "--bundle", "{{bundle_dir}}"]
+    outputs:
+      - { name: features,       from: "$.features" }
+      - { name: feature_names,  from: "$.names" }
+      - { name: feature_count,  from: "$.count" }
+      - { name: select_options, from: "$.select_options" }
+      - { name: new_sentinel,   from: "$.sentinel" }
+
+  # 2. Choose. A matching USER_INPUT auto-selects (existing OR injected-new) with
+  #    no prompt; the lone sentinel at bootstrap (no features yet) auto-confirms.
+  - id: pick
+    action: user_select
+    prompt: "Select a feature (the aggregate, e.g. Order) — or create a new one:"
+    options_from_variable: select_options
+    preselect_from: USER_INPUT
+    single_option_confirm: true
+    outputs:
+      - { name: chosen, from: selection }
+
+  # 3. Only when the user chose "+ create new" (or bootstrapped) do we ask a name.
+  - id: ask_new_name
+    action: ask
+    condition: "{{chosen}} == {{new_sentinel}}"
+    prompt: >
+      Name the new feature — this is the AGGREGATE root (e.g. Order, Invoice,
+      Customer), NOT a single command. Operations like CreateOrder / UpdateOrder
+      become user stories inside it:
+    answer_var: typed_name
+
+  # 4. Coalesce the target name. The engine has no compound conditions, so this
+  #    is two ordered sets: default to the pick, then override with the typed
+  #    name only on the "create new" branch.
+  - id: name_from_pick
+    action: set
+    vars: { target_name: "{{chosen}}" }
+  - id: name_from_new
+    action: set
+    condition: "{{chosen}} == {{new_sentinel}}"
+    vars: { target_name: "{{typed_name}}" }
+
+  # 5. Create-or-select the aggregate dir + persist it as the active feature.
+  - id: set_feature
+    action: execute_script
+    script: { ref: actions }
+    subcommand: set-feature
+    args: ["--feature", "{{target_name}}"]
+    outputs:
+      - { name: feature,     from: "$.feature" }
+      - { name: feature_dir, from: "$.feature_dir" }
+      - { name: spec_file,   from: "$.spec_file" }
+      - { name: existed,     from: "$.existed" }
+      - { name: created,     from: "$.created" }
+      - { name: spec_exists, from: "$.spec_exists" }
+
+outputs:
+  feature: "{{feature}}"
+  feature_dir: "{{feature_dir}}"
+  created: "{{created}}"
+  spec_exists: "{{spec_exists}}"
+  note: "Active feature set in .appweaver/feature.json — the aggregate boundary for its single spec.md + design.md."
+  next: "/appweaver specify <what this feature does>   (authors {{feature_dir}}/spec.md; each operation = a user story)"

package/assets/.appweaver/orchestrator/workflows/aw-spec-select-stack.orch.yaml

@@ -0,0 +1,296 @@
+# =============================================================================
+# aw-spec-select-stack (orchestrator) — declare the project's LANES
+#
+# THE FIRST COMMAND OF EVERY SEQUENCE. Greenfield runs it before constitution;
+# brownfield runs it before onboard. What it writes decides which constitution
+# halves are authored, which rule sets are generated, which subtree each phase may
+# write into, and — in brownfield — which subtree onboard reverse-engineers. It
+# answers one question per lane, twice:
+#
+#     what is this lane's STACK, and where is its SOURCE?
+#
+# Four steps per lane and none of them guess: the menu opens on the stack this
+# repo's own files point at, the source-path question leads with the directory that
+# evidence sits in, and both are only ever proposals — an operator selects from the
+# list or types a path the kit has never seen.
+#
+#   stack-list --suggest backend  → select stack → ask source path → lane-declare
+#   stack-list --suggest frontend → select stack → ask source path → lane-declare
+#
+# (none) IS A REAL ANSWER FOR EITHER LANE, and it is how a project says "I do not
+# have one of these". A backend-only project answers (none) to the UI lane; a
+# UI-only project answers (none) to the service lane. Declining a lane here is what
+# stops `constitution` authoring that lane's half and stops `onboard` generating
+# that lane's rule files — a lane nobody declared is a lane nobody governs.
+#
+# THE POINT OF THIS WORKFLOW is that it is the ONLY writer of .appweaver/stacks.json.
+# `lane-declare` appears in exactly two workflows — this one, where a person picks,
+# and `onboard`, which declares what it reverse-engineered and never overwrites a
+# lane a person already declared. Every other workflow calls `lane-resolve` to read
+# and `lane-verify` to gate, and neither can write.
+#
+# WHY THE SOURCE PATH IS ASKED AND NOT INHERITED. A lane's root is the subtree it
+# OWNS: the only place its implement phase may write, the directory its build and
+# run commands act on, and in brownfield the code onboard reads. A profile's default
+# root describes how a NEW project of that stack is usually laid out, which is a
+# reasonable proposal and a poor assumption — a repo that already exists did not
+# choose its layout from our profiles. So the default is offered, the detected
+# directory is offered ahead of it, and the answer is the operator's.
+#
+# THE PATH IS NOT REQUIRED TO EXIST HERE. Greenfield declares `src/` on day one and
+# `implement` creates it; requiring the directory would make the command unusable
+# for the projects it matters most to. `lane-verify` runs the on-disk check, in the
+# phases that actually read the subtree — implement, build, run, onboard.
+#
+# ZERO LLM: scripts, two gates, two selects and two questions. No generation, no
+# rule resolution.
+#
+# Run (interactive via launcher):
+#   /appweaver select-stack                              # ask everything
+#   /appweaver select-stack dotnet-webapi react-vite     # answer both stacks
+#   /appweaver select-stack none                         # UI lane: none
+# Headless:
+#   --select select_api_stack=<label> --select select_ui_stack=<label>
+#   --answer ask_api_source_path=<path> --answer ask_ui_source_path=<path>
+# =============================================================================
+
+name: aw-spec-select-stack
+description: Declare the project's lanes — each lane's STACK and its SOURCE PATH — and persist them to .appweaver/stacks.json, the single channel every later workflow resolves and gates on. The first command of both the greenfield and the brownfield sequence, and the sole writer of the lane model.
+version: 2.0.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: >
+      Optional stack ids to answer the selections directly, e.g.
+      "dotnet-webapi react-vite". Each id is matched only against its own kind,
+      so one argument can answer both selections, either, or neither. Use "none"
+      to decline a lane.
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+workflow:
+
+  # ═══════════════ SERVICE LANE ═══════════════════════════════════════════════
+
+  # 1. Candidates = the installed backend profiles, plus (none), and — because of
+  #    --suggest — this repo's own answer. Detection and listing are ONE call: both
+  #    questions below need the same file walk, and doing it twice would double the
+  #    only real cost this workflow has. A detected stack LEADS the menu; only an
+  #    explicit argument fills `preselect`, so a scan can never overrule a person.
+  - id: list_api_stacks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: stack-list
+    args: ["--kind", "backend", "--suggest", "--include-none", "--preselect", "{{USER_INPUT}}"]
+    outputs:
+      - { name: api_options,       from: "$.select_options" }
+      - { name: api_ids,           from: "$.ids" }
+      - { name: api_preselect,     from: "$.preselect" }
+      - { name: api_root_options,  from: "$.root_options" }
+      - { name: api_detected,      from: "$.detected_profile" }
+      - { name: api_detected_root, from: "$.detected_root" }
+      - { name: api_none_sentinel, from: "$.none_sentinel" }
+
+  # 2. No profiles installed is a setup error, not an empty menu. Gated on the
+  #    PROFILE ids rather than on the options, because (none) is always an option
+  #    and would make an empty menu look populated.
+  - id: guard_no_api_stacks
+    action: verify_context
+    require_non_empty: api_ids
+    on_empty_message: >
+      No backend stack profiles found under .appweaver/stack-profiles/. Add one
+      (the format is in .appweaver/STACK-PROFILES.md — a project ships its own
+      stacks there), then re-run.
+    on_empty: stop
+
+  # 3. Choose the service stack. A matching id in USER_INPUT auto-selects, and so
+  #    does a detected stack; a project with exactly one candidate auto-confirms.
+  - id: select_api_stack
+    action: user_select
+    prompt: "Select the API (backend) stack — it owns the service lane. This repo's own files point at: {{api_detected}} (leading the list). (none) declares a project with no service lane at all, and stops the technical constitution half and the service rule files being authored:"
+    options_from_variable: api_options
+    preselect_from: api_preselect
+    single_option_confirm: true
+    outputs:
+      - { name: chosen_api, from: selection }
+
+  # 4. Did the operator decline the lane? Compared against the sentinel the lister
+  #    itself returned, so the two never drift apart on a wording change. Stated as
+  #    a positive flag: every step below that only makes sense for a real lane
+  #    conditions on it, and the engine's truthiness test is the whole expression.
+  - id: api_lane_selected
+    action: set
+    vars: { api_selected: "true", api_source_path: "" }
+  - id: api_lane_declined
+    action: set
+    condition: "{{chosen_api}} == {{api_none_sentinel}}"
+    vars: { api_selected: "" }
+
+  # 5. WHERE the service lane's source lives. Offered best-first — where the
+  #    evidence actually sits, then each profile's own default — and free text is
+  #    accepted, because a repo that matches no profile still has a source path.
+  #    The label after the path says why it is offered and is stripped on the way in.
+  - id: ask_api_source_path
+    action: ask
+    condition: "{{api_selected}}"
+    prompt: "Service lane SOURCE PATH — the subtree this lane owns, the only place implement may write, and the directory build/test/run act on. Pick one or type your own:"
+    options_from_variable: api_root_options
+    answer_var: api_source_path
+
+  # 6. Persist it. Root and build/test/run default from the profile; the commands
+  #    are project-supplied strings, so the engine stays stdlib-only and
+  #    stack-ignorant — it shells out and never knows what a compiler is. (none)
+  #    routes through the SAME writer, which is what makes a re-run correct: a lane
+  #    declared in an earlier run is REMOVED here rather than left stranded.
+  - id: declare_api_lane
+    action: execute_script
+    script: { ref: actions }
+    subcommand: lane-declare
+    args: ["--profile", "{{chosen_api}}", "--kind", "backend", "--source-path", "{{api_source_path}}"]
+    outputs:
+      - { name: api_declared,    from: "$.declared" }
+      - { name: api_lane_id,     from: "$.lane_id" }
+      - { name: api_profile,     from: "$.profile" }
+      - { name: api_root,        from: "$.source_path" }
+      - { name: api_root_exists, from: "$.root_exists" }
+
+  # ═══════════════ UI LANE ════════════════════════════════════════════════════
+
+  # 7. Candidates for the UI lane, same shape. The service lane is already declared
+  #    at this point, so a UI stack that would relocate onto it is refused by the
+  #    writer's roots-disjoint check rather than discovered later as two generators
+  #    writing one file.
+  - id: list_ui_stacks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: stack-list
+    args: ["--kind", "frontend", "--suggest", "--include-none", "--preselect", "{{USER_INPUT}}"]
+    outputs:
+      - { name: ui_options,       from: "$.select_options" }
+      - { name: ui_ids,           from: "$.ids" }
+      - { name: ui_preselect,     from: "$.preselect" }
+      - { name: ui_root_options,  from: "$.root_options" }
+      - { name: ui_detected,      from: "$.detected_profile" }
+      - { name: ui_detected_root, from: "$.detected_root" }
+      - { name: ui_none_sentinel, from: "$.none_sentinel" }
+
+  # 8. Choose the UI stack.
+  - id: select_ui_stack
+    action: user_select
+    prompt: "Select the UI (frontend) stack — it owns the web lane, and its root must not overlap the service lane's. This repo's own files point at: {{ui_detected}} (leading the list). (none) declares a backend-only project, and stops the UI constitution half and the frontend rule files being authored:"
+    options_from_variable: ui_options
+    preselect_from: ui_preselect
+    single_option_confirm: true
+    outputs:
+      - { name: chosen_ui, from: selection }
+
+  - id: ui_lane_selected
+    action: set
+    vars: { ui_selected: "true", ui_source_path: "" }
+  - id: ui_lane_declined
+    action: set
+    condition: "{{chosen_ui}} == {{ui_none_sentinel}}"
+    vars: { ui_selected: "" }
+
+  # 9. WHERE the UI lane's source lives.
+  - id: ask_ui_source_path
+    action: ask
+    condition: "{{ui_selected}}"
+    prompt: "UI lane SOURCE PATH — the subtree this lane owns, the only place ui-implement may write. It must not overlap the service lane's. Pick one or type your own:"
+    options_from_variable: ui_root_options
+    answer_var: ui_source_path
+
+  - id: declare_ui_lane
+    action: execute_script
+    script: { ref: actions }
+    subcommand: lane-declare
+    args: ["--profile", "{{chosen_ui}}", "--kind", "frontend", "--source-path", "{{ui_source_path}}"]
+    outputs:
+      - { name: ui_declared,    from: "$.declared" }
+      - { name: ui_lane_id,     from: "$.lane_id" }
+      - { name: ui_profile,     from: "$.profile" }
+      - { name: ui_root,        from: "$.source_path" }
+      - { name: ui_root_exists, from: "$.root_exists" }
+
+  # ═══════════════ CHECK + REPORT ═════════════════════════════════════════════
+
+  # 10. Is what was just written sound? --allow-missing-root because a source path
+  #     declared here legitimately does not exist yet; what this catches is a lane
+  #     declared with NO path at all, which no later phase could act on. The on-disk
+  #     check belongs to the phases that read the subtree, and runs there.
+  - id: verify_lanes
+    action: execute_script
+    script: { ref: actions }
+    subcommand: lane-verify
+    args: ["--allow-missing-root", "--command", "/appweaver select-stack"]
+    outputs:
+      - { name: lanes_ok,       from: "$.ok" }
+      - { name: lanes_issues,   from: "$.message" }
+      - { name: be_root_exists, from: "$.backend_root_exists" }
+      - { name: fe_root_exists, from: "$.frontend_root_exists" }
+
+  # Declining BOTH lanes lands here too, and stopping is right: a project with no
+  # lane at all has nothing for any later phase to govern, build or write into, and
+  # the mistake is cheaper to say now than to discover at constitution.
+  - id: lanes_gate
+    action: verify_context
+    require_true: lanes_ok
+    on_false_message: >
+      Nothing was declared: {{lanes_issues}}
+      Re-run /appweaver select-stack and choose a stack for at least one lane —
+      a service lane, a UI lane, or both.
+    on_false: stop
+
+  # 11. Two ordered sets per lane, because the engine has no conditionals in
+  #     `outputs:`: state the declined case, then override it where a lane was
+  #     actually declared.
+  - id: api_summary_none
+    action: set
+    vars: { api_summary: "(none) — no service lane declared; the technical constitution half and the service rule files are SKIPPED" }
+  - id: api_summary_lane
+    action: set
+    condition: "{{api_declared}}"
+    vars: { api_summary: "{{api_lane_id}} ({{api_profile}}) at {{api_root}} — source path exists: {{api_root_exists}}" }
+
+  - id: ui_summary_none
+    action: set
+    vars: { ui_summary: "(none) — backend-only project; the UI constitution half and the frontend rule files are SKIPPED" }
+  - id: ui_summary_lane
+    action: set
+    condition: "{{ui_declared}}"
+    vars: { ui_summary: "{{ui_lane_id}} ({{ui_profile}}) at {{ui_root}} — source path exists: {{ui_root_exists}}" }
+
+  # 12. Read the finished declaration back through the reader every later workflow
+  #     uses, so what this run reports is what they will resolve.
+  - id: resolve_lanes
+    action: execute_script
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: lanes,      from: "$.lanes" }
+      - { name: lane_count, from: "$.lane_count" }
+      - { name: lane_kinds, from: "$.kinds" }
+      - { name: prototype,  from: "$.prototype" }
+
+outputs:
+  lanes: "{{lanes}}"
+  lane_count: "{{lane_count}}"
+  lane_kinds: "{{lane_kinds}}"
+  api_lane: "{{api_summary}}"
+  ui_lane: "{{ui_summary}}"
+  api_source_path: "{{api_root}}"
+  ui_source_path: "{{ui_root}}"
+  api_source_path_exists: "{{be_root_exists}}"
+  ui_source_path_exists: "{{fe_root_exists}}"
+  api_detected: "{{api_detected}} at {{api_detected_root}}"
+  ui_detected: "{{ui_detected}} at {{ui_detected_root}}"
+  prototype: "{{prototype}}"
+  note: "Lanes persisted to .appweaver/stacks.json. Each lane carries a STACK and a SOURCE PATH, and both are load-bearing. The SOURCE PATH is ownership: implement writes only under the service lane's, ui-implement only under the UI lane's, build/test/run act on it, and onboard reverse-engineers out of it — overlapping paths are refused here rather than discovered later as two generators writing one file. The build/test/run commands are project-supplied strings the engine shells out to, which is how it stays stdlib-only and stack-ignorant. api_detected / ui_detected report what this repo's own files pointed at, whether or not it was chosen — empty on a greenfield repo with nothing to detect. A source path that does not exist yet is NORMAL here and reported rather than refused: greenfield declares src/ before implement creates it. The on-disk check runs in the phases that read the subtree — implement, implement-delta, build, run and onboard all call lane-verify and STOP with the fix named. Declining a lane with (none) is a real declaration and removes any lane of that kind a previous run left behind; it is also what stops that lane's constitution half and rule files being authored. `prototype` is not a lane — it has a root and a run command so an operator can open it, and nothing else. Re-run this workflow any time to re-stack a lane, move a source path, or drop a lane with (none); it is the only workflow that may write this file."
+  next: "GREENFIELD: /appweaver select-domain → constitution → select-feature → specify. BROWNFIELD: /appweaver onboard — it reverse-engineers out of the source paths declared here and generates the project (no select-domain; onboard derives and activates it from the code). Run this workflow FIRST in either sequence: constitution reads the declaration to decide which halves to author, and onboard reads it to decide what to scan."