diff --git a/.agents/commands/claude/review-cycle.md b/.agents/commands/claude/review-cycle.md new file mode 100644 index 0000000..c7be692 --- /dev/null +++ b/.agents/commands/claude/review-cycle.md @@ -0,0 +1,29 @@ +--- +description: "Run a review, fix, and retest loop." +--- + +# /review-cycle + +Run a bounded review, fix, and retest loop using the standards of the current +repository and organization. + +1. Discover local standards before reviewing: + - read the nearest `AGENTS.md`, `CLAUDE.md`, `README.md`, and relevant docs + - inspect repo scripts, package tasks, CI config, and documented validation + - apply any generated org or profile instructions already installed for this agent +2. Identify the target branch, base branch, changed files, open PR, CI state, + and project validation commands. +3. Review the diff from multiple angles: correctness, maintainability, + security, product behavior, test coverage, docs, and consistency with local + standards. +4. Convert actionable findings into a short fix list. Ignore preference-only + churn unless it conflicts with repo/org standards or blocks maintainability. +5. Implement fixes while preserving unrelated user changes. +6. Re-run relevant validation and update docs if behavior or workflow changed. +7. Repeat the review once after fixes. Stop when no material findings remain or + a blocker requires human input. +8. Report what changed, what was validated, which standards were applied, and + any residual risk. + +If local repo or org instructions conflict with this workflow, follow the more +specific repo/org instruction and call out the conflict in the final report. diff --git a/.agents/commands/claude/ship.md b/.agents/commands/claude/ship.md new file mode 100644 index 0000000..881eece --- /dev/null +++ b/.agents/commands/claude/ship.md @@ -0,0 +1,28 @@ +--- +description: "Prepare work and open or update a reviewable PR." +--- + +# /ship + +Prepare the current branch for review using the standards of the current +repository and organization. + +1. Discover local standards before changing behavior: + - read the nearest `AGENTS.md`, `CLAUDE.md`, `README.md`, and relevant docs + - inspect repo scripts, package tasks, CI config, and documented validation + - apply any generated org or profile instructions already installed for this agent +2. Inspect the working tree, branch, upstream state, base branch, open PR, and + current CI state. +3. Remove accidental noise, generated clutter, debug instrumentation, and + unrelated changes from the proposed diff. +4. Confirm docs are updated when behavior, interfaces, config, ops, or + developer workflow changed. +5. Run the narrowest meaningful validation first, then broader validation before + opening or updating the PR. +6. Review the final diff for secrets, unrelated files, and avoidable churn. +7. Create or update a ready-for-review PR with a concise description, + validation results, and known risks. +8. Watch CI and fix straightforward failures until the branch is reviewable. + +If local repo or org instructions conflict with this workflow, follow the more +specific repo/org instruction and call out the conflict in the final report. diff --git a/.agents/commands/codex/review-cycle.md b/.agents/commands/codex/review-cycle.md new file mode 100644 index 0000000..c7be692 --- /dev/null +++ b/.agents/commands/codex/review-cycle.md @@ -0,0 +1,29 @@ +--- +description: "Run a review, fix, and retest loop." +--- + +# /review-cycle + +Run a bounded review, fix, and retest loop using the standards of the current +repository and organization. + +1. Discover local standards before reviewing: + - read the nearest `AGENTS.md`, `CLAUDE.md`, `README.md`, and relevant docs + - inspect repo scripts, package tasks, CI config, and documented validation + - apply any generated org or profile instructions already installed for this agent +2. Identify the target branch, base branch, changed files, open PR, CI state, + and project validation commands. +3. Review the diff from multiple angles: correctness, maintainability, + security, product behavior, test coverage, docs, and consistency with local + standards. +4. Convert actionable findings into a short fix list. Ignore preference-only + churn unless it conflicts with repo/org standards or blocks maintainability. +5. Implement fixes while preserving unrelated user changes. +6. Re-run relevant validation and update docs if behavior or workflow changed. +7. Repeat the review once after fixes. Stop when no material findings remain or + a blocker requires human input. +8. Report what changed, what was validated, which standards were applied, and + any residual risk. + +If local repo or org instructions conflict with this workflow, follow the more +specific repo/org instruction and call out the conflict in the final report. diff --git a/.agents/commands/codex/ship.md b/.agents/commands/codex/ship.md new file mode 100644 index 0000000..881eece --- /dev/null +++ b/.agents/commands/codex/ship.md @@ -0,0 +1,28 @@ +--- +description: "Prepare work and open or update a reviewable PR." +--- + +# /ship + +Prepare the current branch for review using the standards of the current +repository and organization. + +1. Discover local standards before changing behavior: + - read the nearest `AGENTS.md`, `CLAUDE.md`, `README.md`, and relevant docs + - inspect repo scripts, package tasks, CI config, and documented validation + - apply any generated org or profile instructions already installed for this agent +2. Inspect the working tree, branch, upstream state, base branch, open PR, and + current CI state. +3. Remove accidental noise, generated clutter, debug instrumentation, and + unrelated changes from the proposed diff. +4. Confirm docs are updated when behavior, interfaces, config, ops, or + developer workflow changed. +5. Run the narrowest meaningful validation first, then broader validation before + opening or updating the PR. +6. Review the final diff for secrets, unrelated files, and avoidable churn. +7. Create or update a ready-for-review PR with a concise description, + validation results, and known risks. +8. Watch CI and fix straightforward failures until the branch is reviewable. + +If local repo or org instructions conflict with this workflow, follow the more +specific repo/org instruction and call out the conflict in the final report. diff --git a/.agents/skills/review-cycle/SKILL.md b/.agents/skills/review-cycle/SKILL.md new file mode 100644 index 0000000..f769b8d --- /dev/null +++ b/.agents/skills/review-cycle/SKILL.md @@ -0,0 +1,32 @@ +--- +name: review-cycle +description: Use when the user invokes /review-cycle, review-cycle, or asks to run a review, fix, and retest loop before shipping. +metadata: + short-description: Review, fix, and retest work +--- + +# Review Cycle + +Run a bounded review, fix, and retest loop using the standards of the current +repository and organization. + +1. Discover local standards before reviewing: + - read the nearest `AGENTS.md`, `CLAUDE.md`, `README.md`, and relevant docs + - inspect repo scripts, package tasks, CI config, and documented validation + - apply any generated org or profile instructions already installed for this agent +2. Identify the target branch, base branch, changed files, open PR, CI state, + and project validation commands. +3. Review the diff from multiple angles: correctness, maintainability, + security, product behavior, test coverage, docs, and consistency with local + standards. +4. Convert actionable findings into a short fix list. Ignore preference-only + churn unless it conflicts with repo/org standards or blocks maintainability. +5. Implement fixes while preserving unrelated user changes. +6. Re-run relevant validation and update docs if behavior or workflow changed. +7. Repeat the review once after fixes. Stop when no material findings remain or + a blocker requires human input. +8. Report what changed, what was validated, which standards were applied, and + any residual risk. + +If local repo or org instructions conflict with this workflow, follow the more +specific repo/org instruction and call out the conflict in the final report. diff --git a/.agents/skills/review-cycle/agents/gemini.yaml b/.agents/skills/review-cycle/agents/gemini.yaml new file mode 100644 index 0000000..2e74469 --- /dev/null +++ b/.agents/skills/review-cycle/agents/gemini.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Run review cycle" + short_description: "Review, fix, and retest work." +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/review-cycle/agents/openai.yaml b/.agents/skills/review-cycle/agents/openai.yaml new file mode 100644 index 0000000..2e74469 --- /dev/null +++ b/.agents/skills/review-cycle/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Run review cycle" + short_description: "Review, fix, and retest work." +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/ship/SKILL.md b/.agents/skills/ship/SKILL.md index 797aca3..41346a1 100644 --- a/.agents/skills/ship/SKILL.md +++ b/.agents/skills/ship/SKILL.md @@ -1,13 +1,31 @@ --- name: ship -description: Prepare work and create a ready-to-review PR. +description: Use when the user invokes /ship, ship, or asks to prepare current work for review or open/update a pull request. +metadata: + short-description: Prepare and open a reviewable PR --- -Prepare the current branch for review. +# Ship -1. Clean up code and remove noise -2. Ensure docs are updated -3. Run local validation (lint, tests, etc.) -4. Review diff -5. Create/update PR with clear description -6. Watch CI and fix simple failures +Prepare the current branch for review using the standards of the current +repository and organization. + +1. Discover local standards before changing behavior: + - read the nearest `AGENTS.md`, `CLAUDE.md`, `README.md`, and relevant docs + - inspect repo scripts, package tasks, CI config, and documented validation + - apply any generated org or profile instructions already installed for this agent +2. Inspect the working tree, branch, upstream state, base branch, open PR, and + current CI state. +3. Remove accidental noise, generated clutter, debug instrumentation, and + unrelated changes from the proposed diff. +4. Confirm docs are updated when behavior, interfaces, config, ops, or + developer workflow changed. +5. Run the narrowest meaningful validation first, then broader validation before + opening or updating the PR. +6. Review the final diff for secrets, unrelated files, and avoidable churn. +7. Create or update a ready-for-review PR with a concise description, + validation results, and known risks. +8. Watch CI and fix straightforward failures until the branch is reviewable. + +If local repo or org instructions conflict with this workflow, follow the more +specific repo/org instruction and call out the conflict in the final report. diff --git a/README.md b/README.md index 7fe4f98..3a7dbc0 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,10 @@ cd ~/dotfiles ``` dotfiles/ -├── .agents/ # Cross-agent skills +├── agent/ +│ └── manifest.json # Agent workflow manifest for org bootstraps +├── .agents/ # Cross-agent workflow defaults +│ ├── commands/ │ └── skills/ ├── .codex/ # Codex defaults │ └── AGENTS.md @@ -49,6 +52,10 @@ stow zsh bash nushell git To pick up new workstation dependencies later, use `update-home` or rerun `./install.sh`. +Agent workflow definitions live in this repo as generic personal defaults, but +`install.sh` does not install them directly. Organization bootstraps can consume +`agent/manifest.json` and layer their own standards over these defaults. + Audit without mutating packages or links: ```bash diff --git a/agent/manifest.json b/agent/manifest.json new file mode 100644 index 0000000..c8260d6 --- /dev/null +++ b/agent/manifest.json @@ -0,0 +1,60 @@ +{ + "schema": "https://willgriffin.dev/agent-manifest/v1", + "layer": "dotfiles", + "priority": 10, + "agent_docs": [ + { + "id": "dotfiles.codex-defaults", + "targets": ["agents", "codex"], + "path": ".codex/AGENTS.md" + } + ], + "commands": [ + { + "agent": "claude", + "name": "ship", + "path": ".agents/commands/claude/ship.md", + "description": "Prepare work and open or update a reviewable PR" + }, + { + "agent": "claude", + "name": "review-cycle", + "path": ".agents/commands/claude/review-cycle.md", + "description": "Run a review, fix, and retest loop" + }, + { + "agent": "codex", + "name": "ship", + "path": ".agents/commands/codex/ship.md", + "description": "Prepare work and open or update a reviewable PR" + }, + { + "agent": "codex", + "name": "review-cycle", + "path": ".agents/commands/codex/review-cycle.md", + "description": "Run a review, fix, and retest loop" + } + ], + "skills": [ + { + "agent": "codex", + "name": "ship", + "path": ".agents/skills/ship", + "description": "Prepare work and open or update a reviewable PR" + }, + { + "agent": "codex", + "name": "review-cycle", + "path": ".agents/skills/review-cycle", + "description": "Run a review, fix, and retest loop" + }, + { + "agent": "codex", + "name": "resolve", + "path": ".agents/skills/resolve", + "description": "Resolve actionable PR review feedback" + } + ], + "env_requirements": [], + "services": [] +}