@williambeto/ai-workflow 1.18.7 → 1.18.9

package/CHANGELOG.md

@@ -5,7 +5,23 @@ All notable changes to AI Workflow Kit (`ai-workflow`) are documented in this fi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.18.9] - 2026-05-21
+
+### Removed
+
+- **Consumer `workflow:validate` and `workflow:doctor` scripts**: removed thin wrapper aliases from consumer `package.json`. These provided marginal value over direct commands (`npm run validate`, `npx ai-workflow doctor`). Removed `merge-package-json.js`, updated `init.js`, `doctor.js`, `templates.js`, and all documentation references.
+
+## [1.18.8] - 2026-05-20
+
+### Added
+
+- **Discovery gate enforcement**: `opencode/agents/discovery.md` now explicitly blocks execution/delegation requests and routes them to `orchestrator`.
+- **Discovery routing guard docs**: added explicit guard behavior to `opencode/agents/README.md` and `runbooks/agent-delegation-workflow.md` to keep gate behavior consistent across agent docs and runbooks.
+- **Roadmap simplification phases**: added Phase 17/18/19 plan in `ROADMAP.md` for OpenCode-first focus, artifact surface reduction, and consumer-validation/Napkin hardening.
+
+### Changed
+
+- **Roadmap priority update**: `ROADMAP.md` next sprint, next step, and next recommended PR now point to Phase 17 platform focus as immediate priority.
 
 ## [1.18.6] - 2026-05-20
 

package/docs/full-documentation.md

@@ -330,6 +330,7 @@ Runbooks are operational guides for applying the workflow.
 | [`runbooks/how-to-use-skills.md`](runbooks/how-to-use-skills.md) | Choose specialist skills. |
 | [`runbooks/commands-cheatsheet.md`](runbooks/commands-cheatsheet.md) | Choose Codex/OpenCode commands. |
 | [`runbooks/agent-delegation-workflow.md`](runbooks/agent-delegation-workflow.md) | Use orchestrator and handoff routing. |
+| [`runbooks/use-linear-for-operational-planning.md`](runbooks/use-linear-for-operational-planning.md) | Use Linear as the operational backlog when the roadmap is too large for daily planning. |
 | [`runbooks/validation-checklist.md`](runbooks/validation-checklist.md) | Validate docs, code, PRs, builds, security, accessibility, and deploy readiness. |
 | [`runbooks/team-governance-pr-readiness.md`](runbooks/team-governance-pr-readiness.md) | Define PR readiness and approval policy. |
 | [`runbooks/deploy-checklist.md`](runbooks/deploy-checklist.md) | Prepare deploy, smoke tests, and rollback. |

package/docs/npm-consumer-quickstart.md

@@ -49,8 +49,7 @@ The `init` command creates:
 - managed `opencode.jsonc` sections (for `operational` and `full` profiles);
 - `.codex/prompts/README.md` — Codex prompt entrypoint reference;
 - `opencode/README.md` — OpenCode command reference;
-- starter agent and skill files (for the `full` profile);
-- `npm run workflow:validate` and `npm run workflow:doctor` scripts (when `package.json` exists).
+- starter agent and skill files (for the `full` profile).
 
 Use `--dry-run` to preview changes before writing:
 
@@ -124,7 +123,7 @@ Codex users should treat [`AGENTS.md`](AGENTS.md) as the main operational contra
 After `init` and `doctor`, confirm:
 
 - [ ] `npx @williambeto/ai-workflow doctor` reports no errors
-- [ ] `npm run workflow:validate` passes
+- [ ] `npm run validate` passes (or project-specific validation commands)
 - [ ] `README.workflow.md` exists at the project root
 - [ ] `opencode.jsonc` contains managed sections (for `operational`/`full` profiles)
 - [ ] Codex prompt placeholders exist (`.codex/prompts/`)

package/opencode/agents/README.md

