aw-spec-cli 0.1.26 → 0.1.28

package/assets/.appweaver/stack-profiles/angular.json

@@ -4,8 +4,9 @@
   "title": "Angular",
   "language": "TypeScript",
   "ecosystem": "node",
-  "root": "web/",
+  "root": "frontend/",
   "run_from": "root",
+  "conventional_root": "web/",
   "build": "npm run build",
   "test": "npm test",
   "run": "npm start",

package/assets/.appweaver/stack-profiles/blazor-wasm.json

@@ -4,8 +4,9 @@
   "title": "Blazor WebAssembly",
   "language": "C#",
   "ecosystem": "dotnet",
-  "root": "web/",
+  "root": "frontend/",
   "run_from": "root",
+  "conventional_root": "web/",
   "build": "dotnet build",
   "test": "dotnet test",
   "run": "dotnet run",

package/assets/.appweaver/stack-profiles/dotnet-webapi.json

@@ -4,11 +4,26 @@
   "title": "ASP.NET Core Web API",
   "language": "C#",
   "ecosystem": "dotnet",
-  "root": "src/",
-  "test_root": "tests/",
+  "root": "backend/",
+  "test_root": "backend/tests/",
+  "run_from": "root",
+  "conventional_root": "src/",
+  "conventional_test_root": "tests/",
+  "build_files": [
+    "*.sln",
+    "*.slnx",
+    "*.csproj"
+  ],
   "build": "dotnet build",
   "test": "dotnet test",
