@williambeto/ai-workflow 1.18.8 → 1.18.10

package/CHANGELOG.md

@@ -5,7 +5,11 @@ 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
 

package/README.md

@@ -166,7 +166,7 @@ See [`docs/setup-codex-opencode.md`](docs/setup-codex-opencode.md) for installat
 | `@williambeto/ai-workflow` CLI | Preview |
 | Stack variants and examples | Reference — adapt to the target project |
 
-Suitable for **private preview** with developers who accept validation-first workflow assets and can report rough edges. Not ready for broad public announcement until the final public-readiness audit confirms no high-severity blockers remain.
+Suitable for developers and teams who want validation-first AI workflow assets and accept that the CLI, OpenCode integration, and stack variants are still evolving. Use GitHub issues for questions, bugs, and improvement proposals.
 
 ## Current limitations
 
@@ -176,6 +176,8 @@ Suitable for **private preview** with developers who accept validation-first wor
 
 See [`ROADMAP.md`](ROADMAP.md) for planned improvements.
 
+Before changing repository visibility or making a major public-facing release, use [`runbooks/publication-readiness-checklist.md`](runbooks/publication-readiness-checklist.md).
+
 ## Start now
 
 1. Pick one small feature.

package/checklists/change-spec-readiness-checklist.md

@@ -0,0 +1,34 @@
+# Change Spec Readiness Checklist
+
+Use this checklist before implementation starts.
+
+## Clarity and scope
+
+- [ ] Objective is clear and measurable.
+- [ ] Problem is explicit.
+- [ ] Scope and out-of-scope are explicit.
+- [ ] Assumptions are explicit and labeled.
+- [ ] Open questions are resolved or marked as blockers.
+
+## Behavior and design
+
+- [ ] Requirements are testable.
+- [ ] Scenarios cover main flow and key edge cases.
+- [ ] Technical design is lightweight and sufficient for implementation.
+- [ ] Constraints and integration points are explicit.
+
+## Delivery readiness
+
+- [ ] Task breakdown is small, ordered, and reviewable.
+- [ ] Validation plan includes real commands/checks.
+- [ ] Expected evidence is explicit.
+- [ ] Risks include mitigation notes.
+
+## Decision
+
+Mark one:
+
+- [ ] Ready for implementation handoff
+- [ ] Needs clarification
+- [ ] Too broad (split into smaller changes)
+- [ ] Blocked by missing context/decision

package/docs/full-documentation.md

@@ -203,10 +203,18 @@ Spec-Driven commands:
 
 | Command | Purpose |
 | --- | --- |
+| [`opencode/commands/specs/create-spec-from-request.md`](opencode/commands/specs/create-spec-from-request.md) | Turn a vague request into a lightweight change artifact before coding. |
 | [`opencode/commands/specs/create-spec-from-requirement.md`](opencode/commands/specs/create-spec-from-requirement.md) | Draft a testable spec from an approved requirement. |
 | [`opencode/commands/specs/review-spec.md`](opencode/commands/specs/review-spec.md) | Review spec readiness before technical planning. |
 | [`opencode/commands/specs/spec-to-technical-plan.md`](opencode/commands/specs/spec-to-technical-plan.md) | Convert an approved spec into technical planning output. |
 | [`opencode/commands/specs/spec-to-pr-breakdown.md`](opencode/commands/specs/spec-to-pr-breakdown.md) | Split an approved spec into small, reviewable PRs. |
+| [`opencode/commands/specs/spec-to-tasks.md`](opencode/commands/specs/spec-to-tasks.md) | Convert approved spec into small implementation tasks with validation and evidence. |
+
+Consumer-project artifact path convention for lightweight specs:
+
+```txt
+docs/specs/[spec-type]/[yyyy-mm-dd]-[change-slug]/
+```
 
 ## OpenCode agent model
 
@@ -215,6 +223,7 @@ OpenCode agents are operational roles. Skills are reusable capabilities. Command
 | Agent | Role |
 | --- | --- |
 | [`discovery`](opencode/agents/discovery.md) | Explore project context before planning. |
