@williambeto/ai-workflow 1.19.1 → 2.1.0

package/.agents/skills/stack-variant-creator/SKILL.md

@@ -1,265 +0,0 @@
----
-name: stack-variant-creator
-description: Use when creating a workflow variant for a specific tech stack (React, Laravel, Go, Python, etc.) based on the generic ai-workflow core.
----
-
-> Token economy active: keep output compact, context minimal. Reference: `token-economy` + `minimal-context` skills.
-
-# Stack Variant Creator Skill
-
-## Purpose
-
-Create focused workflow variants for specific tech stacks while preserving the generic core of ai-workflow.
-
-A variant adapts the generic skills, prompts, runbooks, and templates to the patterns, conventions, and validation commands of a particular stack — without duplicating or modifying the generic core.
-
-## Use when
-
-- A user asks to create a variant for a new stack (React, Laravel, Go, Python, etc.).
-- A stack-specific workflow pilot is needed to validate adoption.
-- A new skill needs to be created that depends on stack conventions.
-- A runbook needs to be adapted for a specific stack environment.
-
-## Scope
-
-**In scope**:
-
-- create `.agents/skills/<stack-name>/SKILL.md` with stack-specific guidance;
-- create `examples/<stack-name>/` with workflow demonstration files;
-- create `runbooks/<stack-name>-setup.md` for stack-specific bootstrap;
-- add stack-specific validation commands to existing runbooks;
-- create `prompts/commands/<stack-name>.md` for stack-specific command entrypoints.
-
-**Out of scope**:
-
-- modifying generic skills (frontend-implementer, backend-implementer, etc.);
-- changing core workflow prompts (00-bootstrap to 09-deploy);
-- generating application boilerplate or starter code;
-- adding stack-specific assumptions to `AGENTS.md` or `README.md`.
-
-## Workflow
-
-### Step 1 — Define variant scope
-
-Before creating anything, define:
-
-- target stack name (e.g., `react-dashboard`, `laravel-api`);
-- what the variant covers (skills, examples, runbooks, commands);
-- what the generic core must not change;
-- who the audience is (developers familiar with this stack);
-- what existing variant to use as reference pattern.
-
-Reference variants:
-
-```txt
-examples/nuxt-dashboard/    — frontend stack (Nuxt/Vue)
-examples/wordpress-theme/    — PHP stack (WordPress/PHP 7)
-examples/docs-only-repo/     — non-code stack (documentation)
-```
-
-### Step 2 — Create skill directory
-
-Create the skill folder:
-
-```txt
-.agents/skills/<stack-name>/
-```
-
-Reference the existing skill structure:
-
-```txt
-.agents/skills/vue-nuxt/SKILL.md
-.agents/skills/wordpress-engineer/SKILL.md
-```
-
-### Step 3 — Create the stack-specific SKILL.md
-
-The skill must include:
-
-```md
----
-name: <stack-name>
-description: Use when working on <stack description> with <key convention or pattern>.
----
-
-# <Stack Name> Skill
-
-## Purpose
-
-[1-2 sentences describing the role]
-
-## When to use
-
-Use this skill when:
-- [specific use case 1]
-- [specific use case 2]
-
-## Required context
-
-- Working directory contains a <stack> project
-- [specific file patterns or conventions]
-- [specific validation commands]
-
-## Core responsibilities
-
-1. [responsibility 1]
-2. [responsibility 2]
-
-## Stack conventions
-
-### Folder structure
-
-```txt
-[typical folder structure for this stack]
-```
-
-### Key files
-
-| File | Purpose |
-| --- | --- |
-| `file` | description |
-
-### Validation commands
-
-| Command | What it checks |
-| --- | --- |
-| `npm run build` | production build |
-| `npm run lint` | code style |
-| `npm test` | unit tests |
-
-## Constraints
-
-- Do not modify the generic core of ai-workflow
-- Follow existing <stack> patterns and conventions
-- Validate before moving forward
-- Preserve existing behavior unless explicitly requested
-
-## Expected output
-
-- Stack-specific implementation notes
-- Changed files list
-- Validation evidence
-- Final status: Proceed | Needs clarification | Blocked
-
-## Stop conditions
-
-- Stop when required context is missing
-- Stop when implementation would modify the generic core
-- Stop when validation cannot be executed
-```
-
-### Step 4 — Create example workflow (optional)
-
-If the variant needs a demonstration:
-
-```txt
-examples/<stack-name>/
-├── 01-requirement.md
-├── 02-functional-spec.md
-├── 03-technical-plan.md
-├── 04-pr-breakdown.md
-├── 05-execution-handoff.md  (optional)
-└── README.md
-```
-
-Reference: `examples/nuxt-dashboard/README.md`
-
-### Step 5 — Validate
-
-Run these checks:
-
-```bash
-npm run validate:md
-npm run validate:json  # if JSON added
-npm run validate:structure
-```
-
-Check that:
-
-- no generic core file was modified;
-- YAML frontmatter is valid;
-- Markdown formatting is safe;
-- file paths referenced in the skill exist.
-
-### Step 6 — Document the variant
-
-Update `README.md` only to add the new variant to the examples list:
-
-```md
-### Available Examples
-
-```txt
-examples/nuxt-dashboard/    — Nuxt dashboard with shell, auth, CRUD, and validation
-examples/wordpress-theme/   — WordPress theme with PHP 7, hooks, and custom post types
-examples/docs-only-repo/     — Documentation-only repository with Markdown validation
-examples/<stack-name>/       — [stack description]
-```
-```
-
-Do not add stack-specific assumptions to generic sections.
-
-## Constraints
-
-- Do not conflict with `AGENTS.md` hard constraints.
-- Do not modify generic skills, prompts, or core workflow files.
-- Do not generate application boilerplate code.
-- Do not invent stack conventions; follow established patterns.
-- Do not claim validation passed without evidence.
-- Keep variants reviewable and independently useful.
-
-## Validation checklist
-
-- Stack-specific skill has valid YAML frontmatter.
-- Description triggers correctly for the target stack.
-- Folder structure follows existing skill patterns.
-- No generic core files were modified.
-- Markdown formatting is valid.
-- Validation commands are realistic and testable.
-- Example workflow (if created) follows existing patterns.
-
-## Expected output
-
-- `.agents/skills/<stack-name>/SKILL.md` created
-- `examples/<stack-name>/` created (if applicable)
-- Validation evidence from `npm run validate` commands
-- Final status: `Approved`, `Approved with notes`, `Changes requested`, or `Blocked`
-
-## Stop conditions
-
-- Stop when required context (target stack, conventions, commands) is missing.
-- Stop when the variant would require modifying the generic core.
-- Stop when the skill description is too generic to trigger correctly.
-- Stop when validation evidence cannot be produced.
-
-## Example: Creating a React Dashboard variant
-
-```txt
-# Step 1: Define scope
-- Stack: React Dashboard
-- Coverage: skill + example
-- Generic core: unchanged
-- Audience: React/Next.js developers
-
-# Step 2: Create directory
-.agents/skills/react-dashboard/
-
-# Step 3: Create SKILL.md
-.agents/skills/react-dashboard/SKILL.md
-
-# Step 4: Create example
-examples/react-dashboard/
-├── 01-requirement.md
-├── 02-functional-spec.md
-├── 03-technical-plan.md
-├── 04-pr-breakdown.md
-└── README.md
-
-# Step 5: Validate
-npm run validate
-
-# Step 6: Update README examples list only
-```
-
-## Final instruction
-
-Create small, reviewable variants. Do not create a full application inside the starter. The goal is to make the generic workflow faster to adopt for a specific stack, not to replace the stack's official starter.

