aw-spec-cli 0.1.7 → 0.1.9

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

@@ -0,0 +1,267 @@
+# =============================================================================
+# aw-spec-implement-ui (orchestrator) — model-driven UI generation from design.ui.md
+#
+# The frontend lane's Implement phase: GENERATE the screens, components, client state
+# and paired tests for the aggregate STRICTLY from its design.ui.md — the mediator
+# between the spec and the lane's code. It is the twin of `implement`, and it keeps the
+# same contract, one lane over:
+#
+#   • DESIGN-ONLY. implement-ui does NOT read spec.md. The design is the complete,
+#     authoritative source for WHAT to build; anything missing from it is fixed in
+#     design-ui, never compensated for here from the spec or from memory.
+#   • THE FRAMEWORK BINDS HERE. design.ui.md is technology-agnostic — a "component" is
+#     a responsibility, its inputs are field shapes, its states are named. The actual
+#     framework, router, state library, component library and styling approach come
+#     from constitution.ui.md + the lane declaration + this command's rule set.
+#   • ONE SUBTREE. The lane owns the source path .appweaver/stacks.json declares for it,
+#     and nothing outside it. A file written elsewhere belongs to the service lane or
+#     to no lane at all.
+#
+# WHY A SEPARATE COMMAND, NOT A UI BRANCH INSIDE `implement`. The two lanes take their
+# code-generation rules from different map headings and write into disjoint subtrees.
+# Keying the rule maps on `## /aw-spec-implement-ui` gives the lane its own rule set for
+# zero mechanism change; a UI branch inside `implement` would generate frontend code
+# under the service lane's standards.
+#
+# Prereqs: /appweaver design-ui (the UI design), and a frontend project scaffolded under
+# the lane's own source path — implement-ui GENERATES into that tree, so with no project
+# there is nowhere to place the files. The project gate is deliberately LANE-SCOPED: a
+# manifest found only elsewhere in the repository is the service lane's, and accepting
+# it is how a frontend that was never built reports green.
+#
+# ⌛ /appweaver analyze-design-ui — the spec↔design.ui.md conformance gate that would
+# run between design-ui and this phase — is not built yet. Until it is, the two-way
+# check that no UX-/US- fell between the two designs is design.ui.md §7 read by hand.
+#
+# Next: /appweaver build (compiles every declared lane, this one included).
+#
+# Launch:  /appweaver implement-ui [strategy] [guidance]
+# =============================================================================
+
+name: aw-spec-implement-ui
+description: Generate the frontend lane's screens, components, client state and paired tests STRICTLY from the aggregate's design.ui.md, bound to the declared UI stack and written only under that lane's source path. Model-driven and design-only — it does not read the spec, the same contract implement keeps for the service lane. The framework, router, state library and styling approach bind here from constitution.ui.md and the lane declaration; the design stays technology-agnostic. Merges the generated files into the feature's existing OKF concept rather than replacing the service lane's.
+version: 1.0.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional implementation guidance (focus area, screen subset, framework hints).
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+  xref:
+    sh:  .appweaver/scripts/bash/aw-xref.sh
+    ps1: .appweaver/scripts/powershell/aw-xref.ps1
+
+# Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The lane's
+# FRONTEND code-generation rule files are CONFIGURATION, loaded per-command from
+# guardrails/projects/<project>/tech-rule-bindings.md under `## /aw-spec-implement-ui` by
+# the tech-select module. Per the rule-partition this phase loads NO domain rule file —
+# the domain reached the lane through spec → design.ui.md. The lane's ratified base
+# arrives via constitution.ui.md (referred to directly, as-is — NOT mapped).
+# (missing files skipped at assembly time)
+standards:
+  - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
+
+workflow:
+
+  # 0. FRONTEND code-generation rule files → sticky standards (configuration, not
+  #    hardcoded). No blocking gate: an unmapped project soft-continues, because
+  #    constitution.ui.md still carries the lane's conventions and forbidden patterns.
+  - id: tech_select
+    action: include
+    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
+    with: { command: aw-spec-implement-ui }
+
+  # 1. Resolve the current feature + its UI design; require the DESIGN (this phase's
+  #    only input). No spec — the design is the authoritative source for WHAT to build.
+  - id: feature_paths
+    action: execute_script
+    on_error: continue      # never crash raw on 'no feature set' — the gate below explains it
+    script: { ref: actions }
+    subcommand: feature-paths
+    outputs:
+      - { name: feature_dir,      from: "$.feature_dir" }
+      - { name: ui_design_doc,    from: "$.ui_design_file" }
+      - { name: ui_design_exists, from: "$.ui_design_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 (pick or create the aggregate, e.g. Order), then re-run implement-ui."
+
+  - id: verify_ui_design
+    action: verify_context
+    require_true: ui_design_exists
+    on_false: stop
+    on_false_message: "No design.ui.md for the current feature. Run /appweaver design-ui first — implement-ui generates STRICTLY from the UI design, and there is nothing else it may read. Review its §7 Traceability before generating: ⌛ /appweaver analyze-design-ui, the spec↔design.ui.md gate, is not built yet."
+
+  # 1a. Require the FRONTEND LANE and its source path. This phase writes code, and the
+  #     lane's root is the only subtree it may write into — so this runs before the
+  #     project gate, which searches that subtree.
+  - id: lane_gate
+    action: include
+    module: .appweaver/orchestrator/modules/lane-gate.orch.yaml
+    with: { require: frontend, command: "/appweaver implement-ui" }
+
+  # 1b. Require a frontend PROJECT under the LANE'S OWN path. Deterministic structure
+  #     gate: detect-project searches the lane subtree for an ecosystem manifest and
+  #     falls back to the whole repository when it finds none, reporting which scope
+  #     answered. THAT DISTINCTION IS THE GATE HERE. A repo-scope hit in a two-lane
+  #     project is the service lane's manifest, and accepting it is exactly the failure
+  #     the lane model exists to prevent — a frontend that was never scaffolded,
+  #     generated into anyway, reporting green.
+  - id: detect_ui_project
+    action: execute_script
+    script: { ref: actions }
+    subcommand: detect-project
+    args: ["--root", "{{lane_source_path}}"]
+    outputs:
+      - { name: ui_project_present, from: "$.scaffolded" }
+      - { name: project_markers,    from: "$.markers" }
+      - { name: project_scope,      from: "$.scope" }
+
+  - id: ui_project_gate
+    action: verify_context
+    require_value: project_scope
+    equals: "lane"
+    on_mismatch: stop
+    on_mismatch_message: "No frontend project found under the {{lane_id}} lane's source path `{{lane_source_path}}`. implement-ui GENERATES this feature's UI into an existing project tree, so one has to be scaffolded there first: run /appweaver foundation <FoundationName> <AppName> where a foundation bundle ships for {{lane_profile}}, or create the project with the stack's own tooling under that path. Any ecosystem manifest inside the lane's path marks it — package.json, go.mod, pyproject.toml, Cargo.toml, pom.xml, build.gradle(.kts) or .sln/.csproj. A manifest found elsewhere in the repository does NOT count: that one belongs to another lane, and generating this lane's code against it is how a frontend that was never built reports green."
+
+  # 2. Pre-execution hooks.
+  - id: resolve_pre_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "before_implement_ui"]
+    outputs:
+      - { name: before_hooks, from: "$.hooks" }
+  - id: dispatch_pre_hooks
+    action: dispatch_hooks
+    hooks_from_variable: before_hooks
+
+  # 3. Model-driven generation: design.ui.md → screens, components, state + tests.
+  #    The design constrains WHAT to build; constitution.ui.md + the lane fix HOW.
+  #    The spec is deliberately NOT in context — the design is the single source here.
+  - id: ctx_generate
+    action: build_context
+    context:
+      - { path: "{{ui_design_doc}}" }
+      - { path: .appweaver/memory/constitution.ui.md, optional: true }   # the lane's ratified UX-* base — conventions, forbidden patterns, gates
+  - id: generate
+    action: agent_generate
+    tools: "Read,Write,Edit"
+    permission_mode: acceptEdits
+    task: |
+      Generate the production UI code AND paired tests for this feature STRICTLY from
+      its design.ui.md (in context). The design is the complete, authoritative source of
+      WHAT to build — do NOT consult or infer from the spec. This phase is the HOME of
+      the framework-specific, lane-wide code-generation rules. Guidance: {{USER_INPUT}}
+      Rules:
+      - THE DESIGN IS THE ONLY DOMAIN INPUT. You have design.ui.md + the lane's
+        frontend standards, and NO domain rule files. Introduce NO domain rule,
+        identifier, terminology or behaviour the design does not state — everything
+        domain already passed through spec → design.ui.md. If a domain specific seems
+        missing, STOP and surface it; never invent it from memory.
+      - BIND THE STACK: this lane is `{{lane_id}}` — {{lane_title}}, language
+        {{lane_language}} ({{lane_ecosystem}}), declared in .appweaver/stacks.json and
+        built with `{{lane_build}}`, tested with `{{lane_test}}`. Generate in THAT
+        framework and no other, using its idioms, its project layout and its test
+        framework. Take the router, state approach, component library, design system and
+        styling from the UI constitution + the loaded standards; the design is
+        technology-agnostic, so do not re-decide anything already fixed there. If the
+        loaded standards describe a DIFFERENT stack than the one above, the lane wins on
+        framework and layout — follow the standards' INTENT and STOP to surface the
+        mismatch in your summary.
+      - WRITE ONLY UNDER `{{lane_source_path}}` — the source path the `{{lane_id}}` lane
+        declares. That subtree is this lane's; a file outside it belongs to the service
+        lane or to no lane. NEVER touch the service lane's code, not even to add a field
+        the UI wants: a gap in the service surface is a contract delta raised back to
+        that lane. Do not create a parallel source tree because the layout inside this
+        one is unfamiliar; if the design needs a place this subtree has no home for,
+        STOP and surface it.
+      - Follow the UI constitution's folder structure, naming conventions and forbidden
+        patterns, plus the loaded standards, for HOW to structure, name and place files
+        WITHIN that subtree — the design says WHAT to build; these say HOW.
+      - REALISE EVERY DESIGN ELEMENT, changing nothing about WHAT it specifies:
+        • §1 — one route/screen per row, with the navigation shape and the access
+          conditions the row states.
+        • §2 — the client state exactly as owned and scoped there, including its
+          invalidation triggers. Anything the design lists under "what must NOT be held"
+          NEVER reaches client state, storage, the URL or telemetry.
+        • §3 — one component per row, with the responsibility, the input field shapes
+          and the events the design gives it. Compose the shared components the design
+          says it reuses; do not re-implement them.
+        • §4 — EVERY state in EVERY interaction row: loading, empty, error,
+          permission-denied and in-flight/disabled, plus the validation timing, the focus
+          and keyboard behaviour and the concurrency handling stated there. These are
+          requirements, not polish, and they are the first thing a generator drops.
+        • §5 — the service binding, through the lane's own client layer, with the write
+          semantics and rollback each row states.
+        • §6 — the cross-cutting decisions as code: what is hidden vs disabled,
+          accessibility obligations, localization, performance and offline behaviour.
+      - THE CLIENT IS NOT AN AUTHORITY. A client-side validation or permission check
+        restates a server rule for feedback; it never replaces it. Generate no
+        server-side behaviour, no persistence and no business rule evaluation here.
+      - Author a paired test for every screen, interaction and state the design names —
+        including the unwanted-behaviour states from §4 and an accessibility assertion
+        per interactive surface — and cite the spec id (UX-/US-/FR-/CN-/DC-/IC-/SC-)
+        from the design's §7 Traceability in each test. A snapshot alone is not a test.
+      - Do NOT add behaviour the design does not state, and do NOT omit any it does. If
+        the design looks wrong or incomplete, STOP and surface it (it is fixed in
+        design-ui) — never compensate from the spec or from memory.
+      - This feature OWNS its files; never regenerate a file another feature owns, and
+        do not modify the app shell, global layout or design system — they belong to no
+        feature. If one of them has to change, STOP and surface it.
+      - Where generated code depends on a design Assumption (DA-n) or Workaround (WA-n),
+        mark it with a comment citing that id so it is easy to revisit later.
+    outputs:
+      - { name: files, from: "$.files" }
+
+  - id: verify_generated
+    action: verify_context
+    require_non_empty: files
+    on_empty: stop
+    on_empty_message: "No files generated. Ensure /appweaver design-ui produced a filled design.ui.md (not the empty template), then re-run."
+
+  # 3b. OKF knowledge — the feature has ONE concept across both lanes, so the UI files
+  #     JOIN it rather than replace it. --merge unions them with whatever is already
+  #     recorded; without it this run would erase the service lane's source_files, and
+  #     `implement` may have run before or after this one. The concept's Overview is
+  #     NOT re-authored here: it describes the aggregate and its invariants, which is
+  #     the service design's subject, and rewriting it from the UI design would trade a
+  #     domain description for an experience one.
+  - id: xref_concept
+    action: execute_script
+    script: { ref: xref }
+    subcommand: concept-upsert
+    args: ["--feature-dir", "{{feature_dir}}", "--source-files", "{{files}}", "--merge", "--origin", "greenfield"]
+    outputs:
+      - { name: okf_concept, from: "$.concept" }
+
+  # 4. Post-execution hooks.
+  - id: resolve_post_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "after_implement_ui"]
+    outputs:
+      - { name: after_hooks, from: "$.hooks" }
+  - id: dispatch_post_hooks
+    action: dispatch_hooks
+    hooks_from_variable: after_hooks
+
+outputs:
+  feature_dir: "{{feature_dir}}"
+  ui_design_doc: "{{ui_design_doc}}"
+  lane_id: "{{lane_id}}"
+  lane_source_path: "{{lane_source_path}}"
+  files: "{{files}}"
+  okf_concept: "{{okf_concept}}"
+  next: "/appweaver build  (generated the {{lane_id}} lane's UI under {{lane_source_path}} and merged the files into the feature's OKF concept at {{okf_concept}}; build compiles every declared lane, so a break in either one surfaces there)"

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

