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/use-linear-for-operational-planning.md DELETED Viewed

@@ -1,185 +0,0 @@
-# Use Linear for Operational Planning
-## Purpose
-Use this runbook when `ROADMAP.md` is too large for day-to-day planning and the team needs a smaller, current, and auditable operational backlog.
-Linear should become the operational source of truth for next work. `ROADMAP.md` remains the strategic and historical source of truth.
-## When to use
-Use Linear when:
-- the next PR is hard to identify from `ROADMAP.md`;
-- roadmap items are complete but still appear in older audit reports;
-- product, planning, implementation, and validation work need one shared queue;
-- each task needs owner, priority, status, acceptance criteria, and delivery evidence.
-Skip Linear for one-off local edits where a short checklist is enough.
-## Source-of-truth split
-| Source | Role |
-| --- | --- |
-| Linear | Current operational backlog, priorities, owners, status, blockers, and next PRs. |
-| GitHub PRs | Delivery evidence, review discussion, changed files, validation results, and merge history. |
-| `ROADMAP.md` | Strategic phases, durable product direction, historical context, and large milestone sequencing. |
-| `CHANGELOG.md` | Published or release-relevant changes. |
-| `docs/reports/` | Audit inputs, scorecards, and evidence-backed recommendations. |
-Do not use `ROADMAP.md` alone to decide the next implementation step when Linear exists.
-## Linear MCP setup
-Linear's remote MCP endpoint is:
-```txt
-https://mcp.linear.app/mcp
-```
-### Codex
-Preferred setup through the Codex CLI:
-```bash
-codex mcp add linear --url https://mcp.linear.app/mcp
-```
-If this is the first MCP server configured for Codex, enable the remote MCP client in `~/.codex/config.toml`:
-```toml
-[features]
-experimental_use_rmcp_client = true
-```
-Equivalent manual configuration:
-```toml
-[features]
-experimental_use_rmcp_client = true
-[mcp_servers.linear]
-url = "https://mcp.linear.app/mcp"
-```
-Then authenticate:
-```bash
-codex mcp login linear
-```
-### OpenCode
-This repository includes Linear's remote MCP server in `opencode.jsonc`:
-```json
-{
-  "mcp": {
-    "linear": {
-      "type": "remote",
-      "url": "https://mcp.linear.app/mcp",
-      "enabled": true
-    }
-  }
-}
-```
-After updating `opencode.jsonc`, quit and restart OpenCode so the MCP server is loaded from the project config.
-Authenticate through OpenCode's MCP/OAuth flow when prompted. Keep authentication state local to the developer machine.
-Do not commit personal MCP tokens, OAuth state, API keys, or local `~/.codex/config.toml` files to this repository.
-## Recommended Linear project structure
-Create one Linear project:
-```txt
-Public readiness score improvement
-```
-Use these milestones:
-1. **Validation trust**
-2. **Onboarding clarity**
-3. **Platform simplification**
-Initial issue queue:
-| Milestone | Issue | Initial status | Evidence source |
-| --- | --- | --- | --- |
-| Validation trust | Fix E2E validation drift | Done | `npm run test:e2e` passes 14/14; `ROADMAP.md`; `CHANGELOG.md`. |
-| Validation trust | Define stable validation output contract | Todo | `docs/reports/public-readiness-backlog.md`. |
-| Validation trust | Create Go/No-Go public checklist | Todo | `docs/reports/public-readiness-backlog.md`. |
-| Onboarding clarity | Add one adoption decision table | Todo | `docs/reports/project-evaluation.md`. |
-| Onboarding clarity | Reduce entry-doc circular/deep reference chains | Todo | `npm run validate` warnings and audit report. |
-| Platform simplification | Phase 17 PR 1 — Move Codex prompts to legacy | Todo | `ROADMAP.md` Phase 17. |
-| Platform simplification | Phase 17 PR 2 — Simplify `AGENTS.md` to OpenCode-only | Todo | `ROADMAP.md` Phase 17. |
-| Platform simplification | Phase 17 PR 3 — Update README and core docs for single-path | Todo | `ROADMAP.md` Phase 17. |
-## Issue template
-Use this format for Linear issues:
-```md
-## Objective
-What outcome should this issue achieve?
-## Scope
-Included:
-- ...
-Not included:
-- ...
-## Acceptance criteria
-- ...
-## Evidence required
-- Command:
-- Expected result:
-- Manual review:
-## Source context
-- ROADMAP.md:
-- Report/backlog:
-- Related PR:
-## Risk
-Low | Medium | High
-```
-## Operating rules
-- Keep one Linear issue equivalent to one small PR whenever possible.
-- Mark an issue `Done` only when validation evidence is attached or linked.
-- Link the GitHub PR to the Linear issue before review.
-- If an audit finding is already fixed, close it with evidence instead of recreating work.
-- Update `ROADMAP.md` only for durable strategic changes, phase status changes, or historical milestones.
-- Update `CHANGELOG.md` only for published or release-relevant changes.
-## Planning cadence
-Before selecting the next PR:
-1. Check Linear for highest-priority `Todo` or `Blocked` issues.
-2. Confirm the issue still matches current repository evidence.
-3. If evidence contradicts the issue, update or close the issue before implementation.
-4. Select one issue.
-5. Create a scoped branch.
-6. Implement only that issue.
-7. Attach validation evidence before marking it `Done`.
-## Acceptance criteria for Linear adoption
-- A Linear project exists for public-readiness score improvement.
-- The known completed E2E drift item is marked `Done` with evidence.
-- Planned score-improvement items are represented as small issues.
-- Each active issue has acceptance criteria and required evidence.
-- `ROADMAP.md` is no longer used as the only day-to-day planning source.