+| [`spec-engineer`](opencode/agents/spec-engineer.md) | Convert vague requests into lightweight spec-driven change artifacts before coding. |
 | [`planner`](opencode/agents/planner.md) | Convert objectives into requirements, specs, plans, and PR breakdowns. |
 | [`orchestrator`](opencode/agents/orchestrator.md) | Route multi-step work across gates and specialists. |
 | [`implementer`](opencode/agents/implementer.md) | Implement scoped changes. |
@@ -314,6 +323,7 @@ Templates are reusable starting points, not completed project documents.
 | [`templates/README.template.md`](templates/README.template.md) | Base project README. |
 | [`templates/REQUIREMENT.template.md`](templates/REQUIREMENT.template.md) | Product requirement. |
 | [`templates/SPEC.template.md`](templates/SPEC.template.md) | Functional specification. |
+| [`templates/change-proposal.template.md`](templates/change-proposal.template.md) | Lightweight change proposal/spec artifact. |
 | [`templates/TECH-PLAN.template.md`](templates/TECH-PLAN.template.md) | Technical plan. |
 | [`templates/PR-PLAN.template.md`](templates/PR-PLAN.template.md) | PR plan. |
 
@@ -329,7 +339,9 @@ Runbooks are operational guides for applying the workflow.
 | [`runbooks/validate-starter-in-real-project.md`](runbooks/validate-starter-in-real-project.md) | Prove adoption in a real project. |
 | [`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/spec-driven-development.md`](runbooks/spec-driven-development.md) | Run lightweight spec-first flow and artifact conventions before implementation. |
 | [`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

@@ -17,7 +17,13 @@ Do not treat generic skills as OpenCode agents. A skill explains how to perform
 Client/request discovery:
 
 ```txt
-discovery → planner
+discovery → spec-engineer → planner
+```
+
+Lightweight spec-first delivery:
+
+```txt
+request → spec-engineer → implementer
 ```
 
 Feature delivery:
@@ -94,6 +100,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, edit files, perform execution/delegation routing directly (must return `Blocked` and route to `orchestrator`). |
+| `spec-engineer` | Turn vague/risky requests into lightweight change artifacts for implementation handoff. | Request ambiguity is high and team needs explicit agreement before coding. | Implement production code or create heavyweight process for tiny tasks. |
 | `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/spec-engineer.md

@@ -0,0 +1,85 @@
+# Spec-Engineer Agent
+
+## Role
+
+Turn vague, risky, or high-impact requests into lightweight change artifacts that are ready for implementation handoff.
+
+## Use when
+
+- A request is unclear, broad, or ambiguous.
+- The change can affect behavior, architecture, integration, or validation strategy.
+- The team needs explicit agreement on what to build before coding.
+
+## Do not use when
+
+- The task is a tiny docs-only or wording fix.
+- The scope is already fully specified and reviewed.
+
+## Required context
+
+- User request or discovery brief.
+- Repository rules from `AGENTS.md`.
+- Existing spec assets in `templates/`, `checklists/`, and `opencode/commands/specs/`.
+
+## Input discipline
+
+- Use `minimal-context` behavior: read only files needed for the active request.
+- Use `grep`/`glob` before reading large files.
+- Keep outputs compact and implementation-handoff ready.
+
+## Responsibilities
+
+- Receive vague requests and classify whether a spec is needed.
+- Define spec depth level (`tiny` | `standard` | `deep`) based on risk/impact.
+- Generate specification/change artifact before implementation.
+- Set spec status explicitly.
+- Expose assumptions and blocking questions.
+- Define scope and out-of-scope explicitly.
+- Produce requirements, scenarios, and acceptance criteria.
+- Identify edge cases, constraints, and risks.
+- Propose lightweight technical design.
+- Break work into small implementation tasks.
+- Define validation criteria and expected evidence.
+- Request review when uncertainty or risk is non-trivial.
+- Hand off to `implementer` (or `planner` when PR planning is still needed).
+
+## Constraints
+
+- Do not implement production code.
+- Do not refactor unrelated files.
+- Do not approve unresolved assumptions as facts.
+- Do not skip validation criteria or expected evidence.
+- Do not create heavyweight process for trivial work.
+
+## Required workflow
+
+```txt
+1) Receive vague request
+2) Classify if spec is needed
+3) Define spec depth level
+4) Generate specification artifact
+5) Define spec status
+6) Expose assumptions and blocking questions
+7) Define scope and out-of-scope
+8) Define requirements and scenarios
+9) Define acceptance criteria
+10) Define technical constraints and risks
+11) Create small implementation tasks
+12) Define validation and expected evidence
+13) Request review when needed
+14) Generate implementation handoff
+```
+
+## Expected output
+
+- Change artifact using `templates/change-proposal.template.md`
+- Default artifact location in consumer project: `docs/specs/<spec-type>/<yyyy-mm-dd>-<change-slug>/`
+- Spec depth level: `tiny` | `standard` | `deep`
+- Spec status: `Draft` | `In review` | `Ready for implementation handoff` | `Needs clarification` | `Too broad` | `Blocked`
+- Assumptions and blocking questions (if any)
+- Recommended next owner: `implementer` or `planner`
+
+## Stop conditions
+
+- Stop when the change artifact is explicit, testable, and handoff-ready.
+- Stop and mark `Blocked` if missing decisions make implementation unsafe.

package/opencode/commands/README.md

@@ -25,10 +25,12 @@ Adapt file names, command registration, or invocation style to your OpenCode set
 
 | File | Use when |
 | ---- | -------- |
+| `create-spec-from-request.md` | Turn a vague request into a lightweight change artifact before coding. |
 | `create-spec-from-requirement.md` | Draft a testable spec from an approved requirement. |
 | `review-spec.md` | Review spec readiness before technical planning. |
 | `spec-to-technical-plan.md` | Convert approved spec into technical planning output. |
 | `spec-to-pr-breakdown.md` | Split approved spec into small PRs. |
+| `spec-to-tasks.md` | Convert approved spec into small implementation tasks with validation and evidence expectations. |
 
 ## Usage Notes
 

package/opencode/commands/specs/create-spec-from-request.md

@@ -0,0 +1,27 @@
+# OpenCode Command - Create Spec From Request
+
+## Purpose
+
+Turn a vague request into a lightweight, implementation-ready change artifact.
+
+## Constraints
+
+1. Do not implement.
+2. Ask only necessary blocking questions (max 2 by default).
+3. Keep scope and out-of-scope explicit.
+4. Preserve existing behavior unless change is explicitly requested.
+
+## Context To Read
+
+- `templates/change-proposal.template.md`
+- `checklists/change-spec-readiness-checklist.md`
+- `AGENTS.md`
+
+## Expected Output
+
+- Draft change artifact using `templates/change-proposal.template.md`
+- Suggested output path in consumer project: `docs/specs/<spec-type>/<yyyy-mm-dd>-<change-slug>/00-proposal.md`
+- Assumptions
+- Open questions
+- Readiness: `Ready for implementation handoff` | `Needs clarification` | `Too broad` | `Blocked`
+- Recommended next owner: `implementer` | `planner`

package/opencode/commands/specs/review-spec.md

@@ -2,12 +2,14 @@
 
 ## Purpose
 
-Assess whether a spec is ready for technical planning.
+Assess and improve whether a spec/change artifact is ready for implementation handoff.
 
 ## Context To Read
 
 - `templates/SPEC.template.md`
+- `templates/change-proposal.template.md`
 - `checklists/spec-readiness-checklist.md`
+- `checklists/change-spec-readiness-checklist.md`
 - `AGENTS.md`
 
 ## Constraints
@@ -18,7 +20,7 @@ Assess whether a spec is ready for technical planning.
 
 ## Expected Output
 
-- Decision: `Ready` | `Needs clarification` | `Too broad` | `Blocked`
+- Decision: `Ready for implementation handoff` | `Needs clarification` | `Too broad` | `Blocked`
 - Findings by severity (`High`/`Medium`/`Low`)
 - Smallest safe fixes
 - Evidence references

package/opencode/commands/specs/spec-to-tasks.md

@@ -0,0 +1,26 @@
+# OpenCode Command - Spec To Tasks
+
+## Purpose
+
+Convert an approved spec/change artifact into small, reviewable implementation tasks with validation and evidence expectations.
+
+## Constraints
+
+1. Do not implement.
+2. Keep tasks ordered and dependency-aware.
+3. Keep each task objective small and testable.
+4. Include validation criteria and expected evidence.
+
+## Context To Read
+
+- `templates/change-proposal.template.md`
+- `checklists/change-spec-readiness-checklist.md`
+- `AGENTS.md`
+
+## Expected Output
+
+- Ordered task list
+- Per task: objective, scope, out-of-scope, risk note
+- Validation criteria per task
+- Expected evidence per task
+- Recommended first task for implementation

package/opencode.jsonc

@@ -11,6 +11,11 @@
       "description": "Plan requirements, specs, technical plans, and PR breakdowns",
       "prompt": "{file:./opencode/agents/planner.md}"
     },
