@williambeto/ai-workflow 1.18.15 → 1.18.17

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,19 @@
+## [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)
+
+
+### Bug Fixes
+
+* **audit:** harden artifact safety and align CLI/OpenCode catalog ([047c3bd](https://github.com/williambeto/ai-workflow/commit/047c3bd92d2d7fd3bc7bef2afc5f29a8fba441e9))
+* **audit:** harden artifact safety and align CLI/OpenCode catalog ([a13f489](https://github.com/williambeto/ai-workflow/commit/a13f489c1a5cc7a06ba67580b30dd30f670d9b62))
+
 ## [1.18.15](https://github.com/williambeto/ai-workflow/compare/v1.18.14...v1.18.15) (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
 

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.15",
+  "version": "1.18.17",
   "name": "@williambeto/ai-workflow",
   "description": "AI Workflow Kit repository for designing and validating AI-assisted software delivery workflows with Codex and OpenCode",
   "license": "MIT",
@@ -56,6 +56,7 @@
     "validate:json": "node scripts/validate-json.mjs",
     "validate:structure": "node scripts/validate-structure.mjs",
     "validate:refs": "node scripts/validate-refs.mjs",
+    "validate:artifact-safety": "node scripts/validate-artifact-safety.mjs",
     "validate:links": "node scripts/validate-links.mjs",
     "validate:docs-consistency": "node scripts/validate-doc-consistency.mjs",
     "validate:workflow": "node scripts/validate-workflow.mjs",

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/package-assets.js

@@ -38,6 +38,21 @@ export function readPackageFile(relativePath) {
   }
 }
 
+/**
+ * Resolve the current kit version from package metadata.
+ * Returns null if package.json cannot be read/parsed.
+ */
+export function getPackageVersion() {
+  try {
+    const raw = readPackageFile("package.json");
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    return typeof parsed.version === "string" ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Discover ALL files under a package-relative directory.
  * Returns a flat map of { relativePath: content }.

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

@@ -1,4 +1,4 @@
-import { getFullAgentContent, getFullSkillFiles, discoverPackageFiles, readPackageFile } from "./package-assets.js";
+import { getFullAgentContent, getFullSkillFiles, discoverPackageFiles, readPackageFile, getPackageVersion } from "./package-assets.js";
 
 const COMMON_FILES = {
   "README.workflow.md": `# AI Workflow Setup\n\nThis project is configured for Codex and OpenCode workflows via \`ai-workflow\`.\n\n## Quick start\n\n1. Run validation command for your project.\n2. Start your AI workflow using repository prompts and agent commands.\n3. Keep changes small and evidence-based.\n`,
@@ -101,20 +101,20 @@ const FULL_PRIMARY_AGENTS = [
   "release-manager",
   "wordpress-engineer",
   "prompt-engineer",
+  "spec-engineer",
   "orchestrator"
 ];
 
 const FULL_SKILLS = [
   "backend-implementer",
   "build-and-validate",
-  "codex-pr-workflow",
+  "pr-orchestrator",
   "deploy-engineer",
   "docs-writer",
   "frontend-implementer",
   "interface-design",
   "minimal-context",
   "napkin",
-  "nuxt-dashboard-workflow",
   "opencode-agent-design",
   "playwright-cli",
   "product-manager",
@@ -123,10 +123,12 @@ const FULL_SKILLS = [
   "tech-lead",
   "tester",
   "token-economy",
-  "vue-clean-architecture",
+  "vue-nuxt",
   "wordpress-engineer"
 ];
 
+const KIT_VERSION = getPackageVersion() ?? "unknown";
+
 function buildFullFiles() {
   const files = {};
 
@@ -249,7 +251,7 @@ export function buildAiWorkflowConfig({ profile, managedFiles, managedLinks = []
   return {
     $schema: "./schemas/ai-workflow.schema.json",
     version: 2,
-    kitVersion: "0.1.0",
+    kitVersion: KIT_VERSION,
     mode: "standalone",
     profile,
     installedAt: now,

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/publication-readiness-checklist.md

@@ -16,14 +16,20 @@ Use this checklist before making the GitHub repository public or before a major
 - [ ] 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.
+- [ ] Local source archives are created with safe commands (`git archive`), not ad-hoc workspace zips.
+- [ ] Local package inspection uses `npm pack --dry-run` and confirms no secrets or `.git/` content.
 
 ## Suggested verification commands
 
 ```bash
 npm run validate
+npm pack --dry-run
+git archive --format=zip --output ai-workflow-source.zip HEAD
 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.
+
+Avoid manually zipping the working directory (`zip -r .`) for distribution, because it can accidentally include `.env*`, `.git/`, and other local-only files.

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.