@williambeto/ai-workflow 1.18.6 → 1.18.7

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/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/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.7",
   "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/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.