npm - @williambeto/ai-workflow - Versions diffs - 1.19.1 → 2.2.0 - Mend

@williambeto/ai-workflow 1.19.1 → 2.2.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 (397) hide show

package/runbooks/quick-start-guide.md DELETED Viewed

@@ -1,213 +0,0 @@
-# Quick-Start Guide
-## Objective
-This guide takes you from installing AI Workflow Kit in a target project to your first scoped workflow run.
-## Prerequisites
-- Node.js 20+
-- Git
-- A text editor (VS Code recommended)
-## Target-project walkthrough
-### 1. Install in your project
-Run from the root of the project that should receive workflow assets:
-```bash
-npx @williambeto/ai-workflow init --yes
-```
-For existing projects, preview changes first:
-```bash
-npx @williambeto/ai-workflow init --dry-run
-```
-Default profile: `operational`.
-Profile options:
-| Profile | Use when | Notes |
-| --- | --- | --- |
-| `minimal` | You only need basic docs and Codex prompt placeholders. | Skips managed `opencode.jsonc`. |
-| `operational` | You want the default PR workflow. | Adds managed `opencode.jsonc` default agent and `start` command. |
-| `full` | You want starter files for local agents and skills. | Creates starter files under `opencode/agents/` and `.agents/skills/`. |
-### 2. Check installation health
-```bash
-npx @williambeto/ai-workflow doctor
-```
-Expected result: `Final status: PASS` or `PASS_WITH_NOTES` with actionable warnings.
-### 3. Run project validation
-Run the target project's validation commands, for example:
-```bash
-npm run build
-npm run lint
-npm run test
-```
-### 4. Create a requirement
-Use the generated workflow docs and your AI tool to clarify:
-- problem;
-- target user;
-- scope;
-- acceptance criteria;
-- assumptions and open questions.
-### 5. Follow the workflow in order
-```txt
-Requirement
-→ Functional specification
-→ Technical plan
-→ PR breakdown
-→ Implement one PR
-→ Review and fix
-→ Validate with evidence
-```
-OpenCode users can start with `/start`. Codex users can start from `.codex/prompts/start-project.md`.
-### 6. Create your first PR
-```bash
-git switch -c feat/my-feature
-# make your changes
-git add .
-git commit -m "feat: my first feature"
-git push -u origin feat/my-feature
-gh pr create --title "My first PR" --body "## Summary"
-```
-### 7. Run validation before opening a PR
-```bash
-npm run validate
-```
-If the project has no `validate` script, run the actual build/lint/test commands directly and include them in the PR body.
-## Workflow steps reference
-Each workflow step has a recommended prompt and specialist skill:
-| Step | Prompt | Primary skill |
-| ---: | --- | --- |
-| Bootstrap the repository | `prompts/00-bootstrap-project.md` | `docs-writer` |
-| 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` | `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` |
-| Prepare deployment | `prompts/09-deploy.md` | `deploy-engineer` |
-Apply a design pass (`prompts/07-apply-design.md`) when the PR involves user-facing changes.
-### Validation checklist per step
-| Step | Key check |
-| --- | --- |
-| Bootstrap | Repository purpose is clear, structure matches type, no unnecessary code created. |
-| Requirement | Problem is clear, target user identified, scope controlled, acceptance criteria testable. |
-| Specification | Main flow defined, edge cases considered, scope did not expand silently. |
-| Technical plan | Existing patterns identified, risks documented, validation strategy realistic. |
-| PR breakdown | Each PR has one objective, PR 1 is small enough, refactors separated from behavior changes. |
-| Implementation | Only PR 1 implemented, no unrelated changes, existing behavior preserved. |
-| Review | Findings evidence-based, fixes inside PR 1 scope, out-of-scope issues documented. |
-| Validate | Acceptance criteria checked, commands listed with results, untested areas explicit. |
-| Deploy | Environment assumptions clear, smoke tests defined, rollback plan exists. |
-Do not continue to the next step if the current step has unresolved high-severity issues.
-## Common mistakes to avoid
-- generating the full application at once;
-- skipping requirement and specification;
-- creating a technical plan without existing context;
-- implementing before PR breakdown;
-- implementing more than PR 1;
-- accepting vague validation without command evidence;
-- hiding failed commands;
-- making broad refactors mixed with behavior changes;
-- mixing setup, feature, design, and deployment in one PR;
-- committing or deploying without explicit instruction.
-## Recommended first PR types
-Good first PRs are usually:
-- documentation foundation;
-- repository structure;
-- first requirement, spec, or template;
-- basic validation setup;
-- small non-invasive project setup;
-- test around existing behavior;
-- one isolated UI shell;
-- one isolated endpoint or utility.
-Poor first PRs are usually:
-- full application implementation;
-- full architecture migration;
-- dependency upgrade plus feature;
-- database redesign;
-- authentication plus dashboard plus products plus deploy;
-- large design system implementation;
-- production deployment.
-## First PR quality gate
-The first PR is ready only when:
-- the selected PR scope is clear;
-- the implementation matches the PR plan;
-- no unrelated changes were introduced;
-- validation evidence exists;
-- untested areas are documented;
-- regression risks are acceptable;
-- no high-severity issue remains;
-- the PR summary is ready for another developer to review.
-## Contributor setup for this repository
-Use this path only when changing AI Workflow Kit itself:
-```bash
-git clone https://github.com/williambeto/ai-workflow.git
-cd ai-workflow
-npm install
-npm run validate
-```
-## Next steps
-- Read `runbooks/tutorial-walkthroughs.md` for detailed tutorials
-- Read `runbooks/apply-starter-to-real-project.md` for adoption in real projects
-- Read `runbooks/how-to-use-skills.md` to choose the right skill
-- Explore `variants/` for your specific stack
-- Read `docs/full-documentation.md` for the complete reference
-## Useful commands
-| Command | What it does |
-|---------|-----------|
-| `npx @williambeto/ai-workflow init --dry-run` | Previews target-project install changes |
-| `npx @williambeto/ai-workflow init --yes` | Installs default workflow assets |
-| `npx @williambeto/ai-workflow doctor` | Checks local workflow installation |
-| `npm run validate` | Runs target-project validation when available |
-| `npm run validate` | Runs all repository validations when developing this kit |
-| `npm run test:e2e` | Tests validation scripts |
-| `npm run lint:md` | Checks Markdown formatting |
-| `npm run validate:links` | Checks external links |

package/runbooks/tutorial-walkthroughs.md DELETED Viewed

@@ -1,416 +0,0 @@
-# Tutorial Walkthroughs
-## Purpose
-This document provides structured walkthrough scripts for learning and demonstrating the `ai-workflow` workflow.
-Each tutorial maps to a workflow phase and can be used as:
-- a self-guided text tutorial for new users;
-- a script for recording video walkthroughs;
-- a reference for team onboarding sessions.
-## Tutorial index
-| Module | Title | Workflow Phase | Est. Time | Prerequisites |
-|--------|-------|----------------|-----------|---------------|
-| 1 | From Zero to First PR | Bootstrap → Requirement → Spec → Tech Plan → PR Breakdown → Implementation | 30 min | GitHub account, Codex/OpenCode access |
-| 2 | Creating a Requirement | Requirement | 10 min | Module 1 |
-| 3 | Writing a Functional Spec | Specification | 10 min | Module 2 |
-| 4 | Designing a Technical Plan | Technical Plan | 10 min | Module 3 |
-| 5 | Breaking Work into PRs | PR Breakdown | 10 min | Module 4 |
-| 6 | Implementing a PR | Implementation | 15 min | Module 5 |
-| 7 | Reviewing and Fixing | Review | 10 min | Module 6 |
-| 8 | Validating with Evidence | Validation | 10 min | Module 7 |
-| 9 | Deploying a Release | Deployment | 10 min | Module 8 |
-| 10 | Customizing for Your Stack | Variants | 15 min | All above |
----
-## Module 1: From Zero to First PR
-### Objective
-Bootstrap a new project from scratch, define a feature requirement, create a technical plan, split work into PRs, and implement the first PR.
-### Walkthrough
-1. **Clone the starter**
-   ```bash
-   git clone https://github.com/williambeto/ai-workflow.git my-project
-   cd my-project
-   npm install
-   ```
-2. **Review the workflow**
-   Read `AGENTS.md` and `README.md`. Identify the ordered prompt sequence:
-   ```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
-   ```
-3. **Run validation**
-   ```bash
-   npm run validate
-   ```
-   Expected: `Validation passed: 10 check(s) completed.`
-4. **Start with a requirement**
-   Follow `prompts/01-create-requirement.md` to define a small feature. Use `templates/REQUIREMENT.template.md` as a starting point.
-5. **Continue through the chain**
-   Follow each prompt in order. Use the corresponding template for each artifact.
-6. **Create your first PR**
-   Follow `prompts/04-breakdown-prs.md` to split work, then `prompts/05-implement-pr.md` to implement.
-### Key references
-- `AGENTS.md` — agent rules and skill routing
-- `templates/REQUIREMENT.template.md` — requirement template
-- `templates/SPEC.template.md` — specification template
-- `templates/TECH-PLAN.template.md` — technical plan template
-- `templates/PR-PLAN.template.md` — PR breakdown template
-- `opencode/commands/start.md` — OpenCode startup command
-### Validation gate
-```bash
-npm run validate
-```
-All 8 checks must pass before moving to the next module.
----
-## Module 2: Creating a Requirement
-### Objective
-Transform an idea into a structured product requirement with clear scope, acceptance criteria, and open questions.
-### Walkthrough
-1. Open `prompts/01-create-requirement.md`.
-2. Review the expected input/output format in the prompt.
-3. Open `templates/REQUIREMENT.template.md` and copy the structure.
-4. Fill in each section for your chosen feature.
-5. Validate the structure meets these criteria:
-   - Objective is clear and measurable.
-   - Scope boundaries are explicit.
-   - Acceptance criteria are testable.
-   - Open questions are documented.
-### Key references
-- `.agents/skills/product-manager/SKILL.md`
-- `schemas/requirement.schema.json`
----
-## Module 3: Writing a Functional Spec
-### Objective
-Convert a requirement into a detailed functional specification with user stories, acceptance criteria, and non-functional requirements.
-### Walkthrough
-1. Open `prompts/02-create-spec.md`.
-2. Review the expected sections: overview, user stories, acceptance criteria, non-functional requirements, open questions.
-3. Open `templates/SPEC.template.md`.
-4. Map each requirement item to a user story.
-5. Define clear, testable acceptance criteria per story.
-6. Document non-functional constraints (performance, security, accessibility).
-### Key references
-- `.agents/skills/product-manager/SKILL.md`
-- `schemas/functional-spec.schema.json`
----
-## Module 4: Designing a Technical Plan
-### Objective
-Create a technical implementation plan that identifies architecture decisions, component boundaries, data flow, and risk mitigation.
-### Walkthrough
-1. Open `prompts/03-create-tech-plan.md`.
-2. Review the expected structure: architecture overview, component diagram (text), data flow, technology choices, risks.
-3. Open `templates/TECH-PLAN.template.md`.
-4. Identify key architectural decisions and document trade-offs.
-5. Map each spec story to a technical component.
-6. Document risks and mitigation strategies.
-### Key references
-- `.agents/skills/tech-lead/SKILL.md`
-- `schemas/technical-plan.schema.json`
----
-## Module 5: Breaking Work into PRs
-### Objective
-Split a technical plan into small, reviewable, incremental pull requests that preserve no-regression and scope control.
-### Walkthrough
-1. Open `prompts/04-breakdown-prs.md`.
-2. Review the PR breakdown criteria:
-   - Each PR is independently reviewable.
-   - Each PR preserves backward compatibility.
-   - Each PR has clear scope boundaries.
-3. Open `templates/PR-PLAN.template.md`.
-4. List each PR with its scope, files changed, and validation plan.
-5. Order PRs by dependency (foundation first, features on top).
-### Key references
-- `.agents/skills/pr-orchestrator/SKILL.md`
-- `schemas/pr-breakdown.schema.json`
-- `harness/workflows/requirement-to-pr.md`
----
-## Module 6: Implementing a PR
-### Objective
-Implement one small PR from the breakdown, following no-regression rules and scope boundaries.
-### Walkthrough
-1. Open `prompts/05-implement-pr.md`.
-2. Create a feature branch:
-   ```bash
-   git switch -c feat/my-scoped-change
-   ```
-3. Implement changes scoped to the PR.
-4. Run validation after each logical change:
-   ```bash
-   npm run validate
-   ```
-5. Do not introduce unrelated refactors or dependency changes.
-6. Document out-of-scope discoveries as follow-up items.
-### Key references
-- `.agents/skills/frontend-implementer/SKILL.md`
-- `.agents/skills/backend-implementer/SKILL.md`
-- `.agents/skills/build-and-validate/SKILL.md`
-- `scripts/validate-all.mjs`
----
-## Module 7: Reviewing and Fixing
-### Objective
-Review an implemented PR for correctness, scope compliance, regression risk, and evidence quality.
-### Walkthrough
-1. Open `prompts/06-review-and-fix.md`.
-2. Check each scope item from the PR plan.
-3. Verify no unintended changes exist.
-4. Check validation evidence is complete.
-5. Use the severity model (High / Medium / Low) for issues found.
-6. Apply fixes or document as follow-up.
-### Key references
-- `.agents/skills/tester/SKILL.md`
-- `.agents/skills/pr-orchestrator/SKILL.md`
-- `AGENTS.md` (severity model, finding types)
----
-## Module 8: Validating with Evidence
-### Objective
-Run the full validation suite, collect evidence, and produce a validation report.
-### Walkthrough
-1. Open `prompts/08-validate.md`.
-2. Run all validation checks:
-   ```bash
-   npm run validate
-   ```
-3. Collect evidence for each check:
-   - Markdown lint output
-   - JSON validation output
-   - Cross-reference check output
-   - Documentation consistency output
-   - Workflow state output
-   - Schema validation output
-   - Skill validation output
-   - Structure validation output
-4. Optionally run link validation:
-   ```bash
-   npm run validate:links
-   ```
-5. Optionally run end-to-end tests:
-   ```bash
-   npm run test:e2e
-   ```
-6. Document any warnings and decide whether they need action.
-7. Produce a validation report using `schemas/validation-report.schema.json` as a reference.
-### Key references
-- `.agents/skills/tester/SKILL.md`
-- `schemas/validation-report.schema.json`
-- `runbooks/validation-checklist.md`
-- `tests/validate-e2e.mjs`
----
-## Module 9: Deploying a Release
-### Objective
-Prepare and execute a deployment plan with rollback strategy and readiness checklist.
-### Walkthrough
-1. Open `prompts/09-deploy.md`.
-2. Review the deployment readiness checklist in `runbooks/deploy-checklist.md`.
-3. Verify the release tag and CHANGELOG are up to date.
-4. Create a version tag:
-   ```bash
-   git tag -a v1.x.x -m "Release v1.x.x"
-   git push origin v1.x.x
-   ```
-5. The automated release workflow (`.github/workflows/release.yml`) creates a GitHub Release with notes from CHANGELOG.md.
-### Key references
-- `.agents/skills/deploy-engineer/SKILL.md`
-- `runbooks/deploy-checklist.md`
-- `.github/workflows/release.yml`
----
-## Module 10: Customizing for Your Stack
-### Objective
-Adapt the generic workflow to a specific technology stack using the variants system.
-### Walkthrough
-1. Review existing variants in `variants/`:
-   ```txt
-   variants/
-   ├── nuxt/
-   ├── wordpress/
-   ├── node-api/
-   ├── python-api/
-   └── docs-only/
-   ```
-2. Choose the closest variant to your stack.
-3. Review the variant's `AGENTS.md` for stack-specific rules.
-4. Copy the variant into your project.
-5. Customize prompts and validation for your stack.
-6. Ensure generic core files remain unchanged.
-### Key references
-- `.agents/skills/stack-variant-creator/SKILL.md`
-- `variants/` directory
----
-## Quick reference
-### Commands used across tutorials
-| Command | Purpose |
-|---------|---------|
-| `npm run validate` | Run all 8 validation checks |
-| `npm run validate:links` | Check external HTTP links |
-| `npm run test:e2e` | Run end-to-end validation tests |
-| `npm run lint:md` | Check Markdown formatting |
-| `git switch -c <branch>` | Create a feature branch |
-| `git tag -a v1.x.x` | Create a release tag |
-### Skill lookup by tutorial phase
-| Tutorial | Primary Skill | Supporting Skills |
-|----------|--------------|-------------------|
-| Requirement | `product-manager` | `docs-writer`, `tester` |
-| Specification | `product-manager` | `tester`, `docs-writer` |
-| Technical Plan | `tech-lead` | `build-and-validate`, `tester` |
-| 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` |
----
-## Recording tips (for video walkthroughs)
-1. **Preparation**
-   - Prepare the repository in a clean state before recording.
-   - Open all files you will reference in separate tabs.
-   - Run `npm run validate` once before recording to confirm green.
-2. **During recording**
-   - Show each prompt file before executing it.
-   - Show validation output after each step.
-   - Highlight key sections: scope boundaries, evidence requirements, stop conditions.
-   - Keep each module under 15 minutes.
-3. **Post-production**
-   - Add chapter markers for each walkthrough section.
-   - Include on-screen annotations for commands and file paths.
-   - Link to the corresponding prompt, template, or runbook in the video description.
-4. **Suggested titles**
-   - "Codex Workflow Starter: From Zero to First PR"
-   - "How to Write a Great Requirement (with Templates)"
-   - "Breaking Work into Small, Reviewable PRs"
-   - "Validating Your Work with Evidence"
----
-## Next steps after completing tutorials
-1. Explore advanced workflows in `harness/workflows/`.
-2. Read `runbooks/apply-starter-to-real-project.md` for production adoption guidance.
-3. Read `runbooks/team-governance-pr-readiness.md` for team workflow setup.
-4. Customize prompts and templates for your team's conventions.
-5. Create your own stack variant using `.agents/skills/stack-variant-creator/SKILL.md`.