Development Workflow

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

Local validation is targeted: run the checks relevant to what you changed. The repository's README maps each kind of change to its checks, and CI (validate.yml, pull requests only) routes each PR to a full, reduced, or documentation-only test tier and remains the authoritative gate before merge. After one-time setup, from the repository root, the full set CI can run is:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
python3 scripts/validation/validate-skill-metadata.py skills/local-code-review --containment-root .
python3 scripts/validation/validate-skill-metadata.py skills/github-pr-review --containment-root .
python3 scripts/validation/validate-markdown-links.py
python3 -m unittest discover -s tests -t .
./scripts/packaging/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

• Documentation structure and layering (README vs. docs/ vs. policy): policies/documentation-policy.md
• Skill packaging, runbook design, portability: policies/skill-development-policy.md
• Repository-owned Python style: policies/python_scripts_coding_policy.md
• Review orchestration boundaries (implementer/reviewer separation, the local-review approval gate): policies/review-orchestration-policy.md

"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.