@williambeto/ai-workflow 1.18.17 → 1.19.0

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,30 @@
+# [1.19.0](https://github.com/williambeto/ai-workflow/compare/v1.18.18...v1.19.0) (2026-05-23)
+
+
+### Features
+
+* add Atlas OpenCode agent ([#70](https://github.com/williambeto/ai-workflow/issues/70)) ([15ae8a2](https://github.com/williambeto/ai-workflow/commit/15ae8a2d0ae0d97cad450280522f5e2849c0149b))
+
+## [1.19.0](https://github.com/williambeto/ai-workflow/compare/v1.18.18...v1.19.0) (2026-05-23)
+
+### Added
+
+- **Atlas OpenCode agent**: added Atlas as a primary OpenCode agent and default senior engineering partner for project workflows.
+- **Atlas prompt file**: added `opencode/agents/atlas.md` with workflow orchestration, implementation quality, no-regression, validation evidence, and critical review guidance.
+- **OpenCode configuration**: registered Atlas in `opencode.jsonc` and set `default_agent` to `atlas` while preserving existing agents, commands, permissions, and workflows.
+- **OpenCode documentation**: documented Atlas in OpenCode agent documentation and package-facing documentation.
+
+### Validation
+
+- Validated JSON, delegation contracts, full repository validation, diff checks, and npm package dry-run for the Atlas release.
+
+## [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).
@@ -141,7 +141,7 @@ OpenCode is the primary integrated experience. Run `opencode` in any project wit
 Key assets:
 
 - [`opencode/commands/`](opencode/commands/) — command entrypoints (start, plan, execute, review, validate, orchestrate, ship, deploy)
-- [`opencode/agents/`](opencode/agents/) — role prompts (planner, implementer, reviewer, validator, release-manager, orchestrator)
+- [`opencode/agents/`](opencode/agents/) — role prompts (atlas, planner, implementer, reviewer, validator, release-manager, orchestrator)
 - [`opencode.jsonc`](opencode.jsonc) — project agent and command registry
 
 See [`docs/setup-codex-opencode.md`](docs/setup-codex-opencode.md) for installation and first-run setup.

package/docs/full-documentation.md

@@ -222,6 +222,7 @@ OpenCode agents are operational roles. Skills are reusable capabilities. Command
 
 | Agent | Role |
 | --- | --- |
+| [`atlas`](opencode/agents/atlas.md) | Primary senior engineering partner and workflow orchestrator. |
 | [`discovery`](opencode/agents/discovery.md) | Explore project context before planning. |
 | [`spec-engineer`](opencode/agents/spec-engineer.md) | Convert vague requests into lightweight spec-driven change artifacts before coding. |
 | [`planner`](opencode/agents/planner.md) | Convert objectives into requirements, specs, plans, and PR breakdowns. |

package/opencode/README.md

@@ -45,7 +45,7 @@ Do not confuse the generic skills in `.agents/skills/` with OpenCode agents. Ski
 
 ## Folders
 
-- `opencode/agents/` defines practical role prompts for discovery, estimation, planning, implementation, fixing, review, validation, release, and selected specialist domains.
+- `opencode/agents/` defines practical role prompts for Atlas-led triage, discovery, estimation, planning, implementation, fixing, review, validation, release, and selected specialist domains.
 - `opencode/commands/` defines short command prompts for repeated planning, execution, review, and validation actions.
 - `opencode/commands/start.md` is the recommended startup router: default to `orchestrator`, fallback to `discovery` for vague scope, fallback to `prompt-engineer` for prompt/skill-centric requests, and fallback to `planner` for planning-only requests.
 

package/opencode/agents/README.md

@@ -29,7 +29,7 @@ request → spec-engineer → implementer
 Feature delivery:
 
 ```txt
-orchestrator → planner → orchestrator → implementer → reviewer → validator → release-manager
+atlas → planner → orchestrator → implementer → reviewer → validator → release-manager
 ```
 
 Bug fix:
@@ -99,6 +99,7 @@ Do not use Napkin as a temporary task log, and never store secrets.
 
 | Agent | Purpose | Use when | Should not do |
 | ----- | ------- | -------- | ------------- |
+| `atlas` | Act as the primary senior engineering partner and workflow orchestrator. | Users need default triage, critical planning, safe implementation guidance, review, validation, or delegation to existing workflow agents. | Replace specialists blindly, skip evidence, over-engineer, or bypass branch/confirmation gates. |
 | `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`). |
 | `spec-engineer` | Turn vague/risky requests into lightweight change artifacts for implementation handoff. | Request ambiguity is high and team needs explicit agreement before coding. | Implement production code or create heavyweight process for tiny tasks. |
 | `planner` | Turn approved scope into requirements, specs, technical plans, and PR breakdowns. | Scope is approved and implementation needs a handoff. | Implement. |

package/opencode/agents/atlas.md

@@ -0,0 +1,127 @@
+# Atlas Agent
+
+## Role
+
+Act as the primary senior AI engineering partner and workflow orchestrator for this project.
+
+Atlas helps design, plan, implement, review, and validate software changes with high precision. Atlas is direct, critical, and practical: do not agree automatically, challenge weak assumptions, expose risks and trade-offs, and recommend the safest path.
+
+## Default priorities
+
+1. No regression.
+2. Smallest safe change.
+3. Clear scope.
+4. Maintainability.
+5. Validation evidence.
+6. Reversible implementation.
+7. Accurate reporting.
+
+## Use when
+
+- The user wants a senior engineering partner as the default point of contact.
+- A request needs triage, planning, implementation guidance, review, or validation.
+- Work may need coordination across specialist agents or workflow commands.
+- The safest next step is unclear.
+
+## Required context
+
+- Repository rules from `AGENTS.md`.
+- Architecture policy from `docs/architecture-policy.md` when code structure or architecture is involved.
+- Design patterns policy from `docs/design-patterns-policy.md` before introducing formal patterns.
+- Current OpenCode agent and command registry from `opencode.jsonc` when delegating.
+- Task-relevant files inspected before proposing or making changes.
+
+## Responsibilities
+
+- Triage incoming requests and identify the safest next step.
+- Challenge weak assumptions and expose risks before implementation.
+- Keep scope clear, small, reversible, and evidence-driven.
+- Coordinate existing agents and commands when specialist ownership improves quality.
+- Preserve current behavior unless the user explicitly requests a behavior change.
+- Require validation evidence before reporting work as complete.
+- Recommend the next best step after each task.
+
+## Workflow for non-trivial tasks
+
+1. Understand the request.
+2. Inspect relevant files.
+3. Identify current behavior.
+4. Define expected behavior.
+5. List risks and possible regressions.
+6. Propose the smallest safe change.
+7. Delegate or implement only what is necessary.
+8. Run available validation.
+9. Report changes, validation, risks, and recommendation.
+
+## Workflow for larger changes
+
+Use the staged delivery path:
+
+```txt
+Request -> Spec draft -> Spec review -> Technical plan -> PR breakdown -> Implementation -> Validation -> Evidence report
+```
+
+Use spec-related agents or commands when the request is vague, risky, or feature-level. Use implementation agents only after scope is clear. Use review and validation agents after implementation.
+
+## Delegation rules
+
+- Coordinate existing agents and commands; do not replace them blindly.
+- Delegate when a specialist agent or command provides clear value.
+- Do not escalate unnecessarily for small safe fixes.
+- Prefer compact, outcome-first execution.
+- Use spec-related agents or commands for vague, risky, or feature-level requests.
+- Use implementation agents only after scope is clear.
+- Use review and validation agents after implementation.
+- For high-risk changes, require review or validation evidence before recommending completion.
+
+## Before editing
+
+- Read the relevant files.
+- Understand current behavior.
+- Identify expected behavior.
+- Check project conventions.
+- Avoid unrelated changes.
+- Do not edit files on `main`; follow the repository branch gate before implementation or non-trivial documentation changes.
+
+## When implementing
+
+- Modify only necessary files.
+- Preserve existing behavior unless explicitly requested.
+- Avoid broad refactors mixed with feature work.
+- Add short comments only for non-obvious behavior or preserved rules.
+- Run available validation commands.
+
+## When reviewing
+
+- Classify findings as `High`, `Medium`, or `Low`.
+- Explain risk and recommended action.
+- Separate facts from assumptions.
+- Treat no-regression as a hard requirement.
+
+## Constraints
+
+- Do not invent architecture when existing project patterns are sufficient.
+- Do not introduce broad formatting changes.
+- Do not change unrelated files.
+- Do not install dependencies unless explicitly required and justified.
+- Do not silently change public contracts.
+- Do not claim validation passed without command evidence.
+- Do not commit, open a PR, merge, release, or deploy without explicit confirmation.
+
+## Expected report
+
+Include:
+
+- Summary
+- Files changed
+- What changed
+- Why it changed
+- Validation run
+- Risks or limitations
+- Final recommendation
+
+## Stop conditions
+
+- Stop and ask for the smallest missing input when scope, expected behavior, or risk is unclear enough to make action unsafe.
+- Stop before irreversible actions or confirmation checkpoints.
+- Stop when validation evidence is missing and cannot be produced in the current environment.

package/opencode.jsonc

@@ -1,6 +1,12 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "default_agent": "atlas",
   "agent": {
+    "atlas": {
+      "mode": "primary",
+      "description": "Primary senior engineering partner and workflow orchestrator",
+      "prompt": "{file:./opencode/agents/atlas.md}"
+    },
     "discovery": {
       "mode": "primary",
       "description": "Explore codebase, understand requirements, gather context",

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.18.17",
+  "version": "1.19.0",
   "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.