templates

Table of Contents generated with DocToc

• New project — TODO: replace with <Project Name>
  • What each file is for
    • Authoritative manifest (fill this in first)
    • Release state
    • Scope + product mapping
    • Security-model references
    • CVE-allocation mechanics
    • Remediation workflow
    • Editorial + reporter-facing
    • Contributor growth
    • Issue management
    • Repo-health audits
    • Mentoring
    • PR triage and review
    • Privacy and model routing
    • Framework setup
    • External skill sources
  • Recommended setup order
  • Checklist after copying
  • Cross-references

New project — TODO: replace with <Project Name>

Skeleton directory for a new project under this framework. Do not edit the template in place; copy it to projects/<name>/ and fill in every TODO placeholder:

# From the repo root:
cp -R projects/_template projects/<name>
$EDITOR projects/<name>/project.md
grep -rn TODO projects/<name>     # work through the remaining TODOs

The _template prefix keeps this directory out of the way of the active-project resolver (the skills only load projects/<active>/, so a directory that starts with _ is never accidentally picked up).

What each file is for

Once you have copied the template into <project-config>/ in your tracker repo, update this README.md to be your project's file index. Delete the sections your project does not need and fill in the rest.

Authoritative manifest (fill this in first)

File	Purpose
project.md	Project manifest. Identity, repositories, mailing lists, tools enabled, CVE tooling, GitHub project-board + issue-template field declarations. The single file every skill reads to resolve project-scoped references.

Release state

File	Purpose
release-trains.md	Active release branches, release-manager attribution per cut, rotation rosters, security-team roster.
milestones.md	Milestone naming conventions + create-and-assign recipe.
release-management-config.md	Vote window and pass rule, distribution backend and paths, announce/vote list addresses, retention rule. Read by every release-* skill.
release-build.md	How this project builds and signs artefacts: reproducible source-archive recipe (git archive + .gitattributes), build command, the project's optional convenience artefacts (each with its own build, staging, reproducibility mode, vote scope and publish channel), artefact names, checksum algorithm, optional reproducibility checks.
pmc-roster.md	Who is binding. Read wherever a vote is counted or a PMC-only action is gated.

Scope + product mapping

File	Purpose
scope-labels.md	Scope label → CVE product / packageName / collection-URL mapping. Exactly one scope label per tracker.

Security-model references

File	Purpose
security-model.md	Authoritative URL for the project's Security Model + known-useful anchors + drafting rule.
security-intake-config.md	Capability-flag vocabulary for the intake path: how reports arrive, what counts as in scope, and what a receipt says.
scanner-products.md	Private scanner product names, and the finder-anonymisation rule applied before anything is quoted publicly.
security-tracker-stats.md	Which tracker fields and windows the stats dashboard reads, and what it publishes.
distributor-list.md	Optional. The embargo distributor list a pre-announcement goes to, and what it may contain. Absent, no pre-announcement is proposed.

CVE-allocation mechanics

File	Purpose
title-normalization.md	Regex cascade the security-cve-allocate skill applies to tracker titles before pasting them into the CVE-tool allocation form.
cve-allocation-config.md	Capability-flag vocabulary for CVE allocation: who may allocate, and through which tool.

Remediation workflow

File	Purpose
fix-workflow.md	Fork / clone / toolchain specifics, backport-label policy, commit-trailer wording, PR scrubbing, private-PR fallback.
commit-attribution.toml	Which trailer an agent-assisted commit carries (generated-by, assisted-by, co-authored-by, none, custom, or contributor-choice). The project's value wins over a contributor's — see commit-attribution.md.

Editorial + reporter-facing

File	Purpose
naming-conventions.md	Project-specific editorial rules. Keep only the ones that differ from the generic rules in ../../AGENTS.md.
canned-responses.md	Reusable reporter-facing reply templates.
site-repo.md	The project's website repository, and the path a release announcement bumps.

Contributor growth

These files configure the contributor-nomination, committer-onboarding, and contributor-to-committer skill family. Adopters that do not use these skills can delete this group.

File	Purpose
contributor-nomination-config.md	Nomination-brief thresholds and assessment window. Used by contributor-nomination.
committer-onboarding-config.md	Capability-flag vocabulary for committer intake and governance models (icla/dco/no-cla; asf-pmc/github-codeowners/maintainer-roster). Used by committer-onboarding.
committer-readiness.md	Activity thresholds the contributor-to-committer readiness tracker compares against. Added by the contributor-to-committer skill.
contributor-identities.md	The project's community channels, and confirmed mappings from each contributor's GitHub handle to their Slack, Discord, mailing-list, and social-media handles. Written by contributor-identity-map after a maintainer confirms each one.
committer-readiness.md	The project's declared committer and PMC thresholds — what a contributor's activity is measured against.
onboarding-concierge-config.md	The path a new contributor is walked through, and who owns each step.
contributor-sentiment-config.md	Optional. Signal thresholds for the sentiment gate. Every key has a default.

Issue management

These files configure the issue-* skill family — per-issue triage, pool-level reassessment, reproducer extraction, fix drafting, and read-only stats. Adopters that do not use a general-issue tracker (or only run the security skills) can delete this group.