package/runbooks/use-napkin-project-memory.md DELETED Viewed

@@ -1,77 +0,0 @@
-# Use Napkin Project Memory
-## What Napkin is
-Napkin is the repository's durable project-memory workflow.
-It is implemented with:
-- the skill at `.agents/skills/napkin/SKILL.md`;
-- the memory file at `.agents/napkin.md`.
-Napkin is discoverable by both Codex and OpenCode workflows, but it follows progressive disclosure.
-Progressive disclosure means: do not load or rewrite all memory on every task. Read and apply only entries relevant to the active scope.
-## When to read Napkin
-- At task start when work depends on repository structure, workflow constraints, validation behavior, or recurring conventions.
-- Before review and handoff to avoid repeating known mistakes.
-- Before changing skills, prompts, runbooks, validation scripts, or agent instructions.
-## When to update Napkin
-- A repeated failure mode was confirmed and has a clear reusable rule.
-- A user correction should become a stable operating rule.
-- A validated tactic repeatedly improves quality or reliability.
-Do not update Napkin for one-off notes, temporary investigations, or daily status logs.
-## Entry format
-Use this format for each durable entry:
-```md
-### [YYYY-MM-DD] <Category>: <Rule>
-- Instead of: <old behavior or failed assumption>
-- Do: <small repeatable behavior>
-- Evidence/source: <file path, command output, review note, or user correction>
-```
-## Good vs bad examples
-Good:
-```md
-### [2026-05-11] Validation: Run full validation before final report
-- Instead of: Reporting success after partial checks.
-- Do: Run `npm run validate` and include command result evidence.
-- Evidence/source: `AGENTS.md` evidence requirements.
-```
-Bad (task log):
-```md
-### [2026-05-11] Worked on docs
-- Did many edits and fixed things.
-```
-Bad (secret):
-```md
-### [2026-05-11] CI fix
-- Token: ghp_...
-```
-## Validation checklist
-- `.agents/skills/napkin/SKILL.md` exists and is valid.
-- `.agents/napkin.md` exists.
-- Entries are durable, concise, and actionable.
-- Entries include `Instead of`, `Do`, and `Evidence/source`.
-- No secrets or sensitive data are stored.
-- Memory is curated: duplicates merged, stale entries removed.

package/templates/AGENTS.template.md DELETED Viewed

