LarsLaskowski/Squad-Spec-Repository-Template

The shared squad, AI-agent rules and repository scaffolding for all repositories: one stack-neutral
**core** plus one **profile** per tech stack. It is not used through GitHub's "Use this template" button;
the adopt-template skill applies it to an existing (or new) repository and refreshes it there later.
What a repository gets
- **The squad** (.squad/, .claude/agents/squad-*.md) — Lead, Devil's Advocate, Security, Tester,
Dev, Code Officer and Reviewer, run by the squad-issue (bug fixes) and squad-spec (features)
skills: plan → challenge → security review → tests first → implementation until the coverage gate passes
→ format and analyzer gate → review loop → Lead approval → pull request. Details in
core/.squad/routing.md. A PreToolUse hook in every agent's front matter
(.claude/hooks/git-guard.py) denies Git and GitHub writes to the members; only the orchestrating session
commits, pushes and posts.
- **One rule set for Claude Code, mirrored for GitHub Copilot** — CLAUDE.md holds the rules, the skills
create-pr, review-pr, squad-issue, squad-spec and decision-consolidate live under .claude/skills/.
.github/copilot-instructions.md is generated from CLAUDE.md (its own title and introduction, then the same
body), so Copilot's code review, chat and coding agent follow the same rules; config-check.py fails when the
two drift apart. The squad runs on Claude Code subagents; a refresh removes the Codex mirror (AGENTS.md) and
the skill copies under .agents/skills/ and .github/skills/ that older template versions wrote, and lists
every line of the repository that still refers to a removed file.
- **Decision records with a release boundary** — records are edited in place until a v* tag contains them,
then they are append-only (superseded by a new record); a record is added only for a decision with lasting
weight and grouped by topic, and state only the *why*: what holds today is written once in an area document
(docs/areas/ .md, indexed in docs/areas/README.md) that the same PR keeps current. decision-check.py (run by config-check.py) enforces consistency and the
freeze; the decision-consolidate skill folds unreleased chains into one record.
- **Quality gates before the PR** — *Format*, *Analyzer gate* (no diagnostic of any severity in a changed
file) and *Coverage gate* (≥ 80 % on new/changed lines and overall by default, thresholds in
squad_settings.py; Cobertura, lcov or Go coverprofile), plus config-check.py (agents and skills load,
no placeholder left) and scope-check.py (a product change touches no squad file, keeps marked files'
template text and leaves no working record behind). squad-log.py appends the pipeline's log rows.
- **Documentation scaffolding** — docs/CONTRIBUTING.md, docs/ARCHITECTURE.md, docs/UNIT_TESTS.md,
decision records (docs/decisions/, with three process records from decision-seeds/),
specs/_template/, SECURITY.md.
- **GitHub scaffolding** — PR template, issue templates, CI workflow, CodeQL, Dependabot (per profile).
Layout
Four kinds of files in a target repository:
| Kind | Examples | On a refresh |
| ---- | -------- | ------------ |
| managed | .squad/team.md, .squad/routing.md, .claude/agents/squad-*.md (the charters), the template's skills, .squad/tools/*.py (except squad_settings.py), the hooks under .claude/hooks/, feature-request template, specs/ templates, docs/decisions/_template.md, docs/areas/_template.md | overwritten |
| marked | CLAUDE.md, docs/CONTRIBUTING.md, docs/ARCHITECTURE.md, bug report and PR template, decision and area index | rebuilt; blocks keep the repository's content, blocks come from the profile |
| generated | .github/copilot-instructions.md | rebuilt from core/.github/copilot-instructions.md (title and introduction) and the body of the rebuilt CLAUDE.md |