@nusoft/nuos-build-catalogue 0.21.0 → 0.22.0

package/dist/commands/init.js

@@ -51,7 +51,7 @@ const PROTOCOL_DESCRIPTIONS = {
     'end-of-session': 'Capture what happened, update state, write session log, commit',
     'wu-new': 'File a new work unit through a guided plain-English conversation',
     'persona-new': 'File a new persona by walking the seven dimensions conversationally',
-    'plan-orientation': 'Phase A of planning — project description, personas, the horizon map',
+    'plan-orientation': 'Phase A of planning — project description, tech stack, personas, the horizon map',
     'build-wu': 'Orchestrate a swarm of agents to build one work unit end-to-end',
 };
 const TOOLS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {

package/templates/protocols/build-wu.md

@@ -19,6 +19,7 @@ Also read:
 - The contracts it touches (`docs/build/contracts/`)
 - The architecture files for any modules involved (`docs/build/architecture/`)
 - The relevant design-system pieces if the work unit ships a UI surface
+- `methodfile.json`'s `techStack` section — if `techStack.defined` is `true`, extract the fields now; you'll inject them into every agent prompt in Step 4
 - Run `nuos-catalogue search "<work unit title or outcome>"` to find related prior work
 
 Before spawning any agents, search the cross-agent memory for relevant prior findings:
@@ -61,6 +62,20 @@ Skip steps when context allows — implementation-only WUs skip the architect; b
 
 Use Claude Code's **Task tool**. Each spawn names the agent (`subagent_type`), the model (from `methodfile.json`'s `swarm.models` block — usually leave as default), and the precise input.
 
+**Technical context injection:** If `techStack.defined` is `true` in `methodfile.json`, every agent spawn prompt must open with a "Technical context" block:
+
+```
+**Technical context (from methodfile.json):**
+- Languages: [languages]
+- Frontend: [frontend]
+- Backend: [backend]
+- Database: [database]
+- Deployment: [deployment]
+- External services: [externalServices]
+```
+
+Omit `null` fields. If `techStack.defined` is `false` or the section is absent, note it in the swarm audit entry and suggest the operator define the stack (`/plan-orientation` or edit `methodfile.json` directly) before the next swarm run — agents generating code without a known stack default to generic patterns that often need rework.
+
 **Spawn in parallel where possible.** If two agents can work independently (e.g. tester writing tests while reviewer reads design), spawn them in the same message. Sequential when an agent's output is the next agent's input (architect → coder).
 
 For each spawn:
@@ -141,7 +156,7 @@ Every decision made by any agent during the swarm MUST land in the catalogue bef
 
 ## Cost guidance
 
-A typical full-feature swarm spawning architect (Opus, ~30 min) + coder (Sonnet, ~1 hr) + tester (Sonnet, ~30 min) + reviewer (Sonnet, ~15 min) costs substantially less than running the same work as a continuous Opus conversation. Don't sweat exact figures — the 80/20 split is the lever. If a single work unit's swarm cost is becoming meaningful (>>£10), surface that to the operator before continuing; the WU is probably bigger than scoped.
+A typical full-feature swarm spawning architect (Opus, ~30 min) + coder (Sonnet, ~1 hr) + tester (Sonnet, ~30 min) + reviewer (Sonnet, ~15 min) consumes substantially less of the operator's coding-tool plan budget than running the same work as a continuous Opus conversation. The 80/20 split — heavy reasoning for design and debugging only, lighter models for implementation and verification — is the lever. If a single work unit's swarm is consuming an unusual share of the day's plan budget, surface that to the operator before continuing; the WU is probably bigger than scoped.
 
 ---
 
@@ -158,16 +173,6 @@ If the reviewer returns REQUEST CHANGES, re-spawn the coder ONCE to address the
 
 Don't loop indefinitely. A third reviewer rejection is a signal — the work unit's design, contract, or acceptance criteria need clarification, not more code.
 
-### Cost ceiling per work unit
-
-If the estimated cost (per the swarm audit) is exceeding **£10** for a single work unit:
-
-- STOP the swarm
-- Surface the cost trajectory to the operator
-- Recommend either splitting the work unit into smaller pieces, or accepting the higher cost with their explicit go-ahead
-
-This is a soft ceiling — the operator can authorise more. The point is to make cost visible before it accumulates invisibly.
-
 ### Time ceiling per agent
 
 If a single agent's run is taking substantially longer than its rough budget (architect >1 hr, coder >2 hrs, tester >1 hr, reviewer >30 min):

package/templates/protocols/plan-orientation.md

@@ -45,7 +45,43 @@ Listen. Don't interrupt. When they're done, summarise back in 2-3 sentences in y
 
 When the description is settled, **write it into `STATE.md`'s "What is currently in flight" section** — replacing the placeholder. Keep their voice; don't make it sound corporate. Show them the file path and confirm it's saved.
 
