@williambeto/ai-workflow 1.18.16 → 1.18.18

package/.agents/napkin.md

@@ -0,0 +1,89 @@
+# Project Napkin Memory
+
+## Purpose
+
+This file stores durable, reusable project memory for `ai-workflow`.
+
+It captures recurring corrections and stable operational rules that should survive across sessions.
+
+## Usage rules
+
+- Read at relevant task start when work depends on repository structure, workflow rules, validation behavior, or recurring conventions.
+- Apply progressive disclosure: use only entries relevant to the current task.
+- Add entries only when guidance is durable and reusable.
+- Do not store secrets, credentials, tokens, private keys, or personal/environment-sensitive data.
+- Do not use this file as a temporary notes dump or task timeline log.
+
+## Current durable project memory
+
+### [2026-05-11] Workflow: Keep pull requests small and reviewable
+
+- Instead of: Combining multiple workflow phases or unrelated refactors in one change.
+- Do: Implement one scoped PR-sized unit at a time and preserve no-regression behavior.
+- Evidence/source: `AGENTS.md` hard constraints and primary workflow.
+
+### [2026-05-11] Validation: Run full repository validation before closing work
+
+- Instead of: Assuming docs or script edits are safe without full validation.
+- Do: Run `npm run validate` and report command evidence in the final output.
+- Evidence/source: `AGENTS.md` evidence requirements and validation rules.
+
+### [2026-05-11] Skill design: Keep skills portable and lightweight
+
+- Instead of: Embedding heavy repo-specific logic directly into each skill.
+- Do: Keep skills operational, concise, and reusable across real project contexts.
+- Evidence/source: `AGENTS.md` repository context and specialist skill guidance.
+
+### [2026-05-11] Skill structure: Every skill directory needs `SKILL.md`
+
+- Instead of: Treating a skill directory as valid without its required definition file.
+- Do: Ensure each `.agents/skills/*` directory contains `SKILL.md`.
+- Evidence/source: `scripts/validate-skills.mjs` dynamic directory check.
+
+### [2026-05-11] Validation quality: Do not allow incomplete skills to pass
+
+- Instead of: Passing validation when required skill files are missing.
+- Do: Fail validation for missing skill files and treat it as a blocking issue.
+- Evidence/source: `scripts/validate-skills.mjs` failure behavior and repo quality gates.
+
+### [2026-05-11] Review quality: Prefer evidence-based findings
+
+- Instead of: Reporting vague findings without concrete references.
+- Do: Include file paths and command output in findings and validation summaries.
+- Evidence/source: `AGENTS.md` evidence requirements and finding model.
+
+### [2026-05-12] Token economy: Caveman mode does not auto-pass to delegated agents
+
+- Instead of: Activating `/caveman` and assuming all delegated agents stay compact.
+- Do: Each new agent context loads fresh without caveman compression unless the delegation packet explicitly requests it.
+- Do: When delegating, include in the handoff packet: "Use compact output — caveman mode active."
+- Do: For multi-agent chains (planner → implementer → reviewer), activate token-economy + minimal-context in each agent's Required context or delegation contract.
+- Evidence/source: `AGENTS.md` anti-overdelegation rules, `minimal-context` skill, `token-economy` skill.
+
+### [2026-05-13] Phase 8: Codex parity complete — all PRs merged
+
+- Instead of: Leaving Codex users without guided orchestration or debugging entrypoints.
+- Do: After any audit that identifies gaps, create a Phase in ROADMAP.md and deliver PRs sequentially with validation at each step.
+- Do: Mark each Phase as `[x]` in ROADMAP when complete, update status line, and update "next recommended PR".
+- Evidence/source: ROADMAP.md Phase 8 — 6 PRs delivered (orchestrate-next.md, fix-issue.md, deploy.md, autopilot→orchestrator fixes, README tree, AGENTS.md note). PR #89 merged. 9/9 validate checks.
+
+### [2026-05-13] Audit: Napkin works for both Codex and OpenCode
+
+- Instead of: Worrying that Napkin might be tool-specific or only work for OpenCode.
+- Do: Trust that Napkin is fully shared — same file, same skill, same format for both Codex and OpenCode.
+- Do: After any audit or significant workflow change, update Napkin if a durable lesson was confirmed.
+- Evidence/source: `.agents/napkin.md` audit 2026-05-13 — SKILL.md passes validate:skills for both tools; progressive disclosure documented; 0 secrets; 8 valid entries.
+
+### [2026-05-14] Release hygiene: update `package.json` before release
+
+- Instead of: Creating a release tag without aligning repository version metadata.
+- Do: Update `package.json` version before creating a release.
+- Do: Keep version, tag, and release notes aligned so release automation and changelog extraction stay consistent.
+- Evidence/source: `release.yml` extracts notes by tag version; release flow consistency depends on matching semver across tags and project metadata.
+
+### [2026-05-23] Documentation language: English only for repository docs
+
+- Instead of: Adding or keeping Portuguese (or mixed-language) content in official documentation files.
+- Do: Write and maintain all repository documentation in English by default.
+- Do: Apply this rule to docs, runbooks, prompts, specs, and policy files unless a file explicitly declares a localization scope.
+- Evidence/source: User directive in session (2026-05-23) and consistency requirement for public developer experience.

