diff --git a/tools/spec-loop/.last-sync b/tools/spec-loop/.last-sync index 2a95cd94..1dd08632 100644 --- a/tools/spec-loop/.last-sync +++ b/tools/spec-loop/.last-sync @@ -1 +1 @@ -942544abbb9f9eb525359381a56f0404b97442c4 +dd18a3ccfdff1fc258fd4784970018fcc1c7bb91 diff --git a/tools/spec-loop/specs/contributor-growth.md b/tools/spec-loop/specs/contributor-growth.md index d7cec91f..6036e38b 100644 --- a/tools/spec-loop/specs/contributor-growth.md +++ b/tools/spec-loop/specs/contributor-growth.md @@ -12,7 +12,7 @@ source: > Agentic Triage and Agentic Mentoring but are not yet a named family). mentoring-mode.md § Known gaps. Implemented by contributor-nomination, contributor-activity-sweep, committer-onboarding, good-first-issue-author, - and mentoring-welcome. + mentoring-welcome, contributor-to-committer, and good-first-issue-sweep. acceptance: - Every family skill is read-only or propose-before-post; none transitions, promotes, or announces without explicit maintainer @@ -78,6 +78,17 @@ state change for human sign-off. Propose-before-post at every state-changing step. Ships `mode: Triage` + `experimental`, eval suite under `tools/skill-evals/evals/committer-onboarding/`. +- Skill: `contributor-to-committer` — read-only readiness tracker that + maps a contributor's GitHub activity against the adopter's PMC-declared + committer or PMC thresholds; surfaces a traffic-light brief (Not yet / + Approaching / Ready to nominate) plus the specific evidence gaps that + remain. Ships `mode: Mentoring` + `experimental`. +- Skill: `good-first-issue-sweep` — sweeps the open issue backlog for + existing issues that could be labelled as good first issues; classifies + each candidate as READY, NEAR-MISS, or SKIP against the G1–G7 rubric; + applies labels only after explicit maintainer confirmation. Ships + `mode: Mentoring` + `experimental`, eval suite under + `tools/skill-evals/evals/good-first-issue-sweep/`. ## Behaviour & contract @@ -115,10 +126,6 @@ state change for human sign-off. - Auto-promoting a contributor: all promotion decisions stay with the PMC; the skills prepare evidence and checklists, never act on the vote outcome without the nominator's explicit direction. -- Backlog curation (relabeling the existing issue backlog as good - first issue candidates): `good-first-issue-author` drafts net-new - issues only; backlog curation is a separate capability not yet - specced. ## Acceptance criteria @@ -153,13 +160,15 @@ uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-valid before a skill can safely propose anything. These are candidate work items once the active-path skills stabilise and an adopter pilot surfaces the concrete policy knobs needed. -- **Mode boundary with Agentic Mentoring is intentionally fuzzy.** Two family - skills (`mentoring-welcome`, `good-first-issue-author`) carry +- **Mode boundary with Agentic Mentoring is intentionally fuzzy.** Four family + skills (`mentoring-welcome`, `good-first-issue-author`, + `contributor-to-committer`, `good-first-issue-sweep`) carry `mode: Mentoring` and are documented in [mentoring-mode.md](mentoring-mode.md); - three carry `mode: Triage`. A later family-maturity review may - formalise the boundary or merge the families; for now, both specs - cross-reference each other. -- **`experimental` — no adopter pilot has run.** All five skills exist + three carry `mode: Triage` (`contributor-activity-sweep`, + `contributor-nomination`, `committer-onboarding`). A later family-maturity + review may formalise the boundary or merge the families; for now, both + specs cross-reference each other. +- **`experimental` — no adopter pilot has run.** All seven skills exist but no maintainer has run the full contributor-to-committer path end-to-end through the family. Shape may change as adopter pilots surface real-world usage patterns. diff --git a/tools/spec-loop/specs/good-first-issue-sweep.md b/tools/spec-loop/specs/good-first-issue-sweep.md index 845fdf3a..a4e9188f 100644 --- a/tools/spec-loop/specs/good-first-issue-sweep.md +++ b/tools/spec-loop/specs/good-first-issue-sweep.md @@ -7,12 +7,11 @@ status: experimental kind: feature mode: Mentoring source: > - mentoring-mode.md Known Gaps ("the curation counterpart — relabeling the - existing backlog as good-first-issue candidates — is still unspecced"). Companion to good-first-issue-author, which drafts net-new issues from a supplied candidate. This skill covers the complementary sweep-existing- backlog path. Together they fill the newcomer on-ramp from both the - authoring and curation sides. + authoring and curation sides. Shipped in feat(mentoring): add + good-first-issue-sweep skill and eval suite (#632). acceptance: - Classification uses the G1–G7 suitability rubric; the skill never invents or substitutes criteria. diff --git a/tools/spec-loop/specs/mentoring-mode.md b/tools/spec-loop/specs/mentoring-mode.md index 7d802c9a..5f44b4bf 100644 --- a/tools/spec-loop/specs/mentoring-mode.md +++ b/tools/spec-loop/specs/mentoring-mode.md @@ -9,7 +9,7 @@ mode: Mentoring source: > MISSION.md § Technical scope (Mentoring) — "the highest-value project-side mode and the one off-the-shelf agent tooling skips". - docs/modes.md § Mentoring (experimental, 3 skills). Spec exists at + docs/modes.md § Mentoring (experimental, 5 skills). Spec exists at docs/mentoring/spec.md ahead of any skill code. MISSION.md names onboarding latency as one of the two loudest ecosystem complaints; authoring newcomer-ready good first issues targets it directly. @@ -71,6 +71,20 @@ a project can offer a first-time contributor. for explicit maintainer confirmation before posting. Ships `mode: Mentoring` + `experimental`, with an eval suite under `tools/skill-evals/evals/mentoring-welcome/`. +- Skill: `contributor-to-committer` — read-only readiness tracker that + maps a contributor's GitHub activity against the adopter's PMC-declared + committer or PMC thresholds; surfaces a traffic-light brief (Not yet / + Approaching / Ready to nominate) plus the specific evidence gaps that + remain. Ships `mode: Mentoring` + `experimental`, with an eval suite + under `tools/skill-evals/evals/contributor-to-committer/`. +- Skill: `good-first-issue-sweep` — sweeps the open issue backlog for + existing issues that could be labelled as good first issues. Scores each + candidate against the G1–G7 suitability rubric and classifies it as + READY (propose the GFI label), NEAR-MISS (surface specific edits to make + it GFI-ready), or SKIP. Applies labels only after explicit maintainer + confirmation; never edits issue bodies. Ships `mode: Mentoring` + + `experimental`, with an eval suite under + `tools/skill-evals/evals/good-first-issue-sweep/`. ## Behaviour & contract @@ -93,9 +107,6 @@ a project can offer a first-time contributor. - Implementation-detail review that belongs to Agentic Pairing ([Pairing](pairing-mode.md)). - Any contributor-facing message sent without human review. -- Curating or bulk-labeling the *existing* backlog as good first issues: - this skill authors net-new drafts only. Backlog curation and labeling is - a separate capability that is not specced yet. ## Acceptance criteria @@ -113,30 +124,31 @@ a project can offer a first-time contributor. test -f docs/mentoring/spec.md test -f .claude/skills/magpie-good-first-issue-author/SKILL.md test -f .claude/skills/magpie-mentoring-welcome/SKILL.md +test -f .claude/skills/magpie-contributor-to-committer/SKILL.md +test -f .claude/skills/magpie-good-first-issue-sweep/SKILL.md uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate uv run --project tools/skill-evals skill-eval tools/skill-evals/evals/good-first-issue-author/ uv run --project tools/skill-evals skill-eval tools/skill-evals/evals/mentoring-welcome/ +uv run --project tools/skill-evals skill-eval tools/skill-evals/evals/good-first-issue-sweep/ ``` ## Known gaps - **The family now covers the newcomer journey end to end.** - `pr-management-mentor`, `good-first-issue-author`, `mentoring-welcome` - (first-contribution welcome / orientation), and `contributor-to-committer` - (readiness path tracker) all ship. `docs/mentoring/README.md` reflects all - four shipped skills. The two newcomer-facing capabilities this spec - previously flagged as undesigned are both built; the open item that remains - is the backlog-curation counterpart noted above (relabeling the existing - backlog as good-first-issue candidates). -- **`experimental` — no adopter pilot has run.** All four shipped skills - (`pr-management-mentor`, `good-first-issue-author`, `mentoring-welcome`) - and `contributor-to-committer` may change shape as adopter pilots and - contributor-sentiment evaluations land. -- **`good-first-issue-author` shipped `experimental`; no adopter pilot - has authored a live good first issue through it yet.** The suitability - and readiness thresholds may shift once real backlog candidates run - through it. The curation counterpart (relabeling the *existing* backlog - as good-first-issue candidates) is still unspecced. + All five skills ship: `pr-management-mentor`, `good-first-issue-author`, + `mentoring-welcome` (first-contribution welcome / orientation), + `contributor-to-committer` (readiness path tracker), and + `good-first-issue-sweep` (backlog curation / labelling). The on-ramp + supply chain is complete from both the authoring side + (`good-first-issue-author`) and the curation side (`good-first-issue-sweep`). +- **`experimental` — no adopter pilot has run.** All five shipped skills + may change shape as adopter pilots and contributor-sentiment evaluations + land. +- **`good-first-issue-author` and `good-first-issue-sweep` shipped + `experimental`; no adopter pilot has run live good first issue + workflows yet.** The G1–G7 suitability thresholds and the R1–R9 + readiness checklist may shift once real backlog candidates flow through + the skills. - **`mentoring-welcome` shipped `experimental`; no adopter pilot run.** The welcome tone, detecting first-timer vs. repeat contributor, and the content of the orientation template may shift once live threads run diff --git a/tools/spec-loop/specs/overview.md b/tools/spec-loop/specs/overview.md index 34001082..a3e7fb62 100644 --- a/tools/spec-loop/specs/overview.md +++ b/tools/spec-loop/specs/overview.md @@ -31,7 +31,7 @@ Each mode is an independently toggleable set of skills. Maturity mirrors | Mode | Spec | Maturity | |---|---|---| | Agentic Triage | [triage-mode.md](triage-mode.md) | stable (security) / experimental (PR, issue, contributor-nomination) | -| Agentic Mentoring | [mentoring-mode.md](mentoring-mode.md) | experimental (3 skills) | +| Agentic Mentoring | [mentoring-mode.md](mentoring-mode.md) | experimental (5 skills) | | Agentic Drafting | [drafting-mode.md](drafting-mode.md) | stable (security) / experimental (issue, audit-finding-fix, release-announce-draft) | | Agentic Pairing | [pairing-mode.md](pairing-mode.md) | experimental (2 skills) | @@ -54,8 +54,8 @@ Each mode is an independently toggleable set of skills. Maturity mirrors | Adapters (Gmail / PonyMail / Jira / GitHub / mail-source / forwarder-relay / mail-archive / github-body-field / github-rollup) | [adapters.md](adapters.md) | | Project-agnosticism (de-ASF coupling) | [project-agnosticism.md](project-agnosticism.md) | | Meta & quality tooling | [meta-and-quality-tooling.md](meta-and-quality-tooling.md) | -| Reviewer routing (proposed, Agentic Triage) | [reviewer-routing.md](reviewer-routing.md) | -| Cross-project skill reconciler (proposed, infra) | [skill-reconciler.md](skill-reconciler.md) | +| Reviewer routing (experimental, Agentic Triage) | [reviewer-routing.md](reviewer-routing.md) | +| Cross-project skill reconciler (experimental, infra) | [skill-reconciler.md](skill-reconciler.md) | ## The non-negotiables every area inherits diff --git a/tools/spec-loop/specs/reviewer-routing.md b/tools/spec-loop/specs/reviewer-routing.md index e5f1ba66..b9e39fc1 100644 --- a/tools/spec-loop/specs/reviewer-routing.md +++ b/tools/spec-loop/specs/reviewer-routing.md @@ -13,7 +13,9 @@ source: > reviews" (overview.md § Substrate; projects/_template adopter config), but no skill turns that roster plus repository signal into an assignee suggestion. triage-mode.md § What it does ("propose routing to the - right human") names the behaviour; no skill implements it yet. + right human") names the behaviour. Skill ships experimental in + .claude/skills/magpie-reviewer-routing/ with an eval suite under + tools/skill-evals/evals/reviewer-routing/. acceptance: - The skill is read-only on tracker state and proposes-then-confirms; it never assigns, requests review, or labels without confirmation. @@ -44,9 +46,9 @@ side: a grounded brief a human acts on, not a state change. ## Where it lives -- Skill (proposed, not implemented): `reviewer-routing` under - `skills/`, in the Agentic Triage family alongside `pr-management-triage` and - `issue-triage`. +- Skill: `reviewer-routing` under `.claude/skills/magpie-reviewer-routing/`, + in the Agentic Triage family alongside `pr-management-triage` and + `issue-triage`. Eval suite under `tools/skill-evals/evals/reviewer-routing/`. - Roster source: the project's configured reviewer roster (`projects//` adopter config; `pmc-roster.md` for ASF projects, an arbitrary maintainer list for non-ASF adopters). The @@ -111,9 +113,7 @@ uv run --project tools/skill-evals skill-eval tools/skill-evals/evals/reviewer-r ## Known gaps -- **No skill is implemented yet.** This spec is `proposed`; the plan - pass turns it into a single build item (one skill plus its eval suite). -- **Open-review-load signal is unspecified in detail.** Whether load is +- **Open-review-load signal is implementation-defined.** Whether load is counted as open review requests, assigned-and-unreviewed PRs, or a decay-weighted recent count is left to the implementation; the contract only requires that some load signal is present and shown. @@ -121,3 +121,6 @@ uv run --project tools/skill-evals skill-eval tools/skill-evals/evals/reviewer-r assumes an adopter declares a maintainer list; no non-ASF profile fixture exercises routing yet (overlaps the non-ASF adopter profile work item in IMPLEMENTATION_PLAN). +- **`experimental` — no adopter pilot has run.** The skill ships but no + end-to-end routing workflow has been exercised in a live maintainer + session; signal weights and roster-match heuristics may change. diff --git a/tools/spec-loop/specs/skill-reconciler.md b/tools/spec-loop/specs/skill-reconciler.md index 48e3e6ae..e1acb205 100644 --- a/tools/spec-loop/specs/skill-reconciler.md +++ b/tools/spec-loop/specs/skill-reconciler.md @@ -14,7 +14,9 @@ source: > `source` tag so the split is a registry query). PRINCIPLES.md on the safety baseline that must stay eventually-consistent across every copy. meta-and-quality-tooling.md (the skill-authoring/quality family this - joins). No reconciler tool or skill exists yet. + joins). Skill ships experimental in + .claude/skills/magpie-skill-reconciler/ with an eval suite under + tools/skill-evals/evals/skill-reconciler/. acceptance: - The reconciler is read-only: it produces a structured diff and a reconciliation proposal; it never rewrites either skill without human @@ -52,10 +54,11 @@ that a maintainer should not ignore. ## Where it lives -- Skill (proposed, not implemented): `skill-reconciler` under `skills/`, +- Skill: `skill-reconciler` at `.claude/skills/magpie-skill-reconciler/`, in the meta / quality family with `write-skill`, `optimize-skill`, and `list-skills` (see [meta-and-quality-tooling.md](meta-and-quality-tooling.md)). -- Optional deterministic helper (proposed): a `uv` tool under `tools/` + Eval suite under `tools/skill-evals/evals/skill-reconciler/`. +- Optional deterministic helper (not yet built): a `uv` tool under `tools/` that does the structural diff (frontmatter, section headings, step-by-step decision rules, placeholder inventory) so the skill reasons over a normalised diff rather than raw text. Follows the