+    "spec-engineer": {
+      "mode": "primary",
+      "description": "Turn vague requests into lightweight spec-driven change artifacts",
+      "prompt": "{file:./opencode/agents/spec-engineer.md}"
+    },
     "implementer": {
       "mode": "primary",
       "description": "Implement features, fixes, and code changes",
@@ -142,6 +147,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)",
@@ -197,6 +209,21 @@
       "description": "Prepare deployment readiness and rollback plan",
       "agent": "deploy-engineer",
       "template": "{file:./opencode/commands/deploy.md}"
+    },
+    "spec-create": {
+      "description": "Create a lightweight spec/change artifact from a vague request",
+      "agent": "spec-engineer",
+      "template": "{file:./opencode/commands/specs/create-spec-from-request.md}"
+    },
+    "spec-review": {
+      "description": "Review or improve spec readiness for implementation handoff",
+      "agent": "spec-engineer",
+      "template": "{file:./opencode/commands/specs/review-spec.md}"
+    },
+    "spec-tasks": {
+      "description": "Convert approved spec into small implementation tasks",
+      "agent": "spec-engineer",
+      "template": "{file:./opencode/commands/specs/spec-to-tasks.md}"
     }
   }
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.18.8",
+  "version": "1.18.10",
   "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

@@ -2,7 +2,7 @@
 
 `@williambeto/ai-workflow` is the npm CLI for installing AI Workflow Kit assets into a project.
 
