@williambeto/ai-workflow 1.18.6 → 1.18.8

package/.agents/skills/backend-implementer/SKILL.md

@@ -46,6 +46,19 @@ When acting as backend implementer, Codex must:
 10. update or add tests when behavior changes;
 11. document assumptions, limitations, and untested areas.
 
+## Branch safety gate (mandatory before edits)
+
+Before changing files, enforce branch safety:
+
+1. run `git status -sb`;
+2. if current branch is `main`, create/switch to a scoped branch before writing:
+
+```bash
+git switch -c feat/<short-task-slug>
+```
+
+Never implement directly on `main`.
+
 ## Backend implementation principles
 
 ### 1. Existing patterns first

package/.agents/skills/deploy-engineer/SKILL.md

@@ -47,6 +47,19 @@ When acting as deploy engineer, Codex must:
 10. avoid unsafe deployment recommendations without evidence;
 11. provide a clear release recommendation.
 
+## Branch safety gate (mandatory before edits)
+
+This role is often review-only. If deployment/release work requires file edits (workflow, runbook, or config changes):
+
+1. run `git status -sb`;
+2. if current branch is `main`, create/switch to a scoped branch before writing:
+
+```bash
+git switch -c chore/<short-task-slug>
+```
+
+Do not apply release-related edits directly on `main`.
+
 ## Deployment principles
 
 ### 1. Build before deploy

package/.agents/skills/docs-writer/SKILL.md

@@ -48,6 +48,19 @@ When acting as docs writer, Codex must:
 10. check code fences, headings, tables, and lists;
 11. state assumptions and gaps clearly.
 
+## Branch safety gate (mandatory for non-trivial docs edits)
+
+For non-trivial documentation updates (new sections, policy changes, runbook/process updates):
+
+1. run `git status -sb`;
+2. if current branch is `main`, create/switch to a scoped branch before writing:
+
+```bash
+git switch -c docs/<short-task-slug>
+```
+
+Do not edit non-trivial documentation directly on `main`.
+
 ## Documentation principles
 
 ### 1. Audience first

package/.agents/skills/frontend-implementer/SKILL.md

@@ -46,6 +46,19 @@ When acting as frontend implementer, Codex must:
 10. validate the change with relevant checks;
 11. document assumptions, limitations, and untested areas.
 
+## Branch safety gate (mandatory before edits)
+
+Before changing files, enforce branch safety:
+
+1. run `git status -sb`;
+2. if current branch is `main`, create/switch to a scoped branch before writing:
+
+```bash
+git switch -c feat/<short-task-slug>
+```
+
+Never implement directly on `main`.
+
 ## Frontend implementation principles
 
 ### 1. Existing patterns first

package/.agents/skills/tester/SKILL.md

@@ -45,6 +45,19 @@ When acting as tester, Codex must:
 10. separate confirmed issues from hypotheses;
 11. provide a clear approval or rejection recommendation.
 
+## Branch safety gate (mandatory if fixes are applied)
+
+Tester is primarily review/validation. If a validation task includes direct fixes:
+
+1. run `git status -sb`;
+2. if current branch is `main`, create/switch to a scoped branch before writing:
+
+```bash
+git switch -c fix/<short-task-slug>
+```
+
+Do not apply fixes directly on `main`.
+
 ## Validation mindset
 
 Act as a skeptical reviewer.

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
 
 ### Added

package/README.md

@@ -7,8 +7,6 @@ Most AI coding workflows fail because they start with code.
 
 **AI Workflow Kit** is a software delivery workflow for Codex and OpenCode: requirements first, small PRs, specialist agents, validation evidence, and no-regression rules.
 
-> Historical note: this project originated as `codex-repo-starter` and now continues as AI Workflow Kit. The npm CLI package is `@williambeto/ai-workflow`.
-
 ## Why this exists
 
 AI coding tools are powerful, but without workflow discipline they often create oversized changes, vague requirements, hidden assumptions, unreviewable diffs, skipped validation, architecture drift, and cleanup work disguised as speed.

package/docs/full-documentation.md

