Skip to content

Development Workflow

Jump to bottom
amirbena edited this page Sep 17, 2026 · 2 revisions

Development Workflow

A contributor-oriented navigation page for working on this repository — not on either Skill's review behavior as a user. Every rule here is owned by AGENTS.md, policies/, and CONTRIBUTING.md — this page links out rather than restating them.

Start here

Development of this repository has one canonical entrypoint: AGENTS.md. It states the global invariants (dedicated task branches, read-only Git safety, clean task exit, one canonical home per rule) and routes each task to the one focused policy under policies/ that owns its detail.

Contribution paths

CONTRIBUTING.md defines three ownership classes, applied via GitHub Issue labels:

Label For
good first issue A bounded task with an already-well-defined expected behavior — fixtures, docs, bounded tests, isolated tooling
contributor-owned A whole capability whose boundaries/invariants/acceptance-criteria are defined but implementation approach is open
maintainer-led Semantic/architectural contracts — finding identity, severity, decision derivation, evidence thresholds, cross-Skill contracts

Full model: policies/contribution-ownership-policy.md.

Claiming and branching

  1. Comment /claim on an open, unclaimed issue with a contribution-ready label.
  2. Fork, then create a branch named <type>/<short-description> — feat/, fix/, docs/, test/, refactor/, chore/, research/.
  3. Implement the issue without unrelated changes.

Full claim mechanics (bot behavior, churn protection, /unclaim): CONTRIBUTING.md.

Validation before opening a PR

From the repository root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
python3 scripts/validate-skill-metadata.py skills/local-code-review --containment-root .
python3 scripts/validate-skill-metadata.py skills/github-pr-review --containment-root .
python3 scripts/validate-markdown-links.py
python3 -m unittest discover -s tests -t .
./scripts/package-skills.sh all

Run one test module with, e.g. python3 -m unittest tests.unit.review.test_decision_semantics. Test suite layout (unit/, policy/, reference/, integration/) is documented in tests/README.md.

CHANGELOG and release intent

Never edit CHANGELOG.md directly. A release-worthy change (it touches shipped Skill content under skills//shared/, or the packaging/distribution scripts) declares its intent as two lines in the pull request description — Release category: and Release entry: — checked by a deterministic classifier before merge. Everything else declares Release category: none. Full convention: docs/RELEASE.md, policies/release-changelog-policy.md.

PR and merge

Opening a PR applies .github/PULL_REQUEST_TEMPLATE.md automatically. main is protected; every PR must satisfy repository checks and review before an authorized maintainer merges it — claiming an issue never bypasses that. Full merge/Git rules: policies/git-pr-merge-policy.md.

Documentation and Skill-development rules

"Where do I put a new rule?"

See Repository-Documentation-Map for the full ownership breakdown — it answers exactly this question for any kind of change.

Wiki Page Map

Page What it covers
Home Wiki entry point: what the two Skills are and where to go next.
Getting-Started First steps to package and run either Skill.
Choosing-a-Review-Skill How to decide between local-code-review and github-pr-review.
How-the-Review-Model-Works Concept-level walkthrough of the review pipeline shared by both Skills.
Architecture-Overview Component-level map of how the repository's pieces fit together.
Specialist-Depth-Review When and how a review goes deeper than its base pass.
Local-Code-Review-Guide Usage guide for reviewing local, not-yet-PR'd Git changes.
GitHub-PR-Review-Guide Usage guide for reviewing an existing GitHub Pull Request.
Review-Context-and-Existing-Evidence How optional requirements/context and prior review evidence are supplied.
Feature-Pages Index of per-feature capability pages and their shared template.
Feature-Delta-Re-Review How a re-review scopes itself to only what changed since the last pass.
Feature-GitHub-Publication-and-Authorization What a PR review publishes to GitHub and under what authority.
Feature-Human-Style-Review-Output The senior-engineer-voice prose summary output option.
Feature-Requirement-Coverage How supplied requirements are checked and reported as covered or not.
Feature-Runtime-Validation-Evidence How a review can execute commands or reproductions as evidence.
Severity-and-Decision-Model The P0/P1/P2 severity levels and how the merge decision is derived.
Packaging-and-Portability How the Skills go from source repository to a standalone archive.
Development-Workflow Contributor guide for working on this repository itself.
Benchmark-Testing Orientation to this repository's own review-quality benchmark pipeline.
Repository-Documentation-Map Where each concern's canonical, authoritative source lives.
AI-Code-Review-Landscape Neutral snapshot comparing this project against other AI code-review products.
FAQ Short, practical answers to common questions.

Clone this wiki locally