@williambeto/ai-workflow 1.19.1 → 2.2.0

package/.agents/skills/pr-orchestrator/SKILL.md

@@ -1,366 +0,0 @@
----
-name: pr-orchestrator
-description: Use when planning, implementing, reviewing, or validating small pull requests with Codex while preserving scope and avoiding regressions.
----
-
-> Token economy active: keep output compact, context minimal. Reference: `token-economy` + `minimal-context` skills.
-
-# PR Orchestrator Skill
-
-## Purpose
-
-Use this skill when Codex needs to plan, execute, review, or prepare a pull request in a controlled and incremental way.
-
-The goal of this skill is to prevent uncontrolled changes, oversized pull requests, unclear scope, missing validation, and regression risk.
-
-This skill helps Codex work in small, reviewable steps.
-
-## When to use this skill
-
-Use this skill when the task involves:
-
-- creating a pull request plan;
-- implementing one pull request from a larger technical plan;
-- reviewing the scope of a PR;
-- splitting work into smaller PRs;
-- preparing a PR summary;
-- validating whether a PR is ready;
-- identifying changed files;
-- documenting commands executed;
-- checking if the implementation stayed within scope.
-
-## Core responsibilities
-
-When acting with this skill, Codex must:
-
-1. identify the goal of the PR;
-2. define the exact scope;
-3. list files expected to change;
-4. enforce branch gate before editing (never implement directly on `main`);
-5. avoid unrelated changes;
-6. preserve existing behavior unless explicitly changed;
-7. implement the smallest safe change;
-8. validate the result;
-9. document what changed;
-10. document what was not changed;
-11. identify regression risks;
-12. prepare a clear PR summary.
-
-## PR workflow principles
-
-### 1. Small PRs first
-
-Prefer small, isolated pull requests.
-
-A PR should have one clear purpose.
-
-Avoid combining unrelated concerns such as:
-
-- refactor plus feature;
-- UI change plus architecture change;
-- bug fix plus dependency upgrade;
-- documentation rewrite plus implementation;
-- test setup plus production behavior change.
-
-### 2. Scope control
-
-Before making or reviewing changes, Codex must define what is inside and outside the PR scope.
-
-A good PR scope should answer:
-
-- What problem is this PR solving?
-- What files or areas are expected to change?
-- What behavior must remain unchanged?
-- What is explicitly out of scope?
-
-### 2.1 Branch gate before implementation
-
-Before editing files for a PR, Codex must verify current branch and block implementation on `main`.
-
-Required check:
-
-```bash
-git status -sb
-```
-
-If on `main`, create a scoped branch and continue only outside `main`:
-
-```bash
-git switch -c <type>/<short-pr-slug>
-```
-
-### 3. No regression
-
-Existing behavior must be preserved unless the requirement explicitly asks for a behavior change.
-
-If behavior changes, Codex must state:
-
-- what changed;
-- why it changed;
-- where it changed;
-- how it was validated.
-
-### 4. Evidence before approval
-
-A PR should not be considered ready without validation evidence.
-
-Evidence may include:
-
-- tests executed;
-- build result;
-- lint result;
-- typecheck result;
-- manual validation steps;
-- screenshots when relevant;
-- file-level review;
-- comparison with acceptance criteria.
-
-### 5. Do not hide uncertainty
-
-If something was not tested, Codex must state it.
-
-If an assumption was made, Codex must state it.
-
-If validation could not be completed, Codex must not claim the PR is ready.
-
-## PR planning checklist
-
-Before implementation, define:
-
-- PR title;
-- objective;
-- context;
-- expected behavior;
-- files likely to change;
-- files that should not change;
-- acceptance criteria;
-- validation commands;
-- manual validation steps;
-- regression risks;
-- rollback considerations when relevant.
-
-## Implementation checklist
-
-During implementation, Codex must:
-
-- stay within the planned scope;
-- follow existing project patterns;
-- avoid unnecessary abstractions;
-- avoid unrelated formatting changes;
-- avoid dependency changes unless required;
-- keep changes small and traceable;
-- preserve public APIs unless explicitly changed;
-- update tests when behavior changes;
-- update documentation when workflow or usage changes.
-
-## Review checklist
-
-Before preparing the PR summary, Codex must check:
-
-- Does the implementation match the requirement?
-- Did any unrelated file change?
-- Are there unexpected generated files?
-- Are there missing tests?
-- Are edge cases handled?
-- Are error states handled when relevant?
-- Are accessibility, security, performance, and maintainability risks acceptable?
-- Were validation commands executed?
-- Are untested areas documented?
-
-## Output format
-
-When using this skill to plan a PR, Codex should respond with:
-
-```md
-# PR Plan
-
-## Title
-
-Short PR title.
-
-## Objective
-
-One sentence describing the goal.
-
-## Context
-
-Brief explanation of why this PR is needed.
-
-## Scope
-
-### Included
-
-- Item 1
-- Item 2
-
-### Not included
-
-- Item 1
-- Item 2
-
-## Expected files
-
-- `path/to/file`
-
-## Acceptance criteria
-
-- Criterion 1
-- Criterion 2
-
-## Validation plan
-
-### Automated checks
-
-- `command`
-
-### Manual checks
-
-- Step 1
-- Step 2
-
-## Regression risks
-
-- Risk 1
-- Risk 2
-
-## Notes
-
-Relevant assumptions or constraints.
-```
-
-When using this skill after implementation, Codex should respond with:
-
-```md
-# PR Summary
-
-## Summary
-
-Short explanation of what changed.
-
-## Files changed
-
-- `path/to/file` — what changed and why
-
-## Validation
-
-### Executed
-
-- `command` — result
-
-### Not executed
-
-- Check not executed — reason
-
-## Regression risks
-
-- Risk 1
-- Risk 2
-
-## Out of scope
-
-- Item 1
-- Item 2
-
-## Final status
-
-Ready for review | Needs changes | Blocked
-
-Effort: AI elapsed ~Xm | Senior dev estimate ~Ym
-```
-
-## Severity model
-
-Use severity when reviewing PR issues.
-
-### High
-
-Use `High` when the PR introduces or may introduce:
-
-- broken core functionality;
-- failing build;
-- failing required tests;
-- security issue;
-- data loss;
-- deployment failure;
-- severe regression;
-- broken authentication or authorization;
-- broken critical user flow.
-
-### Medium
-
-Use `Medium` when the PR introduces or may introduce:
-
-- incomplete implementation;
-- weak validation;
-- unclear behavior;
-- maintainability risk;
-- missing tests for important behavior;
-- inconsistent project pattern;
-- fragile assumptions.
-
-### Low
-
-Use `Low` when the PR includes:
-
-- minor naming issue;
-- small documentation gap;
-- non-blocking cleanup;
-- minor formatting inconsistency;
-- small readability issue.
-
-## Boundaries
-
-When using this skill, Codex must not:
-
-- implement multiple unrelated PRs at once;
-- change architecture without explicit approval;
-- add dependencies without justification;
-- rewrite unrelated files;
-- silently change behavior;
-- claim tests passed without evidence;
-- ignore failing validation;
-- hide untested areas;
-- make commits unless explicitly instructed;
-- push branches unless explicitly instructed;
-- merge PRs unless explicitly instructed.
-
-## Approval criteria
-
-A PR can be considered ready for review when:
-
-- the objective is clear;
-- the scope is controlled;
-- the implementation matches the requirement;
-- no unrelated changes were introduced;
-- relevant validation was executed or explicitly documented as not executed;
-- no high-severity issue remains;
-- regression risks are listed;
-- the PR summary is clear.
-
-Use `Ready for review` only when the PR is safe to inspect by another developer.
-
-Use `Needs changes` when the implementation is incomplete, risky, or insufficiently validated.
-
-Use `Blocked` when required context, files, commands, environment, or decisions are missing.
-
-## Good PR behavior
-
-A good Codex-driven PR is:
-
-- small;
-- scoped;
-- reversible;
-- validated;
-- easy to review;
-- aligned with existing patterns;
-- explicit about assumptions;
-- explicit about what was not tested.
-
-The goal is not to produce the largest possible change.
-
-The goal is to produce the smallest safe change that moves the project forward.
-
-## Stop conditions
-
-- Stop when the PR is small, scoped, validated, and ready for review.
-- Stop and report `Blocked` if required context, files, or decisions are missing.