@@ -6,8 +6,6 @@ This document is the detailed reference for **AI Workflow Kit**.
 
 Use the root `README.md` as the landing page. Use this document when you need the full repository map, workflow explanation, role model, validation model, and adoption guidance.
 
-Historical note: this project started as `codex-repo-starter` and now continues as `ai-workflow`.
-
 ## What AI Workflow Kit is
 
 AI Workflow Kit is a documentation-first workflow system for AI-assisted software delivery.

package/docs/npm-consumer-quickstart.md

@@ -68,7 +68,7 @@ The `init` command installs workflow assets into `.ai-workflow/` and creates sym
 - Run `npx @williambeto/ai-workflow init --force` to regenerate managed files when the package is updated.
 - Backup copies of replaced files are stored in `.ai-workflow-backups/`.
 
-There is no `.workflow/` directory. Workflow assets are managed under `.ai-workflow/` with symlinks in project-root paths for tool compatibility.
+There is no `.workflow/` directory in this onboarding path. Legacy `.workflow` submodule guidance is deprecated for npm consumers. Workflow assets are managed under `.ai-workflow/` with symlinks in project-root paths for tool compatibility.
 
 ## OpenCode quickstart
 

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/agents/fixer.md

@@ -29,6 +29,7 @@ Diagnose and fix bugs, regressions, failing tests, build failures, warnings, and
 
 ## Constraints
 
+- Enforce branch gate before any write: run `git status -sb`; if branch is `main`, create/switch to `git switch -c fix/<short-task-slug>` before editing.
 - Do not rewrite large areas without evidence.
 - Do not mix unrelated refactors into the fix.
 - Do not change behavior without stating it.

package/opencode/agents/orchestrator.md

@@ -34,6 +34,7 @@ Route work automatically across agents and run end-to-end workflow orchestration
 - Enforce design-pattern justification before allowing formal pattern abstractions.
 - Evaluate gate criteria for the next transition.
 - Route to next agent only when gate is `Pass`.
+- Enforce delegation-by-step: for planner/implementer/reviewer/validator/release-manager steps, delegate to the step owner instead of executing specialist work inline.
 - Return blocked transitions with smallest safe fix request.
 - Ask user confirmation only at required checkpoints.
 - Preserve branch gate and no-regression constraints.
@@ -90,11 +91,17 @@ Every specialist response must include:
 ## Anti-overdelegation rules
 
 - Do not delegate trivial one-file documentation edits.
-- Do not delegate when the active primary agent can safely complete the task using existing instructions.
+- Do not delegate when the active primary agent can safely complete the task using existing instructions **only for non-specialist trivial work** (for example: one-file wording or formatting updates).
 - Do not delegate to more than 2 agents unless the task is explicitly cross-functional.
 - Prefer one owner + one reviewer instead of broad parallel delegation.
 - Always delegate validation/review for high-risk implementation.
 
+## Delegation enforcement
+
+- For any active step owner in `planner -> implementer -> reviewer -> validator -> release-manager`, orchestration must delegate to that owner.
+- If orchestration cannot delegate due to missing input packet, missing context, or unresolved gate criteria, return `Blocked` and request the smallest safe missing input.
+- Do not bypass required owner delegation by completing specialist work in orchestrator responses.
+
 ## Escalation rules
 
 - If implementation changes architecture, consult `tech-lead`.

package/opencode/agents/planner.md

@@ -39,6 +39,7 @@ Transform approved scope into a requirement, functional specification, technical
 ## Constraints
 
 - Do not implement.
+- If non-trivial documentation edits are requested, enforce branch gate first: run `git status -sb`; if branch is `main`, create/switch to `git switch -c <type>/<short-task-slug>` before writing.
 - Do not plan multiple unrelated features together.
 - Do not skip validation planning.
 - Do not ignore `AGENTS.md`.

package/opencode/agents/release-manager.md

@@ -30,6 +30,7 @@ Close the Git and PR cycle safely.
 ## Constraints
 
 - Do not merge with a dirty worktree.
+- If requested to apply fixes before release, enforce branch gate first: run `git status -sb`; if branch is `main`, create/switch to `git switch -c chore/<short-task-slug>` before editing.
 - Do not skip validation.
 - Do not invent commit messages unrelated to the diff.
 - Do not delete branches or merge unless explicitly requested.