-  "run": "dotnet run --project {{root}}",
+  "run": "dotnet run --project {{host}}",
+  "contract_run": "dotnet run --project {{host}} -- --environment Development --urls http://localhost:5000",
+  "contract": "http://localhost:5000/swagger/v1/swagger.json",
+  "host_patterns": [
+    "**/*.AppHost.csproj",
+    "**/*.Api.csproj",
+    "**/*.Service.csproj"
+  ],
   "detect": [
     "*.sln",
     "src/**/*.csproj"

package/assets/.appweaver/stack-profiles/go-chi.json

@@ -4,7 +4,12 @@
   "title": "Go + chi",
   "language": "Go",
   "ecosystem": "go",
-  "root": "internal/",
+  "root": "backend/",
+  "run_from": "root",
+  "conventional_root": "internal/",
+  "build_files": [
+    "go.mod"
+  ],
   "build": "go build ./...",
   "test": "go test ./...",
   "run": "go run ./cmd/api",

package/assets/.appweaver/stack-profiles/java-spring.json

@@ -4,12 +4,21 @@
   "title": "Spring Boot",
   "language": "Java",
   "ecosystem": "java",
-  "root": "src/main/java/",
-  "test_root": "src/test/java/",
+  "root": "backend/",
+  "test_root": "backend/src/test/java/",
   "run_from": "root",
-  "build": "./mvn clean install",
-  "test": "./mvn test",
-  "run": "./mvn spring-boot:run",
+  "conventional_root": "src/main/java/",
+  "conventional_test_root": "src/test/java/",
+  "build_files": [
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts"
+  ],
+  "build": "./mvnw clean install",
+  "test": "./mvnw test",
+  "run": "./mvnw spring-boot:run",
+  "contract_run": "./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8080",
+  "contract": "http://localhost:8080/v3/api-docs",
   "detect": [
     "pom.xml",
     "build.gradle"

package/assets/.appweaver/stack-profiles/nextjs.json

@@ -4,8 +4,9 @@
   "title": "Next.js",
   "language": "TypeScript",
   "ecosystem": "node",
-  "root": "web/",
+  "root": "frontend/",
   "run_from": "root",
+  "conventional_root": "web/",
   "build": "npm run build",
   "test": "npm test",
   "run": "npm run dev",

package/assets/.appweaver/stack-profiles/node-express.json

@@ -4,8 +4,14 @@
   "title": "Express + TypeScript",
   "language": "Node.js",
   "ecosystem": "node",
-  "root": "src/",
-  "test_root": "tests/",
+  "root": "backend/",
+  "test_root": "backend/tests/",
+  "run_from": "root",
+  "conventional_root": "src/",
+  "conventional_test_root": "tests/",
+  "build_files": [
+    "package.json"
+  ],
   "build": "npm run build",
   "test": "npm test",
   "run": "npm run dev",

package/assets/.appweaver/stack-profiles/python-fastapi.json

@@ -4,8 +4,15 @@
   "title": "FastAPI",
   "language": "Python",
   "ecosystem": "python",
-  "root": "app/",
-  "test_root": "tests/",
+  "root": "backend/",
+  "test_root": "backend/tests/",
+  "run_from": "root",
+  "conventional_root": "app/",
+  "conventional_test_root": "tests/",
+  "build_files": [
+    "pyproject.toml",
+    "requirements.txt"
+  ],
   "build": "python -m compileall {{root}}",
   "test": "pytest",
   "run": "uvicorn app.main:app --reload",

package/assets/.appweaver/stack-profiles/react-vite.json

@@ -4,8 +4,9 @@
   "title": "React + Vite",
   "language": "TypeScript",
   "ecosystem": "node",
-  "root": "web/",
+  "root": "frontend/",
   "run_from": "root",
+  "conventional_root": "web/",
   "build": "npm run build",
   "test": "npm test",
   "run": "npm run dev",

package/assets/.appweaver/stack-profiles/sveltekit.json

@@ -4,8 +4,9 @@
   "title": "SvelteKit",
   "language": "TypeScript",
   "ecosystem": "node",
-  "root": "web/",
+  "root": "frontend/",
   "run_from": "root",
+  "conventional_root": "web/",
   "build": "npm run build",
   "test": "npm test",
   "run": "npm run dev",

package/assets/.appweaver/stack-profiles/vue-vite.json

@@ -4,8 +4,9 @@
   "title": "Vue 3 + Vite",
   "language": "TypeScript",
   "ecosystem": "node",
-  "root": "web/",
+  "root": "frontend/",
   "run_from": "root",
+  "conventional_root": "web/",
   "build": "npm run build",
   "test": "npm test",
   "run": "npm run dev",

package/assets/.appweaver/stacks.json

@@ -1,3 +1,42 @@
 {
-  "lanes": []
+  "lanes": [],
+  "_lane_format": {
+    "lanes": [
+      {
+        "id": "service",
+        "kind": "backend",
+        "profile": "dotnet-webapi",
+        "stack": "ASP.NET Core Web API",
+        "origin": "declared",
+        "root": "backend/",
+        "test_root": "backend/tests/",
+        "run_from": "root",
+        "build": "dotnet build",
+        "test": "dotnet test",
+        "run": "dotnet run --project {{host}}",
+        "migrate": "dotnet ef database update --project {{host}}",
+        "contract_run": "dotnet run --project {{host}} -- --environment Development --urls http://localhost:5000",
+        "contract": "http://localhost:5000/swagger/v1/swagger.json"
+      },
+      {
+        "id": "web",
+        "kind": "frontend",
+        "profile": "nextjs",
+        "stack": "Next.js",
+        "origin": "declared",
+        "root": "frontend/",
+        "test_root": "frontend/",
+        "run_from": "root",
+        "build": "npm run build",
+        "test": "npm test",
+        "run": "npm run dev",
+        "migrate": "",
+        "client": "npx openapi-typescript {{contract}} -o lib/api/schema.d.ts"
+      }
+    ],
+    "prototype": {
+      "root": "prototype/",
+      "run": "npm run dev --prefix prototype"
+    }
+  }
 }

package/assets/.appweaver/templates/constitution-ui-template.md

@@ -90,9 +90,9 @@
 <!-- Form: the lane's structural mandate, named as the lane rules name it. -->
 
 [UI_STRUCTURE_CONTENT]
-<!-- Form: the lane root and the layout beneath it, as the mapped rules define it for this
+<!-- Form: the lane root folder and the layout beneath it, as the mapped rules define it for this
      lane's stack, including where generated contract clients land. This layout sits
-     ENTIRELY under the lane's root; it never adds to the service lane's structure in
+     ENTIRELY under the lane root folder; it never adds to the service lane's structure in
      constitution.technical.md. -->
 
 ## [UI_CONVENTIONS_SECTION_NAME]

package/assets/.appweaver/templates/delta-design-template.md

@@ -89,7 +89,7 @@ it realises. "Realisation only — no spec delta" for a plan-only change.]
 | Section (§) | Element | Kind | Serves |
 |---|---|---|---|
 | Application (§2) | `[Command/Query]` + handler | use-case | US-[n] · FR-[nnn] |
-| API (§3) | `[VERB] [/route]` | endpoint | US-[n] · FR-[nnn] |
+| API (§3) | `[OperationId]` · `[VERB] [/route]` | endpoint | US-[n] · FR-[nnn] |
 | Domain (§1) | `[Event]` handling / `[VO]` mapping | model realisation | BR-[nnn] · CN-[nnn] |
 | Infrastructure (§4.2) | `I[External]` adapter | contract realisation | IC-[nnn] |
 | Cross-cutting (§5) | [audit / retention / exposure decision] | constraint realisation | CN-[nnn] · DC-[nnn] |
@@ -118,12 +118,14 @@ realisation); new migration needed? (yes/no); any contract change other systems
   What this change adds to or alters in the service's PUBLISHED surface — the only part
   of this document the frontend lane may bind against. One row per contract; the frontend
   delta plan cites these rather than re-deriving them. "None" when the surface is