-It prepares a repository for Codex and OpenCode workflows with local prompts, workflow scripts, managed `opencode.jsonc` sections, and doctor checks.
+It prepares a repository for Codex and OpenCode workflows with local prompts, generated workflow assets, managed `opencode.jsonc` sections, and doctor checks.
 
 ## Commands
 
@@ -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/publication-readiness-checklist.md

@@ -0,0 +1,29 @@
+# Publication Readiness Checklist
+
+## Purpose
+
+Use this checklist before making the GitHub repository public or before a major public-facing release.
+
+## Checklist
+
+- [ ] `README.md` describes the project as public-ready enough for its current maturity.
+- [ ] `README.md` does not contain private-preview or not-ready-for-public language.
+- [ ] `SECURITY.md` exists and explains how to report vulnerabilities.
+- [ ] `package.json` metadata points to the public repository, license, and npm package.
+- [ ] Public docs do not contain local absolute paths.
+- [ ] Public docs do not contain private client, customer, or target-project names.
+- [ ] Historical repository names are removed, redacted, or clearly marked as historical.
+- [ ] GitHub-only folders (`evidence/`, `examples/`, `variants/`, `scripts/`, `tests/`) are appropriate for public readers.
+- [ ] CI and publish workflows reference secrets through GitHub Actions secrets only.
+- [ ] `npm run validate` passes.
+
+## Suggested verification commands
+
+```bash
+npm run validate
+grep -R --exclude=publication-readiness-checklist.md "/home/" README.md docs runbooks evidence packages examples variants || true
+grep -R --exclude=publication-readiness-checklist.md "private preview\|private-preview\|not ready for broad public" README.md docs runbooks packages evidence || true
+grep -R --exclude=publication-readiness-checklist.md "arco-ptp" README.md docs runbooks packages evidence || true
+```
+
+Review any matches before publication. Some historical references may be acceptable only when they are explicitly anonymized or explained.

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/spec-driven-development.md