-## Step 3 — One persona, then one or two more (15-20 min)
+## Step 3 — Tech stack (5 min)
+
+Now ask what they're building it with:
+
+> "Before we meet the people your project is for — quickly, what are you building it with? Language, framework, database, where it'll run. If you know already, brilliant. If you haven't decided, just say so and we'll note it as an open question."
+
+Listen and capture what they give you. Common patterns:
+- *"Next.js, PostgreSQL, deployed on Vercel"* → frontend + database + deployment all filled
+- *"React Native with Firebase"* → frontend + database/backend filled
+- *"Not sure yet"* → set `defined: false`, file a Q-NNN
+
+**Write the result to `methodfile.json` now**, under the `techStack` section:
+
+```json
+{
+  "techStack": {
+    "defined": true,
+    "languages": ["TypeScript"],
+    "frontend": "Next.js 15 (App Router)",
+    "backend": "Next.js API Routes / Server Actions",
+    "database": "PostgreSQL (Supabase)",
+    "deployment": "Vercel",
+    "externalServices": ["Stripe"],
+    "notes": null
+  }
+}
+```
+
+Fill in what you know; set unknown fields to `null`. If nothing is settled, set `defined: false`, leave all fields null, and file a Q-NNN open question: *"Tech stack not yet decided — revisit before Phase B."*
+
+Show the operator the updated `methodfile.json` and confirm it saved. Tell them:
+
+> *"This means every agent we spawn later will know what it's building against — language, framework, where it runs. Just a few fields, but it prevents a lot of wrong output later."*
+
+**Drift discipline:** partial information is fine and still valuable. An operator who says *"definitely Next.js, not sure about the database yet"* should have `frontend: "Next.js"`, `database: null`, `defined: true`. Partial is better than undefined.
+
+## Step 4 — One persona, then one or two more (15-20 min)
 
 Tell the operator what's coming:
 
@@ -59,7 +95,7 @@ When P001 is filed, surface it and ask:
 
 If yes, run `/persona-new` again. Aim for **1-3 total** — more than 3 in Phase A usually means the project is overscoped; file the rest as open questions and revisit later.
 
-## Step 4 — Map 1: The Horizon (8-10 min)
+## Step 5 — Map 1: The Horizon (8-10 min)
 
 When the personas are filed, transition:
 
@@ -75,7 +111,7 @@ Use the template at `docs/build/maps/01-template.md`. Walk through its sections
 
 Write the map to `docs/build/maps/01-the-horizon.md`. Show them the file path and confirm.
 
-## Step 5 — Open questions (2 min)
+## Step 6 — Open questions (2 min)
 
 Pass over the conversation looking for anything the operator wasn't sure about. For each:
 
@@ -84,7 +120,7 @@ Pass over the conversation looking for anything the operator wasn't sure about.
 
 > "I noticed a few things you weren't sure about yet — [list]. I've filed them as open questions so we'll come back to them. Two of them affect Phase B (Architecture), so we'll definitely hit them next session."
 
-## Step 6 — Close (2 min)
+## Step 7 — Close (2 min)
 
 Update STATE.md:
 
@@ -96,6 +132,7 @@ Then tell the operator what they now have:
 
 > "You've got your first catalogue substrate:
 >
+> - **Tech stack** defined in `methodfile.json` — (or flagged as an open question if not yet settled)
 > - **[N] personas** in `docs/build/personas/` — these anchor every later decision
 > - **Map 1** at `docs/build/maps/01-the-horizon.md` — the whole-project picture
 > - **[N] open questions** in `docs/build/open-questions/` — these are what we'll resolve as planning continues

package/templates/protocols/wu-new.md

@@ -42,6 +42,8 @@ For infrastructure work, persona / trigger / walkthrough are marked `N/A — inf
 
 ## Step 4 — File the work unit
 
+Before writing the file, check `methodfile.json`'s `techStack.defined`. If it's `false` or the field is absent, tell the operator: *"I notice the tech stack isn't defined yet — that normally happens during Phase A planning. Want to define it now, or shall I file an open question?"* Either way, continue filing the work unit. If `defined` is `true`, the acceptance criteria may reference the stack where relevant (e.g. *"renders correctly with Next.js App Router SSR"*).
+
 1. **Number it.** Scan `docs/build/work-units/` and `docs/build/work-units/done/` for the highest existing 3-digit prefix; new number is max + 1.
 2. **Slugify the title.** Lowercase; dashes for spaces; no special characters; cap at 60 chars.
 3. **Write the file** at `docs/build/work-units/NNN-slug.md`. Use `001-template-simple.md` for the simple shape, `001-template-full.md` for the full shape.

package/templates/starter-kit/methodfile.json

@@ -9,6 +9,16 @@
     "tagline": "{{PROJECT_TAGLINE}}",
     "domain": "{{PROJECT_DOMAIN}}"
   },
+  "techStack": {
+    "defined": false,
+    "languages": [],
+    "frontend": null,
+    "backend": null,
+    "database": null,
+    "deployment": null,
+    "externalServices": [],
+    "notes": null
+  },
   "catalogue": {
     "root": "docs/build/",
     "registers": {