-  unchanged, which is what a purely internal refactor should say.
+  unchanged, which is what a purely internal refactor should say. The operation id is the
+  endpoint's name in the published API document, unique across the service; an endpoint
+  the master plan already names keeps that id.
 -->
 
-| Contract | Change | Shape | Serves |
-|---|---|---|---|
-| `[VERB] [/route]` | added / changed | [request → response field shapes] | IC-[nnn] · FR-[nnn] |
+| Operation id | Contract | Change | Shape | Serves |
+|---|---|---|---|---|
+| `[OperationId]` | `[VERB] [/route]` | added / changed | [request → response field shapes] | IC-[nnn] · FR-[nnn] |
 
 ## Other open deltas
 

package/assets/.appweaver/templates/design-template.md

@@ -254,10 +254,13 @@ text, and do not add a rule the model does not carry)*
   per the constitution — adapt for gRPC/GraphQL/CLI if the stack differs), NOT as
   controller code. Pin route, verb, auth, request/response shape, status codes, and
   the error contract. Delegates to an Application use-case; no business logic here.
+  The OPERATION ID is the endpoint's name in the published API document, unique across
+  the service: the frontend plan cites it, and implement gives the endpoint exactly it.
 -->
 
 ### `[VERB] [/route]` — [purpose] · Serves US-Y · FR-00X
 
+- **Operation id**: `[OperationId]`
 - **Auth**: [required role/scope]
 - **Request**: `[path/query params]` + body `{ [field]: [type], … }`
 - **Success**: `2xx` → `{ [response shape] }`

package/assets/.appweaver/templates/ui-delta-design-template.md

@@ -76,7 +76,7 @@ CN-/DC-/IC-) it realises. "Realisation only — no spec delta" for a plan-only c
 | Navigation & Screens (§1) | `[screen]` | screen | US-[n] |
 | Component Structure (§3) | `[component]` | component | US-[n] · FR-[nnn] |
 | Client State (§2) | `[state]` | state | FR-[nnn] · DC-[nnn] |