package/opencode/commands/orchestrate.md

@@ -20,10 +20,12 @@ This command does not implement code by itself; it routes work to the correct ne
 4. If gate is `Blocked`, stop escalation and return smallest safe fix request to previous owner.
 5. Enforce branch gate for any execution step (no implementation on `main`).
 6. Preserve one primary agent per step.
-7. Do not skip validation gate before release recommendations.
-8. Apply anti-overdelegation: do not delegate trivial one-file doc edits; do not route to more than 2 agents unless cross-functional.
-9. Use delegation contract fields in every handoff: task summary, relevant files, constraints, expected output, validation required, risk level, do-not-change list, evidence required.
-10. Require specialist responses to include summary/findings, files changed or inspected, risks, validation commands, open questions, and recommendation.
+7. Enforce delegation-by-step: do not execute planner/implementer/reviewer/validator/release-manager specialist work inline; route to the step owner.
+8. If required owner delegation cannot be performed (missing packet/context/gate input), return `Blocked` with the smallest safe missing-input request.
+9. Do not skip validation gate before release recommendations.
+10. Apply anti-overdelegation: do not delegate trivial one-file doc edits; do not route to more than 2 agents unless cross-functional.
+11. Use delegation contract fields in every handoff: task summary, relevant files, constraints, expected output, validation required, risk level, do-not-change list, evidence required.
+12. Require specialist responses to include summary/findings, files changed or inspected, risks, validation commands, open questions, and recommendation.
 
 ## Expected Output
 

package/opencode.jsonc

@@ -195,7 +195,7 @@
     },
     "deploy": {
       "description": "Prepare deployment readiness and rollback plan",
-      "agent": "release-manager",
+      "agent": "deploy-engineer",
       "template": "{file:./opencode/commands/deploy.md}"
     }
   }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.18.6",
+  "version": "1.18.8",
   "name": "@williambeto/ai-workflow",
   "description": "AI Workflow Kit repository for designing and validating AI-assisted software delivery workflows with Codex and OpenCode",
   "license": "MIT",
@@ -64,7 +64,8 @@
     "validate:delegation": "node scripts/validate-delegation.mjs",
     "validate:cli-smoke": "node scripts/validate-cli-smoke.mjs",
     "test:e2e": "node tests/validate-e2e.mjs",
-    "validate": "node scripts/validate-all.mjs"
+    "validate": "node scripts/validate-all.mjs",
+    "release:ship": "node scripts/release-ship.mjs"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",

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/publish-package-checklist.md

@@ -23,9 +23,30 @@ Use this runbook to publish `@williambeto/ai-workflow` to npm with explicit safe
 - [ ] `package.json` version is intentional.
 - [ ] `CHANGELOG.md` reflects the release.
 - [ ] `npm run validate` passes.
+- [ ] `npm pack --dry-run` reviewed (file list, size, no surprises).
+- [ ] No sensitive or non-essential files appear in tarball output.
+- [ ] `package.json` `files` allowlist still matches intended distributable assets.
+- [ ] `.npmignore` hardening file is present and reviewed for drift.
 - [ ] Dry-run workflow succeeded (`dry_run=true`).
 - [ ] Release decision/approval is explicit.
 
+## Continuous hardening baseline (every release)
+
+Run this baseline before any real publish:
+
+```bash
+npm run validate
+npm pack --dry-run
+```
+
+Then verify explicitly:
+
+1. Tarball contains only expected runtime/docs assets.
+2. No local, test, evidence, or backup outputs leaked.
+3. Publish path remains allowlist-first (`package.json` `files`) with `.npmignore` as defense-in-depth.
+
+If any unexpected file appears, stop and return `Blocked` until the package boundary is corrected.
+
 ## Publish steps
 
 1. Open GitHub Actions.
@@ -40,6 +61,7 @@ Use this runbook to publish `@williambeto/ai-workflow` to npm with explicit safe
 - Workflow run URL.
 - `npm run validate` result from workflow logs.
 - `npm pack --dry-run` output.
+- Tarball boundary decision note (why contents are safe for public publish).
 - Published version and npm package URL.
 - Any warnings and mitigation notes.