@abarcenas/ai-workflow-template 1.44.0 → 1.46.0

package/.agents/skills/domain-modeling/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the *active* discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `GLOSSARY.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── GLOSSARY.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `GLOSSARY-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── GLOSSARY-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── GLOSSARY.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── GLOSSARY.md
+│       └── docs/adr/
+```
+
+Create files lazily: only when you have something to write. If no `GLOSSARY.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `GLOSSARY.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account': do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"
+
+### Update GLOSSARY.md inline
+
+When a term is resolved, update `GLOSSARY.md` right there. Don't batch these up: capture them as they happen. Use the format in [GLOSSARY-FORMAT.md](./GLOSSARY-FORMAT.md).
+
+`GLOSSARY.md` should be totally devoid of implementation details. Do not treat `GLOSSARY.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/.agents/skills/grill-me/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-me
+description: A relentless interview to sharpen a plan or design.
+disable-model-invocation: true
+---
+
+Call the Skill tool with "grilling".

package/.agents/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+disable-model-invocation: true
+---
+
+Call the Skill tool twice, for "grilling" and "domain-modeling".

package/.agents/skills/grilling/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

package/.agents/skills/prototype/LOGIC.md

@@ -0,0 +1,67 @@
+# Logic Prototype
+
+A single, self-contained HTML file (a **shareable demo**) that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape**: the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it's one file with nothing to install, you can hand it to a non-developer (a designer, a PM, a domain expert) and let them feel the model for themselves. So it speaks their language, not the code's.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like," this is the wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, at the top of the demo (in a visible intro, not just a comment). A logic prototype that answers the wrong question is pure waste, so make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Isolate the logic in a portable module
+
+Put the actual logic (the bit that's answering the question) in a single `<script>` block written as a small, pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway; this module isn't.
+
+The right shape depends on the question:
+
+- **A pure reducer**: `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine**: explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state, just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a page. Keep it pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the other direction. This is what makes the prototype useful past its own lifetime: once the question's answered, the validated reducer / machine / function set lifts into the real module on its own.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS: no framework, no bundler, no server, everything inline so it opens by double-click and survives being emailed around. Anyone should be able to run it by opening it.
+
+Write it for a non-developer. Every label is in **domain language**, not code: buttons and state read like the business, not the reducer. Explain in plain words what's happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state**: the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call out what just changed.
+3. **Free-play buttons**: one button per action, always available, so anyone can poke at the model in any order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs**: a set of **scenarios**, one per tab. Each tab holds a short plain-language description of the scenario (the situation it sets up and what to watch for) and underneath it, the ordered **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same way every time.
+
+Choose scenarios that demonstrate the awkward cases, the ones hard to reason about on paper: the happy path, a tricky edge case, an attempt at something that should be illegal.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no gimmicks: nothing that competes with the state and the buttons.
+
+### 4. Hand it over
+
+Send them the file, or open it for them. They'll click through the walkthroughs and free-play whenever they get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different"; those are the bugs in the _idea_, which is the whole point. If they want new actions or a new scenario, add them. Prototypes evolve.
+
+### 5. Capture the answer and the prototype
+
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the HTML shell rides along to the throwaway branch that keeps the prototype as a primary source, and being one self-contained file, it stays trivially re-runnable there.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button handlers, it's no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a React app or a dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The logic module behind it is the bit worth keeping.

package/.agents/skills/prototype/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: prototype
+description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## Pick a branch
+
+Identify which question is being answered, using the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a single shareable HTML file (free-play buttons plus tabbed guided walkthroughs) that pushes the state machine through cases that are hard to reason about on paper, and that a non-developer can drive.
+- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts, so getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+
+## Rules that apply to both
+
+1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious, but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
+2. **Trivial to run.** A UI prototype starts from one command in the project's task runner: `pnpm <name>`, `python <path>`, `bun <path>`, etc. A logic demo is a single HTML file the user double-clicks. Either way, no thinking required to start it.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE, wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
+6. **Capture it when done.** Fold any validated decision into the real code, then capture the prototype itself as a **primary source**: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too (the verdict and the question it settled) in the issue or a commit. The main branch keeps only the validated decision.

package/.agents/skills/prototype/UI.md

@@ -0,0 +1,112 @@
+# UI Prototype
+
+Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
+
+If the question is about logic/state rather than what something looks like, this is the wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Two sub-shapes: strongly prefer sub-shape A
+
+A UI prototype is much easier to judge when it's **butting up against the rest of the app**: real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
+
+### Sub-shape A: adjustment to an existing page (preferred)
+
+The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay. Only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
+
+If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow), it's still sub-shape A. Mount the variants inside the host page.
+
+### Sub-shape B: a new page (last resort)
+
+Only use this when the thing being prototyped genuinely has no existing page to live inside (e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible).
+
+Create a **throwaway route** following whatever routing convention the project already uses. Don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
+
+Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
+
+In both sub-shapes the floating bottom bar is identical.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise, so cap there.
+
+Write down the plan in one line, in the prototype's location or a top-of-file comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+This works whether the user is here to push back or not.
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
+- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different**: different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher component on the route:
+
+```tsx
+// pseudo-code, adapt to the project's framework
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
+  </>
+);
+```
+
+For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
+
+For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow**: cycles to the previous variant (wraps around).
+- **Variant label**: shows the current variant key and, if the variant exports a name, that name too. e.g. `B (Sidebar layout)`.
+- **Right arrow**: cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param (use the framework's router, e.g. `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
+- Hidden in production builds: gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
+
+Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
+
+### 5. Hand it over
+
+Surface the URL (and the `?variant=` keys). The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"**, which is the actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, capture the answer (which variant and why), then capture the prototype the way the [SKILL](SKILL.md) describes. Fold the winner into the real code and move the rest onto the throwaway branch, not into main:
+
+- **Sub-shape A**: fold the winner into the existing page; drop the losing variants and the switcher from main.
+- **Sub-shape B**: promote the winning variant to a real route; drop the throwaway route and the switcher from main.
+
+The full set of variants is the primary source, so it lands on the throwaway branch, not the bin, since variant components and the switcher left in the main branch rot fast and confuse the next reader.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub: the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