@@ -56,6 +56,11 @@ Orchestrated delivery (automatic routing gates):
 orchestrator (gate A/B/C/D) -> next agent by pass/block result
 ```
 
+Discovery routing guard:
+
+- `discovery` is clarification-only.
+- If execution, file edits, validation execution, release actions, or specialist delegation is requested during discovery, the correct behavior is `Blocked` + handoff to `orchestrator`.
+
 Delegation policy baseline:
 
 - route ownership by dominant task type using `AGENTS.md` delegation matrix;
@@ -88,7 +93,7 @@ Do not use Napkin as a temporary task log, and never store secrets.
 
 | Agent | Purpose | Use when | Should not do |
 | ----- | ------- | -------- | ------------- |
-| `discovery` | Turn vague requests into a discovery brief. | Scope, risks, dependencies, and unknowns are unclear. | Estimate price, implement, or create a detailed technical plan. |
+| `discovery` | Turn vague requests into a discovery brief. | Scope, risks, dependencies, and unknowns are unclear. | Estimate price, implement, edit files, perform execution/delegation routing directly (must return `Blocked` and route to `orchestrator`). |
 | `planner` | Turn approved scope into requirements, specs, technical plans, and PR breakdowns. | Scope is approved and implementation needs a handoff. | Implement. |
 | `implementer` | Implement one selected PR. | A PR plan or handoff exists. | Expand scope or do opportunistic refactors. |
 | `fixer` | Diagnose and fix bugs, regressions, failures, and warnings. | There is broken behavior or failed validation. | Rewrite large areas without evidence. |

package/opencode/agents/discovery.md

@@ -25,14 +25,23 @@ Turn vague client or user requests, screenshots, notes, and rough ideas into a c
 - Surface risks, dependencies, and blocked decisions.
 - Ask up to 5 discovery questions.
 - Recommend the next workflow step.
+- If the request includes implementation, file edits, execution flow, or specialist delegation, return `Blocked` and hand off to `orchestrator`.
 
 ## Constraints
 
 - Do not estimate price directly.
 - Do not implement.
+- Do not edit files or perform write operations.
 - Do not create a detailed technical plan before scope is clear.
 - Do not ask more than 5 questions.
 
+## Gate behavior (defensive)
+
+- Discovery is a clarification step, not an execution owner.
+- If a request requires implementation, review, validation, release actions, or multi-agent routing, output `Blocked` and route to `orchestrator`.
+- Branch gate ownership is `orchestrator` (and step owners). Discovery must not bypass it.
+- If Discovery is ever asked to perform a write operation, stop and return `Blocked` with this minimum safe instruction: run `git status -sb`; if branch is `main`, create/switch to a scoped branch before any edits.
+
 ## Expected output
 
 - Objective
@@ -43,6 +52,8 @@ Turn vague client or user requests, screenshots, notes, and rough ideas into a c
 - Dependencies
 - Up to 5 discovery questions
 - Recommended next step
+- Gate result (`Pass` for discovery-only scope, `Blocked` when execution/delegation is requested)
+- Next agent (`orchestrator`) when blocked
 
 ## Stop conditions
 

package/opencode.jsonc

@@ -142,6 +142,13 @@
       "prompt": "{file:.agents/skills/playwright-cli/SKILL.md}"
     }
   },
+  "mcp": {
+    "linear": {
+      "type": "local",
+      "command": ["npx", "-y", "mcp-remote", "https://mcp.linear.app/mcp"],
+      "enabled": true
+    }
+  },
   "command": {
     "start": {
       "description": "Select default startup route (orchestrator with fallback)",

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.18.7",
+  "version": "1.18.9",
   "name": "@williambeto/ai-workflow",
   "description": "AI Workflow Kit repository for designing and validating AI-assisted software delivery workflows with Codex and OpenCode",
   "license": "MIT",

package/packages/ai-workflow/README.md

@@ -37,8 +37,8 @@ npx @williambeto/ai-workflow init --dry-run
 - `init` creates or merges managed sections in `opencode.jsonc` for operational/full profiles.
 - `full` profile also installs local Codex prompt starter files (`start`, `orchestrate-next`, `plan`, `execute`, `review`, `validate`) under `.codex/prompts/`, plus OpenCode agents and skills under `opencode/agents/` and `.agents/skills/`.
 - conflict backups are stored under `.ai-workflow-backups/` with per-file retention.
-- `workflow:validate` uses `npm run validate --if-present` for safer cross-project onboarding.
-- `doctor` validates profile readiness (`.ai-workflow.json`, workflow scripts, and `opencode.jsonc` managed blocks for operational/full profiles).
+
+- `doctor` validates profile readiness (`.ai-workflow.json` and `opencode.jsonc` managed blocks for operational/full profiles).
 
 ## Profiles
 
@@ -77,6 +77,6 @@ This CLI is in preview. It is validated for:
 - `init --yes`;
 - `doctor`;
 - managed `opencode.jsonc` merge with JSONC comments;
-- `workflow:validate` in projects with a `validate` script.
+- `npm run validate` in projects with a `validate` script.
 
 Before using it in a shared project, inspect generated files and commit only intentional changes.

package/packages/ai-workflow/src/commands/doctor.js

@@ -148,16 +148,10 @@ export async function runDoctor({ cwd }) {
     try {
       const packageJson = await readJson(packageJsonPath);
       const scripts = packageJson.scripts ?? {};
-      if (scripts["workflow:validate"] && scripts["workflow:doctor"]) {
-        console.log("PASS package.json workflow scripts present");
-      } else {
-        hasWarning = true;
-        console.log("WARN package.json missing workflow scripts");
-      }
 
       if (!scripts.validate) {
         hasWarning = true;
-        console.log("WARN package.json has no validate script; workflow:validate may be a no-op");
+        console.log("WARN package.json has no validate script");
       }
     } catch {
       hasFailure = true;

package/packages/ai-workflow/src/commands/init.js

@@ -3,7 +3,6 @@ import path from "node:path";
 import { createInstallPlan } from "../core/install-plan.js";
 import { buildAiWorkflowConfig, getTemplateFiles, isValidProfile } from "../core/templates.js";
 import { exists, writeFileSafe } from "../core/filesystem.js";
-import { mergeWorkflowScripts } from "../core/merge-package-json.js";
 import { createManagedBackup, createManagedPathBackup } from "../core/backup.js";
 import { mergeOpencodeConfig } from "../core/opencode-merge.js";
 import { buildSymlinkEntries, isSymlinkTo } from "../core/symlink-layout.js";
@@ -135,7 +134,6 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
     linkCreated.push(linkPath);
   }
 
-  const mergeResult = await mergeWorkflowScripts(cwd, { dryRun: false });
   const opencodeResult =
     selectedProfile === "minimal"
       ? { reason: "skipped (minimal profile)" }
@@ -143,7 +141,7 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
 
   console.log("Installation complete.");
   console.log(`- profile: ${selectedProfile}`);
-  console.log(`- package.json scripts: ${mergeResult.reason}`);
+
   console.log(`- opencode.jsonc: ${opencodeResult.reason}`);
   console.log(`- symlink layout: ${linkCreated.length > 0 ? `created ${linkCreated.length}` : "already-up-to-date"}`);
   if (backups.length > 0) {
@@ -167,5 +165,4 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
   console.log(`- dependency install: ${noInstall ? "skipped (--no-install)" : "not managed in this step"}`);
   console.log("Next steps:");
   console.log("  npx @williambeto/ai-workflow doctor");
-  console.log("  npm run workflow:validate");
 }

package/packages/ai-workflow/src/core/templates.js

@@ -259,10 +259,6 @@ export function buildAiWorkflowConfig({ profile, managedFiles, managedLinks = []
     managedBlocks: getManagedBlocks(profile),
     fileHashes: {},
     backupsDir: ".ai-workflow-backups",
-    scripts: {
-      "workflow:validate": "npm run validate --if-present",
-      "workflow:doctor": "ai-workflow doctor"
-    },
     compatibility: {
       codex: true,
       opencode: true

package/runbooks/agent-delegation-workflow.md

@@ -14,6 +14,12 @@ Delegate when at least one is true:
 
 Do not delegate for trivial one-file edits that the active primary agent can complete safely.
 
+## Discovery guard (mandatory)
+
+- `discovery` is clarification-only and is not an execution owner.
+- If a request during discovery requires implementation, file edits, validation execution, release actions, or specialist delegation, return `Blocked` and hand off to `orchestrator`.
+- Branch gate ownership remains with `orchestrator` and step owners (`planner`, `implementer`, `fixer`, `reviewer`, `validator`, `release-manager`) before write operations.
+
 ## Delegation matrix
 
 | Task type | Primary owner |

package/runbooks/quick-start-guide.md

@@ -46,13 +46,7 @@ Expected result: `Final status: PASS` or `PASS_WITH_NOTES` with actionable warni
 
 ### 3. Run project validation
 
-If the target project has a `validate` script, run:
-
-```bash
-npm run workflow:validate
-```
-
-If not, use the target project's real checks, for example:
+Run the target project's validation commands, for example:
 
 ```bash
 npm run build