@@ -8,10 +8,9 @@ Standard flow:
 
 ```txt
 Request
-→ Spec draft
+→ Change proposal / lightweight spec
 → Spec review
-→ Technical plan
-→ PR breakdown
+→ Task breakdown
 → Implementation
 → Validation
 → Evidence report
@@ -32,6 +31,11 @@ For tiny docs-only edits, use proportional workflow.
 
 ## Assets to use
 
+- Lightweight change template: `templates/change-proposal.template.md`
+- Lightweight readiness checklist: `checklists/change-spec-readiness-checklist.md`
+- Request-to-spec command: `opencode/commands/specs/create-spec-from-request.md`
+- Spec-to-tasks command: `opencode/commands/specs/spec-to-tasks.md`
+- Spec-first owner: `opencode/agents/spec-engineer.md`
 - Spec template: `templates/SPEC.template.md`
 - Readiness checklist: `checklists/spec-readiness-checklist.md`
 - Draft prompt: `.codex/prompts/specs/create-spec-from-requirement.md`
@@ -39,15 +43,52 @@ For tiny docs-only edits, use proportional workflow.
 - Plan prompt: `.codex/prompts/specs/spec-to-technical-plan.md`
 - PR prompt: `.codex/prompts/specs/spec-to-pr-breakdown.md`
 
+## Artifact location convention (consumer project)
+
+Store generated spec artifacts in the consumer repository using this default path:
+
+```txt
+docs/specs/[spec-type]/[yyyy-mm-dd]-[change-slug]/
+```
+
+Allowed `<spec-type>` values:
+
+- `feature`
+- `bugfix`
+- `refactor`
+- `ui-change`
+- `architecture`
+- `workflow`
+- `integration`
+- `test-strategy`
+
+Recommended files inside each folder:
+
+```txt
+00-proposal.md
+01-spec.md
+02-design.md
+03-tasks.md
+04-validation.md
+05-handoff.md
+```
+
+For `tiny` specs, allow a minimal set:
+
+```txt
+00-proposal.md
+03-tasks.md
+04-validation.md
+```
+
 ## Connection to PR execution
 
 After spec review passes:
 
-1. produce technical plan;
-2. split into small PRs;
-3. implement PR 1 only;
-4. run validation before claiming success;
-5. return evidence for commands, changed files, and acceptance-criteria coverage.
+1. split into small implementation tasks (or PRs when needed);
+2. implement one scoped task/PR only;
+3. run validation before claiming success;
+4. return evidence for commands, changed files, and acceptance-criteria coverage.
 
 ## Required evidence after validation
 

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/templates/change-proposal.template.md

@@ -0,0 +1,97 @@
+# Change Proposal (Lightweight Spec)
+
+Suggested save path (consumer project):
+
+`docs/specs/<spec-type>/<yyyy-mm-dd>-<change-slug>/00-proposal.md`
+
+## Spec level
+
+`tiny` | `standard` | `deep`
+
+## Spec status
+
+`Draft` | `In review` | `Ready for implementation handoff` | `Needs clarification` | `Too broad` | `Blocked`
+
+## Title
+
+[Short change title]
+
+## Objective
+
+[Outcome this change must achieve]
+
+## Background
+
+[Context needed to understand this request]
+
+## Problem
+
+[Current pain, failure mode, or gap]
+
+## Proposed change
+
+[What will change and why this is the smallest safe approach]
+
+## Scope
+
+### Included
+
+- [In-scope item]
+
+### Out of scope
+
+- [Explicitly excluded item]
+
+## Requirements
+
+- [Clear, testable requirement]
+
+## Scenarios
+
+### Scenario 1 — [Name]
+
+- Given [state]
+- When [action]
+- Then [expected result]
+
+### Scenario 2 — [Name or `Not applicable`]
+
+- Given [state]
+- When [action]
+- Then [expected result]
+
+## Technical design
+
+- [High-level design choice]
+- [Constraints, integration points, and trade-offs]
+
+## Task breakdown
+
+1. [Small implementation task]
+2. [Small implementation task]
+3. [Small validation or hardening task]
+
+## Validation plan
+
+- [Command or check]
+- [Acceptance criteria coverage method]
+
+## Risks
+
+- [Risk + mitigation]
+
+## Open questions
+
+- [Question that blocks or may affect scope]
+
+## Expected evidence
+
+- Commands executed and results
+- Files changed
+- Acceptance criteria/scenario coverage
+- Untested areas and residual risks
+
+## Handoff
+
+- Recommended next owner: `implementer` | `planner`
+- Readiness: `Ready for implementation handoff` | `Needs clarification` | `Too broad` | `Blocked`

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" };
-}