| 1 | # Copilot Instructions for SquadScope |
| 2 | |
| 3 | This repository uses the **Squad agent** as the default for all AI-assisted work. |
| 4 | |
| 5 | ## Default Agent |
| 6 | |
| 7 | Always use `--agent squad` when running Copilot CLI on this repository. |
| 8 | |
| 9 | ## Repository Context |
| 10 | |
| 11 | - **Project:** SquadScope (public brand: Claracle) — AI-powered GitHub trend analysis |
| 12 | - **Architecture:** See `architecture.md` in repo root |
| 13 | - **Squad team:** See `.squad/team.md` for current roster |
| 14 | |
| 15 | ## Key Conventions |
| 16 | |
| 17 | - All pipeline scripts are in `scripts/` (Python) |
| 18 | - Content is Hugo markdown in `content/` |
| 19 | - Config shared with Podcaster lives in `config/podcast.json` |
| 20 | - Changes to `config/podcast.json` MUST be coordinated with SquadScope-Podcaster repo |
| 21 | - Never commit secrets; use GitHub environment secrets |
| 22 | - PRs required for `main` branch (branch protection enabled) |
| 23 | - CI must be correct, not just green — verify rendered output for site changes |
| 24 | |
| 25 | ## Cross-Repo Impact |
| 26 | |
| 27 | Changes to these files affect the Podcaster repo: |
| 28 | |
| 29 | - `config/podcast.json` — Podcaster reads this config for episode generation |
| 30 | - `scripts/podcaster_handoff.py` — defines the handoff payload contract |
| 31 | |
| 32 | ## Testing |
| 33 | |
| 34 | - Run `pytest tests/` for unit tests |
| 35 | - Hugo build: `hugo --minify` must succeed |
| 36 | - Handoff smoke: `.github/workflows/podcaster-handoff-smoke.yml` |
| 37 | |
| 38 | ## DevSecOps Guardrails |
| 39 | |
| 40 | Part of the DevSecOps Guardrails epic (jmservera/SquadScope-Coordinator#33). |
| 41 | Baselines and per-tool docs live in `docs/devsecops/`. Phase A tooling is |
| 42 | **warning-only / non-blocking** today; do not weaken or skip a real gate to make |
| 43 | CI pass — CI must be correct, not just green. |
| 44 | |
| 45 | ### Before you push (always) |
| 46 | |
| 47 | - Run the local tests: `pytest tests/`. |
| 48 | - If you changed a `Dockerfile`/`Containerfile`: run `docker build` locally. |
| 49 | - Lint/format Python with **ruff**. |
| 50 | - If you changed IaC or container files: run **checkov**. |
| 51 | - If you changed anything under `.github/workflows/`: run **zizmor**. |
| 52 | |
| 53 | ### Tooling (run manually) |
| 54 | |
| 55 | ```bash |
| 56 | # Python lint/format — ruff (config in pyproject.toml; see docs/devsecops/ruff-baseline.md) |
| 57 | pip install ruff==0.15.7 |
| 58 | ruff check . # lint (report) |
| 59 | ruff check . --fix # apply safe fixes |
| 60 | ruff format . # format |
| 61 | |
| 62 | # IaC / container / Actions scan — checkov (see docs/devsecops/checkov-baseline.md) |
| 63 | pip install checkov==3.2.533 |
| 64 | checkov --directory . --framework github_actions dockerfile secrets \ |
| 65 | --skip-path node_modules --skip-path .venv --compact --soft-fail |
| 66 | |
| 67 | # GitHub Actions security — zizmor (see docs/devsecops/zizmor-baseline.md) |
| 68 | pipx install zizmor |
| 69 | zizmor .github/workflows/ |
| 70 | ``` |
| 71 | |
| 72 | ### Git hooks |
| 73 | |
| 74 | Local pre-commit/pre-push hooks live in `.pre-commit-config.yaml` (ruff, |
| 75 | checkov, pytest, docker build). Install them once and keep tool versions in |
| 76 | sync with CI — see `docs/devsecops/pre-commit.md`: |
| 77 | |
| 78 | ```bash |
| 79 | pip install pre-commit |
| 80 | pre-commit install --hook-type pre-commit --hook-type pre-push |
| 81 | ``` |
| 82 | |
| 83 | **Emergency skip:** `git commit --no-verify` / `git push --no-verify` bypasses |
| 84 | local hooks — use only for genuine emergencies and follow up by fixing the |
| 85 | skipped findings. Never disable the CI gates themselves to land a change. |
| 86 | |
| 87 | ### Ownership |
| 88 | |
| 89 | - **URL** (DevSecOps Specialist) owns the guardrail pipeline, tooling, hooks, |
| 90 | dependency scanning, and secret detection. |
| 91 | - **Hermes** (Security & Threat Analyst) owns security review, threat modeling, |
| 92 | and alert triage. |
| 93 | - Infra, `Dockerfile`/`Containerfile`, and workflow changes should be reviewed by |
| 94 | URL (pipeline impact) and Hermes (security). |