-| Contract Binding (§5) | `[VERB] [/route]` | binding | IC-[nnn] |
+| Contract Binding (§5) | `[OperationId]` · `[VERB] [/route]` | binding | IC-[nnn] |
 
 ## MODIFIED — existing experience elements
 

package/assets/.appweaver/templates/ui-design-template.md

@@ -196,11 +196,13 @@ a lost connection mid-flight.]
      internals: no table, no handler, no persistence assumption crosses this
      line. An interface the experience needs and the service does not offer is a
      CONTRACT DELTA raised back to the service lane, never a workaround in the
-     client. -->
+     client. The OPERATION ID is the one backend-plan.md §3 gives the endpoint —
+     the name implement finds it by in the exported API document, and checks
+     before generating. `—` when no service plan names it yet, with a §8 DA-n. -->
 
-| Screen / component | Operation | Sends (field shape) | Receives (field shape) | Failure handling | Serves |
-|---|---|---|---|---|---|
-| `[Screen]` | `[operation]` | [field: type, …] | [field: type, …] | [the §4 state it produces] | FR-[nnn] · IC-[nnn] |
+| Screen / component | Operation id | Operation | Sends (field shape) | Receives (field shape) | Failure handling | Serves |
+|---|---|---|---|---|---|---|
+| `[Screen]` | `[OperationId]` | `[operation]` | [field: type, …] | [field: type, …] | [the §4 state it produces] | FR-[nnn] · IC-[nnn] |
 
 **Write semantics**: [per mutating operation — optimistic or pessimistic, what
 it invalidates, and how an optimistic update rolls back.]

package/assets/.claude/skills/appweaver/SKILL.md

@@ -1,55 +1,16 @@
 ---
 name: "appweaver"
-description: "Parametric launcher (Claude Code): run ANY converted aw-spec skill on the aw-orchestrator under one of the 4 strategies (agent [default], spawn, sdk, sdk-apply)."
-argument-hint: "<skill> [strategy] [input…] — e.g. 'select-domain', 'specify spawn Build an order API', 'analyze-slice'"
-compatibility: "Requires .appweaver/orchestrator/ and the claude CLI on PATH"
+description: "Parametric launcher: run ANY converted aw-spec skill on the aw-orchestrator under one of the 4 strategies (agent [default], spawn, sdk, sdk-apply)."
+argument-hint: "<skill> [strategy] [input…] — e.g. 'select-stack', 'specify spawn Build an order API', 'analyze-slice'"
+compatibility: "Requires .appweaver/orchestrator/ and python3"
 user-invocable: true
 disable-model-invocation: false
 ---
 
-# Orchestrator Skill Launcher
+# AppWeaver launcher
 
-Runs one converted `aw-spec-*` workflow on the shared, agent-agnostic engine. All orchestration and **all context management live in the workflow YAML + engine** (`.appweaver/orchestrator/orchestrator.py`): the interpreter assembles the COMPLETE payload (system + user) for every request; you never author generation context yourself. Execution follows the chosen strategy; the checkpoint channel carries every human-facing interaction regardless of strategy.
+Read `.appweaver/orchestrator/LAUNCHER.md` and follow it exactly.
 
-- **Engine + workflows (common, shared by all agents):** `.appweaver/orchestrator/orchestrator.py`, `.appweaver/orchestrator/workflows/aw-spec-<skill>.orch.yaml`, shared modules in `.appweaver/orchestrator/modules/`, shared scripts in `.appweaver/scripts/`
-- **This agent's transport profile:** `.claude/agent.json`
+Several agents read this folder, so this launcher names no agent: find the row for the agent you are in the profile table of `LAUNCHER.md` — that row is your transport profile. If you have no row, only the `agent` strategy is available.
 