package/.github/workflows/npm-publish.yml

@@ -22,6 +22,16 @@ jobs:
       - name: Run unit tests
         run: npm run test:unit
 
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run Playwright tests
+        run: npm test
+        env:
+          CI: true
+          # The config defaults to headed mode; CI runners have no display.
+          HEADLESS: 'true'
+
       - name: Publish to npm
         run: npm publish --access public
         env:

package/.github/workflows/pr-test.yml

@@ -21,3 +21,34 @@ jobs:
 
       - name: Run unit tests
         run: npm run test:unit
+
+  playwright:
+    runs-on: ubuntu-latest
+    env:
+      CI: true
+      # The config defaults to headed mode; CI runners have no display.
+      HEADLESS: 'true'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run Playwright tests
+        run: npm test
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7

package/.opencode/agents/architect.agent.md

@@ -6,7 +6,6 @@ permission:
   search: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Architect - System Design

package/.opencode/agents/coder.agent.md

@@ -8,7 +8,6 @@ permission:
   execute: "allow"
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Coder - Implementation

package/.opencode/agents/deployer.agent.md

@@ -9,7 +9,6 @@ permission:
   "github/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Deployer - Release Engineering

package/.opencode/agents/designer.agent.md

@@ -6,7 +6,6 @@ permission:
   search: "allow"
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Designer - UI/UX

package/.opencode/agents/e2e-tester.agent.md

@@ -7,7 +7,6 @@ permission:
   "chrome-devtools/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # E2E Tester - Browser Automation

package/.opencode/agents/implementer.agent.md

@@ -8,7 +8,6 @@ permission:
    execute: allow
    "memory-bank/*": allow
    "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Implementer - Implementation Planning

package/.opencode/agents/orchestrator/feature-pipeline.agent.md

@@ -8,7 +8,6 @@ permission:
   todo: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Feature Pipeline

package/.opencode/agents/orchestrator/orchestrator.agent.md

@@ -13,7 +13,6 @@ permission:
   "chrome-devtools/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Orchestrator - Multi-Agent Workflow
@@ -26,12 +25,13 @@ You are a master orchestration agent that coordinates specialized sub-agents to
 - **basePath**: Root directory for the work (defaults to current workspace)
 - **logFile**: Path to the orchestration log (defaults to `docs/.orchestrator-log.md`)
 - **autoConfirm**: If `true`, execute all pipeline steps without pausing. If `false`, ask the user before each delegation. (Default: `false`)
