@williambeto/ai-workflow 1.18.17 → 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/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [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)
 
 

package/README.md

@@ -108,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/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.18.17",
+  "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/core/templates.js

@@ -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/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.