@@ -0,0 +1,287 @@
+# =============================================================================
+# aw-spec-implement (orchestrator) — model-driven code generation from the DESIGN
+#
+# The spec-anchored Implement phase: GENERATE the source files + paired tests for
+# the aggregate STRICTLY from its single high-level design.md — the mediator between
+# spec and code. Implement does NOT read spec.md: `analyze` already guaranteed the
+# design conforms to the spec (spec is the anchor), so the design is the complete,
+# authoritative source for WHAT to build. The target STACK is bound here from the
+# constitution + the active stack profile (the design is technology-agnostic).
+# Prereqs: run /appweaver design then analyze-design first (the gate conforms the
+# design to the spec + closes any open change), and scaffold the project once —
+# implement GENERATES into that project tree, so with no project there is nowhere
+# to place the files. /appweaver foundation unpacks one where a bundle ships for the
+# stack; a stack with no bundle scaffolds with its own tooling instead, and the gate
+# below accepts either, since it tests for a project rather than for a bundle.
+#
+# Next: Build (compile + fix; reconcile only high-level variations into design.md).
+#
+# Launch:  /appweaver implement [strategy] [guidance]
+# =============================================================================
+
+name: aw-spec-implement
+description: Generate the aggregate's source files and paired tests STRICTLY from its design.md, bound to the project's stack. Model-driven, design-only (does not read the spec — analyze already conformed the design to it).
+version: 2.1.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional implementation guidance (stack hints, focus area).
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+  xref:
+    sh:  .appweaver/scripts/bash/aw-xref.sh
+    ps1: .appweaver/scripts/powershell/aw-xref.ps1
+
+# Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The
+# FRAMEWORK / code-generation rule files are no longer hardcoded here — they are now
+# CONFIGURATION, loaded per-command from guardrails/projects/<project>/tech-rule-bindings.md
+# by the tech-select module (see the workflow's tech_select step), exactly as design's
+# technical rules are. Per the rule-partition, implement still generates from design.md +
+# these HOW-to-build standards and loads NO domain rule file — the tech map lists only
+# technical files. The architecture principles come via constitution.technical.md
+# (referred to directly, as-is — NOT mapped); the structure via design.md. Component
+# rule docs are NOT loaded here — implement codes against a component's PORT; adding the
+# component itself is a separate step, /appweaver add-component. (missing files skipped)
+standards:
+  - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
+
+workflow:
+
+  # 0. TECHNICAL rule files → sticky standards (configuration, not hardcoded).
+  #    tech-select reads guardrails/projects/<project>/tech-rule-bindings.md under
+  #    "## /aw-spec-implement" and loads that set into the sticky standards the
+  #    agent_generate step ALWAYS prepends. No domain rule file is loaded here — the
+  #    tech map lists only technical files (rule-partition intact). No blocking gate:
+  #    an unconfigured project soft-continues (constitution.technical.md still carries
+  #    the tech base, referred to directly below).
+  - id: tech_select
+    action: include
+    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
+    with: { command: aw-spec-implement }
+
+  # 1. Resolve the current feature + its design; require the DESIGN (implement's
+  #    only input). No spec — analyze already conformed the design to the spec.
+  - id: feature_paths
+    action: execute_script
+    on_error: continue      # never crash raw on 'no feature set' — the gate below explains it
+    script: { ref: actions }
+    subcommand: feature-paths
+    outputs:
+      - { name: feature_dir,   from: "$.feature_dir" }
+      - { name: design_doc,    from: "$.design_file" }
+      - { name: design_exists, from: "$.design_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 (pick or create the aggregate, e.g. Order), then re-run implement."
+
+  - id: verify_design
+    action: verify_context
+    require_true: design_exists
+    on_false: stop
+    on_false_message: "No design.md for the current feature. Run /appweaver design then /appweaver analyze-design first — implement generates STRICTLY from the conformed design."
+
+  # 1a. Require the SERVICE LANE and its source path. Implement writes code, and
+  #     the lane's root is the subtree it is allowed to write into — so this runs
+  #     before the foundation gate, which searches that subtree for a project.
+  - id: lane_gate
+    action: include
+    module: .appweaver/orchestrator/modules/lane-gate.orch.yaml
+    with: { require: backend, command: "/appweaver implement" }
+
+  # 1b. Require the PROJECT — a scaffolded, compiling tree — to be present. Implement
+  #     GENERATES the aggregate's code INTO it; with no project there is nowhere to place
+  #     the files. Deterministic structure gate: searches the LANE'S OWN subtree for an
+  #     ecosystem manifest (.sln/.csproj, pom.xml, build.gradle, package.json, go.mod,
+  #     Cargo.toml, pyproject.toml), falling back to the whole repo for the layout that
+  #     keeps its manifest beside the lane root rather than inside it, and ignoring the
+  #     framework/spec/guardrails/foundations dirs — never trusts the model for this.
+  #     How the project got there is not asked: `foundation` unpacked it, or the team
+  #     scaffolded it with the stack's own tooling.
+  - id: detect_foundation
+    action: execute_script
+    script: { ref: actions }
+    subcommand: detect-project
+    args: ["--root", "{{lane_source_path}}"]
+    outputs:
+      - { name: foundation_present, from: "$.scaffolded" }
+      - { name: project_markers,    from: "$.markers" }
+      - { name: project_scope,      from: "$.scope" }
+
+  - id: foundation_gate
+    action: verify_context
+    require_true: foundation_present
+    on_false: stop
+    on_false_message: "No project found under the {{lane_id}} lane's source path `{{lane_source_path}}`, nor anywhere else in this repository. Implement GENERATES the aggregate's code into an existing project tree, so one has to be scaffolded first: run /appweaver foundation <FoundationName> <AppName> where a foundation bundle ships for this stack, or create the project with the stack's own tooling under that path. Any ecosystem manifest marks it — .sln/.csproj, pom.xml, build.gradle(.kts), package.json, go.mod, Cargo.toml or pyproject.toml."
+
+  # 2. Pre-execution hooks.
+  - id: resolve_pre_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "before_implement"]
+    outputs:
+      - { name: before_hooks, from: "$.hooks" }
+  - id: dispatch_pre_hooks
+    action: dispatch_hooks
+    hooks_from_variable: before_hooks
+
+  # 3. Model-driven generation: design.md → source files + paired tests.
+  #    The design constrains WHAT to build; the constitution/stack profile fixes HOW.
+  #    The spec is deliberately NOT in context — the design is the single source here.
+  - id: ctx_generate
+    action: build_context
+    context:
+      - { path: "{{design_doc}}" }
+      - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain
+  - id: generate
+    action: agent_generate
+    tools: "Read,Write,Edit"
+    permission_mode: acceptEdits
+    task: |
+      Generate the production code AND paired tests for this aggregate STRICTLY from
+      its design.md (in context). The design is the complete, authoritative source of
+      WHAT to build — do NOT consult or infer from the spec; `analyze` already
+      conformed the design to the spec. This phase is the HOME of the
+      technology-specific, solution-wide code-generation rules. Guidance: {{USER_INPUT}}
+      Rules:
+      - THE DESIGN IS THE ONLY DOMAIN INPUT. You have design.md + framework/code
+        standards, and NO domain rule files. Introduce NO domain rule, identifier,
+        terminology, or behaviour that the design does not state — everything domain
+        already passed through spec → design. If a domain specific seems missing, STOP
+        and surface it; never invent it from memory.
+      - BIND THE STACK: this lane is `{{lane_id}}` — {{lane_title}}, language
+        {{lane_language}} ({{lane_ecosystem}}), declared in .appweaver/stacks.json and
+        compiled with `{{lane_build}}`, tested with `{{lane_test}}`. Generate in THAT
+        language and framework and no other, using its idioms, its project layout and
+        its test framework. Take persistence, messaging and the remaining technology
+        choices from the constitution's technology base + the loaded standards; the
+        design is technology-agnostic, so do not re-decide anything already fixed there.
+        If the loaded standards describe a DIFFERENT stack than the one above, the lane
+        wins on language and layout — the standards' stack-specific mechanics do not
+        apply, so follow their INTENT and STOP to surface the mismatch in your summary.
+      - WRITE ONLY UNDER `{{lane_source_path}}` — the source path the `{{lane_id}}`
+        lane declares in .appweaver/stacks.json. That subtree is this lane's, and a file
+        outside it belongs to another lane or to no lane at all. Do not create a
+        parallel source tree because the layout inside it is unfamiliar; if the design
+        needs a place this subtree has no home for, STOP and surface it.
+      - Follow the project's folder/layer convention + the loaded coding-standards,
+        dependency-policy and testing standards for HOW to structure, name, and place
+        files WITHIN that subtree — the design says WHAT to build; these standards
+        (identical for every feature) say HOW.
+      - COMPONENTS: when the design's External Integrations table depends on a framework
+        component (e.g. `IEmailService`, `IJobScheduler`), code against that component's
+        ABSTRACTION / port as the design declares — do NOT hand-roll it. Installing the
+        component into the project (packages, provider wiring, config) is a SEPARATE step:
+        /appweaver add-component <Component>. If the port isn't present yet, code to
+        it and note add-component as the prerequisite; do not load component rule docs here.
+      - Realise EVERY design element as code, changing nothing about WHAT it specifies:
+        one file per Domain type / Application use-case / API endpoint / Infrastructure
+        adapter, placed by layer. Preserve the ubiquitous-language names verbatim.
+      - Enforce EXACTLY as the design states: every Domain invariant, Application
+        handler orchestration, and API error contract; the cross-cutting constraints in
+        the Cross-Cutting Concerns table (audit / retention / data-exposure — the
+        CN-/DC- realisations); and each integration contract (IC-) in the External
+        Integrations table. Implement every port the design declares.
+      - Author a paired test for every design behaviour / use-case / endpoint; derive
+        the cases from the design's pre/post/invariant contracts and cite the spec id
+        (FR / BR / CN / DC / IC / US) from the design's Traceability section. Include tests
+        for the constraints — e.g. an audit record is emitted, a DC-restricted field is
+        NOT exposed on the public surface, an IC- projection round-trips.
+      - Do NOT add behaviour the design does not state, and do NOT omit any it does.
+        If the design looks wrong or incomplete, STOP and surface it (it is fixed in
+        design/analyze) — never compensate from the spec or from memory.
+      - This aggregate OWNS its files; never regenerate a file another feature owns.
+      - Where generated code depends on a design Assumption (DA-n) or Workaround
+        (WA-n), mark it with a comment citing that id so it is easy to revisit later.
+    outputs:
+      - { name: files, from: "$.files" }
+
+  - id: verify_generated
+    action: verify_context
+    require_non_empty: files
+    on_empty: stop
+    on_empty_message: "No files generated. Ensure /appweaver design produced a filled design.md (not the empty template) and passed analyze, then re-run."
+
+  # 3b. OKF knowledge + cross-references (deterministic, design-derived). Greenfield's
+  #     entry into the shared OKF bundle: author THIS aggregate's concept (its source_files
+  #     = the files just generated), then record its cross-slice edges — write a
+  #     Cross-References row into every SIBLING aggregate it uses (from design.md §1
+  #     References-by-id + its External integrations table), reconcile-on-write so a dropped
+  #     dependency self-heals and a used sibling with no concept yet is stubbed. Finally
+  #     author the concept's Overview prose (3c). This is enrichment downstream of a
+  #     successful generate — it never re-decides WHAT was built.
+  - id: xref_concept
+    action: execute_script
+    script: { ref: xref }
+    subcommand: concept-upsert
+    args: ["--feature-dir", "{{feature_dir}}", "--source-files", "{{files}}", "--origin", "greenfield"]
+    outputs:
+      - { name: okf_concept, from: "$.concept" }
+
+  - id: xref_record
+    action: execute_script
+    script: { ref: xref }
+    subcommand: record
+    args: ["--feature-dir", "{{feature_dir}}", "--design", "{{design_doc}}", "--origin", "greenfield"]
+    outputs:
+      - { name: xref_wrote,      from: "$.wrote" }
+      - { name: xref_edge_count, from: "$.edge_count" }
+
+  # 3c. The concept's Overview — the ONE part of the OKF concept a deterministic script
+  #     cannot produce (prose distilled from design.md §1). The model authors the text
+  #     only; concept-overview splices it into the `## Overview` section alone, so the
+  #     Cross-References rows other slices own are structurally out of reach.
+  - id: okf_overview
+    action: agent_query
+    context: ["{{design_doc}}"]
+    include_standards: false
+    schema: { overview: "<2-4 sentences of prose>" }
+    mock: { overview: "" }
+    task: |
+      Write the OKF knowledge-concept Overview for the aggregate that design.md (in
+      context) describes. 2-4 sentences of PROSE, distilled from §1 Domain Model:
+      - name the aggregate ROOT and what the aggregate IS;
+      - state the INVARIANTS it guards (from §1 / the design's business rules);
+      - state its TRANSACTION BOUNDARY — what it OWNS inside the boundary vs what it
+        only REFERENCES by id.
+      Plain prose only: no headings, no bullets, no code fences, no file paths, and no
+      restating of the dependency edges (those live in the Depends-On / Cross-References
+      tables). Describe only what the design states — invent nothing.
+    outputs:
+      - { name: okf_overview, from: "$.overview" }
+
+  - id: okf_overview_write
+    action: execute_script
+    script: { ref: xref }
+    subcommand: concept-overview
+    args: ["--feature-dir", "{{feature_dir}}", "--text", "{{okf_overview}}"]
+
+  # 4. Post-execution hooks.
+  - id: resolve_post_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "after_implement"]
+    outputs:
+      - { name: after_hooks, from: "$.hooks" }
+  - id: dispatch_post_hooks
+    action: dispatch_hooks
+    hooks_from_variable: after_hooks
+
+outputs:
+  feature_dir: "{{feature_dir}}"
+  design_doc: "{{design_doc}}"
+  files: "{{files}}"
+  okf_concept: "{{okf_concept}}"
+  xref_edge_count: "{{xref_edge_count}}"
+  next: "/appweaver build  (OKF concept authored at {{okf_concept}}; {{xref_edge_count}} cross-slice edge(s) recorded into sibling aggregates)"