npm - @williambeto/ai-workflow - Versions diffs - 1.19.0 → 2.1.0 - Mend

@williambeto/ai-workflow 1.19.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (391) hide show

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

@@ -1,713 +0,0 @@
-# How to Use Skills
-## Purpose
-Use this runbook to decide which specialist skill should be used for each phase of a Codex-assisted workflow.
-The goal is to avoid asking one generic agent to do everything.
-Each skill should give Codex a focused role, clearer boundaries, and better validation behavior.
-## When to use
-Use this runbook when:
-- starting a new Codex session;
-- choosing the right skill for a task;
-- switching from planning to implementation;
-- switching from implementation to validation;
-- reviewing a PR;
-- preparing deployment;
-- diagnosing why Codex output is too broad, vague, or unsafe.
-## Skill directory
-```txt
-.agents/skills/
-├── backend-implementer/
-│   └── SKILL.md
-├── build-and-validate/
-│   └── SKILL.md
-├── pr-orchestrator/
-│   └── SKILL.md
-├── deploy-engineer/
-│   └── SKILL.md
-├── docs-writer/
-│   └── SKILL.md
-├── frontend-implementer/
-│   └── SKILL.md
-├── product-manager/
-│   └── SKILL.md
-├── seo-audit/
-│   └── SKILL.md
-├── tech-lead/
-│   └── SKILL.md
-└── tester/
-    └── SKILL.md
-```
-## Core rule
-Use one primary skill per task.
-Use supporting skills only when they improve the result.
-Do not combine too many skills at once. Too many roles can make the output broad, inconsistent, or unfocused.
-## Official team router (agent auto-load + skill auto-load)
-Use this as the default auto-load map for daily work.
-| Agent role | Auto-loaded primary skills | Contextual skills |
-| ---------- | -------------------------- | ----------------- |
-| `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 |
-Policy:
-- keep one primary agent role per workflow step;
-- use one primary skill and up to one supporting skill per task when possible;
-- add `napkin` for recurring operational decisions;
-- add `interface-design` only for interface-focused work.
-## Skill selection table
-| Task type                     | Primary skill          | Supporting skills                         |
-| ----------------------------- | ---------------------- | ----------------------------------------- |
-| Clarify an idea or feature    | `product-manager`      | `tester`, `docs-writer`                   |
-| Create a requirement          | `product-manager`      | `tester`, `docs-writer`                   |
-| Review a requirement          | `product-manager`      | `tester`                                  |
-| Create a functional spec      | `product-manager`      | `tester`, `docs-writer`                   |
-| 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           | `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`, `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`                   |
-| Prepare deployment            | `deploy-engineer`      | `build-and-validate`, `tester`            |
-| Review deployment readiness   | `deploy-engineer`      | `tester`, `build-and-validate`            |
-## Skill responsibilities
-### `product-manager`
-Use for product clarity.
-Best for:
-- problem definition;
-- target user;
-- goal;
-- scope;
-- user stories;
-- acceptance criteria;
-- assumptions;
-- open questions;
-- requirement readiness.
-Do not use as the primary skill for implementation.
-### `tech-lead`
-Use for technical direction.
-Best for:
-- architecture boundaries;
-- current state analysis;
-- technical approach;
-- trade-offs;
-- file boundaries;
-- risk analysis;
-- validation strategy;
-- PR breakdown input.
-Do not use as the primary skill for writing all code unless explicitly requested.
-### `pr-orchestrator`
-Use for PR discipline.
-Best for:
-- PR planning;
-- PR scope;
-- changed file summaries;
-- validation summaries;
-- regression risks;
-- final PR summaries;
-- checking whether a PR stayed in scope.
-Do not use as a substitute for product, technical, or test judgment.
-### `frontend-implementer`
-Use for frontend implementation.
-Best for:
-- UI components;
-- pages;
-- layouts;
-- routing;
-- frontend state;
-- forms;
-- styling;
-- accessibility basics;
-- frontend API integration;
-- frontend tests.
-Do not use to redesign the product or invent a new UI system unless the design/technical plan requires it.
-### `backend-implementer`
-Use for backend implementation.
-Best for:
-- API endpoints;
-- services;
-- repositories;
-- validation;
-- authentication;
-- authorization;
-- persistence;
-- migrations;
-- external integrations;
-- backend tests.
-Do not use to change API contracts, database schema, or authorization behavior silently.
-### `tester`
-Use for validation and review.
-Best for:
-- acceptance criteria validation;
-- regression review;
-- edge cases;
-- severity classification;
-- evidence-based findings;
-- approval recommendation;
-- separating confirmed issues from hypotheses.
-Do not use to implement fixes unless explicitly requested.
-### `build-and-validate`
-Use for command-based validation.
-Best for:
-- lint;
-- typecheck;
-- tests;
-- builds;
-- artifacts;
-- CI failures;
-- command discovery;
-- package manager rules;
-- failure diagnosis.
-Do not use to invent command results or switch package managers without reason.
-### `docs-writer`
-Use for documentation.
-Best for:
-- README;
-- AGENTS;
-- DESIGN;
-- requirements;
-- specs;
-- technical plans;
-- runbooks;
-- templates;
-- Markdown validation;
-- documentation clarity.
-Do not use to invent project behavior, commands, or architecture.
-### `deploy-engineer`
-Use for deployment and release readiness.
-Best for:
-- deploy plans;
-- environment configuration;
-- secrets handling;
-- smoke tests;
-- rollback plans;
-- CI/CD review;
-- production risk;
-- post-deploy checks.
-Do not use to deploy production without explicit instruction.
-## Workflow by phase
-### Phase 1 — Idea to requirement
-Use:
-```txt
-prompts/01-create-requirement.md
-.agents/skills/product-manager/SKILL.md
-```
-Optional validation:
-```txt
-.agents/skills/tester/SKILL.md
-```
-Goal:
-- make the problem clear;
-- define target user;
-- define scope;
-- write testable acceptance criteria.
-Do not implement.
-### Phase 2 — Requirement to specification
-Use:
-```txt
-prompts/02-create-spec.md
-.agents/skills/product-manager/SKILL.md
-```
-Optional validation:
-```txt
-.agents/skills/tester/SKILL.md
-```
-Goal:
-- define behavior;
-- define flows;
-- define states;
-- define edge cases;
-- make the spec testable.
-Do not write the technical plan yet unless requested.
-### Phase 3 — Specification to technical plan
-Use:
-```txt
-prompts/03-create-tech-plan.md
-.agents/skills/tech-lead/SKILL.md
-```
-Supporting skills:
-```txt
-.agents/skills/build-and-validate/SKILL.md
-.agents/skills/tester/SKILL.md
-```
-Goal:
-- identify current state;
-- follow existing patterns;
-- define the technical approach;
-- list likely files;
-- define risks;
-- define validation strategy.
-Do not implement.
-### Phase 4 — Technical plan to PR breakdown
-Use:
-```txt
-prompts/04-breakdown-prs.md
-.agents/skills/pr-orchestrator/SKILL.md
-```
-Supporting skills:
-```txt
-.agents/skills/tech-lead/SKILL.md
-.agents/skills/tester/SKILL.md
-```
-Goal:
-- split work into small PRs;
-- define PR scope;
-- define expected files;
-- define validation per PR;
-- define regression risks.
-Do not implement.
-### Phase 5 — Implement selected PR
-Use:
-```txt
-prompts/05-implement-pr.md
-```
-Choose one primary implementer:
-```txt
-.agents/skills/frontend-implementer/SKILL.md
-.agents/skills/backend-implementer/SKILL.md
-.agents/skills/docs-writer/SKILL.md
-.agents/skills/deploy-engineer/SKILL.md
-.agents/skills/build-and-validate/SKILL.md
-```
-Supporting skills:
-```txt
-.agents/skills/pr-orchestrator/SKILL.md
-.agents/skills/tester/SKILL.md
-```
-Goal:
-- implement only the selected PR;
-- preserve scope;
-- list changed files;
-- validate or document unexecuted checks.
-Do not implement future PRs.
-### Phase 6 — Review and fix
-Use:
-```txt
-prompts/06-review-and-fix.md
-.agents/skills/tester/SKILL.md
-```
-Supporting skills:
-```txt
-.agents/skills/build-and-validate/SKILL.md
-.agents/skills/pr-orchestrator/SKILL.md
-```
-Goal:
-- review against the selected PR;
-- identify findings;
-- fix only in-scope issues;
-- validate after fixes.
-Do not refactor unrelated code.
-### Phase 7 — Validate
-Use:
-```txt
-prompts/08-validate.md
-.agents/skills/tester/SKILL.md
-```
-Supporting skill:
-```txt
-.agents/skills/build-and-validate/SKILL.md
-```
-Goal:
-- check acceptance criteria;
-- check validation evidence;
-- list untested areas;
-- list regression risks;
-- give approval recommendation.
-Do not implement fixes unless explicitly requested.
-### Phase 8 — Deploy
-Use:
-```txt
-prompts/09-deploy.md
-.agents/skills/deploy-engineer/SKILL.md
-```
-Supporting skills:
-```txt
-.agents/skills/build-and-validate/SKILL.md
-.agents/skills/tester/SKILL.md
-```
-Goal:
-- define deployment scope;
-- confirm validation evidence;
-- check environment configuration;
-- define smoke tests;
-- define rollback or recovery.
-Do not deploy production unless explicitly instructed.
-## How to ask Codex to use a skill
-Use a direct instruction like:
-```md
-Use the skill `.agents/skills/tester/SKILL.md`.
-Validate this PR against the selected requirement, specification, technical plan, and PR plan.
-Do not implement fixes. Return findings with severity, evidence, impact, and final recommendation.
-```
-Or:
-```md
-Use the skill `.agents/skills/frontend-implementer/SKILL.md`.
-Implement only PR 1 from the approved PR plan.
-Preserve existing behavior, avoid unrelated refactors, list changed files, and run or document validation.
-```
-## Skill chaining
-Skill chaining means using multiple skills in sequence, not all at once.
-Good sequence:
-```txt
-product-manager → tester → tech-lead → pr-orchestrator → implementer → tester → build-and-validate
-```
-Bad sequence:
-```txt
-Use all skills and implement the whole feature.
-```
-Why the bad sequence is risky:
-- scope becomes unclear;
-- roles conflict;
-- output becomes too broad;
-- implementation may start before validation;
-- review boundaries become weak.
-## Multi-skill rules
-Use multiple skills only when the task clearly needs them.
-Examples:
-### Requirement review
-Primary:
-```txt
-product-manager
-```
-Supporting:
-```txt
-tester
-```
-Reason:
-- product manager checks clarity and scope;
-- tester checks testability.
-### Technical plan
-Primary:
-```txt
-tech-lead
-```
-Supporting:
-```txt
-build-and-validate
-tester
-```
-Reason:
-- tech lead defines approach;
-- build-and-validate checks realistic commands;
-- tester checks acceptance criteria coverage.
-### PR implementation
-Primary:
-```txt
-frontend-implementer
-```
-Supporting:
-```txt
-pr-orchestrator
-tester
-```
-Reason:
-- implementer changes files;
-- PR workflow controls scope;
-- tester checks acceptance criteria and regression risk.
-## Decision tree
-Use this quick decision tree:
-```txt
-Is the request unclear or product-focused?
-└── Use product-manager.
-Is the expected behavior defined but the technical path unclear?
-└── Use tech-lead.
-Is the work too large or needs PR planning?
-└── Use pr-orchestrator.
-Is the task frontend implementation?
-└── Use frontend-implementer.
-Is the task backend implementation?
-└── Use backend-implementer.
-Is the task documentation?
-└── Use docs-writer.
-Is the task validation, review, or acceptance criteria checking?
-└── Use tester.
-Is the task command/build/test/CI focused?
-└── Use build-and-validate.
-Is the task release/deployment focused?
-└── Use deploy-engineer.
-```
-## Anti-patterns
-Avoid these patterns.
-### Generic agent does everything
-```md
-Build the full feature, test it, document it, and prepare deployment.
-```
-Risk:
-- too broad;
-- hard to review;
-- likely scope creep;
-- unclear validation.
-Better:
-```md
-Use `prompts/04-breakdown-prs.md` with `pr-orchestrator` to split this feature into safe PRs.
-```
-### Implementation before requirement
-```md
-Implement this idea directly.
-```
-Risk:
-- unclear behavior;
-- missing acceptance criteria;
-- wrong scope.
-Better:
-```md
-Use `prompts/01-create-requirement.md` with `product-manager` first.
-```
-### Validation without evidence
-```md
-Check if this is good.
-```
-Risk:
-- vague review;
-- no acceptance criteria;
-- no command evidence.
-Better:
-```md
-Use `tester` to validate this against the acceptance criteria. Separate confirmed issues from hypotheses and list untested areas.
-```
-### Too many skills at once
-```md
-Use all skills to build this.
-```
-Risk:
-- conflicting roles;
-- bloated output;
-- hidden assumptions.
-Better:
-```md
-Use `tech-lead` first to create a technical plan. Do not implement yet.
-```
-## Quality gate before switching skills
-Before moving from one skill to the next, check:
-- Is the current output complete enough?
-- Is the final recommendation clear?
-- Are assumptions visible?
-- Are open questions listed?
-- Are blockers resolved or explicitly deferred?
-- Is the next skill actually needed?
-- Is the next step small enough?
-## Final instruction
-Use skills deliberately.
-Choose the smallest role set that can safely complete the current workflow step.