File	Purpose
issue-tracker-config.md	Tracker URL, project key, auth model, default query templates. Used by every issue-* skill.
runtime-invocation.md	Build prerequisite, run-a-single-file recipe, stream-capture conventions, network/dependency handling. Used by issue-reproducer.
reassess-pool-defaults.md	Named pools for reassessment sweeps (open-eol, reopened, stale-unresolved, project-specific). Used by issue-reassess.
reproducer-conventions.md	Evidence-package directory layout and frozen-copy discipline. Used by issue-reproducer and issue-reassess-stats.

Repo-health audits

These files configure the ci-runner-audit and workflow-security-audit skills and the planned dependency-audit, license-compliance-audit, and flaky-test-triage skills. Adopters who do not use repo-health audits can delete this group.

File	Purpose
repo-health-config.md	Per-skill switches: deprecated runner labels, zizmor rule classes, dependency managers, SPDX expression, flaky-test thresholds. Used by every *-audit and flaky-test-triage skill.

Mentoring

File	Purpose
good-first-issue-config.md	What counts as a good first issue here: labels, size limits, and the areas safe to hand to a newcomer.
mentoring-config.md	Tone knobs and hand-off protocol for the thread-level mentoring skill.
mentoring-welcome-config.md	Optional. Wording and triggers for first-time-contributor welcomes.
newcomer-issue-explainer-config.md	Optional. How much context an explanation carries, and the register it is written in.

PR triage and review

These files configure the pr-management-triage, pr-management-stats, pr-management-code-review, and pr-management-stack-review skills. Adopters who only use the security skills can delete these four files; adopters running maintainer-side PR-queue management fill them in.

File	Purpose
pr-management-config.md	Committers team handle, area-label prefix, project-specific labels (ready for maintainer review, etc.), grace windows. Used by pr-management-triage and pr-management-stats.
pr-management-triage-comment-templates.md	Comment-body URLs (PR quality criteria, two-stage triage rationale), AI-attribution footer wording, project display name. Used by pr-management-triage.
pr-management-triage-ci-check-map.md	CI-check name pattern → category name + doc-URL mapping for the violations comment. Used by pr-management-triage.
pr-management-code-review-criteria.md	List of project's review-criteria source files (repo-wide AGENTS.md, code-review docs, per-area AGENTS.md), security-model calibration doc, backport-branch pattern, section-anchor URLs. Used by pr-management-code-review and pr-management-stack-review.
pr-management-quick-merge-config.md	Thresholds, path globs, and the merge-command template for the express lane.
reviewer-roster.md	Who reviews what. Read by pr-management-reviewer-routing to propose a reviewer.
stale-sweep-config.md	Optional. Grace windows and exemption labels for stale sweeps. Absent, the framework defaults apply.

Each PR-skill reads its project-specific content exclusively from the files listed below. No defaults are baked into the framework — every adopter provides their own values in <project-config>/. See projects/_template/pr-management-*.md for concrete examples (filled in with the Apache Airflow project's values, which new adopters can use as a reference when drafting their own configuration).

Privacy and model routing

File	Purpose
privacy-llm.md	Optional. Which model tier may see which class of content, for projects routing foundation-private information away from third-party models.

Framework setup

File	Purpose
magpie-setup.md	Optional. Overrides for the setup family's own checks. Every key has a default.

External skill sources

File	Purpose
skill-sources.md	The install gate for pulling skills/families from trusted external repos. Lists the source ids this project trusts and commits each pin. /magpie-setup fetches only what is listed here. Leave empty to run only in-tree framework skills. See docs/skill-sources/.

Recommended setup order

After copying the template, fill in the core project files before the optional skill-family files:

1. Start with project.md, because every skill uses it to resolve project-scoped references.
2. Fill in security-model.md so security-facing workflows have an authoritative source.
3. Add current release details to release-trains.md.
4. Define tracker organization in scope-labels.md and milestones.md.
5. Prepare reporter-facing text in canned-responses.md.
6. Document the fix flow in fix-workflow.md.
7. If your project uses the issue or PR-management skill families, fill in the optional files they read, such as issue-tracker-config.md, runtime-invocation.md, pr-management-config.md, and pr-management-code-review-criteria.md.

Run grep -rn TODO projects/<name> after copying and again before opening a pull request so no template placeholders are left behind.

Checklist after copying

• cp -R projects/_template projects/<name> done.
• Every TODO in project.md resolved (grep: grep -n TODO projects/<name>/project.md).

Security workflow (delete this group if not using the security skills):

• scope-labels.md lists at least one scope label (exactly-one-of rule).
• security-model.md points at the project's authoritative Security-Model URL.
• release-trains.md has at least one current release branch + its RM.
• canned-responses.md has at least the "Confirmation of receiving the report" template filled in (the security-issue-import skill sends this verbatim).

PR triage and review (delete this group if not using the pr-* skills):

• pr-management-config.md — committers team handle and area-label prefix filled in.
• pr-management-triage-comment-templates.md — <quality_criteria_url>, <two_stage_triage_rationale_url>, and <project_display_name> filled in.
• pr-management-triage-ci-check-map.md — at least one CI-check pattern row filled in (or the catch-all row pointing at the project's static-checks doc).
• pr-management-code-review-criteria.md — at least one repo-wide review-criteria source file declared.

Common finishers:

• config/active-project.md updated to the new directory name if this working tree should target the new project.
• Root README.md "Current projects" table updated with a row for the new project + a link to this README.md.
• prek run --all-files passes.

Cross-references

• ../../README.md — framework-level "Adopting the framework" view + bootstrap walk-through.
• ../../AGENTS.md — the placeholder convention that lets skills resolve <project-config>/ to the adopter's path at agent harness.