package/.agents/skills/{codex-pr-workflow → pr-orchestrator}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: codex-pr-workflow
+name: pr-orchestrator
 description: Use when planning, implementing, reviewing, or validating small pull requests with Codex while preserving scope and avoiding regressions.
 ---
 
 > Token economy active: keep output compact, context minimal. Reference: `token-economy` + `minimal-context` skills.
 
-# Codex PR Workflow Skill
+# PR Orchestrator Skill
 
 ## Purpose
 

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [1.18.18](https://github.com/williambeto/ai-workflow/compare/v1.18.17...v1.18.18) (2026-05-23)
+
+
+### Bug Fixes
+
+* **init:** include napkin memory in npm install ([f4f2e31](https://github.com/williambeto/ai-workflow/commit/f4f2e313dfae85daa31c92d60d5402df48c83b62))
+
+## [1.18.17](https://github.com/williambeto/ai-workflow/compare/v1.18.16...v1.18.17) (2026-05-23)
+
+
+### Bug Fixes
+
+* **init:** ignore generated workflow footprint ([15eba7a](https://github.com/williambeto/ai-workflow/commit/15eba7a2ac3ad81af3f6e6984be900717a6e89ef))
+* **init:** use canonical opencode full config ([8b8551d](https://github.com/williambeto/ai-workflow/commit/8b8551d5af00b8924dbc8f2244b159f091fcb810))
+
 ## [1.18.16](https://github.com/williambeto/ai-workflow/compare/v1.18.15...v1.18.16) (2026-05-22)
 
 

package/README.md

@@ -64,6 +64,7 @@ Use:
 - `templates/SPEC.template.md`
 - `checklists/spec-readiness-checklist.md`
 - `runbooks/spec-driven-development.md`
+- `runbooks/branch-cleanup.md`
 
 ## The anti-chaos rules
 
@@ -107,7 +108,7 @@ npx @williambeto/ai-workflow init --dry-run
 | Profile | Use when |
 | --- | --- |
 | `minimal` | You only need basic docs and Codex prompt placeholders. |
-| `operational` (default) | You want the repeatable PR workflow with OpenCode `start` command. |
+| `operational` | You want the repeatable PR workflow with OpenCode `start` command. |
 | `full` | You want starter files for the full agent and skill catalog. |
 
 For a full walkthrough with Codex and OpenCode quickstart paths, validation checklist, and troubleshooting, see [`docs/npm-consumer-quickstart.md`](docs/npm-consumer-quickstart.md).

package/docs/full-documentation.md

@@ -242,7 +242,7 @@ Skills define focused behavior for AI agents. Use exactly one primary skill per
 | --- | --- |
 | [`product-manager`](.agents/skills/product-manager/SKILL.md) | Clarifying requirements, users, scope, and acceptance criteria. |
 | [`tech-lead`](.agents/skills/tech-lead/SKILL.md) | Planning architecture, trade-offs, risks, and sequencing. |
-| [`codex-pr-workflow`](.agents/skills/codex-pr-workflow/SKILL.md) | Splitting, executing, reviewing, and summarizing small PRs. |
+| [`pr-orchestrator`](.agents/skills/pr-orchestrator/SKILL.md) | Splitting, executing, reviewing, and summarizing small PRs. |
 | [`frontend-implementer`](.agents/skills/frontend-implementer/SKILL.md) | Frontend UI, routing, state, styling, and accessibility work. |
 | [`backend-implementer`](.agents/skills/backend-implementer/SKILL.md) | APIs, services, data, validation, auth, and server-side tests. |
 | [`tester`](.agents/skills/tester/SKILL.md) | Acceptance criteria, regression coverage, and validation evidence. |
@@ -266,7 +266,7 @@ Skills define focused behavior for AI agents. Use exactly one primary skill per
 | --- | --- |
 | Requirement or acceptance criteria | `product-manager` |
 | Technical plan | `tech-lead` |
-| PR breakdown | `codex-pr-workflow` |
+| PR breakdown | `pr-orchestrator` |
 | Frontend implementation | `frontend-implementer` |
 | Backend implementation | `backend-implementer` |
 | Test strategy or review | `tester` |

package/opencode/agents/README.md

@@ -79,9 +79,9 @@ Delegation policy baseline:
 When routing to an agent, use this baseline skill auto-load map:
 
 ```txt
-planner -> product-manager + tech-lead + codex-pr-workflow
-implementer -> codex-pr-workflow + tester + (frontend-implementer or backend-implementer)
-reviewer -> tester + codex-pr-workflow
+planner -> product-manager + tech-lead + pr-orchestrator
+implementer -> pr-orchestrator + tester + (frontend-implementer or backend-implementer)
+reviewer -> tester + pr-orchestrator
 validator -> build-and-validate + tester
 release-manager -> deploy-engineer
 ```

package/opencode.jsonc

@@ -96,10 +96,10 @@
       "description": "Plan and review deployment, release, rollback, CI/CD readiness",
       "prompt": "{file:.agents/skills/deploy-engineer/SKILL.md}"
     },
-    "codex-pr-workflow": {
+    "pr-orchestrator": {
       "mode": "subagent",
       "description": "Plan and validate small PRs, preserve scope, avoid regressions",
-      "prompt": "{file:.agents/skills/codex-pr-workflow/SKILL.md}"
+      "prompt": "{file:.agents/skills/pr-orchestrator/SKILL.md}"
     },
     "build-and-validate": {
       "mode": "subagent",

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.18.16",
+  "version": "1.18.18",
   "name": "@williambeto/ai-workflow",
   "description": "AI Workflow Kit repository for designing and validating AI-assisted software delivery workflows with Codex and OpenCode",
   "license": "MIT",
@@ -24,6 +24,7 @@
     "packages/ai-workflow/src/",
     ".codex/prompts/",
     ".agents/skills/",
+    ".agents/napkin.md",
     "opencode/agents/",
     "opencode/commands/",
     "opencode/README.md",

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

@@ -20,6 +20,65 @@ function printPlan(actions) {
   }
 }
 
+function toIgnoreEntries(linkPath) {
+  if (linkPath === "README.workflow.md") {
+    return [linkPath];
+  }
+
+  const normalized = linkPath.endsWith("/") ? linkPath.slice(0, -1) : linkPath;
+  return [normalized, `${normalized}/`];
+}
+
+function buildGitignoreBlock(entries) {
+  const unique = Array.from(new Set(entries));
+  const sorted = unique.sort((a, b) => a.localeCompare(b));
+
+  return [
+    "# BEGIN AI WORKFLOW KIT",
+    "# AI Workflow Kit generated files",
+    ...sorted,
+    "# END AI WORKFLOW KIT"
+  ].join("\n");
+}
+
+async function upsertGitignoreBlock(cwd, entries) {
+  const gitignorePath = path.join(cwd, ".gitignore");
+  const block = buildGitignoreBlock(entries);
+  const beginMarker = "# BEGIN AI WORKFLOW KIT";
+  const endMarker = "# END AI WORKFLOW KIT";
+
+  const hasGitignore = await exists(gitignorePath);
+  if (!hasGitignore) {
+    await writeFileSafe(gitignorePath, `${block}\n`);
+    return "created";
+  }
+
+  const current = await fs.readFile(gitignorePath, "utf8");
+  const beginIndex = current.indexOf(beginMarker);
+  const endIndex = current.indexOf(endMarker);
+
+  if (beginIndex >= 0 && endIndex > beginIndex) {
+    const before = current
+      .slice(0, beginIndex)
+      .replace(/\n?# AI Workflow Kit generated files\n?$/, "\n")
+      .replace(/[ \t]+$/gm, "")
+      .replace(/\n*$/, "\n");
+    const afterStart = endIndex + endMarker.length;
+    const after = current.slice(afterStart).replace(/^\n*/, "\n");
+    const next = `${before}${block}${after}`;
+    if (next !== current) {
+      await writeFileSafe(gitignorePath, next);
+      return "updated";
+    }
+    return "unchanged";
+  }
+
+  const separator = current.endsWith("\n") ? "\n" : "\n\n";
+  const next = `${current}${separator}${block}\n`;
+  await writeFileSafe(gitignorePath, next);
+  return "updated";
+}
+
 export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite, profile }) {
   const selectedProfile = profile ?? "full";
   const installRoot = ".ai-workflow";
@@ -139,10 +198,20 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
       ? { reason: "skipped (minimal profile)" }
       : await mergeOpencodeConfig(cwd, { force, backupRoot, profile: selectedProfile });
 
+  const generatedIgnoreEntries = [
+    ".ai-workflow/",
+    ".ai-workflow.json",
+    ".ai-workflow-backups/",
+    ...linkEntries.flatMap((entry) => toIgnoreEntries(entry.linkPath))
+  ];
+
+  const gitignoreResult = await upsertGitignoreBlock(cwd, generatedIgnoreEntries);
+
   console.log("Installation complete.");
   console.log(`- profile: ${selectedProfile}`);
 
   console.log(`- opencode.jsonc: ${opencodeResult.reason}`);
+  console.log(`- .gitignore: ${gitignoreResult}`);
   console.log(`- symlink layout: ${linkCreated.length > 0 ? `created ${linkCreated.length}` : "already-up-to-date"}`);
   if (backups.length > 0) {
     console.log(`- backups created: ${backups.length}`);

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

@@ -1,10 +1,40 @@
 import path from "node:path";
 import { exists, readJsonc, writeFileSafe } from "./filesystem.js";
 import { createManagedBackup } from "./backup.js";
+import { readPackageFile } from "./package-assets.js";
 
 const LEGACY_MARKER = "_aiWorkflowManaged";
 
+function loadCanonicalFullConfig() {
+  try {
+    const raw = readPackageFile("opencode.jsonc");
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+
+    if (!parsed || typeof parsed !== "object") return null;
+    if (!parsed.agent || !parsed.command) return null;
+
+    if (!parsed.agent.default) {
+      parsed.agent.default = {
+        mode: "primary",
+        description: "Default OpenCode agent for this project",
+        prompt:
+          "You are the default OpenCode agent for this repository. Follow local project docs and validation commands."
+      };
+    }
+
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
 function buildManagedConfig(profile = "full") {
+  const canonicalFull = profile === "full" ? loadCanonicalFullConfig() : null;
+  if (canonicalFull) {
+    return canonicalFull;
+  }
+
   const fullPrimaryAgents =
     profile === "full"
       ? {
@@ -31,7 +61,7 @@ function buildManagedConfig(profile = "full") {
       ? {
           "backend-implementer": { mode: "subagent", description: "Backend implementation specialist", prompt: "{file:./.agents/skills/backend-implementer/SKILL.md}" },
           "build-and-validate": { mode: "subagent", description: "Build and validation specialist", prompt: "{file:./.agents/skills/build-and-validate/SKILL.md}" },
-          "codex-pr-workflow": { mode: "subagent", description: "PR breakdown and flow specialist", prompt: "{file:./.agents/skills/codex-pr-workflow/SKILL.md}" },
+          "pr-orchestrator": { mode: "subagent", description: "PR breakdown and flow specialist", prompt: "{file:./.agents/skills/pr-orchestrator/SKILL.md}" },
           "deploy-engineer": { mode: "subagent", description: "Deploy and release specialist", prompt: "{file:./.agents/skills/deploy-engineer/SKILL.md}" },
           "docs-writer": { mode: "subagent", description: "Documentation specialist", prompt: "{file:./.agents/skills/docs-writer/SKILL.md}" },
           "frontend-implementer": { mode: "subagent", description: "Frontend implementation specialist", prompt: "{file:./.agents/skills/frontend-implementer/SKILL.md}" },
@@ -114,6 +144,14 @@ export async function mergeOpencodeConfig(cwd, { force = false, backupRoot = ".a
   const next = {
     ...currentWithoutLegacy,
     $schema: current.$schema ?? managed.$schema,
+    ...(managed.mcp
+      ? {
+          mcp: {
+            ...(current.mcp ?? {}),
+            ...managed.mcp
+          }
+        }
+      : {}),
     agent: {
       ...(current.agent ?? {}),
       ...managed.agent

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

@@ -108,7 +108,7 @@ const FULL_PRIMARY_AGENTS = [
 const FULL_SKILLS = [
   "backend-implementer",
   "build-and-validate",
-  "codex-pr-workflow",
+  "pr-orchestrator",
   "deploy-engineer",
   "docs-writer",
   "frontend-implementer",
@@ -154,6 +154,12 @@ function buildFullFiles() {
     }
   }
 
+  // ── Napkin memory seed (used by napkin skill) ─────────────────────
+  const napkinContent = readPackageFile(".agents/napkin.md");
+  if (napkinContent !== null) {
+    files[".agents/napkin.md"] = napkinContent;
+  }
+
   // ── OpenCode commands ────────────────────────────────────────────
   const commandFiles = discoverPackageFiles("opencode/commands");
   for (const [relPath, content] of Object.entries(commandFiles)) {

package/prompts/03-create-tech-plan.md

@@ -35,14 +35,14 @@ Supporting skills:
 ```txt
 .agents/skills/tester/SKILL.md
 .agents/skills/build-and-validate/SKILL.md
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 ```
 
 Use `tester` to check whether the plan is testable.
 
 Use `build-and-validate` to define realistic validation commands.
 
-Use `codex-pr-workflow` to split the work into safe pull requests.
+Use `pr-orchestrator` to split the work into safe pull requests.
 
 ## Required input
 

package/prompts/04-breakdown-prs.md

@@ -27,7 +27,7 @@ Do not use this prompt to implement the PR directly.
 Use this prompt with:
 
 ```txt
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 ```
 
 Supporting skills:

package/prompts/05-implement-pr.md

@@ -38,11 +38,11 @@ Common options:
 Supporting skills:
 
 ```txt
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 .agents/skills/tester/SKILL.md
 ```
 
-Use `codex-pr-workflow` to keep the PR scoped.
+Use `pr-orchestrator` to keep the PR scoped.
 
 Use `tester` to check whether the implementation satisfies the PR acceptance criteria.
 

package/prompts/06-review-and-fix.md

@@ -34,14 +34,14 @@ Supporting skills:
 
 ```txt
 .agents/skills/build-and-validate/SKILL.md
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 ```
 
 Use `tester` to verify correctness, regressions, edge cases, and acceptance criteria.
 
 Use `build-and-validate` to run or interpret validation commands.
 
-Use `codex-pr-workflow` to ensure fixes stay inside the selected PR scope.
+Use `pr-orchestrator` to ensure fixes stay inside the selected PR scope.
 
 ## Required input
 

package/prompts/08-validate.md

@@ -35,14 +35,14 @@ Supporting skills:
 
 ```txt
 .agents/skills/build-and-validate/SKILL.md
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 .agents/skills/docs-writer/SKILL.md
 .agents/skills/deploy-engineer/SKILL.md
 ```
 
 Use `build-and-validate` for command execution and failure analysis.
 
-Use `codex-pr-workflow` to check PR scope and review readiness.
+Use `pr-orchestrator` to check PR scope and review readiness.
 
 Use `docs-writer` when validating documentation, prompts, templates, or runbooks.
 

package/prompts/09-deploy.md

@@ -36,7 +36,7 @@ Supporting skills:
 ```txt
 .agents/skills/build-and-validate/SKILL.md
 .agents/skills/tester/SKILL.md
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 .agents/skills/docs-writer/SKILL.md
 ```
 
@@ -44,7 +44,7 @@ Use `build-and-validate` to verify build, tests, artifacts, and command results.
 
 Use `tester` to verify acceptance criteria, smoke tests, and regression risks.
 
-Use `codex-pr-workflow` to confirm that the deployed scope matches the approved PR scope.
+Use `pr-orchestrator` to confirm that the deployed scope matches the approved PR scope.
 
 Use `docs-writer` when deployment instructions, release notes, or runbooks need documentation.
 

package/runbooks/apply-starter-to-real-project.md

@@ -184,7 +184,7 @@ Examples:
 | Nuxt Dashboard | `vue-nuxt`, `vue-nuxt`, `frontend-implementer`, `build-and-validate` |
 | WordPress | `wordpress-engineer`, `docs-writer`, `build-and-validate`, `tester` |
 | Testing automation | `tester`, `build-and-validate` |
-| Prompt/system work | `token-economy`, `opencode-agent-design`, `codex-pr-workflow`, `docs-writer` |
+| Prompt/system work | `token-economy`, `opencode-agent-design`, `pr-orchestrator`, `docs-writer` |
 | Release flow | `deploy-engineer`, `build-and-validate` |
 
 Select one primary skill for the current task. Add supporting skills only when they improve the result.

package/runbooks/branch-cleanup.md

@@ -0,0 +1,109 @@
+# Branch Cleanup Runbook
+
+## Purpose
+
+Keep local and remote branches clean after each merged PR.
+
+This reduces confusion, avoids stale references, and keeps the repository focused on active work.
+
+## When to use
+
+- After merging any PR.
+- At the end of a feature/fix cycle.
+- Before starting a new work item.
+
+## Prerequisites
+
+- Your latest PR is already merged.
+- You have no uncommitted local changes.
+
+Check:
+
+```bash
+git status -sb
+```
+
+## Standard cleanup workflow
+
+1) Switch to main and sync:
+
+```bash
+git switch main
+git pull origin main
+```
+
+1) Delete merged local work branch:
+
+```bash
+git branch -d <type>/<short-slug>
+```
+
+1) Delete remote work branch:
+
+```bash
+git push origin --delete <type>/<short-slug>
+```
+
+1) Prune stale remote references:
+
+```bash
+git fetch -p origin
+```
+
+1) Confirm final branch state:
+
+```bash
+git branch -a
+```
+
+Expected result:
+
+- Local: only `main` (or only currently active work branch + `main`)
+- Remote: only active branches that still matter
+
+## Optional one-line cleanup (local only)
+
+Delete all local branches except `main`:
+
+```bash
+git for-each-ref --format='%(refname:short)' refs/heads | while read b; do if [ "$b" != "main" ]; then git branch -D "$b"; fi; done
+```
+
+Use with care: this force-deletes local branches.
+
+## Safety rules
+
+- Do not delete `main`.
+- Do not delete branches with unmerged work unless explicitly approved.
+- Prefer `git branch -d` (safe) before `-D` (force).
+
+## Troubleshooting
+
+### "remote ref does not exist"
+
+Cause: the remote branch was already deleted.
+
+Action:
+
+```bash
+git fetch -p origin
+```
+
+### Branch still appears after deletion
+
+Cause: stale local remote-tracking reference.
+
+Action:
+
+```bash
+git fetch -p origin
+git branch -a
+```
+
+## Compliance checklist
+
+- [ ] PR merged
+- [ ] Local work branch deleted
+- [ ] Remote work branch deleted
+- [ ] Stale refs pruned
+- [ ] `git branch -a` verified

package/runbooks/deploy-checklist.md

@@ -33,7 +33,7 @@ Supporting skills:
 ```txt
 .agents/skills/build-and-validate/SKILL.md
 .agents/skills/tester/SKILL.md
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 .agents/skills/docs-writer/SKILL.md
 ```
 

package/runbooks/how-to-use-skills.md

@@ -28,7 +28,7 @@ Use this runbook when:
 │   └── SKILL.md
 ├── build-and-validate/
 │   └── SKILL.md
-├── codex-pr-workflow/
+├── pr-orchestrator/
 │   └── SKILL.md
 ├── deploy-engineer/
 │   └── SKILL.md
@@ -60,9 +60,9 @@ Use this as the default auto-load map for daily work.
 
 | Agent role | Auto-loaded primary skills | Contextual skills |
 | ---------- | -------------------------- | ----------------- |
-| `planner` | `product-manager`, `tech-lead`, `codex-pr-workflow` | `napkin` when decisions should be preserved across sprints |
-| `implementer` | `codex-pr-workflow`, `tester`, plus one implementer skill (`frontend-implementer` or `backend-implementer`) | `interface-design` for UI/UX refinement tasks |
-| `reviewer` | `tester`, `codex-pr-workflow` | `interface-design` when reviewing design/system consistency |
+| `planner` | `product-manager`, `tech-lead`, `pr-orchestrator` | `napkin` when decisions should be preserved across sprints |
+| `implementer` | `pr-orchestrator`, `tester`, plus one implementer skill (`frontend-implementer` or `backend-implementer`) | `interface-design` for UI/UX refinement tasks |
+| `reviewer` | `tester`, `pr-orchestrator` | `interface-design` when reviewing design/system consistency |
 | `validator` | `build-and-validate`, `tester` | `deploy-engineer` for deploy-readiness checks |
 | `release-manager` | `deploy-engineer` | `napkin` when release lessons should be persisted |
 
@@ -84,12 +84,12 @@ Policy:
 | Review a functional spec      | `tester`               | `product-manager`                         |
 | Create a technical plan       | `tech-lead`            | `build-and-validate`, `tester`            |
 | Review a technical plan       | `tech-lead`            | `tester`                                  |
-| Break work into PRs           | `codex-pr-workflow`    | `tech-lead`, `tester`                     |
-| Implement frontend work       | `frontend-implementer` | `codex-pr-workflow`, `tester`             |
-| Implement backend work        | `backend-implementer`  | `codex-pr-workflow`, `tester`             |
+| Break work into PRs           | `pr-orchestrator`    | `tech-lead`, `tester`                     |
+| Implement frontend work       | `frontend-implementer` | `pr-orchestrator`, `tester`             |
+| Implement backend work        | `backend-implementer`  | `pr-orchestrator`, `tester`             |
 | Write or update documentation | `docs-writer`          | `tester`                                  |
 | Validate build/test commands  | `build-and-validate`   | `tester`                                  |
-| Review implemented PR         | `tester`               | `build-and-validate`, `codex-pr-workflow` |
+| Review implemented PR         | `tester`               | `build-and-validate`, `pr-orchestrator` |
 | Fix validation failures       | `build-and-validate`   | `tester`, relevant implementer            |
 | Apply UI/design improvements  | `frontend-implementer` | `tester`, `docs-writer`                   |
 | Audit SEO/AEO/GEO visibility  | `seo-audit`            | `tester`, `docs-writer`                   |
@@ -133,7 +133,7 @@ Best for:
 
 Do not use as the primary skill for writing all code unless explicitly requested.
 
-### `codex-pr-workflow`
+### `pr-orchestrator`
 
 Use for PR discipline.
 
@@ -341,7 +341,7 @@ Use:
 
 ```txt
 prompts/04-breakdown-prs.md
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 ```
 
 Supporting skills:
@@ -382,7 +382,7 @@ Choose one primary implementer:
 Supporting skills:
 
 ```txt
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 .agents/skills/tester/SKILL.md
 ```
 
@@ -408,7 +408,7 @@ Supporting skills:
 
 ```txt
 .agents/skills/build-and-validate/SKILL.md
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 ```
 
 Goal:
@@ -500,7 +500,7 @@ Skill chaining means using multiple skills in sequence, not all at once.
 Good sequence:
 
 ```txt
-product-manager → tester → tech-lead → codex-pr-workflow → implementer → tester → build-and-validate
+product-manager → tester → tech-lead → pr-orchestrator → implementer → tester → build-and-validate
 ```
 
 Bad sequence:
@@ -574,7 +574,7 @@ frontend-implementer
 Supporting:
 
 ```txt
-codex-pr-workflow
+pr-orchestrator
 tester
 ```
 
@@ -596,7 +596,7 @@ Is the expected behavior defined but the technical path unclear?
 └── Use tech-lead.
 
 Is the work too large or needs PR planning?
-└── Use codex-pr-workflow.
+└── Use pr-orchestrator.
 
 Is the task frontend implementation?
 └── Use frontend-implementer.
@@ -637,7 +637,7 @@ Risk:
 Better:
 
 ```md
-Use `prompts/04-breakdown-prs.md` with `codex-pr-workflow` to split this feature into safe PRs.
+Use `prompts/04-breakdown-prs.md` with `pr-orchestrator` to split this feature into safe PRs.
 ```
 
 ### Implementation before requirement

package/runbooks/publish-package-checklist.md

@@ -27,6 +27,28 @@ This split prevents accidental automated npm publishes while keeping semantic-re
 4. Require `NPM_TOKEN` secret for real publish.
 5. Do not publish if repository state, version intent, or release notes are unclear.
 
+## Local terminal vs GitHub Actions authentication
+
+`NPM_TOKEN` configured in GitHub secrets applies only to GitHub Actions jobs. It does not authenticate local terminal publish commands.
+
+- If local `npm publish` fails with `E401` or `E404`, this can still be expected even when CI publish works.
+- Prefer the workflow path (`.github/workflows/publish-npm.yml`) as the source of truth for production publish.
+
+Quick checks:
+
+```bash
+# Local auth check (optional)
+npm whoami
+
+# Registry verification after CI publish
+npm view @williambeto/ai-workflow versions --json --registry https://registry.npmjs.org
+```
+
+Expected behavior:
+
+- Local may fail if terminal auth is missing.
+- CI publish should succeed when `secrets.NPM_TOKEN` is valid.
+
 ## Pre-publish checklist
 
 - [ ] `package.json` version is intentional.

package/runbooks/quick-start-guide.md

@@ -107,7 +107,7 @@ Each workflow step has a recommended prompt and specialist skill:
 | Create the requirement | `prompts/01-create-requirement.md` | `product-manager` |
 | Create the specification | `prompts/02-create-spec.md` | `product-manager` + `tester` |
 | Create the technical plan | `prompts/03-create-tech-plan.md` | `tech-lead` |
-| Break work into PRs | `prompts/04-breakdown-prs.md` | `codex-pr-workflow` |
+| Break work into PRs | `prompts/04-breakdown-prs.md` | `pr-orchestrator` |
 | Implement PR 1 | `prompts/05-implement-pr.md` | Frontend/backend/docs/deploy implementer |
 | Review and fix | `prompts/06-review-and-fix.md` | `tester` |
 | Validate | `prompts/08-validate.md` | `tester` + `build-and-validate` |

package/runbooks/tutorial-walkthroughs.md

@@ -182,7 +182,7 @@ Split a technical plan into small, reviewable, incremental pull requests that pr
 
 ### Key references
 
-- `.agents/skills/codex-pr-workflow/SKILL.md`
+- `.agents/skills/pr-orchestrator/SKILL.md`
 - `schemas/pr-breakdown.schema.json`
 - `harness/workflows/requirement-to-pr.md`
 
@@ -240,7 +240,7 @@ Review an implemented PR for correctness, scope compliance, regression risk, and
 ### Key references
 
 - `.agents/skills/tester/SKILL.md`
-- `.agents/skills/codex-pr-workflow/SKILL.md`
+- `.agents/skills/pr-orchestrator/SKILL.md`
 - `AGENTS.md` (severity model, finding types)
 
 ---
@@ -373,9 +373,9 @@ Adapt the generic workflow to a specific technology stack using the variants sys
 | Requirement | `product-manager` | `docs-writer`, `tester` |
 | Specification | `product-manager` | `tester`, `docs-writer` |
 | Technical Plan | `tech-lead` | `build-and-validate`, `tester` |
-| PR Breakdown | `codex-pr-workflow` | `tech-lead`, `tester` |
-| Implementation | `frontend-implementer` or `backend-implementer` | `codex-pr-workflow`, `tester` |
-| Review | `tester` | `build-and-validate`, `codex-pr-workflow` |
+| PR Breakdown | `pr-orchestrator` | `tech-lead`, `tester` |
+| Implementation | `frontend-implementer` or `backend-implementer` | `pr-orchestrator`, `tester` |
+| Review | `tester` | `build-and-validate`, `pr-orchestrator` |
 | Validation | `tester` | `build-and-validate` |
 | Deployment | `deploy-engineer` | `build-and-validate`, `tester` |
 

package/runbooks/validation-checklist.md

@@ -33,7 +33,7 @@ Supporting skills:
 
 ```txt
 .agents/skills/build-and-validate/SKILL.md
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 .agents/skills/docs-writer/SKILL.md
 .agents/skills/deploy-engineer/SKILL.md
 ```

package/templates/AGENTS.template.md

@@ -42,7 +42,7 @@ Use the relevant skill depending on the task.
 ```txt
 .agents/skills/product-manager/SKILL.md
 .agents/skills/tech-lead/SKILL.md
-.agents/skills/codex-pr-workflow/SKILL.md
+.agents/skills/pr-orchestrator/SKILL.md
 .agents/skills/frontend-implementer/SKILL.md
 .agents/skills/backend-implementer/SKILL.md
 .agents/skills/tester/SKILL.md
@@ -55,7 +55,7 @@ Use the relevant skill depending on the task.
 
 - Use `product-manager` to clarify requirements, scope, users, outcomes, and acceptance criteria.
 - Use `tech-lead` to create technical plans, identify architecture boundaries, risks, and trade-offs.
-- Use `codex-pr-workflow` to plan, scope, summarize, and review pull requests.
+- Use `pr-orchestrator` to plan, scope, summarize, and review pull requests.
 - Use `frontend-implementer` for UI, component, state, routing, styling, accessibility, and frontend API integration work.
 - Use `backend-implementer` for APIs, services, repositories, persistence, validation, authentication, authorization, and backend integrations.
 - Use `tester` for acceptance criteria validation, regression review, edge cases, and final approval checks.