-- **confirmationGates**: Agents whose output requires mandatory user confirmation before the pipeline advances to the next step. Confirmation is requested *after* the agent produces its output, regardless of `autoConfirm`. Default: `["researcher", "implementer"]`
+- **confirmationGates**: Agents whose output requires mandatory user confirmation before the pipeline advances to the next step. Confirmation is requested *after* the agent produces its output, regardless of `autoConfirm`. Default: `["researcher", "implementer", "scope"]`. `scope` is included because its output is a set of open questions that only the user can answer — the gate is structural, not merely a post-output checkpoint (see Step 2a).
 
 ## Sub-Agent Registry
 
 | Role | Agent File | subagent_type | Typical Tools | When to Deploy |
 |---|---|---|---|---|
+| scope | `scope.agent.md` | `scope` | read, search, edit, skill, question (no `execute` — never builds or runs anything) | Underspecified request, vague or unmeasurable success criteria, unknown boundaries, or an explicit request to narrow scope; runs the scoping interview only — never designs or builds |
 | researcher | `researcher.agent.md` | `researcher` | read, search, web, ddg-search/*, context7/* (read-only — no edit, no execute) | Technical unknowns, library evaluation, spike investigation |
 | architect | `architect.agent.md` | `architect` | read, search (no edit — design docs only) | System design, component architecture, data flow planning |
 | implementer | `implementer.agent.md` | `implementer` | read, search, edit, execute | Translating plans into actionable implementation steps |
@@ -83,6 +83,7 @@ All project context reading (memory bank, architecture docs, learned knowledge)
 
 Based on the analysis, build an ordered list of sub-agent delegations. Common patterns:
 
+- **Foggy feature**: scope ⏸️ → researcher ⏸️ → implementer ⏸️ → architect → coder → unit-tester → e2e-tester → reviewer → deployer
 - **Full feature**: researcher ⏸️ → implementer ⏸️ → architect → coder → unit-tester → e2e-tester → reviewer → deployer
 - **Quick fix**: coder → unit-tester → reviewer
 - **Research spike**: researcher ⏸️ → architect
@@ -93,8 +94,71 @@ Based on the analysis, build an ordered list of sub-agent delegations. Common pa
 
 **Note:** ⏸️ marks a *confirmation gate* — the orchestrator will pause after that agent's output and wait for user confirmation before proceeding.
 
+**Scope insertion:** `scope` may also be inserted at the front of *any* pattern above when the request is underspecified. See Step 2a for the exact insertion rule, the always-interactive override, the round-trip protocol, and the prototype hand-off.
+
 You may skip, reorder, or parallelize steps based on the request. Document your reasoning in the log.
 
+### Step 2a: Scope Insertion, Interactivity, and Hand-Off
+
+`scope` is the front door for underspecified work. It narrows the problem through numbered-question rounds and terminates with a spike document (`docs/spike-<feature>.md`) that `researcher` and `implementer` already accept as input. It never designs, plans, or builds.
+
+#### Insertion rule (REQ-09)
+
+Insert `scope` at the front of the pipeline when **any** of these is true:
+
+- The request has no clear specification, or several plausible interpretations.
+- Success criteria are vague or unmeasurable ("make it faster", "clean this up").
+- The boundary of the change is unknown, or the orchestrator cannot name the files/components to change.
+- The user explicitly asks to narrow scope, grill the request, or write a spike first.
+
+Do **not** insert `scope` when **any** of these is true:
+
+- The request carries a concrete spec with testable acceptance criteria.
+- An existing plan or spike file already settles the open decisions.
+- The change is mechanical (rename, version bump, formatting, dependency update) and its scope is unambiguous.
+
+When in doubt, prefer inserting `scope` — a short interview is cheaper than building the wrong feature.
+
+**Execution override:** for a `scope` step, use the round protocol below instead of the generic Step 4 delegation template.
+
+#### Always-interactive rule (REQ-10, D-06)
+
+`scope` is a mandatory pause point **regardless of `autoConfirm`**. `autoConfirm: true` must never skip it, and the orchestrator must never let the agency answer the scope agent's questions on the user's behalf — no "assume reasonable defaults", no inferred answers, no silence-as-consent. A grilling agent that answers its own questions is broken by definition. This is why `scope` is in the `confirmationGates` default list: its gate is structural (the pipeline cannot advance without human answers), not just a post-output checkpoint.
+
+For every scope round, the orchestrator must:
+
+1. Present the returned numbered questions **verbatim** to the user, including each recommended answer.
+2. Collect the user's answers (a bare "yes" accepts the recommendation).
+3. Append the answers to the draft file, delegating that write to a sub-agent if needed — the orchestrator itself never writes files.
+4. Re-delegate with **only the draft path** plus the previous step summary. Do not replay the conversation; the draft is the whole handoff.
+
+#### Round-trip protocol
+
+One delegation is one round. Delegate the round with these inputs:
+
+```text
+Agent: "Scope - Feature Scoping" (.opencode/agents/scope.agent.md)
+work_unit: {feature}
+basePath: {basePath}
+draftPath: docs/spike-<feature>.draft.md
+feature: <feature>
+Previous step context: {previous_step_summary}
+```
+
+The agent returns exactly one of two statuses:
+
+- **`Status: QUESTIONS (round N)`** — relay the questions to the user (see above), record the answers in the draft, then delegate another round with the same `draftPath`. Repeat until termination. Do not cap the number of rounds; the agent decides when the frontier is empty.
+- **`Status: TERMINATED`** — the agent has written `docs/spike-<feature>.md`. Capture the output path and hand that spike to `researcher` as the required input. When the spike's recommended next step says no external evidence is needed, hand it straight to `implementer` instead.
+
+#### Prototype hand-off (REQ-11)
+
+The scope agent never builds prototypes — it has no command-execution permission. When a round returns `prototype needed: <question>`, read the branch that follows it:
+
+- **`logic`** — delegate to `coder` to build a throwaway prototype that answers the state-model or data-flow question.
+- **`UI`** — delegate to `designer` to produce a UI prototype or design spec.
+
+Pass the prototype question, the draft path, and the scope context to the delegate. When the prototype result comes back, append the evidence to the draft (again delegating the write) and re-delegate the scope round with only the draft path, so the agent can record the evidence and recompute its frontier.
+
 ### Step 3: Initialize Log
 
 Create or append to the log file at `{logFile}` with:
@@ -110,7 +174,7 @@ For each step in the pipeline:
 2. **If autoConfirm is true**: Proceed immediately. Log that the step is starting.
 3. Look up the step's `subagent_type` from the Sub-Agent Registry table (e.g., `researcher`, `architect`, `implementer`, `coder`, `designer`, `unit-tester`, `e2e-tester`, `reviewer`, `deployer`, `tracker`).
 4. **If the step is "coder"**: Check whether the latest implementer plan contains parallel batch annotations (look for `**Batch` or `Parallel` in the plan file). See "Parallel Coder Execution" below.
-5. **Otherwise**: Invoke the sub-agent using the Task tool with `subagent_type` matching the step's type (NOT `"general"`) and the following prompt structure:
+5. **Otherwise** (except `scope`, which uses the Step 2a round protocol): Invoke the sub-agent using the Task tool with `subagent_type` matching the step's type (NOT `"general"`) and the following prompt structure:
 
 ```
 This phase must be performed as the agent "{agent_name}" defined in ".opencode/agents/{agent_file}".
@@ -129,7 +193,7 @@ IMPORTANT:
 6. Capture the sub-agent's response summary.
 7. Update the log file with: step name, status (SUCCESS/SKIPPED/FAILED), duration, artifacts produced, key findings.
 8. If a required step fails, stop the pipeline and report to the user.
-9. **Confirmation Gate**: If the current agent is in the `confirmationGates` list (default: `["researcher", "implementer"]`):
+9. **Confirmation Gate**: If the current agent is in the `confirmationGates` list (default: `["researcher", "implementer", "scope"]`):
    - Present the agent's output summary (key findings, files produced, artifacts) to the user.
    - Ask: **"{agent_name} output is ready. Review the summary above. Confirm to proceed to the next step?"**
    - **Do not advance** to the next pipeline step until the user explicitly confirms.

package/.opencode/agents/orchestrator/tdd-orchestrator.agent.md

@@ -8,7 +8,6 @@ permission:
   todo: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # TDD Orchestrator - Test-Driven Development

package/.opencode/agents/plan.agent.md

@@ -9,7 +9,6 @@ permission:
   question: allow
   webfetch: allow
   websearch: allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Plan Mode - Strategic Planning & Architecture Assistant

package/.opencode/agents/researcher.agent.md

@@ -9,7 +9,6 @@ permission:
   "context7/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Technical spike research mode

package/.opencode/agents/reviewer.agent.md

@@ -8,7 +8,6 @@ permission:
   "github/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Reviewer - Code Quality