@@ -98,10 +92,10 @@ gh pr create --title "My first PR" --body "## Summary"
 ### 7. Run validation before opening a PR
 
 ```bash
-npm run workflow:validate
+npm run validate
 ```
 
-If `workflow:validate` reports no project `validate` script, include the actual build/lint/test commands you ran in the PR body.
+If the project has no `validate` script, run the actual build/lint/test commands directly and include them in the PR body.
 
 ## Workflow steps reference
 
@@ -212,7 +206,7 @@ npm run validate
 | `npx @williambeto/ai-workflow init --dry-run` | Previews target-project install changes |
 | `npx @williambeto/ai-workflow init --yes` | Installs default workflow assets |
 | `npx @williambeto/ai-workflow doctor` | Checks local workflow installation |
-| `npm run workflow:validate` | Runs target-project validation when available |
+| `npm run validate` | Runs target-project validation when available |
 | `npm run validate` | Runs all repository validations when developing this kit |
 | `npm run test:e2e` | Tests validation scripts |
 | `npm run lint:md` | Checks Markdown formatting |

package/runbooks/use-linear-for-operational-planning.md

@@ -0,0 +1,185 @@
+# Use Linear for Operational Planning
+
+## Purpose
+
+Use this runbook when `ROADMAP.md` is too large for day-to-day planning and the team needs a smaller, current, and auditable operational backlog.
+
+Linear should become the operational source of truth for next work. `ROADMAP.md` remains the strategic and historical source of truth.
+
+## When to use
+
+Use Linear when:
+
+- the next PR is hard to identify from `ROADMAP.md`;
+- roadmap items are complete but still appear in older audit reports;
+- product, planning, implementation, and validation work need one shared queue;
+- each task needs owner, priority, status, acceptance criteria, and delivery evidence.
+
+Skip Linear for one-off local edits where a short checklist is enough.
+
+## Source-of-truth split
+
+| Source | Role |
+| --- | --- |
+| Linear | Current operational backlog, priorities, owners, status, blockers, and next PRs. |
+| GitHub PRs | Delivery evidence, review discussion, changed files, validation results, and merge history. |
+| `ROADMAP.md` | Strategic phases, durable product direction, historical context, and large milestone sequencing. |
+| `CHANGELOG.md` | Published or release-relevant changes. |
+| `docs/reports/` | Audit inputs, scorecards, and evidence-backed recommendations. |
+
+Do not use `ROADMAP.md` alone to decide the next implementation step when Linear exists.
+
+## Linear MCP setup
+
+Linear's remote MCP endpoint is:
+
+```txt
+https://mcp.linear.app/mcp
+```
+
+### Codex
+
+Preferred setup through the Codex CLI:
+
+```bash
+codex mcp add linear --url https://mcp.linear.app/mcp
+```
+
+If this is the first MCP server configured for Codex, enable the remote MCP client in `~/.codex/config.toml`:
+
+```toml
+[features]
+experimental_use_rmcp_client = true
+```
+
+Equivalent manual configuration:
+
+```toml
+[features]
+experimental_use_rmcp_client = true
+
+[mcp_servers.linear]
+url = "https://mcp.linear.app/mcp"
+```
+
+Then authenticate:
+
+```bash
+codex mcp login linear
+```
+
+### OpenCode
+
+This repository includes Linear's remote MCP server in `opencode.jsonc`:
+
+```json
+{
+  "mcp": {
+    "linear": {
+      "type": "remote",
+      "url": "https://mcp.linear.app/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+After updating `opencode.jsonc`, quit and restart OpenCode so the MCP server is loaded from the project config.
+
+Authenticate through OpenCode's MCP/OAuth flow when prompted. Keep authentication state local to the developer machine.
+
+Do not commit personal MCP tokens, OAuth state, API keys, or local `~/.codex/config.toml` files to this repository.
+
+## Recommended Linear project structure
+
+Create one Linear project:
+
+```txt
+Public readiness score improvement
+```
+
+Use these milestones:
+
+1. **Validation trust**
+2. **Onboarding clarity**
+3. **Platform simplification**
+
+Initial issue queue:
+
+| Milestone | Issue | Initial status | Evidence source |
+| --- | --- | --- | --- |
+| Validation trust | Fix E2E validation drift | Done | `npm run test:e2e` passes 14/14; `ROADMAP.md`; `CHANGELOG.md`. |
+| Validation trust | Define stable validation output contract | Todo | `docs/reports/public-readiness-backlog.md`. |
+| Validation trust | Create Go/No-Go public checklist | Todo | `docs/reports/public-readiness-backlog.md`. |
+| Onboarding clarity | Add one adoption decision table | Todo | `docs/reports/project-evaluation.md`. |
+| Onboarding clarity | Reduce entry-doc circular/deep reference chains | Todo | `npm run validate` warnings and audit report. |
+| Platform simplification | Phase 17 PR 1 — Move Codex prompts to legacy | Todo | `ROADMAP.md` Phase 17. |
+| Platform simplification | Phase 17 PR 2 — Simplify `AGENTS.md` to OpenCode-only | Todo | `ROADMAP.md` Phase 17. |
+| Platform simplification | Phase 17 PR 3 — Update README and core docs for single-path | Todo | `ROADMAP.md` Phase 17. |
+
+## Issue template
+
+Use this format for Linear issues:
+
+```md
+## Objective
+
+What outcome should this issue achieve?
+
+## Scope
+
+Included:
+- ...
+
+Not included:
+- ...
+
+## Acceptance criteria
+
+- ...
+
+## Evidence required
+
+- Command:
+- Expected result:
+- Manual review:
+
+## Source context
+
+- ROADMAP.md:
+- Report/backlog:
+- Related PR:
+
+## Risk
+
+Low | Medium | High
+```
+
+## Operating rules
+
+- Keep one Linear issue equivalent to one small PR whenever possible.
+- Mark an issue `Done` only when validation evidence is attached or linked.
+- Link the GitHub PR to the Linear issue before review.
+- If an audit finding is already fixed, close it with evidence instead of recreating work.
+- Update `ROADMAP.md` only for durable strategic changes, phase status changes, or historical milestones.
+- Update `CHANGELOG.md` only for published or release-relevant changes.
+
+## Planning cadence
+
+Before selecting the next PR:
+
+1. Check Linear for highest-priority `Todo` or `Blocked` issues.
+2. Confirm the issue still matches current repository evidence.
+3. If evidence contradicts the issue, update or close the issue before implementation.
+4. Select one issue.
+5. Create a scoped branch.
+6. Implement only that issue.
+7. Attach validation evidence before marking it `Done`.
+
+## Acceptance criteria for Linear adoption
+
+- A Linear project exists for public-readiness score improvement.
+- The known completed E2E drift item is marked `Done` with evidence.
+- Planned score-improvement items are represented as small issues.
+- Each active issue has acceptance criteria and required evidence.
+- `ROADMAP.md` is no longer used as the only day-to-day planning source.

package/packages/ai-workflow/src/core/merge-package-json.js

@@ -1,44 +0,0 @@
-import path from "node:path";
-import { exists, readJson, writeFileSafe } from "./filesystem.js";
-
-export async function mergeWorkflowScripts(cwd, { dryRun = false } = {}) {
-  const packageJsonPath = path.join(cwd, "package.json");
-
-  if (!(await exists(packageJsonPath))) {
-    return { changed: false, reason: "package.json not found" };
-  }
-
-  const packageJson = await readJson(packageJsonPath);
-  const scripts = packageJson.scripts ?? {};
-  const shouldSetDefaultValidate =
-    scripts["workflow:validate"] === undefined ||
-    scripts["workflow:validate"] === "npm run validate";
-
-  const mergedScripts = {
-    ...scripts,
-    "workflow:validate": shouldSetDefaultValidate
-      ? "npm run validate --if-present"
-      : scripts["workflow:validate"],
-    "workflow:doctor": scripts["workflow:doctor"] ?? "ai-workflow doctor"
-  };
-
-  const changed =
-    scripts["workflow:validate"] !== mergedScripts["workflow:validate"] ||
-    scripts["workflow:doctor"] !== mergedScripts["workflow:doctor"];
-
-  if (!changed) {
-    return { changed: false, reason: "workflow scripts already present" };
-  }
-
-  if (dryRun) {
-    return { changed: true, reason: "dry-run" };
-  }
-
-  const next = {
-    ...packageJson,
-    scripts: mergedScripts
-  };
-
-  await writeFileSafe(packageJsonPath, `${JSON.stringify(next, null, 2)}\n`);
-  return { changed: true, reason: "scripts merged" };
-}