@@ -1,397 +0,0 @@
-# AGENTS.md
-## Purpose
-This file defines how AI agents should work in this repository.
-It exists to make AI-assisted development safer, more consistent, and easier to review.
-Agents must use this file as the main project instruction source before planning, implementing, reviewing, validating, or deploying changes.
-## Repository context
-[Describe the repository purpose]
-Example:
-```txt
-This repository is a Workflow starter kit for studying and evolving AI-assisted software delivery workflows with ordered prompts, specialist skills, templates, runbooks, and progressive validation.
-```
-## Primary workflow
-Agents should follow this workflow unless the user explicitly requests a different path:
-1. clarify the requirement;
-2. create or update the functional specification;
-3. create or update the technical plan;
-4. break the work into small pull requests;
-5. implement one PR at a time;
-6. review and fix the selected PR;
-7. validate with evidence;
-8. prepare deployment only when requested.
-Do not skip steps for medium or high-risk changes.
-For small documentation changes, use a proportional workflow.
-## Specialist skills
-Use the relevant skill depending on the task.
-```txt
-.agents/skills/product-manager/SKILL.md
-.agents/skills/tech-lead/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
-.agents/skills/build-and-validate/SKILL.md
-.agents/skills/docs-writer/SKILL.md
-.agents/skills/deploy-engineer/SKILL.md
-```
-### Skill usage guide
-- 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 `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.
-- Use `build-and-validate` for commands, builds, lint, typecheck, tests, artifacts, and failure diagnosis.
-- Use `docs-writer` for README, AGENTS, DESIGN, requirements, specs, tech plans, runbooks, and documentation validation.
-- Use `deploy-engineer` for release readiness, environment configuration, smoke tests, rollback, and deployment risk.
-## Prompt workflow
-Use the ordered prompts when running a structured workflow.
-```txt
-prompts/00-bootstrap-project.md
-prompts/01-create-requirement.md
-prompts/02-create-spec.md
-prompts/03-create-tech-plan.md
-prompts/04-breakdown-prs.md
-prompts/05-implement-pr.md
-prompts/06-review-and-fix.md
-prompts/07-apply-design.md
-prompts/08-validate.md
-prompts/09-deploy.md
-```
-### Prompt usage guide
-- Use `00-bootstrap-project.md` to create the initial project foundation.
-- Use `01-create-requirement.md` to turn an idea into a product requirement.
-- Use `02-create-spec.md` to turn an approved requirement into a functional specification.
-- Use `03-create-tech-plan.md` to turn an approved specification into a technical plan.
-- Use `04-breakdown-prs.md` to split the technical plan into reviewable PRs.
-- Use `05-implement-pr.md` to implement one selected PR.
-- Use `06-review-and-fix.md` to review and fix one implemented PR.
-- Use `07-apply-design.md` to apply UI/design refinements without changing product behavior.
-- Use `08-validate.md` to validate with evidence before moving forward.
-- Use `09-deploy.md` to prepare or review deployment.
-## Hard constraints
-Agents must always follow these constraints:
-- Preserve existing behavior unless a behavior change is explicitly requested.
-- Treat no-regression as a hard requirement.
-- Keep changes small and reviewable.
-- Do not implement multiple PRs at once.
-- Do not introduce unrelated refactors.
-- Do not add, remove, or upgrade dependencies without explicit justification.
-- Do not invent architecture when existing project patterns are sufficient.
-- Do not change public contracts silently.
-- Do not expose secrets, tokens, credentials, or private keys.
-- Do not claim tests, builds, or validations passed without evidence.
-- Do not hide untested areas.
-- Do not make commits unless explicitly instructed.
-- Do not deploy unless explicitly instructed.
-## Scope control
-Before editing files, agents must identify:
-- the task objective;
-- the files likely to change;
-- the files that should not change;
-- what is in scope;
-- what is out of scope;
-- expected validation;
-- known risks.
-If new work is discovered during implementation, agents must classify it as:
-```md
-## Out-of-scope follow-up
-- Issue:
-- Evidence:
-- Impact:
-- Recommended future PR:
-```
-Do not implement out-of-scope discoveries automatically.
-## Existing patterns first
-Agents must inspect and follow existing project patterns before proposing new ones.
-Prefer existing patterns for:
-- folder structure;
-- naming;
-- routing;
-- components;
-- services;
-- repositories;
-- stores;
-- middleware;
-- validation;
-- error handling;
-- tests;
-- build scripts;
-- documentation style;
-- deployment scripts.
-Introduce a new pattern only when:
-- the existing pattern cannot support the requirement;
-- the new pattern reduces real complexity or risk;
-- the trade-off is documented;
-- the change is scoped and reviewable.
-## Validation rules
-Agents must validate proportionally to the risk of the change.
-### Documentation changes
-Check:
-- Markdown formatting;
-- closed code fences;
-- heading hierarchy;
-- correct file paths;
-- clear instructions;
-- no conflicting guidance.
-### Frontend changes
-Check:
-- affected UI behavior;
-- loading, empty, error, and success states when relevant;
-- responsive behavior when relevant;
-- accessibility basics;
-- lint, typecheck, tests, or build when available.
-### Backend changes
-Check:
-- API behavior;
-- validation;
-- authentication;
-- authorization;
-- data integrity;
-- error handling;
-- tests or build when available.
-### Deployment changes
-Check:
-- build status;
-- environment configuration;
-- secrets handling;
-- smoke tests;
-- rollback or recovery path.
-## Evidence requirements
-Every validation summary must include evidence.
-Valid evidence includes:
-- command executed;
-- command result;
-- relevant error output;
-- file path;
-- line reference when available;
-- test name;
-- manual check result;
-- screenshot reference when relevant;
-- CI result;
-- acceptance criteria comparison.
-Invalid evidence includes:
-- “looks good” without support;
-- assumed command success;
-- vague claims;
-- unverified behavior;
-- hidden skipped checks.
-If validation was not executed, agents must state why.
-## Severity model
-Use this severity model when reporting issues.
-### High
-Use `High` when the issue can cause:
-- broken critical functionality;
-- security vulnerability;
-- data loss;
-- data corruption;
-- deployment failure;
-- failing required tests;
-- severe regression;
-- inaccessible critical flow;
-- incorrect business behavior.
-### Medium
-Use `Medium` when the issue can cause:
-- incomplete validation;
-- incorrect secondary behavior;
-- weak error handling;
-- maintainability risk;
-- missing tests for important behavior;
-- fragile assumptions;
-- partial mismatch with requirements.
-### Low
-Use `Low` when the issue is related to:
-- minor wording issue;
-- small formatting problem;
-- small readability improvement;
-- optional cleanup;
-- low-risk consistency issue.
-## Output expectations
-For planning tasks, agents should provide:
-- objective;
-- scope;
-- files likely to change;
-- risks and trade-offs;
-- validation plan;
-- final recommendation.
-For implementation tasks, agents should provide:
-- summary;
-- files changed;
-- behavior preserved;
-- behavior changed;
-- validation executed;
-- validation not executed;
-- regression risks;
-- final status.
-For review tasks, agents should provide:
-- findings;
-- severity;
-- evidence;
-- impact;
-- recommendation;
-- how to validate after fixes;
-- final recommendation.
-## Approval rules
-Use these final statuses consistently.
-### Approved
-Use when all relevant checks pass and no important issue remains.
-### Approved with notes
-Use when the result is acceptable but minor gaps, low-risk issues, or non-critical untested areas remain.
-### Changes requested
-Use when medium or high issues remain and should be fixed before moving forward.
-### Blocked
-Use when required context, files, environment, validation evidence, decisions, or permissions are missing.
-## Destructive operations
-Do not run or recommend destructive operations without explicit approval.
-Examples:
-```bash
-rm -rf
-git reset --hard
-git clean -fd
-docker system prune
-dropdb
-truncate table
-php artisan migrate:fresh
-npm publish
-pnpm publish
-composer update
-kubectl delete
-terraform destroy
-```
-If a destructive operation appears necessary, explain:
-- why it is needed;
-- what can be lost;
-- safer alternatives;
-- rollback or recovery options.
-## Documentation standards
-Documentation should be:
-- clear;
-- actionable;
-- structured;
-- consistent with repository terminology;
-- explicit about assumptions;
-- explicit about open questions;
-- valid Markdown.
-Use:
-- `txt` code fences for file trees;
-- `bash` code fences for shell commands;
-- `md` code fences for Markdown examples;
-- backticks for file paths and commands.
-When nesting Markdown code fences, use four backticks for the outer block.
-## Security rules
-Agents must not:
-- expose secrets;
-- print real credentials;
-- commit `.env` files unless explicitly intended and safe;
-- weaken authentication or authorization;
-- log tokens, passwords, private keys, or sensitive personal data;
-- recommend unsafe production operations without risk disclosure.
-## Final instruction
-When uncertain, agents must not guess silently.
-State the assumption, classify the risk, and recommend the smallest safe next step.