-  > Claude Code spawns via the `claude -p` CLI (native `--system-prompt`,
-  > `--tools`, and `--bare` isolation). Its `sdk` block declares the SDK the
-  > `sdk`/`sdk-apply` strategies import (`claude-agent-sdk`) and the adapter
-  > (`.appweaver/orchestrator/adapters/claude_agent_sdk.py`, shared per-SDK)
-  > that owns its calling convention.
-
-## Execution Steps
-
-1. **Parse Arguments** (`<skill> [strategy] [input…]`):
-   - `skill` (required): the aw-spec skill name, e.g. `demo`, `select-domain`, `foundation`, `specify`, `design`, `implement`, `build`. Resolve the workflow file `.appweaver/orchestrator/workflows/aw-spec-<skill>.orch.yaml`. If it does not exist, list the available `aw-spec-*.orch.yaml` files in that folder and stop.
-   - `strategy` (optional, one of `agent`, `spawn`, `sdk`, `sdk-apply`; default `agent` — YOU fulfill each generation through the checkpoint channel, no profile needed): who executes each generation. Always pass `--strategy <strategy>`.
-   - Everything after the strategy is the user input: pass it as `--input "<text>"` (omit when empty).
-   - `--agent-profile .claude/agent.json` is required for `spawn`, `sdk`, and `sdk-apply` (`agent` needs no profile). If the SDK package isn't installed, add `--sdk-install`.
-   - **Always** pass `--checkpoint .appweaver/orchestrator/.state/<skill>.state.json` — for EVERY strategy. Converted skills contain interactive steps (questions, selections, hooks); the checkpoint is how they reach you and the user. Strategies only govern who generates.
-   - `spawn` may also add `--isolation bare|fresh` and `--model <name>`; `sdk`/`sdk-apply` accept `--model <name>`.
-
-2. **Run the Interpreter**:
-   ```bash
-   python3 .appweaver/orchestrator/orchestrator.py \
-     .appweaver/orchestrator/workflows/aw-spec-<skill>.orch.yaml \
-     --strategy <strategy> \
-     --checkpoint .appweaver/orchestrator/.state/<skill>.state.json \
-     [--agent-profile .claude/agent.json]   # spawn, sdk, sdk-apply \
-     [--input "<user input>"] \
-     --json
-   ```
-
-3. **Handle the Suspend/Resume Loop** — whenever the command exits with code `2`, read the printed `pending` JSON and dispatch on `pending.kind`; fulfill it, write the response to `pending.response_path`, then re-run the SAME command. Repeat until exit `0` (done) or `1` (stopped by a gate).
-   - **`ask`** — ask the USER the `prompt` with the listed `options` (use your question tool). Write the chosen answer as PLAIN TEXT to `response_path` (comma-separated values when `multi` is true).
-   - **`select`** — ask the USER to pick ONE of `options`; write the chosen value as plain text to `response_path`.
-   - **`hook`** — run each MANDATORY hook in `hooks` (each is a slash command of THIS agent) in this conversation; optional hooks at your discretion. Then write `done` to `response_path`.
-   - **`author`** — read `system_path` + `user_path` and treat them as your ONLY standards and context. Author the COMPLETE content of the file named in `target` and write it — content ONLY, no commentary, no code fence — to `response_path`. Do NOT write the target file yourself; the interpreter does that.
-   - **`agent_generate`** — read `system_path` + `user_path`; perform the task YOURSELF with the listed `tools` within `permission_mode`; write your full final reply — ending with the required ```json fence — to `response_path`.
-   - **`agent_query` / `agent_review`** — same as above but READ-ONLY (do not modify files); the reply must end with the required ```json fence.
-   - **`apply`** — an isolated generation already decided the changes: read `artifact_path` and write its file contents EXACTLY to the paths it names, then write the confirmation ```json fence to `response_path`.
-   - If `pending.note` is present, your previous response was rejected — follow the note and rewrite `response_path`.
-
-4. **Report**:
-   Report the final JSON (`status`, `outputs`, and any `reason`) to the user. On `stopped`, relay the gate message verbatim — it tells the user what to fix or run first.
+The arguments are the text the user typed after `/appweaver`.

package/assets/foundations/dotnet/ModularMonolith/ModularMonolith.Reference.rules.json

@@ -0,0 +1,31 @@
+{
+  "format": "aw-spec-pack-rules/v1",
+  "rules": [
+    {
+      "path": "src/AppWeaver.ModularMonolith.Infrastructure/DatabaseContext/ApplicationDbContext.cs",
+      "action": "merge",
+      "note": "The base project's DbContext has the full OnModelCreating and no DbSet<> properties; the sample's has the sample's DbSet<> properties, its own usings, and nothing else.",
+      "instruction": [
+        "Produce one ApplicationDbContext based on the EXISTING file (the base project's DbContext):",
+        "- add every using directive the INCOMING file has that the EXISTING file lacks;",
+        "- insert every INCOMING `public DbSet<...>` property, with any comment above it, as one block right after the class's opening brace (before OnModelCreating);",
+        "- keep everything else in the EXISTING file unchanged."
+      ]
+    },
+    {
+      "path": "src/AppWeaver.ModularMonolith.Domain/Interfaces/IApplicationDbContext.cs",
+      "action": "merge",
+      "note": "The base project's interface has the usings, the namespace and SaveChangesAsync; the sample's has only the sample's DbSet<> properties.",
+      "instruction": [
+        "Produce one IApplicationDbContext based on the EXISTING file (the base project's interface), keeping its using directives, its namespace and SaveChangesAsync:",
+        "- insert every INCOMING `DbSet<...>` property, with any comment above it, as one block right after the interface's opening brace (before SaveChangesAsync);",
+        "- keep everything else in the EXISTING file unchanged."
+      ]
+    },
+    {
+      "path": "src/AppWeaver.ModularMonolith.Domain/AppWeaver.ModularMonolith.Domain.csproj",
+      "action": "replace",
+      "note": "The sample ships the Domain project file too; its copy is written over the base project's."
+    }
+  ]
+}

package/assets/foundations/dotnet/ModularMonolith/ModularMonolith.lane.json

@@ -0,0 +1,6 @@
+{
+  "format": "aw-spec-pack-lane/v1",
+  "note": "How this pack's service is started on its own to export its API document. The AppHost (the lane's run command) needs Docker for its infrastructure; the API project alone runs on the local infrastructure. Development keeps HTTPS redirection off so the document is served over http. The pack's configuration carries no ConnectionStrings:SqliteConnection, which the local infrastructure reads, so the command supplies one.",
+  "contract_run": "dotnet run --project src/AppWeaver.ModularMonolith.API -- --environment Development --urls http://localhost:5000 --ConnectionStrings:SqliteConnection \"Data Source=App_Data/app.db\"",
+  "contract": "http://localhost:5000/swagger/v1/swagger.json"
+}

package/assets/foundations/dotnet/VerticalSlice/VerticalSlice.Reference.rules.json

@@ -0,0 +1,16 @@
+{
+  "format": "aw-spec-pack-rules/v1",
+  "rules": [
+    {
+      "path": "src/AppWeaver.VerticalSlice.Service/Infrastructure/ApplicationDbContext.cs",
+      "action": "merge",
+      "note": "The base project's DbContext has the full OnModelCreating and no DbSet<> properties; the sample's has the sample's DbSet<> properties, its own usings, and nothing else.",
+      "instruction": [
+        "Produce one ApplicationDbContext based on the EXISTING file (the base project's DbContext):",
+        "- add every using directive the INCOMING file has that the EXISTING file lacks;",
+        "- insert every INCOMING `public DbSet<...>` property, with any comment above it, as one block right after the class's opening brace (before OnModelCreating);",
+        "- keep everything else in the EXISTING file unchanged."
+      ]
+    }
+  ]
+}

package/assets/foundations/dotnet/VerticalSlice/VerticalSlice.lane.json

@@ -0,0 +1,6 @@
+{
+  "format": "aw-spec-pack-lane/v1",
+  "note": "How this pack's service is started on its own to export its API document. The AppHost (the lane's run command) needs Docker for Postgres and Redis; the Service project alone runs on SQLite. Development keeps HTTPS redirection off so the document is served over http. The pack's configuration carries no ConnectionStrings:SqliteConnection, which the local infrastructure reads, so the command supplies one.",
+  "contract_run": "dotnet run --project src/AppWeaver.VerticalSlice.Service -- --environment Development --urls http://localhost:5000 --ConnectionStrings:SqliteConnection \"Data Source=App_Data/app.db\"",
+  "contract": "http://localhost:5000/swagger/v1/swagger.json"
+}

package/assets/foundations/foundation.spec.template.txt

@@ -0,0 +1,98 @@
+# kind: backend
+# profiles: dotnet-webapi
+# title: <one line shown in the /appweaver foundation pick list>
+# contract-run: dotnet run --project src/<App>.Api -- --environment Development --urls http://localhost:5000
+# contract: http://localhost:5000/swagger/v1/swagger.json
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# FOUNDATION SPEC TEMPLATE — how to describe a base project for /appweaver foundation
+#
+# A spec is the alternative to a pack. A pack (<Name>.pack.txt) is a verified project
+# unpacked byte-for-byte; a spec DESCRIBES the project, and an agent builds it into the
+# lane root folder when the operator picks it. Use one where no pack ships for the
+# stack, or where the project is easier to describe than to keep as a frozen copy.
+#
+# WHERE IT GOES. Copy this file to foundations/<ecosystem>/<Name>/<Name>.spec.txt —
+# <ecosystem> is the `ecosystem` of the stack profile (.appweaver/stack-profiles/*.json:
+# dotnet, java, node, python, go …). A directory may hold a pack, specs, or both; every
+# *.spec.txt in it is its own entry, named after the file. It is listed for a lane only
+# when its header admits that lane:
+#
+#   # kind:      backend | frontend   (absent = backend)
+#   # profiles:  stack-profile ids, comma-separated (absent = any profile of that kind
+#                in the ecosystem — say which, because `node` covers Next.js, Angular,
+#                Vue, SvelteKit and the Express backend alike)
+#   # title:     the label in the pick list
+#
+# Three more header lines carry the API CONTRACT between the lanes. /appweaver foundation
+# records them on the lane in .appweaver/stacks.json once the project is built, and
+# /appweaver implement uses them to export the service's OpenAPI document and generate the
+# frontend's client from it before it generates the frontend. A spec that leaves one out
+# is asked for it at the end of the build; leaving the answer empty keeps the stack
+# profile's default.
+#
+#   # contract-run:  (backend) the command that starts the API ON ITS OWN — no
+#                    orchestration host, nothing it needs that is not on this machine —
+#                    run in the lane root folder. <App> stands for the app name given
+#                    at /appweaver foundation
+#   # contract:      (backend) the URL that running API serves its OpenAPI document at
+#   # client:        (frontend) the command that generates the API client from that
+#                    document; {{contract}} in it stands for the document's path
+#
+# The header is the leading block of `#` lines; the first line that does not start with
+# `#` ends it. Everything after this header block is the spec itself, written for the
+# agent that builds the project — be concrete. The same shape works for a spec given at
+# the [manual spec] prompt (as a file path, or pasted as text).
+#
+# WHAT THE AGENT ALREADY KNOWS, so the spec need not repeat it: the lane root folder (the
+# WHOLE project goes inside it: build files, source and tests), its test
+# path inside that folder, and its build command, which runs in that folder (from
+# .appweaver/stacks.json), the project name the operator entered, and the technical rules
+# the selected project maps under `## /aw-spec-foundation-backend` or
+# `## /aw-spec-foundation-frontend` in its tech-rule-bindings.md. Where this spec is
+# silent the agent follows those rules; where the two disagree the spec wins and the
+# agent names the conflict. Paths below are relative to the lane root folder.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# <Project kind> foundation — <stack and version>
+
+## Purpose
+One or two sentences: what this base project is for, and what it deliberately leaves out
+(business features come later from /appweaver implement).
+
+## Create
+The commands that create the project, in order, and where their output must land.
+- e.g. `dotnet new webapi -n <ProjectName> -o src/<ProjectName>.Api`
+- e.g. a solution file at the top of the lane root folder, referencing every project
+
+## Packages
+Exact packages (and versions where it matters), split by project.
+
+## Layout
+The folder structure the project starts with, as a tree. Name the folders feature code will
+later go into, even when they start empty (add a .gitkeep).
+
+## Starter files
+Each file the base project needs beyond what the tools generate — what it contains, not
+just its name: configuration, the composition root, a health endpoint, the error-handling
+middleware, a sample test that proves the test project runs.
+
+## Configuration
+Settings files, environment variables, ports, connection strings (placeholders, never
+secrets).
+
+## API document
+Backend: the API serves its OpenAPI document at the `# contract:` URL, and the
+`# contract-run:` command starts it on its own on the port that URL names — over http, with
+every setting it needs to start present in its configuration (a local database file, not a
+container). Frontend: say which tool the `# client:` command runs, so it is installed as a
+development dependency.
+
+## Tests
+The test project(s): framework, where they live (the lane's test path), and the one test that
+must pass on a fresh scaffold.
+
+## Done when
+How to confirm the scaffold works — the lane's build passes, the test command passes, the app
+starts and answers a named URL (for a backend, the `# contract:` URL, started with the
+`# contract-run:` command).

package/assets/foundations/java/Hexagonal/Hexagonal.lane.json

@@ -0,0 +1,6 @@
+{
+  "format": "aw-spec-pack-lane/v1",
+  "note": "How this pack's service is started on its own to export its API document. It is one Maven module on a local H2 file database, so the Maven wrapper starts it as it is; springdoc serves the OpenAPI document at /v3/api-docs. The port is pinned so the URL below is where it answers.",
+  "contract_run": "./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8080",
+  "contract": "http://localhost:8080/v3/api-docs"
+}

package/assets/foundations/java/Hexagonal/Hexagonal.pack.txt

@@ -8,7 +8,7 @@
 # --- Java foundation replacement contract ---
 #   Java content: io.appweaver -> <lowercase-app-name>
 #   Java path:    io/appweaver -> <lowercase-app-name>
-#   Application directory preserves the user-provided name.
+#   Unpacked into --out-dir as-is: that directory is the Maven module.
 # ============================================================
 
 <<<DIR path=".mvn">>>
@@ -657,6 +657,13 @@ Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"
 			<artifactId>spring-boot-starter-web</artifactId>
 		</dependency>
 
+		<!-- OpenAPI document at /v3/api-docs and Swagger UI at /swagger-ui.html -->
+		<dependency>
+			<groupId>org.springdoc</groupId>
+			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+			<version>3.1.1</version>
+		</dependency>
+
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-data-jpa</artifactId>

package/assets/foundations/java/Hexagonal/unpack-foundation.sh

@@ -206,11 +206,10 @@ apply_repl() {
 
 # ----------------------------------------------------------- output root ------------
 
-if [ "$OUT_DIR" = "." ]; then
-  OUT_ROOT="$TARGET_APP_NAME"
-else
-  OUT_ROOT="$OUT_DIR/$TARGET_APP_NAME"
-fi
+# The pack is the Maven module itself (pom.xml, mvnw, src/main/java, src/test/java), and it
+# lands in --out-dir exactly as packed: that directory IS the module. The app name renames
+# the Java package; it does not add a folder.
+OUT_ROOT="$OUT_DIR"
 
 # ----------------------------------------------------------- parse pack blocks -------