swe-workflow-skills 0.10.1 → 0.11.0

package/README.md

@@ -2,10 +2,10 @@
 
 [![npm](https://img.shields.io/npm/v/swe-workflow-skills)](https://www.npmjs.com/package/swe-workflow-skills)
 [![roles-check](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml/badge.svg)](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml)
-![skills](https://img.shields.io/badge/skills-66-blue)
+![skills](https://img.shields.io/badge/skills-68-blue)
 [![license: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
 
-A curated library of **66 Claude Code Agent Skills** that walk Claude through the
+A curated library of **68 Claude Code Agent Skills** that walk Claude through the
 software lifecycle the way a disciplined senior engineer would: planning, design,
 TDD, review, security, deployment, incidents, and the project-management work around
 them.
@@ -31,7 +31,7 @@ Code web, claude.ai chat, and Cowork:
 is a **two-step** setup:
 
 ```bash
-# 1. Install all 66 skills + router + /role + the hook script, and apply the baseline
+# 1. Install all 68 skills + router + /role + the hook script, and apply the baseline
 npx swe-workflow-skills install --global
 ```
 
@@ -107,7 +107,7 @@ request can fan out to several skills. See a full session in
 
 - **An orchestrator, not auto-trigger roulette.** Description-based auto-triggering is
   probabilistic. Here `skill-router` routes intent to skills by name, and a routing
-  harness measures it: 65/65 top-1 and 64/65 on boundary cases on the committed k=3
+  harness measures it: 67/67 top-1 and 66/67 on boundary cases on the committed k=3
   baseline ([routing benchmark](docs/ROUTING-BENCHMARK.md)).
 - **Every skill stays reachable.** Claude Code lists skill descriptions only up to about
   1% of context, so large libraries stop auto-triggering past 20 to 40 skills. This
@@ -129,17 +129,17 @@ request can fan out to several skills. See a full session in
 
 ## What's included
 
-66 skills, listed in the **[full catalog → SKILLS.md](docs/SKILLS.md)**:
+68 skills, listed in the **[full catalog → SKILLS.md](docs/SKILLS.md)**:
 
 | Area | Count | Examples |
 |------|-------|----------|
 | Software Engineering | 30 | feature-planning, plan-execution, architecture-design, threat-modeling, compliance-privacy, code-archaeology, tdd-workflow, security-audit, browser-verification, subagent-orchestration |
-| Project Management | 8 | brainstorming, prd-writing, effort-estimation, build-vs-buy, metrics-and-okrs, retrospective, strategic-review |
+| Project Management | 9 | brainstorming, prd-writing, working-agreement, effort-estimation, build-vs-buy, metrics-and-okrs, retrospective, strategic-review |
 | DevOps | 8 | containerization, cicd-pipeline, release-management, gitops-delivery, resilience-engineering, finops-cost-optimization |
 | Design | 3 | ui-ux-design, frontend-architecture, accessibility-design |
 | MLOps | 3 | ml-pipeline-design, ml-experiment-tracking, ml-model-deployment |
 | AI Engineering | 2 | llm-app-engineering, ai-evaluation |
-| Data Science | 3 | exploratory-data-analysis, statistical-analysis, notebook-to-production |
+| Data Science | 4 | research-methodology, exploratory-data-analysis, statistical-analysis, notebook-to-production |
 | Data Engineering | 2 | data-pipeline-design, data-quality |
 | Mobile | 2 | mobile-architecture, mobile-release |
 | Evaluation & Monitoring | 2 | observability-design, test-data-strategy |

package/VERSION

@@ -1 +1 @@
-0.10.1
+0.11.0

package/catalog.json

@@ -228,7 +228,7 @@
     },
     {
       "name": "project-documentation",
-      "description": "Write project docs — README, contributing guides, API docs, changelogs, inline docs — and reconcile existing docs after a change made them wrong. Owns doc drift from the change in front of you; a repo-wide doc-rot audit belongs to technical-debt-review. Triggers: write a README, document this project, contributing guide, changelog, API docs, this needs docs, docstrings, do the docs still match, are the docs still accurate, doc sweep, stale docs, doc drift, I renamed X — what else needs updating.",
+      "description": "Write project docs — README, contributing guides, API docs, changelogs, inline docs — and reconcile existing docs after a change made them wrong. Owns doc drift from the change in front of you; a repo-wide doc-rot audit belongs to technical-debt-review; how the project is run (process, tracking, session routines) → working-agreement. Triggers: write a README, document this project, contributing guide, changelog, API docs, this needs docs, docstrings, do the docs still match, are the docs still accurate, doc sweep, stale docs, doc drift, I renamed X — what else needs updating.",
       "path": "project-documentation/SKILL.md"
     },
     {
@@ -251,6 +251,11 @@
       "description": "Cut and publish software releases right-sized to the project — semver decisions, changelogs, tagging, automated version bumps (release-please, changesets, semantic-release), publishing gates, npm/PyPI/container registry publishing, pre-release channels, monorepo versioning. Triggers: cut a release, release this, publish to npm, publish to PyPI, publish this package, version bump, what version should this be, semver, changelog, tag a release, release notes, GitHub release, prerelease, release automation, release PR. Deploy-time safety → deployment-checklist; commit/PR hygiene → git-workflow.",
       "path": "release-management/SKILL.md"
     },
+    {
+      "name": "research-methodology",
+      "description": "Run DS/ML research with defensible claims — framework and rigor, data understood before claims, method decision records, claims traced to evidence, sources verified. Production serving → ml-model-deployment. Triggers: research project, thesis, plan the research track, is this finding solid, can I claim this, why this method, literature review, verify these sources, deep research citations.",
+      "path": "research-methodology/SKILL.md"
+    },
     {
       "name": "resilience-engineering",
       "description": "Design systems that survive failure — failure-mode analysis, resilience patterns (timeouts, retries with backoff, circuit breakers, bulkheads, load shedding, graceful degradation), chaos experiments, disaster recovery with RTO/RPO, backup restore testing, game days. Triggers: chaos engineering, disaster recovery, DR plan, what if the database goes down, single point of failure, failover, circuit breaker, RTO, RPO, game day, high availability. An incident happening NOW → incident-response; undoing a bad deploy → rollback-strategy.",
@@ -326,6 +331,11 @@
       "description": "Evidence gate before any claim that work is done, fixed, passing, or deployed. Route here when a message declares the work finished or asks to commit, push, merge, ship, or close it out, including a brief sign-off, and before git-workflow or release-management act on it. Writing the commit message or PR text itself → git-workflow. Triggers: is it done, did it work, tests pass, verify, ready to commit, before I push, confirm the fix.",
       "path": "verification-before-completion/SKILL.md"
     },
+    {
+      "name": "working-agreement",
+      "description": "Define and validate how a multi-session project is run — where plans, status and decisions live, session routines, new work, milestone close. README/CONTRIBUTING → project-documentation. Triggers: where is progress tracked, how do we track this, is this milestone done, how is this project run, document our process, working agreement, definition of done, plans and status out of sync.",
+      "path": "working-agreement/SKILL.md"
+    },
     {
       "name": "writing-skills",
       "description": "Use when authoring, editing, or reviewing a skill in this library — a new SKILL.md, one that under-triggers, or hardening an existing one. Covers description and listing-budget rules, frontmatter, progressive disclosure, the 3-eval rule, and pressure-testing against rationalizations. Triggers: write a skill, new skill, edit a skill, skill isn't triggering.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {

package/roles.json

@@ -97,6 +97,7 @@
       "core": "technical",
       "skills": [
         "ml-pipeline-design",
+        "research-methodology",
         "ml-experiment-tracking",
         "ml-model-deployment",
         "ai-evaluation",
@@ -135,6 +136,7 @@
       "core": "technical",
       "skills": [
         "exploratory-data-analysis",
+        "research-methodology",
         "statistical-analysis",
         "notebook-to-production",
         "ml-experiment-tracking",
@@ -171,6 +173,7 @@
         "dependency-impact-analysis",
         "technical-debt-review",
         "project-review",
+        "working-agreement",
         "configuration-strategy",
         "performance-optimization"
       ]
@@ -187,6 +190,7 @@
         "project-proposal",
         "prd-writing",
         "project-review",
+        "working-agreement",
         "strategic-review",
         "code-reviewing",
         "incident-response",
@@ -201,6 +205,7 @@
       "skills": [
         "project-proposal",
         "prd-writing",
+        "working-agreement",
         "effort-estimation",
         "metrics-and-okrs",
         "retrospective",

package/skills/exploratory-data-analysis/SKILL.md

@@ -21,6 +21,12 @@ customer? a customer-month?)? Duplicate keys and mixed grains invalidate every
 later statistic. If the eventual use is prediction, note *when* the prediction
 would be made — that timestamp drives the leakage checks in step 5.
 
+Also establish **which source is authoritative**: the curated table rather than
+the raw inputs it was built from (trace how it's produced — `code-archaeology` —
+when that isn't documented), and which fields are validated measurements versus
+informational ones (estimates, free text, fields only some forms collected).
+Profiling the wrong table produces a confident description of the wrong data.
+
 ### 2. Profile structurally
 
 Column types, ranges, cardinality, and summary statistics for every column —

package/skills/feature-planning/SKILL.md

@@ -91,6 +91,8 @@ For each risk, suggest a mitigation strategy or a spike task to reduce uncertain
 
 Output the complete plan using the template at [templates/plan.md](templates/plan.md) — in the reply itself, not as a promise to produce one. Offer to save it as a markdown file in the project (e.g., `docs/plans/feature-name.md`); saving is a convenience, not the deliverable.
 
+If the plan spans several sessions or milestones, fill its **Tracking** field from the project's working agreement (where task status will live). When the project has none, say so and hand off to `working-agreement` so status has a home before execution starts.
+
 ## Principles Applied
 
 - **YAGNI**: Only plan what's needed now. Flag nice-to-haves separately.

package/skills/feature-planning/templates/plan.md

@@ -6,6 +6,7 @@
 **Date**: [YYYY-MM-DD]
 **Author**: [Name]
 **Status**: Draft | In Review | Approved
+**Tracking**: [where task status lives, per the working agreement — e.g. tracker milestone link, the status column below, or none]
 
 ## Summary
 [2-3 sentences: what this feature does and why it matters]

package/skills/plan-execution/SKILL.md

@@ -43,6 +43,13 @@ checkpoint, write down **before starting it**:
 A checkpoint whose verification you can't name isn't a checkpoint — split or
 rescope it until it has one.
 
+Read the project's **working agreement** too (linked from CLAUDE.md or the
+README): it says where task status is recorded, what evidence closes a task, and
+what a session records when it ends. Steps 3 and 6 follow it. When the plan spans
+sessions and no agreement exists, invoke `working-agreement` — it drafts one under
+stated assumptions in the same response, so execution isn't held up — because
+progress recorded only in this session is invisible to the next one.
+
 ### Step 2: Execute a Batch, Logging Drift As You Go
 
 Work the checkpoint's tasks. Any deviation from the plan — a different approach,
@@ -50,12 +57,16 @@ an extra task, a skipped step, a surprise — goes into a **drift log** the mome
 it happens, even when the deviation is an improvement. Undocumented "better
 ideas" are how a plan dies without anyone deciding to kill it.
 
+When a task needs a human — a review, an approval, field data — first do every
+part you can do yourself, then hand over a runbook: what is needed, where the
+data is, what to run, what to look for, and what to send back.
+
 ### Step 3: Verify the Checkpoint
 
 Run the verification you declared in Step 1 — fresh, in full, reading the entire
 output (see `verification-before-completion` for the gate function). Only then
 mark the checkpoint done, recording the evidence next to it: the command and its
-observed result. A failed verification means the checkpoint stays open — fix and
+observed result — in the place the working agreement names for status. A failed verification means the checkpoint stays open — fix and
 re-verify; two consecutive failed checkpoints are a re-planning trigger, not a
 push-through-it signal.
 
@@ -147,6 +158,8 @@ in checkpoint 5, and each looked locally complete while the README fell behind
 both. Take the identifiers the plan touched end to end, grep the docs for them,
 and reconcile what they name. The plan's own artifacts count: a checkpoint list
 that still describes the pre-drift design is a stale document like any other.
+So does the status record: close the plan where the working agreement says —
+items closed or moved on with a reason, the plan's header marked closed.
 
 ## Rationalizations to Reject
 
@@ -182,6 +195,7 @@ that still describes the pre-drift design is a stale document like any other.
 ## Cross-Skill References
 
 - `feature-planning` — creates and (on re-plan) revises the plan this skill executes
+- `working-agreement` — where status is recorded and how sessions start, end and close a plan; invoked at Step 1 when the plan spans sessions and none exists
 - `data-modeling` — where a schema question surfaced mid-execution belongs
 - `architecture-design` — where a structural or boundary question belongs
 - `verification-before-completion` — the per-claim evidence gate each checkpoint applies, and the publish gate on every checkpoint commit

package/skills/plan-execution/evals/evals.json

@@ -10,7 +10,8 @@
         "Defines checkpoints with a concrete, named verification (command or observation) for each, declared before executing that batch",
         "Marks a checkpoint done only after running its verification fresh and recording the evidence (command and observed result)",
         "Tracks deviations from the plan in a drift log or equivalent explicit record",
-        "States the per-checkpoint reporting rule it will follow — each checkpoint reported as verified-done with its recorded evidence, or explicitly not done — and rules out vague 'mostly done' states"
+        "States the per-checkpoint reporting rule it will follow — each checkpoint reported as verified-done with its recorded evidence, or explicitly not done — and rules out vague 'mostly done' states",
+        "States where checkpoint status and evidence will be recorded so a later session can find them (per the project's working agreement, or by establishing one when none exists), rather than leaving progress only in the conversation"
       ]
     },
     {

package/skills/project-documentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-documentation
-description: "Write project docs — README, contributing guides, API docs, changelogs, inline docs — and reconcile existing docs after a change made them wrong. Owns doc drift from the change in front of you; a repo-wide doc-rot audit belongs to technical-debt-review."
+description: "Write project docs — README, contributing guides, API docs, changelogs, inline docs — and reconcile existing docs after a change made them wrong. Owns doc drift from the change in front of you; a repo-wide doc-rot audit belongs to technical-debt-review; how the project is run (process, tracking, session routines) → working-agreement."
 when_to_use: "Triggers: write a README, document this project, contributing guide, changelog, API docs, this needs docs, docstrings, do the docs still match, are the docs still accurate, doc sweep, stale docs, doc drift, I renamed X — what else needs updating."
 ---
 
@@ -230,3 +230,4 @@ For code-level documentation (JSDoc, Python docstrings, Go doc comments):
 - `architecture-documentation` — C4 diagrams and docs-as-code for the architecture docs this skill points at
 - `verification-before-completion` — the doc-drift and publish gates that read the versioned/internal boundary above
 - `technical-debt-review` — a repo-wide doc-rot audit, as opposed to the drift from the change in front of you
+- `working-agreement` — owns the process document (where things live, session routines, tracking) and its validation; this skill writes the README and CONTRIBUTING text that link to it, and a sync sweep includes it when a change alters how the project is run

package/skills/project-review/SKILL.md

@@ -35,6 +35,9 @@ Read the project's own statements of intent before judging anything:
   phase does it say it's in, and what does it promise for the milestone in question?
 - **The hard boundaries** — declared scope and explicit non-goals. These are what
   you measure scope drift against.
+- **The working agreement** — where the project says status lives and how
+  milestones close. If "what's done" can't be answered from where it says, or
+  there is no agreement, that is a finding: re-validate it with `working-agreement`.
 
 Capture this as the baseline. Everything downstream is "reality vs this baseline."
 

package/skills/research-methodology/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: research-methodology
+description: "Run DS/ML research with defensible claims — framework and rigor, data understood before claims, method decision records, claims traced to evidence, sources verified. Production serving → ml-model-deployment."
+when_to_use: "Triggers: research project, thesis, plan the research track, is this finding solid, can I claim this, why this method, literature review, verify these sources, deep research citations."
+---
+
+# Research Methodology
+
+Research differs from feature work in one way that changes everything: the
+output is a **claim**, and a claim is only as good as the trail behind it. The
+data was understood, the method was chosen for stated reasons, the experiment
+was defined before its result, the number traces to the code and data that
+produced it, and the sources say what they're cited for.
+
+This skill does not impose a structure. The user picks the framework and how
+much rigour the work needs. What it holds fixed are the four rules below,
+because each one, skipped, has produced a claim that had to be withdrawn.
+
+## ⛔ The Iron Law
+
+**No claim leaves the project — into a thesis, a report, a decision — without
+its trail: the data behind it understood, the method behind it decided on the
+record, the number traced to what produced it, the sources resolved.**
+
+A striking result is the one that most needs the trail. "We'll add it in the
+next revision" is how an unchecked claim survives into the final text.
+
+## Workflow
+
+### Step 1: Agree the Framework and the Rigor
+
+Check the project's working agreement for a Methodology section. If there is
+none, offer options with a recommendation — don't impose one:
+
+- **CRISP-DM** (the default recommendation): business understanding → data
+  understanding → data preparation → modeling → evaluation → deployment, iterated.
+  Its data-understanding phase before modeling is the step research most often skips.
+- **TDSP** (Microsoft's Team Data Science Process): similar loop, adds roles and
+  standard documents; fits a team with a client.
+- **The user's own**, written down in a few lines.
+
+And the **rigour level**: thesis or publication grade (every claim registered,
+sources resolved to their identity), or internal and exploratory (claims marked
+provisional, lighter citation). The user sets it; record it.
+
+Write the choice into the working agreement's Methodology section (create the
+agreement via `working-agreement` if the project has none), along with where
+experiments, method decisions and claims live — see
+[templates/traceability.md](templates/traceability.md).
+
+**This step is not a gate on delivering.** Plan under the recommended framework
+and state it — *"Planned under CRISP-DM at `<rigour>`; say if you'd rather use
+another"* — then carry the plan in the same response.
+
+### Step 2: Understand the Data Before Any Claim
+
+**Invoke `exploratory-data-analysis`** before any result is interpreted, and
+plan it as the first item of the track, not an afterthought. Running a benchmark
+early to smoke-test the pipeline is fine; reading meaning into its numbers before
+this step is not. For research it must cover:
+
+- **Which source is authoritative** — the curated table, not the raw one it was
+  built from. Read how it is produced (`code-archaeology` for the pipeline).
+- **How reliable each field is** — validated measurement, or informational
+  (an estimate, a free-text note, a field only some forms collected).
+- **The distribution of every variable a claim will be split by.** A gap between
+  two groups means little if one group has 30 members.
+- **What the reference data covers and doesn't.** A survey that lists some
+  households in some places makes every detection elsewhere look like a false
+  positive: precision against it is a lower bound for the surveyed area, not a
+  property of the method.
+
+### Step 3: Decide Methods on the Record
+
+Every choice that shapes a result — algorithm, matching rule, threshold, metric,
+validation design — gets a **method decision record**
+([templates/method-decision-record.md](templates/method-decision-record.md)):
+the candidates, the evidence for each, the criteria, the decision, and the
+alternatives worth trying later. "DBSCAN is standard" is a reason to list it, not
+to choose it.
+
+Include **instrument validity**: was the tool, model or product built and
+evaluated for the variable you're about to report on? A building detector says
+nothing reliable about roof material unless someone measured that. If it wasn't,
+a result about that variable describes the instrument, not the world.
+
+### Step 4: Define Each Experiment Before Its Result
+
+Before running: hypotheses, primary metric, operating point, decision rule, and
+which method decisions it rests on. Log and compare runs per
+`ml-experiment-tracking`; choose tests, intervals and multiple-comparison
+handling per `statistical-analysis`. A change after results exist is an
+**amendment**: label it as one, with the reason.
+
+### Step 5: Trace Every Claim
+
+Each number that may be quoted goes in a claims register
+([templates/claims-register.md](templates/claims-register.md)): the claim in
+words, its scope (area, population, product, period), the experiment, the
+commit and data version that produced it, and its status — provisional,
+supported or withdrawn.
+
+Write findings at the strength the evidence has:
+- **Measured** — "recall was 0.41 (n = …, 95% CI …) for straw-and-mud roofs
+  against 0.78 for chapa, in the surveyed area": state it.
+- **Explained or generalized** — "the product under-detects traditional roofs":
+  only after Step 2's distributions, Step 3's instrument check and the
+  confounders are done. Until then it is a provisional observation, worded as one.
+
+Under deadline, write the supported part now and mark the rest provisional. The
+minimal check a striking subgroup claim needs (group counts, per-group metric
+with intervals, one confounder cross-tab) is usually an hour, not a revision.
+
+### Step 6: Verify Sources
+
+Every source that carries a claim passes the identity rule in
+[references/source-verification.md](references/source-verification.md): it
+resolves to a DOI, arXiv ID, ISBN with chapter, standard, or versioned page, and
+the quoted text is in a captured copy, not a search summary. Run this as an
+audit over any deep-research report before its citations are reused. Scale it
+to the rigour set in Step 1, and apply the same test to tools: a library or
+product the method depends on must be maintained and widely used, checked per
+`dependency-management`.
+
+## Rationalizations to Reject
+
+| Excuse | Reality |
+|--------|---------|
+| "The result is striking; the EDA can come later" | Striking subgroup results are the likeliest to be small-n noise or skewed labels. The check is small; the retraction isn't. |
+| "We'll add the data description in the next revision" | The claim gets written now and survives into the final text. Write it at the strength the data supports today. |
+| "DBSCAN / U-Net / X is the standard method" | Standard is a reason to list it as a candidate. Record what else was considered and why it lost. |
+| "The product is state of the art" | For what task? A detector evaluated on building presence hasn't been evaluated on roof material. |
+| "Low precision means the method is poor" | Against an incomplete reference, unmatched detections include real objects nobody surveyed. Bound it to the surveyed area. |
+| "The deep-research report already has citations" | Its citations are claims about sources. Resolve each one before reusing it. |
+| "We need the 1977 original for every citation" | Not for established results: a trusted later work that states them is enough. Chase the original when the claim is contested or load-bearing. |
+
+## Red Flags — Stop and Check
+
+- A results section exists and no EDA of the labels does.
+- A method appears in code with no record of why it was chosen.
+- A claim is stratified by a variable whose group sizes nobody has looked at.
+- An experiment's decision rule was written after its result.
+- A number in the draft can't be traced to a commit and data version.
+- A citation points at a blog, a summary page, or a search snippet.
+
+## Cross-Skill References
+
+- **`exploratory-data-analysis` — invoke it in Step 2, before the first result
+  is interpreted.** This skill still decides which claims wait on it; EDA does
+  the profiling.
+- `statistical-analysis` — tests, intervals, power and multiple comparisons for
+  each experiment.
+- `ml-experiment-tracking` — logging, comparing and reproducing runs.
+- `working-agreement` — holds the Methodology section and the rest of how the
+  project runs (where status lives, session routines).
+- `plan-execution` — works through the research plan checkpoint by checkpoint.
+- `code-archaeology` — traces how a curated dataset is produced from raw inputs.
+- `notebook-to-production` and `ml-pipeline-design` — when exploratory code
+  becomes a pipeline others rely on.
+- Out of scope: serving a model in production → `ml-model-deployment`.

package/skills/research-methodology/evals/evals.json

@@ -0,0 +1,58 @@
+{
+  "skill_name": "research-methodology",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Research project for a master's thesis and an NGO: detect rural households in the Argentine Gran Chaco from free satellite imagery and public building-footprint products (Google Open Buildings, Microsoft, Overture), and validate against the NGO's household survey (about 1,800 households with GPS points, roof material and household size). The repo has a methodology doc, a roadmap with phases A-D, a uv/DVC/MLflow setup and the survey snapshot. Plan the next track: our first experiment benchmarks the existing footprint products against the survey points, clustering footprints into homesteads with DBSCAN, and we also want to say which roof materials the products miss.",
+      "expected_output": "Plans the track as research, not as a software feature. Puts understanding the survey data first (an EDA step: distribution of roof material and household size, GPS quality, coverage of the surveyed area, which table is curated) before the benchmark is run or any claim about roof materials is made. Records the method choice (DBSCAN for homestead clustering) as a decision with candidates, reasons and alternatives to try, rather than taking it as given. Pre-registers the experiment's hypotheses, metric and decision rule before results exist. Shows how a later reader traces roadmap phase -> task -> experiment -> code -> result -> claim. Offers a process framework (e.g. CRISP-DM) and asks how much rigour the thesis needs, rather than imposing a rigid structure.",
+      "assertions": [
+        "Puts an exploratory data analysis of the survey labels (e.g. roof material distribution, household size, GPS quality, survey coverage) before the benchmark results are interpreted or any claim about roof materials is made",
+        "Treats the choice of DBSCAN as a method decision to record, with at least one alternative and the reason for choosing it, rather than taking it as given",
+        "Pre-registers the experiment: hypotheses, metric and decision rule written before results exist",
+        "Shows how a reader traces the work from the roadmap phase to the task, the experiment, the code and the resulting claim",
+        "Offers or names a process framework (e.g. CRISP-DM or TDSP) or asks which one to follow, rather than imposing a fixed structure",
+        "Questions whether footprint-detection products can support a roof-material claim at all, given they are built to detect buildings rather than classify roofs"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Experiment A01 is done. Google Open Buildings found 62% of surveyed households overall but only 41% of households with straw-and-mud roofs, versus 78% for corrugated-metal (chapa) roofs. Precision was low, 0.38. Write the findings paragraph for the thesis chapter: the products under-detect traditional roofs, and precision is poor.",
+      "expected_output": "Does not write the two findings as established claims yet. Asks or checks what the claims rest on: how roof materials are distributed in the survey (if most roofs are chapa, the straw-and-mud stratum may be small, with wide intervals), whether the detector was ever built or evaluated for roof material, and confounders such as campaign, region or GPS error that correlate with roof type. For precision, notes that the survey covers only surveyed households and areas, so detections outside that coverage are not necessarily false positives, which makes 0.38 a lower bound for the surveyed area, not a property of the product. Offers a provisional wording that states what was measured, with its limits, and lists the checks (EDA, stratum sizes and intervals, instrument validity) that would make it a thesis claim.",
+      "assertions": [
+        "Does not state 'the products under-detect traditional roofs' as an established finding without first checking the roof-material distribution and stratum sizes in the survey data",
+        "Raises whether the detector was built or evaluated for roof material, i.e. whether the instrument is valid for this variable",
+        "Raises at least one confounder that could explain the roof-type gap (e.g. campaign, region, settlement density, GPS error)",
+        "Points out that precision measured against a survey that does not cover every building in the area treats unsurveyed buildings as false positives, so 0.38 is a lower bound tied to the surveyed area",
+        "Offers wording that reports what was measured with its limits, or lists the checks needed before the claim can go into the thesis"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Our churn model is trained and validated. Help me deploy it as a real-time scoring endpoint behind our API, with monitoring for drift and a safe rollout.",
+      "expected_output": "Recognizes this as production model deployment, which belongs to ml-model-deployment, not research methodology. Hands off to or works under ml-model-deployment. Does not start a research-framework, method-decision-record or claims-register process for a deployment task.",
+      "assertions": [
+        "Recognizes the request as deploying a model to production (ml-model-deployment's domain), not as research methodology",
+        "Refers to or proceeds under ml-model-deployment for serving, drift monitoring and rollout",
+        "Does not impose research artefacts such as a method decision record, a claims register or a research framework on this request"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "The thesis draft is due to my director on Friday. The benchmark results are in and they look clear: recall 0.62 overall, and the roof finding is striking. There's no time for an EDA now. Just write the results section with the claims; we'll add the data description in the next revision.",
+      "pressure": [
+        "time",
+        "sunk_cost",
+        "authority"
+      ],
+      "expected_behavior": "Does not write unsupported claims into the thesis. Separates what can be stated now (the measured recall in the surveyed area, with its definition and scope) from what cannot (the roof-material finding) until the label distribution and stratum sizes are known. Points out that the minimal EDA needed for the roof claim (a cross-tab of roof class counts and recall by stratum with intervals) is small and fits before Friday. Offers the results section with the supported claim written and the roof finding marked provisional or moved to an exploratory note.",
+      "assertions": [
+        "Does not write the roof-material finding as an established claim in the results section",
+        "Writes or offers the supported part (the measured recall with its scope and definition) so the deadline is still served",
+        "Names the minimal data check the roof claim needs (e.g. roof-class counts and recall per stratum with intervals) and says it fits before the deadline",
+        "Rejects 'add the data description in the next revision' because a claim drafted without the data check tends to survive into the final text"
+      ]
+    }
+  ]
+}

package/skills/research-methodology/references/source-verification.md

@@ -0,0 +1,71 @@
+# Source Verification
+
+Adapted from article-craft's `references/source-verification.md`
+(swestash/article-craft), cut down for research projects.
+
+The rule: **cite only what you opened.**
+
+## Trust tiers
+
+- **Tier 1 — cite freely:** peer-reviewed papers and proceedings, standards,
+  canonical books cited to chapter or section, primary documentation with a
+  stated version or date (dataset cards, product technical reports, API docs).
+- **Tier 2 — cite with attribution:** vendor engineering blogs and release notes
+  (primary for the vendor's own product, marketing-adjacent for comparisons);
+  public repositories, for what the code actually does; preprints, flagged as
+  preprints.
+- **Tier 3 — use to find, never to cite:** community blogs, aggregators, SEO
+  pages, forum answers, model-generated summaries (including search snippets and
+  WebFetch output). A fact found only in Tier 3 is not established.
+
+## The identity rule
+
+Every claim that carries weight must end at something with an identity: a DOI,
+an arXiv ID, an ISBN with chapter or page, a standard's designation, a versioned
+documentation URL, a dated release note, a commit SHA. Anything that cannot
+resolve to an identity is Tier 3, whatever it looks like.
+
+This catches the two common failures without having to judge pages:
+- **Citogenesis** — a page repeats a claim and gets cited as if it made it.
+  Follow it to the work that established it.
+- **Fabricated references** — "Smith et al. 2019" that doesn't exist fails the
+  moment you try to resolve it.
+
+## Capture, then quote
+
+A search snippet or WebFetch result is a summary written by a model, not the
+source. Use it to decide what to open. Then capture the page or PDF to a file
+(with its URL, fetch date and any version it states), read it, and quote from
+the file. A quote should be findable in the captured copy.
+
+For two-column PDFs, extract in reading order, or quotes will be interleaved
+across columns.
+
+## Proportionality
+
+Scale the checking to the claim and the rigour level the project agreed:
+
+- **Established results** don't need the original: a 1977 textbook result
+  restated in a trusted recent work can be cited through that work. Chase the
+  original when the claim is contested, load-bearing for your argument, or the
+  later works disagree.
+- **Single studies are evidence, not consensus.** When a key claim rests on one
+  paper, check whether later work adopted it, and say so in the text.
+- **Independent corroboration only:** sources that trace to one origin count as one.
+- **Paywalled or unreachable sources:** list them as gaps with what each would
+  support. Ask the user for a copy, or cite through a reachable work that
+  reports it. Don't cite from the abstract alone as if from the paper.
+
+## Auditing a deep-research report
+
+Before reusing a report's citations:
+1. List each cited claim and the source it points to.
+2. Resolve each source's identity and tier. Tier 3 → find the primary or drop the claim.
+3. Spot-check quotes against captured copies, starting with the claims the
+   project's argument depends on.
+4. Record what was verified, what is a preprint, and what remains a gap.
+
+## When verification fails
+
+Cut the claim, or narrow it to what the evidence supports. A weaker claim that
+holds is worth more than a strong one that doesn't.

package/skills/research-methodology/templates/claims-register.md

@@ -0,0 +1,19 @@
+# Claims Register Template
+
+Every number or finding that may be quoted outside the project (thesis, report,
+funding request) gets a row. Save as `docs/claims.md`.
+
+```markdown
+# Claims
+
+A claim may be quoted only at its status. Provisional claims are quoted with
+their caveat or not at all.
+
+| ID | Claim, in words | Scope (area, population, product, period) | Evidence (experiment, commit, data version) | Checks done | Status |
+|---|---|---|---|---|---|
+| C-001 | [e.g. "Open Buildings matched 62% of surveyed households (95% CI …)"] | [surveyed parajes, department X, survey 2019–2023] | [A01, abc1234, data v3] | [EDA AE01; n per group; CI method] | Supported |
+| C-002 | [e.g. "Detection is lower for straw-and-mud roofs"] | | | [missing: roof-class counts, instrument validity, confounders] | Provisional |
+
+Status values: **Provisional** (measured, checks incomplete) · **Supported**
+(checks done) · **Withdrawn** (with the reason and date).
+```

package/skills/research-methodology/templates/method-decision-record.md

@@ -0,0 +1,41 @@
+# Method Decision Record Template
+
+One per method choice that shapes a result. Like an ADR, but the evidence is
+data and literature rather than system constraints. Save as
+`docs/methods/MDR-NNNN-<topic>.md`.
+
+```markdown
+# MDR-NNNN: [the question, e.g. "How to group building footprints into homesteads"]
+
+**Status:** Proposed | Accepted | Superseded by MDR-NNNN
+**Date:** YYYY-MM-DD
+**Used by:** [phase / work package / experiments]
+
+## Question
+[What has to be decided, and which results depend on it.]
+
+## Candidates
+| Candidate | How it works (one line) | Evidence for | Evidence against | Sources |
+|---|---|---|---|---|
+| [e.g. DBSCAN] | | | | [DOI / arXiv] |
+| [e.g. single-linkage with distance cut] | | | | |
+| [e.g. alpha shapes per cluster] | | | | |
+
+## Instrument validity
+[Was each candidate (or the product/model it relies on) built and evaluated for
+this variable and this setting? If not, what does that limit?]
+
+## Criteria
+[How candidates are compared: accuracy on what, cost, interpretability,
+parameter sensitivity. Set before comparing.]
+
+## Decision
+[The choice and the reason, in a few sentences. Parameters and how they were set.]
+
+## Alternatives to try later
+[Candidates not chosen that would be worth testing if the result is weak, with
+what would trigger trying them.]
+
+## Consequences
+[What this decision commits the project to; which claims inherit its limits.]
+```

package/skills/research-methodology/templates/traceability.md

@@ -0,0 +1,50 @@
+# Traceability Template
+
+The chain a reader follows from "why are we doing this" to "which code produced
+this number", and back. Add it to the working agreement's Methodology section, or
+as `docs/research-workflow.md` linked from there. Rename the paths to the project's.
+
+```markdown
+## The chain
+
+methodology            WHY + WHAT: framework, phases, gates between phases
+      │
+roadmap                WHEN: phases and milestones, the gate each one must pass
+      │
+phase plan             TASKS: work packages → acceptance, experiment, status
+      │                (status lives where the working agreement says)
+method decisions       WHY THIS METHOD: candidates, evidence, decision, alternatives
+      │
+experiment README      ONE QUESTION: hypotheses and decision rule written before
+      │                the run; results; decision; claims produced; how to reproduce
+      ├── notebook       where we look and explain: plots, tables, interpretation
+      └── src module     tested code for anything reused or reported
+              │
+          pipeline config + lock   what exactly ran: data hashes, code, parameters
+              │
+          metrics / reports        results (aggregates only if the data is sensitive)
+              │
+claims register        numbers we may quote, each linked to its experiment and status
+
+## Which file answers what
+
+| Question | Open |
+|---|---|
+| Why this approach, what are the phases? | methodology |
+| Which phase are we in, what's next? | roadmap → phase plan |
+| Why this method, what else could we try? | method decisions |
+| What did we look at in the data? | the EDA experiment and its notebook |
+| What was tested, found and decided? | the experiment README |
+| How do I re-run it? | the experiment README's Reproduce section |
+| Can I quote this number? | claims register |
+| Where does this dataset come from, under what licence? | the data inventory / source registry |
+
+## Notebooks and code
+
+- **Notebooks** are where we look and explain. They read pipeline outputs and
+  import from the package. Commit them in a diff-friendly form (e.g. jupytext).
+- **The package** holds anything reused or reported, with tests. When a notebook
+  cell becomes something we rely on, it moves into a module.
+- **The pipeline** runs both, so a rendered notebook always matches the data and
+  code it was produced from.
+```

package/skills/skill-router/SKILL.md

@@ -94,6 +94,7 @@ installed skill by name, regardless of role.
 ### Plan & Define
 - **brainstorming** — divergent Socratic ideation *before* a spec exists; opens options, then hands off
 - **feature-planning** — break a feature into scoped tasks, acceptance criteria, dependencies
+- **working-agreement** — define and validate how a multi-session project is run: where status lives, session routines, new work, milestone close
 - **build-vs-buy** — build in-house vs vendor/SaaS vs adopt OSS: TCO, lock-in, exit costs
 - **prd-writing** — write a PRD / RFC / tech spec to align on the WHAT and WHY
 - **project-proposal** — business case / budget / go-no-go before a project starts
@@ -175,6 +176,7 @@ installed skill by name, regardless of role.
 - **data-quality** — dbt tests, expectations, data contracts, freshness, lineage / blast radius
 
 ### Data Science
+- **research-methodology** — research with defensible claims: framework and rigor, data understood first, method decisions, claims traced, sources verified
 - **exploratory-data-analysis** — profile an unfamiliar dataset: missingness structure, distributions, leakage, hypotheses
 - **statistical-analysis** — hypothesis tests, experiment design/power, confidence intervals, multiple-comparison discipline
 - **notebook-to-production** — refactor analysis notebooks to tested, parameterized, scheduled production code
@@ -200,6 +202,13 @@ leads instead, and `feature-planning` then scopes the work that the chosen optio
 implies. Planning tasks against an unmade decision produces a plan you throw away.
 Either way both skills are in the chain; what changes is which one runs first.
 
+**New project / multi-session work**
+`prd-writing` or `feature-planning` (the first plan that spans sessions) →
+`working-agreement` (how the project is run, validated by a fresh reader) →
+`plan-execution` (records status where the agreement says). In a project that
+already runs without one — nobody can say what's done — `working-agreement`
+leads, reconstructing the current process first.
+
 **Bug / incident**
 `incident-response` (if prod is down) → `bug-investigating` → `tdd-workflow`
 (regression test) → `verification-before-completion` (the repro now passes, and
@@ -231,6 +240,13 @@ Notebook to production: `exploratory-data-analysis` (understand the data) →
 (modules, tests, scheduling); if the notebook trains a model →
 `ml-pipeline-design` instead.
 
+**Research / data-science project**
+`research-methodology` leads: it agrees the framework (CRISP-DM by default, or
+the user's own) and the rigor, and the framework's phases set the order — not a
+fixed chain. What holds under any framework: `exploratory-data-analysis` before
+any result is interpreted, `statistical-analysis` and `ml-experiment-tracking`
+per experiment, `plan-execution` for the work itself.
+
 **Pre-public / pre-milestone review**
 `strategic-review` (vision, positioning, market) → `project-review` (scope,
 roadmap, implementation, evidence) → synthesis → `artifact-design` (interactive

package/skills/working-agreement/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: working-agreement
+description: "Define and validate how a multi-session project is run — where plans, status and decisions live, session routines, new work, milestone close. README/CONTRIBUTING → project-documentation."
+when_to_use: "Triggers: where is progress tracked, how do we track this, is this milestone done, how is this project run, document our process, working agreement, definition of done, plans and status out of sync."
+---
+
+# Working Agreement
+
+A working agreement says how a project runs, so that humans and agents read
+and write the same places: where the plan lives, where status lives, what a
+session does when it starts and ends, how new work gets in, how a milestone
+closes. This skill does not choose the process for the user. It makes sure one
+is chosen, written down where every later session finds it, and **checked by
+someone who did not write it**.
+
+Without one, each session improvises: progress lands in a handoff nobody
+commits, a report doubles as a tracker once, and work starts on a milestone
+that has no plan. Nobody decides to drift; there was nothing to drift from.
+
+## ⛔ The Iron Law
+
+**An agreement is not in force until a fresh reader can answer every core
+scenario from the documents alone.**
+
+The author cannot test it: the author fills every gap from memory without
+noticing. The content of the agreement is the user's choice; the validation is
+not optional.
+
+## Workflow
+
+### Step 1: Find the Agreement, Then Pick the Mode
+
+Look for an agreement on record: a pointer in CLAUDE.md, the README or
+CONTRIBUTING; a `docs/how-we-work.md` or similar; tracker conventions.
+
+- **Found** → read it and follow it. Re-validate (Step 5) only when a trigger
+  fires: a milestone closes, the process changed, or someone asked a question
+  the agreement should have answered.
+- **Not found, small work** (one session, one person, nothing to hand over) →
+  skip this skill; say so in one line.
+- **Not found, large work** (spans sessions or milestones, or several people or
+  agents) → pick the mode:
+  - **Define (greenfield)** — nothing practiced yet. Go to Step 2.
+  - **Discover (brownfield)** — practice exists: plans, reports, issues, git
+    log, handoffs. First write the **as-is** from that evidence: where each kind
+    of fact lives today, and where it cannot be found. Name each gap concretely
+    ("the plan has no per-task status; the report was written once at close;
+    progress lives in gitignored handoffs"). That list is what Step 3 fixes.
+    Answer the user's immediate question (is M0 done?) from the same evidence,
+    or say exactly what would have to be checked.
+
+**Exit condition** — one line, then keep going in the same response:
+*"No agreement on record; `<define | discover>`: `<one-line state of practice>`."*
+
+**This step is not a gate on delivering.** When you can't read the repo, state
+what you assume exists and continue. Carry the options, the draft agreement and
+the validation in the same response; questions go next to the draft, not in
+place of it.
+
+### Step 2: Offer Options and Recommend One
+
+Two decisions, each offered as options with a recommendation fitted to the
+project — see [references/options.md](references/options.md):
+
+1. **Process shape** — milestone plans, Kanban, Scrum, or for research work a
+   methodology framework (hand that section to `research-methodology`).
+2. **Where status lives** — an external tracker (GitHub/GitLab issues, Jira,
+   Linear) when one exists or can be connected; a status column in each plan
+   when there is no tool; or no tracking for short single-person work. A planned
+   switch ("markdown until the GitLab remote exists") is a valid choice: record
+   the trigger for the switch.
+
+Don't make the draft wait on the answer: draft under the recommendation and say
+*"Drafted under `<choice>` — pick another and I'll revise."*
+
+### Step 3: Write the Agreement
+
+Use [templates/agreement.md](templates/agreement.md). Every agreement covers:
+
+- **Where things live** — one owner per kind of fact (scope, plan, task status,
+  decisions, results, session context), with when each changes. Other places
+  link to the owner; they never copy it.
+- **Starting a session** — where to read what to do next, and in what order.
+- **During the work** — where decisions, drift and new findings go.
+- **Ending a session** — where progress and evidence are recorded, what a
+  handoff may and may not contain.
+- **New work** — how a new milestone, an added task, a bug and an open question
+  each enter.
+- **Definition of Done** — what evidence closes a task.
+- **Closing a milestone** — what is checked, what is written, what moves on.
+- **Asking a human** — requests for human work come as runbooks: what is needed,
+  where the data is, what to run, what to look for, what to send back.
+
+Rules that keep it honest:
+
+- **Status lives in one place.** A plan or report that also carries status is a
+  second copy, and the second copy goes stale.
+- **Handoffs are context, not status.** Nobody should need a handoff to know
+  what is done.
+- **Versioned documents only use terms a reader can resolve** — no labels from a
+  gitignored plan or a chat.
+- **Right-size it.** One page for a two-person project is enough.
+
+### Step 4: Prove the Tracker Connection
+
+If status lives in an external tool, prove the agent can **read and write** it
+before the agreement depends on it: list the open items, and create, update or
+comment on one. A tool that is configured but not loaded in this session is not
+connected. If it can't be proven now, the agreement names the fallback (a CLI,
+or the human updates the tracker from a list the agent writes) and the fallback
+is what's in force.
+
+### Step 5: Validate With a Fresh Reader
+
+Walk the scenario bank in [references/validation.md](references/validation.md)
+against the written agreement, **in the same response as the draft**. Don't
+promise the check for after the user answers your questions: the gaps it finds
+are part of what they are answering.
+
+- **Preferred:** a subagent that sees only the repo's documents, not this
+  conversation, answers each scenario twice: as a new agent session and as a new
+  human contributor. Each answer must cite one file and section.
+- **Fallback** (no subagent available, or no repo yet): walk the scenarios
+  yourself, in the reply, and label it a self-check — weaker, because you wrote
+  it.
+- Add the coverage check for the chosen process shape and, when the project
+  already has docs, the conformance check: do they follow the agreement's own
+  rules (same reference)?
+
+Score each scenario: **answered in one place**, **ambiguous** (two places, or
+two readings), or **missing**. Every ambiguous or missing scenario becomes a
+question for the user or a fix to the draft. Repeat until the core scenarios
+are all answered in one place.
+
+**Exit condition:** *"Validated: `<n>/<n>` core scenarios answered from the
+documents. Open: `<questions>`."*
+
+### Step 6: Wire It In and Keep It Alive
+
+- Put a pointer in CLAUDE.md (agents read it every session) and the README
+  (humans): *"`docs/how-we-work.md` is the process; follow it."* Both the
+  agreement and the pointer must be **tracked** files: if CLAUDE.md is
+  gitignored, a collaborator's assistant never sees it — point from the README or
+  a committed AGENTS.md, and keep only personal state in untracked files.
+- **If the agreement and practice disagree, fix the agreement first**, in its
+  own commit, then act.
+- Re-validate at milestone close, after a retrospective changes the process,
+  during `project-review`, and whenever a question the agreement should answer
+  had to be asked.
+
+## Rationalizations to Reject
+
+| Excuse | Reality |
+|--------|---------|
+| "It looks complete; we'll fix gaps as we hit them" | A gap is hit by the person who needed the answer, at that moment, after the drift has started. Five scenarios take minutes now. |
+| "I wrote it, I can tell it's clear" | The author fills gaps from memory. That is why the reader must be fresh. |
+| "The plan already has a Status field" | A plan's lifecycle (Draft, Active, Closed) is not task status. Where does task 14's status live, and who updates it? |
+| "The handoff says what was done" | Handoffs are uncommitted and per-session. Status nobody else can see isn't status. |
+| "We use GitLab, so tracking is covered" | Choosing a tool isn't an agreement. Which facts live there, which in docs, who updates what, when? |
+| "The MCP server is configured" | Configured isn't connected. Prove one read and one write in this session. |
+| "This is project management overhead for a small project" | Then the agreement is one page. Skipping it is how a small project loses track of what's done. |
+
+## Red Flags — Stop and Check
+
+- A session starts work and can't name which plan item it advances.
+- The same task's status appears in two documents.
+- "Is X done?" can only be answered by reading git log or a handoff.
+- Work began on a milestone that has no plan.
+- The agreement names a tool that no session has written to.
+
+## Cross-Skill References
+
+- `plan-execution` — follows the agreement: reads it at Step 1, records status
+  where it says, closes out by its rules. When a plan spans sessions and no
+  agreement exists, it comes here first.
+- `feature-planning` and `prd-writing` — hand off here when the first plan or
+  PRD that spans sessions is written.
+- `research-methodology` — writes the agreement's Methodology section for
+  research and data-science projects.
+- `project-documentation` — writes the README and CONTRIBUTING text that link to
+  the agreement, and includes the agreement in its sync sweep. The agreement's
+  content and validation stay here.
+- `retrospective` — process changes agreed in a retro come back here as edits to
+  the agreement, followed by re-validation.
+- `project-review` — re-validates the agreement as part of an execution review.

package/skills/working-agreement/evals/evals.json

@@ -0,0 +1,60 @@
+{
+  "skill_name": "working-agreement",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We're starting a new open-source app for an NGO: offline survey collection on Android, a Python sync server and a web admin. The PRD is written (docs/product/prd-mvp.md) and the roadmap splits the work into milestones M0-M3 (docs/plans/roadmap.md). Two volunteers will build it over several months, mostly in sessions with Claude Code, with no fixed deadlines. There's no Git remote yet; we'll probably use GitLab later. Before we write the first milestone plan, set up how this project will be run so every later session, human or agent, knows what to do.",
+      "expected_output": "Treats this as defining the project's working agreement (greenfield). Offers recommended options rather than imposing one: a process shape (milestone plans, Kanban, Scrum) and a tracking choice (external tracker such as GitLab issues once the remote exists, a status table in each plan until then, or none), with a recommendation. Drafts the agreement itself in the same response: where each kind of fact lives with one owner per fact, what to do at session start, during and at session end, how new work enters, a Definition of Done, how a milestone closes, how decisions are recorded. Then validates the draft by walking concrete scenarios against it and lists the gaps or ambiguities as questions. Says the agreement gets a pointer from CLAUDE.md or the README so later sessions find it.",
+      "assertions": [
+        "Offers at least two options for how progress is tracked (e.g. an external tracker such as GitLab issues, a status table in the plan files, or no tracking), with a recommendation, rather than imposing a single scheme without asking",
+        "Drafts the agreement itself in the same response rather than only asking questions or promising to write it later",
+        "The draft states where each kind of information lives (plans, task status, decisions, results, session context), with one owner for each kind",
+        "The draft gives a routine for starting a session and for ending one: where to read what to do next, and where to record progress",
+        "The draft says how new or unplanned work is added and how a milestone is closed",
+        "Validates the draft by walking concrete scenarios against it (for example a new session starting, a task blocked on a human, a decision changing) and reports the gaps or ambiguities found as questions, rather than declaring the agreement complete",
+        "Says the agreement is linked from CLAUDE.md, the README or an equivalent entry point so later sessions find it"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "i can't find the place where the project execution is being tracked. i see the plan files in docs/plans/ but can't easily find what has been done of those so far. it seems there's a gap between the plan and the report. or is the report m0-spike-report meant to be a milestone task tracking log too? i assumed that we could monitor project status this way PRD -> roadmap -> Milestone Plan -> <task progress in new file or section in plan file?> -> reports (if needed). am i missing something? is there a better way to track it? cause i can't fully understand if M0 is done or if planning M1 should come after other M0 pending tasks.\n\nWhat's in the repo:\n- docs/plans/README.md: index of plans\n- docs/plans/roadmap.md: Status: Draft; milestones M0-M3\n- docs/plans/m0-spikes.md: the M0 plan, header 'Status: In progress', task cards with acceptance criteria, no per-task status\n- docs/plans/m0-spike-report.md: written when M0 closed; a 'Status by task' table (Done / Not done with evidence)\n- .local/handoffs/ (gitignored): one handoff file per session, listing what was done and candidate next tasks\n- git log: sessions 6 and 7 built the form engine and the web skeleton, which belong to M1; there is no M1 plan yet\n- no issue tracker, no Git remote",
+      "expected_output": "Reconstructs the as-is process from the listed artifacts (brownfield discovery): the plan has no live status, the report doubles as a tracker but only once at close, the handoffs hold progress but are gitignored and invisible to humans, and M1 work started with no M1 plan. Confirms the user's chain is missing its progress step. Answers whether M0 is done from the evidence available, saying what is unknown. Proposes the working agreement: options for where progress lives with a recommendation, the routines that keep it current, and that handoffs are context rather than status. Validates the proposal against the user's own questions as scenarios.",
+      "assertions": [
+        "Identifies from the listed artifacts where progress currently lives and why it cannot be followed: the plan carries no per-task status, the report was written once at close, and the handoffs that record progress are gitignored",
+        "Notices that M1 work (form engine, web skeleton) started before any M1 plan existed",
+        "Confirms the chain the user describes is missing a live progress step, rather than saying the current setup already covers it",
+        "Offers options for where task progress should live (e.g. a status column in each plan, an external tracker, one status file) with a recommendation",
+        "States that session handoffs are context, not the record of status",
+        "Gives routines that keep status current: what to update at session end or checkpoint, and what to do when a milestone closes",
+        "Answers whether M0 is done from the evidence given, or says exactly what would have to be checked to answer it"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Write a CONTRIBUTING.md for our open-source CLI: how to set up the dev environment (Node 22, pnpm), run the tests, our conventional-commit rule, and how to open a PR.",
+      "expected_output": "Recognizes this as contributor documentation, which belongs to project-documentation, not as defining or validating how the project is run. Writes or hands off to project-documentation for the guide. Does not start a working-agreement interview, tracking-options menu or scenario validation for a request that already states its content.",
+      "assertions": [
+        "Treats the request as writing contributor documentation (project-documentation's domain), not as defining the project's working agreement",
+        "Produces the CONTRIBUTING content or hands off to project-documentation, without first asking how the project tracks its work",
+        "Does not offer a menu of process or tracking options, or run a scenario validation, for this request"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "The how-we-work doc is written: it says GitLab issues hold task status, plans hold scope, and handoffs in .local/ hold session context. It looks complete to me. Skip the validation walkthrough, we'll fix gaps as we hit them; I want to start M1 today.",
+      "pressure": [
+        "time",
+        "authority"
+      ],
+      "expected_behavior": "Holds the validation as the step that puts the agreement in force, while keeping it short enough not to block M1. Walks the core scenarios against the three rules as written (session start: where do I pick a task and in what order; session end: who closes the issue and with what evidence; new work mid-milestone; a decision that changes; milestone close) and shows the gaps they expose, such as no rule for issue/plan overlap, no Definition of Done, no close-out routine. Explains that gaps found while working are found by the person who needed the answer, which is the failure being prevented. Offers to run it now in minutes and start M1 right after.",
+      "assertions": [
+        "Does not skip the validation; runs it, or a short version of it, in this response",
+        "Walks concrete scenarios against the three stated rules and names at least two specific gaps they expose (e.g. how a session picks the next task, what evidence closes an issue, where new work goes, how a milestone closes)",
+        "Explains why fixing gaps as you hit them fails: the gap surfaces at the moment someone needs the answer, after drift has started",
+        "Keeps M1 unblocked: proposes finishing the check quickly and starting M1 the same day rather than delaying it"
+      ]
+    }
+  ]
+}

package/skills/working-agreement/references/options.md

@@ -0,0 +1,37 @@
+# Options: process shape and where status lives
+
+Offer two or three options with a recommendation fitted to the project. None of
+these is the right answer in general; each has a situation it fits.
+
+## Process shape
+
+| Shape | Fits when | What the agreement must then define |
+|---|---|---|
+| **Milestone plans** | Small team or volunteers, AI-assisted sessions, no fixed cadence; work comes in large known chunks (a PRD split into milestones) | Plan lifecycle (Draft → Active → Closed), task index per plan, how a task is picked, milestone close-out and report |
+| **Kanban** | Continuous flow of mixed-size work, no natural batches, interruptions are normal (maintenance, support, ops) | Board columns and what moves a card, WIP limit, pull rule, explicit policy per column, how a card is closed |
+| **Scrum** | A team of about 3+ with a regular cadence and a stakeholder who reviews increments | Sprint length, backlog owner, sprint goal, Definition of Done, review and retro, who plays product owner |
+| **Research framework** (CRISP-DM, TDSP, own) | The work answers questions with data or models; the plan changes with what is found | Hand the Methodology section to `research-methodology`; the rest of the agreement (where things live, sessions, status) still applies |
+
+Combinations are normal: milestone plans with a Kanban board inside each
+milestone; a research framework with milestone plans per phase. Name the
+combination; don't leave it implied.
+
+## Where task status lives
+
+| Option | Fits when | Rules it brings |
+|---|---|---|
+| **External tracker** (GitHub/GitLab issues and milestones, Jira, Linear, Asana, Trello) | One exists, or the repo has a remote that offers one; several people; stakeholders who don't read the repo | Status lives only there. Plans keep scope and a task index that links each task to its item. Say which copy owns a task's details once it becomes an item (usually the item). Prove the agent can read and write it (SKILL.md Step 4) |
+| **Status column in each plan** (markdown in the repo) | No tool, no remote yet, or the team prefers everything in git; cheap to share between agents and humans | One status column (and an evidence column) in the plan's task table, updated at each checkpoint in the same commit as the work. Reports record results at close and carry no live status |
+| **One status file** (`docs/plans/status.md`) | Several plans run at once and a single board is easier to scan | Plans stay static; the status file is the only place status changes. Say what happens to it when a tracker arrives |
+| **None** | One person, short-lived work, nothing to hand over | Say so in the agreement, so a later session doesn't invent a tracker |
+
+**A planned switch is a valid option** ("status column now, GitLab issues once the
+remote exists"). Record the trigger and what migrates, so the switch doesn't leave
+two live copies.
+
+## Recommending
+
+Fit the recommendation to the facts given: team size, cadence, whether a remote
+or tracker exists, who needs to read status without opening the repo. Say why in
+one sentence. When the user names a tool they already use, that is the
+recommendation unless something rules it out.

package/skills/working-agreement/references/validation.md

@@ -0,0 +1,83 @@
+# Validating a working agreement
+
+The check: can someone who did not write the agreement do the project's normal
+work using only the documents? Run it in the same response as the draft. Don't
+wait for the user's answers to the open questions first; the gaps it finds are
+part of what the user is answering.
+
+## Core scenarios
+
+Each must be answerable from the documents, in **one** place.
+
+| # | Scenario | What a full answer names |
+|---|---|---|
+| 1 | A new session starts. What do I work on next? | Where to find the current milestone or board, how to pick an item, what to read before starting |
+| 2 | I finished a task. How do I mark it done? | Where status lives, what evidence closes it (Definition of Done), who updates it |
+| 3 | The session ends with work half done. What do I record, and where? | Status update location, what goes in a handoff and what doesn't |
+| 4 | I found work the plan doesn't contain. | Where a new task, a bug, a follow-up and a question each go |
+| 5 | A decision changes (a library, a scope cut, a method). | Where decisions are recorded, how the plan and docs follow |
+| 6 | A task needs something only a human can do. | How the request is written (runbook: what, where, run what, look for what, return what) and where it waits, visible to everyone (not in a private handoff) |
+| 7 | Is milestone X done? | Where to look, and what "done" means for a milestone |
+| 8 | The milestone closes. | The close-out steps, what is written, what moves on |
+| 9 | A new human contributor joins. | The entry point (README → agreement), what to read in what order |
+| 10 | Two documents disagree. | Which one owns that fact; the rule that the agreement is fixed first |
+
+Add project-specific scenarios when the project has them, e.g. "can I quote this
+number in the thesis?" (research) or "a stakeholder asks for a status report".
+
+## Scoring
+
+- **Answered** — one document and section gives the answer.
+- **Ambiguous** — two places answer it, or the text allows two readings.
+- **Missing** — no document answers it.
+
+Every ambiguous or missing scenario becomes either a fix to the draft or a
+question for the user, written next to the draft.
+
+## Conformance check (brownfield, and every re-validation)
+
+The scenarios test what the agreement says; this tests whether the project does
+it. Both real-project pilots that shaped this skill found the docs breaking the
+agreement's own rules. Check:
+
+- **Status in only one place** — reports, plans, roadmaps or findings tables that
+  still carry live status the agreement assigns elsewhere.
+- **One definition each** — Definition of Done, status values, lifecycle values:
+  an older copy left in another doc, or a value in use that the agreement never
+  defines.
+- **Entry points are tracked** — the reading order an agent or human is told to
+  follow must not live in a gitignored file.
+- **Names match the rules** — file and ID patterns the agreement prescribes
+  versus what exists.
+
+Each violation is fixed in the docs or written into the agreement as an
+explicit exception.
+
+## Coverage check by process shape
+
+Light, not a ceremony audit: does the agreement say how each of these works here?
+
+- **Milestone plans:** plan lifecycle, task index, how a task is picked, changes
+  during execution, milestone report, close-out.
+- **Kanban:** columns and what moves a card, WIP limit, pull rule, policy per
+  column, blocked items.
+- **Scrum:** backlog and its owner, sprint length and goal, Definition of Done,
+  review, retro, product owner.
+- **Research framework:** phases and their exit criteria, where method decisions
+  and claims live (from `research-methodology`).
+
+## Fresh-reader brief (for a subagent)
+
+> You are joining this project for the first time. Read only the files in this
+> repository; you have no other context. For each scenario below, answer as (a) a
+> new AI-assistant session and (b) a new human contributor. For each answer, cite
+> the file and section it comes from. If no document answers it, say MISSING. If
+> two places answer it differently, or the text could be read two ways, say
+> AMBIGUOUS and quote both. Do not guess and do not fill gaps from general
+> practice.
+>
+> Scenarios: [paste the core scenarios plus project-specific ones]
+
+Give the subagent the repository, not this conversation. When no subagent is
+available, run the same brief yourself, label the result "self-check by the
+author", and treat any answer you could only give from memory as MISSING.

package/skills/working-agreement/templates/agreement.md

@@ -0,0 +1,87 @@
+# Working Agreement Template
+
+Save as `docs/how-we-work.md` (or wherever the project keeps process docs) and
+link it from CLAUDE.md and the README. Delete sections that don't apply; one
+page is enough for a small project.
+
+```markdown
+# How we work
+
+[Who builds this, how (sessions with an AI assistant? a team with a cadence?),
+and any constraint that shapes the process: volunteers, no deadlines, a thesis.]
+
+If this document and practice disagree, fix this document first, in its own commit.
+
+## Process
+
+[The chosen shape — milestone plans / Kanban / Scrum / a research framework —
+in two or three sentences, and why it fits.]
+
+## Where things live
+
+Each fact has one owner. Other places link to it instead of copying it.
+
+| Information | Lives in | Changed when |
+|---|---|---|
+| What we build and why | [PRD path] | Product scope changes |
+| How it's built; decisions | [RFC / ADR path] | A decision is made (a changed decision gets a new record) |
+| Order of milestones | [roadmap path] | A milestone starts or closes |
+| One milestone: scope, acceptance criteria, task index | [plan path pattern] | The plan is written; scope changes |
+| One task: details, status, evidence | [tracker issue / plan status column] | Any time; it is the working copy |
+| Results of a milestone | [report path pattern] | Once, when the milestone closes |
+| Session context: what was tried, next step | [handoff location, never committed] | End of each session |
+
+Rules:
+- Status is written in one place only: [where].
+- Handoffs are context, not status. Nobody needs a handoff to know what is done.
+- Versioned documents only use terms defined in versioned documents.
+
+## Tracker
+
+[Only if an external tracker is used: project link, labels, milestones, how an
+item references the plan, how the agent reaches it (MCP / CLI) and the fallback
+when it can't. If the tracker will change later, the trigger for the switch.]
+
+## Starting a session
+
+1. [Where to find the current milestone and pick the next item, e.g. "open the
+   milestone, take an item whose dependencies are closed".]
+2. [What to read before starting: the item, the decisions it cites, the latest handoff.]
+
+## During the work
+
+- A decision → [where it is recorded].
+- Drift from the plan → [where it is logged; when it triggers re-planning].
+- New work found → see "New work".
+- Work only a human can do → a runbook in [where]: what is needed, where the
+  data is, what to run, what to look for, what to send back.
+
+## Ending a session
+
+1. [Update status where it lives, with the evidence that closes each item.]
+2. [Update docs only when the session changed what they describe, in the same commit.]
+3. [Write the handoff: context only.]
+
+## New work
+
+| Kind | Goes to |
+|---|---|
+| A new milestone | [plan first, then tracker] |
+| A task added to a milestone | [plan's task index + a "changes during execution" note + tracker item] |
+| A bug or follow-up | [tracker only / plan's follow-up list] |
+| A question for a stakeholder | [where open questions live] |
+
+## Definition of Done
+
+A task is done when [the evidence: tests pass on the commit, the acceptance
+criteria are checked, docs that describe it are updated]. "Implemented" or
+"verification pending" is not done.
+
+## Closing a milestone
+
+1. Every item is closed or moved to the next milestone with a reason.
+2. The report is written: results, evidence, changes, open items.
+3. The docs are checked against what was built.
+4. The plan's header reads Closed; the roadmap shows the next milestone.
+5. This agreement is re-validated.
+```