package/.agents/skills/tech-lead/SKILL.md

@@ -1,453 +0,0 @@
----
-name: tech-lead
-description: Use when making technical decisions, reviewing architecture, identifying trade-offs, or splitting software work into safe incremental steps.
----
-
-> Token economy active: keep output compact, context minimal. Reference: `token-economy` + `minimal-context` skills.
-
-# Tech Lead Skill
-
-## Purpose
-
-Use this skill when Codex needs to transform requirements or specifications into a safe technical direction.
-
-The tech lead role is responsible for technical judgment, architecture boundaries, implementation strategy, risk control, trade-off analysis, and pull request planning.
-
-This skill does not focus on writing all code directly. It focuses on choosing the safest technical path before implementation starts.
-
-## When to use this skill
-
-Use this skill when the task involves:
-
-- creating a technical plan;
-- reviewing a specification for implementation readiness;
-- choosing an architecture approach;
-- breaking work into pull requests;
-- identifying technical risks;
-- defining validation strategy;
-- reviewing implementation scope;
-- deciding whether a refactor is justified;
-- protecting existing behavior from regression.
-
-## Core responsibilities
-
-When acting as tech lead, Codex must:
-
-1. understand the requirement or specification;
-2. identify the current project structure and existing patterns;
-3. avoid inventing architecture when existing patterns are sufficient;
-4. define a safe implementation strategy;
-5. identify files or areas likely to change;
-6. identify risks, trade-offs, and constraints;
-7. split work into small pull requests;
-8. define validation steps;
-9. protect existing behavior;
-10. document assumptions and open technical questions;
-11. recommend whether implementation should proceed.
-
-## Technical leadership principles
-
-### 1. Existing patterns first
-
-Prefer the project’s existing architecture, naming, folder structure, and conventions.
-
-Do not introduce new patterns unless there is a clear reason.
-
-A new abstraction is only justified when it reduces real complexity, duplication, risk, or maintenance cost.
-
-### 2. Small safe steps
-
-Prefer incremental changes.
-
-A technical plan should make the next step reviewable and reversible.
-
-Avoid large changes that combine:
-
-- architecture changes;
-- feature work;
-- refactoring;
-- dependency upgrades;
-- formatting-only changes;
-- unrelated cleanup.
-
-### 3. No regression
-
-Existing behavior must be preserved unless the requirement explicitly asks for a behavior change.
-
-If behavior must change, state:
-
-- what changes;
-- why it changes;
-- where it changes;
-- how it will be validated.
-
-### 4. Trade-offs must be explicit
-
-Every technical approach has a cost.
-
-When proposing a solution, include trade-offs such as:
-
-- speed vs maintainability;
-- simplicity vs extensibility;
-- local fix vs architectural change;
-- short-term patch vs long-term refactor;
-- strict typing vs development speed;
-- test coverage vs delivery time.
-
-### 5. Validation before confidence
-
-Do not claim that a plan is safe without validation strategy.
-
-A good technical plan defines how the change will be checked.
-
-## Technical plan structure
-
-When creating a technical plan, use this structure:
-
-```md
-# Technical Plan
-
-## Summary
-
-Short explanation of the proposed technical direction.
-
-## Inputs
-
-- Requirement:
-- Specification:
-- Relevant constraints:
-
-## Current state
-
-Brief description of the current implementation or project structure.
-
-## Proposed approach
-
-Explain the implementation strategy.
-
-## Files likely to change
-
-- `path/to/file` — expected change
-
-## Files that should not change
-
-- `path/to/file` — reason
-
-## Data flow / control flow
-
-Explain how the feature or change should work technically.
-
-## Risks and trade-offs
-
-| Risk / Trade-off | Impact   | Mitigation   |
-| ---------------- | -------- | ------------ |
-| Risk 1           | Impact 1 | Mitigation 1 |
-
-## Pull request breakdown
-
-### PR 1 — Title
-
-Scope:
-
-- Item 1
-- Item 2
-
-Validation:
-
-- Check 1
-- Check 2
-
-### PR 2 — Title
-
-Scope:
-
-- Item 1
-- Item 2
-
-Validation:
-
-- Check 1
-- Check 2
-
-## Validation strategy
-
-### Automated checks
-
-- `command`
-
-### Manual checks
-
-- Step 1
-- Step 2
-
-## Open technical questions
-
-- Question 1
-
-## Final recommendation
-
-Proceed | Needs clarification | Split first | Not recommended
-```
-
-## Architecture review checklist
-
-Use this checklist when reviewing or creating a technical plan.
-
-### Scope
-
-- Is the problem technically understood?
-- Is the scope small enough?
-- Are unrelated changes excluded?
-- Are behavior changes explicit?
-- Is refactoring separated from feature work?
-
-### Architecture
-
-- Does the plan follow existing patterns?
-- Is the proposed abstraction necessary?
-- Are responsibilities separated?
-- Is the data flow understandable?
-- Are dependencies pointing in the right direction?
-- Is the solution over-engineered?
-- Is the solution under-engineered?
-
-### Maintainability
-
-- Is the change easy to review?
-- Is the change easy to test?
-- Is the change easy to rollback?
-- Are names and boundaries clear?
-- Is duplication acceptable or should it be removed?
-- Are there hidden coupling risks?
-
-### Testing and validation
-
-- Are acceptance criteria covered?
-- Are automated tests planned when relevant?
-- Are manual checks defined?
-- Is build validation included?
-- Are regression risks listed?
-- Are untested areas visible?
-
-### Security and reliability
-
-Use this section when relevant.
-
-- Are authentication and authorization preserved?
-- Are secrets protected?
-- Is user input handled safely?
-- Are failure modes defined?
-- Are external service failures considered?
-- Is there a rollback or fallback path?
-
-### Performance
-
-Use this section when relevant.
-
-- Does the plan add unnecessary work on render or request?
-- Does it increase network calls?
-- Does it affect bundle size?
-- Does it introduce expensive loops?
-- Does it affect caching?
-- Is the performance risk acceptable?
-
-## PR breakdown rules
-
-When breaking work into PRs:
-
-- one PR should have one primary purpose;
-- validation should be possible per PR;
-- refactors should be isolated when possible;
-- dependency upgrades should be isolated;
-- tests should be close to the behavior they validate;
-- documentation should be updated in the same PR only when it documents that PR’s behavior;
-- avoid PRs that are too large to review safely.
-
-A good PR breakdown should allow the project to stay working after each PR.
-
-## Decision model
-
-Use the following decision labels.
-
-### Proceed
-
-Use when the requirement or spec is clear enough, the technical path is safe, and implementation can start.
-
-### Needs clarification
-
-Use when important technical or product information is missing.
-
-### Split first
-
-Use when the work is too broad and should be broken down before implementation.
-
-### Not recommended
-
-Use when the proposed approach creates more risk than value, conflicts with existing architecture, or solves the wrong problem.
-
-## Severity model
-
-Use severity when reviewing technical risks.
-
-### High
-
-Use `High` when the issue can cause:
-
-- severe regression;
-- broken critical flow;
-- security vulnerability;
-- deployment failure;
-- data loss;
-- architecture conflict;
-- unreviewable PR size;
-- missing validation for critical behavior.
-
-### Medium
-
-Use `Medium` when the issue can cause:
-
-- maintainability risk;
-- unclear responsibilities;
-- fragile abstraction;
-- incomplete validation;
-- unnecessary complexity;
-- inconsistent project pattern;
-- unclear rollback path.
-
-### Low
-
-Use `Low` when the issue is related to:
-
-- minor naming issue;
-- small documentation gap;
-- non-blocking cleanup;
-- optional simplification;
-- minor consistency improvement.
-
-## Review output format
-
-When reviewing a technical plan, Codex should respond using this structure:
-
-```md
-# Tech Lead Review
-
-## Summary
-
-Short conclusion.
-
-## Status
-
-Proceed | Needs clarification | Split first | Not recommended
-
-## What is good
-
-- Item 1
-- Item 2
-
-## What is fragile
-
-- Item 1
-- Item 2
-
-## What is excessive
-
-- Item 1
-- Item 2
-
-## Risks
-
-### Risk 1
-
-Severity: High | Medium | Low
-
-Description:
-Explain the risk.
-
-Impact:
-Explain why it matters.
-
-Mitigation:
-Explain the smallest safe mitigation.
-
-## Missing information
-
-- Item 1
-- Item 2
-
-## Recommended PR breakdown
-
-### PR 1 — Title
-
-- Scope:
-- Validation:
-
-## Final recommendation
-
-Clear next step.
-```
-
-## Boundaries
-
-When acting as tech lead, Codex must not:
-
-- jump directly into implementation unless explicitly asked;
-- introduce new architecture without justification;
-- hide trade-offs;
-- ignore existing project patterns;
-- combine unrelated changes;
-- approve unclear specs;
-- approve oversized PRs;
-- treat assumptions as facts;
-- skip validation planning;
-- change public behavior without making it explicit;
-- recommend dependency upgrades without a clear reason.
-
-## Approval criteria
-
-A technical plan can move to implementation when:
-
-- the requirement or spec is clear;
-- the proposed approach follows or intentionally extends existing patterns;
-- scope is controlled;
-- files likely to change are identified;
-- behavior changes are explicit;
-- risks and trade-offs are documented;
-- validation strategy is defined;
-- work is split into reviewable PRs;
-- no high-severity unresolved technical risk remains.
-
-Use `Proceed` when implementation can safely start.
-
-Use `Needs clarification` when required information is missing.
-
-Use `Split first` when the plan is too large for safe implementation.
-
-Use `Not recommended` when the approach is technically unsafe or misaligned.
-
-## Good tech lead behavior
-
-A good tech lead response is:
-
-- pragmatic;
-- explicit about trade-offs;
-- protective of existing behavior;
-- strict about scope;
-- skeptical of unnecessary abstraction;
-- clear about validation;
-- focused on small, reviewable delivery steps.
-
-The goal is not to design the most impressive architecture.
-
-The goal is to choose the safest technical path that solves the problem with acceptable risk.
-
-## Expected output
-
-- Technical plan with clear scope, approach, files likely to change, risks, trade-offs, and PR breakdown.
-- Validation strategy with automated and manual checks.
-- Open technical questions and assumptions explicitly listed.
-- Final recommendation: `Proceed`, `Needs clarification`, `Split first`, or `Not recommended`.
-
-## Stop conditions
-
-- Stop when the technical plan is complete, scoped, and ready for implementation.
-- Stop and report `Blocked` if required context, specification, or technical information is missing.