Add PI workflow skills for task-aware orchestration

packages/plugin-research/manifest.json

@@ -6,9 +6,64 @@
   "description": "Canonical research evidence and data-inventory workflows for BrainPilot experts.",
   "categories": ["analysis", "workflow", "skills"],
   "engines": { "brainpilot": ">=0.1.2 <0.2.0" },
+  "protocols": { "agentInstructions": "1" },
   "environments": ["local", "cloud"],
   "contributes": {
     "skills": [
+      {
+        "id": "frame-scientific-decision",
+        "title": "Frame Scientific Decision",
+        "description": "Expose unresolved outcome-sensitive choices before the Principal delegates scientific work.",
+        "entry": "skills/frame-scientific-decision/SKILL.md",
+        "targets": [
+          "principal"
+        ]
+      },
+      {
+        "id": "coordinate-model-selection",
+        "title": "Coordinate Model Selection",
+        "description": "Coordinate grounded comparison and selection when a model or method choice affects the outcome.",
+        "entry": "skills/coordinate-model-selection/SKILL.md",
+        "targets": [
+          "principal"
+        ]
+      },
+      {
+        "id": "coordinate-data-analysis",
+        "title": "Coordinate Data Analysis",
+        "description": "Coordinate reproducible analysis from data inventory through interpretation and audit.",
+        "entry": "skills/coordinate-data-analysis/SKILL.md",
+        "targets": [
+          "principal"
+        ]
+      },
+      {
+        "id": "coordinate-literature-synthesis",
+        "title": "Coordinate Literature Synthesis",
+        "description": "Coordinate source-grounded factual or literature research without unnecessary execution work.",
+        "entry": "skills/coordinate-literature-synthesis/SKILL.md",
+        "targets": [
+          "principal"
+        ]
+      },
+      {
+        "id": "coordinate-study-design",
+        "title": "Coordinate Study Design",
+        "description": "Coordinate evidence-grounded experimental, observational, or protocol design.",
+        "entry": "skills/coordinate-study-design/SKILL.md",
+        "targets": [
+          "principal"
+        ]
+      },
+      {
+        "id": "coordinate-software-delivery",
+        "title": "Coordinate Software Delivery",
+        "description": "Coordinate implementation and debugging without expanding ordinary engineering into a research workflow.",
+        "entry": "skills/coordinate-software-delivery/SKILL.md",
+        "targets": [
+          "principal"
+        ]
+      },
       {
         "id": "source-grounded-research-report",
         "title": "Source-Grounded Research Report",
@@ -23,6 +78,16 @@
         "entry": "skills/create-data-inventory/SKILL.md",
         "targets": ["engineer"]
       }
+    ],
+    "agentInstructions": [
+      {
+        "id": "principal-research-workflows",
+        "title": "PI research workflow skills",
+        "entry": "prompts/principal.md",
+        "targets": ["principal"],
+        "mode": "append",
+        "priority": 50
+      }
     ]
   }
 }

packages/plugin-research/package.json

@@ -4,8 +4,8 @@
   "engines": { "node": ">=22" },
   "license": "AGPL-3.0-only",
   "type": "module",
-  "description": "Canonical research reports and data inventories for BrainPilot experts",
-  "files": ["manifest.json", "skills"],
+  "description": "Canonical research workflow, reporting, and data-inventory skills for BrainPilot",
+  "files": ["manifest.json", "prompts", "skills"],
   "exports": {
     "./package.json": "./package.json",
     "./manifest.json": "./manifest.json"

packages/plugin-research/prompts/principal.md

@@ -0,0 +1,8 @@
+# PI workflow skills
+
+Before the first substantive delegation, load `frame-scientific-decision` and
+every applicable `coordinate-*` workflow Skill that applies to the request.
+Compose matching Skills for mixed tasks in evidence-dependency order. Router
+Skills supply domain methods; a missing router match calls for Librarian
+grounding and never waives a workflow. Delivery shape and design hints do not
+by themselves fix an outcome-sensitive scientific choice.

packages/plugin-research/skills/coordinate-data-analysis/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: coordinate-data-analysis
+description: Coordinate analysis, quality control, statistics, visualization, or scientific interpretation of task-relevant data. Principal must use when the main output is evidence derived from supplied observations rather than selection of a predictive model or design of a new study.
+---
+
+# Coordinate Data Analysis
+
+State the scientific question, authorized data scope, natural grouping unit,
+target outcomes, and claims the analysis must support.
+
+1. Dispatch Engineer to invoke `create-data-inventory`, reconcile identifiers,
+   labels, shapes, missingness, split boundaries, and decision-relevant variation.
+2. Dispatch Librarian only when assumptions, measures, or method choices require
+   external evidence; do not substitute generic literature for inspecting the
+   actual data.
+3. Dispatch Experimentalist to write the analysis protocol: estimand, inclusion
+   rules, transformations, controls, statistical model, multiplicity handling,
+   uncertainty, sensitivity checks, and acceptance criteria.
+4. Dispatch Engineer to execute the frozen protocol and save machine-readable
+   results, diagnostics, figures, logs, and reproducible code.
+5. Dispatch Experimentalist to interpret the saved evidence, distinguish
+   observation from inference, and request bounded sensitivity work for material
+   unresolved assumptions.
+6. Use `audit-feedback-loop` before delivering consequential results.
+
+Do not force a model-survey workflow when the method is externally fixed or the
+task is descriptive. Do not treat a plausible figure, successful script, or
+aggregate metric as sufficient when group-level failures, leakage, missingness,
+or robustness could reverse the conclusion.
+
+Complete only when the handoff names the data inventory, analysis protocol,
+executed outputs, diagnostics, sensitivity evidence, interpretation, limitations,
+and applicable audit verdict.

packages/plugin-research/skills/coordinate-data-analysis/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Coordinate Data Analysis"
+  short_description: "Plan valid data analysis and interpretation"
+  default_prompt: "Use $coordinate-data-analysis to organize a reproducible analysis from data inventory through interpretation."

packages/plugin-research/skills/coordinate-literature-synthesis/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: coordinate-literature-synthesis
+description: Coordinate a literature review, factual research answer, method landscape, or evidence synthesis that must be grounded in inspectable sources. Principal must use when source quality and reconciliation, rather than experiment execution or data processing, determine the answer.
+---
+
+# Coordinate Literature Synthesis
+
+Define the bounded questions, decision context, required recency, and claims the
+final report must support. Specify which claims require primary sources,
+authoritative documentation, benchmark records, or review-level synthesis.
+
+1. Dispatch Librarian to invoke `source-grounded-research-report`. Split truly
+   independent source or evidence-extraction slices when breadth warrants it.
+2. Require one canonical report that identifies sources precisely, records exact
+   supporting locations, reconciles contradictions, separates direct evidence
+   from inference, and marks unresolved claims `unverified`.
+3. Route targeted follow-up research for missing decision-critical evidence;
+   avoid broad repeated searches after the gap is bounded.
+4. Use Auditor evidence review for consequential quantitative, comparative, or
+   citation claims. Use Writer only after the evidence content is stable.
+
+Do not dispatch Engineer merely to make the workflow look complete. Add
+implementation or data-analysis work only when the user's requested outcome
+actually requires it.
+
+Complete only when every decision-relevant claim maps to an inspectable source
+or an explicit unresolved limitation, contradictions are synthesized, and the
+canonical report path is ready for handoff.

packages/plugin-research/skills/coordinate-literature-synthesis/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Coordinate Literature Synthesis"
+  short_description: "Organize source-grounded research synthesis"
+  default_prompt: "Use $coordinate-literature-synthesis to organize a source-grounded literature research workflow."

packages/plugin-research/skills/coordinate-model-selection/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: coordinate-model-selection
+description: Coordinate evidence-based selection of a data-driven model, algorithm, decoder, architecture, or analysis pipeline. Principal must use when performance depends on a method choice not explicitly fixed by the user, including tasks that submit one final class or file, provide design hints, use a frozen scorer, or hide the final test set.
+---
+
+# Coordinate Model Selection
+
+Define the target claim, primary metric, natural generalization unit, constraints,
+and available comparison data. Separate externally fixed requirements from hints
+that still leave a method choice.
+
+Coordinate the evidence chain:
+
+1. Dispatch Engineer to create the data inventory, inspect representative real
+   inputs, verify compute, and build decision-neutral evaluation plumbing.
+2. In parallel, dispatch Librarian to compare substantively different credible
+   method families, established baselines, applicability, costs, and limitations.
+3. Synthesize those artifacts. Preserve at least one credible baseline and enough
+   distinct candidates to expose the decision; justify every material exclusion.
+4. Dispatch Experimentalist to predeclare the comparison protocol: splits,
+   grouping unit, seeds or resampling, primary and guardrail metrics, failure
+   diagnostics, budget, staged reductions, selection rule, and stopping rule.
+5. Dispatch Engineer to implement and execute that protocol on authorized real
+   data. Treat import checks, loss decrease, subsets, and short runs as
+   feasibility evidence only.
+6. Dispatch Experimentalist to review saved results independently, request
+   bounded follow-up work when the rule requires it, freeze the final comparable
+   snapshot, and apply the declared decision rule once.
+7. Use `audit-feedback-loop` on the frozen selected artifact and its complete
+   evidence chain.
+
+Do not let the first runnable model become the implicit incumbent. Do not infer
+that model selection is impossible merely because the evaluator owns the final
+held-out test. If comparison evidence is genuinely unavailable, preserve a
+validated fallback and report the result as empirically unresolved.
+
+Complete only when the handoff names the data contract, method survey, protocol,
+baseline, candidate results including failures, decision record, selected
+artifact, and final audit verdict.

packages/plugin-research/skills/coordinate-model-selection/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Coordinate Model Selection"
+  short_description: "Compare candidate methods before model delivery"
+  default_prompt: "Use $coordinate-model-selection to plan a grounded candidate comparison and final model decision."

packages/plugin-research/skills/coordinate-software-delivery/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: coordinate-software-delivery
+description: Coordinate implementation, debugging, integration, refactoring, deployment preparation, or test work whose desired software behavior is already defined. Principal must use to keep engineering tasks efficient and to escalate only genuine scientific, product, or external-API uncertainties.
+---
+
+# Coordinate Software Delivery
+
+Define the observable software outcome, affected scope, constraints, acceptance
+tests, and whether the request is implementation or diagnosis only.
+
+1. For a reported bug, dispatch Engineer to establish a tight reproduction and
+   identify the cause before changing behavior. For a build request, require a
+   concrete implementation plan proportional to risk.
+2. Dispatch Librarian only for authoritative external API, specification, or
+   dependency facts that cannot be established locally.
+3. Dispatch Experimentalist only when the implementation contains an unresolved
+   scientific method, evaluation, or interpretation decision. If that occurs,
+   pause binding implementation and route through the appropriate research
+   workflow.
+4. Dispatch Engineer to implement, preserve unrelated work, and verify with the
+   smallest relevant test surface plus broader checks proportional to risk.
+5. Use code/artifact audit or review for high-risk changes; do not require a
+   literature survey for ordinary repository work.
+
+Keep diagnosis and repair distinct when the user requested only an explanation.
+Do not claim success from compilation alone when runtime behavior, migration,
+packaging, or integration is part of acceptance.
+
+Complete only when the root cause or design rationale is explicit, the requested
+change is implemented within scope, relevant tests pass, residual risks are
+named, and the user receives the primary file or change pointers.

packages/plugin-research/skills/coordinate-software-delivery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Coordinate Software Delivery"
+  short_description: "Route implementation and debugging without research sprawl"
+  default_prompt: "Use $coordinate-software-delivery to plan an efficient implementation, debugging, and verification workflow."

packages/plugin-research/skills/coordinate-study-design/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: coordinate-study-design
+description: Coordinate design of an experiment, observational study, scientific protocol, measurement plan, or data-collection strategy. Principal must use when the user needs a defensible study plan rather than analysis of an already fixed dataset or implementation of fixed software behavior.
+---
+
+# Coordinate Study Design
+
+Clarify the scientific objective, target population or system, feasible resources,
+intended claim, and decisions the study must enable.
+
+1. Dispatch Librarian to ground constructs, measures, prior effects, established
+   paradigms, known confounds, and ethical or reporting standards.
+2. Dispatch Experimentalist to turn that evidence into a protocol with hypotheses,
+   outcomes, controls, randomization or counterbalancing, sampling and power,
+   exclusion rules, stopping criteria, data-quality checks, and a prespecified
+   analysis plan.
+3. Dispatch Engineer only for feasibility prototypes, stimulus generation,
+   instrumentation, simulations, or data plumbing required to test the protocol.
+4. Return feasibility findings to Experimentalist for protocol revision; keep
+   scientific choices with the protocol owner rather than the implementer.
+5. Use the applicable audit workflow to check evidence, internal consistency,
+   leakage, reproducibility, and claim scope before handoff.
+
+Do not silently turn a design request into actual participant recruitment, data
+collection, or high-impact execution. Ask the user before actions requiring new
+authority, cost, exposure, or irreversible external state.
+
+Complete only when the protocol links every important design choice to evidence
+or a stated constraint and includes operational feasibility, analysis, quality,
+stopping, limitation, and audit information.

packages/plugin-research/skills/coordinate-study-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Coordinate Study Design"
+  short_description: "Ground and review experimental study protocols"
+  default_prompt: "Use $coordinate-study-design to coordinate evidence-grounded study and protocol design."

packages/plugin-research/skills/frame-scientific-decision/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: frame-scientific-decision
+description: Expose the claim, evidence, externally fixed constraints, and unresolved outcome-sensitive choices before BrainPilot's Principal delegates scientific work. Principal must use for experiment design, data analysis, modelling, prediction, method recommendation, or scientific interpretation where a choice could change the conclusion.
+---
+
+# Frame Scientific Decision
+
+Frame the task around the decision the user needs, not the shape of the final
+artifact. Create a compact decision map before the first substantive delegation:
+
+| Decision | Can change metric or claim? | Fixed by | Evidence needed | Owner | Resolution rule |
+|---|---|---|---|---|---|
+
+List the intended outcome, acceptance criterion, claims to support, authorized
+data and evidence, available compute and time, and every unresolved choice that
+could materially change the outcome.
+
+Count a choice as fixed only when the user, task specification, or an external
+protocol independently determines it. Treat hints, examples, familiar defaults,
+and the first plausible implementation as open choices. A single requested file,
+class, report, or final model fixes delivery shape, not the scientific method.
+Fixed input/output, preprocessing, or training rules do not automatically fix
+architecture, capacity, features, statistics, or decision criteria.
+
+A private final test prevents inspection of that test; it does not invalidate
+predeclared comparison on authorized training and validation data. Failure to
+find a matching local Skill increases the need for Librarian grounding when
+knowledge is missing; it never proves that research is unnecessary.
+
+Route each unresolved choice to the applicable workflow Skill:
+
+- model, algorithm, architecture, decoder, or pipeline →
+  `coordinate-model-selection`;
+- analysis, statistics, visualization, or interpretation →
+  `coordinate-data-analysis`;
+- factual or literature evidence → `coordinate-literature-synthesis`;
+- hypothesis, experiment, measurement, or sampling →
+  `coordinate-study-design`;
+- implementation or debugging with fixed behavior →
+  `coordinate-software-delivery`.
+
+Compose workflows for mixed tasks in evidence-dependency order. Complete the
+frame only when every outcome-sensitive choice has an owner, evidence source,
+and checkable resolution or stopping rule. Then dispatch the first upstream task
+and stop the turn.

packages/plugin-research/skills/frame-scientific-decision/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Frame Scientific Decision"
+  short_description: "Expose unresolved choices before PI delegates work"
+  default_prompt: "Use $frame-scientific-decision to map every outcome-sensitive open decision before delegating the task."

packages/runtime/src/__tests__/personas.test.ts

@@ -59,6 +59,8 @@ describe("personas", () => {
 
   it("PI and methodology agents enforce skills-first preflight", () => {
     expect(PERSONAS.principal!).toContain("Skills-first preflight");
+    expect(PERSONAS.principal!).toContain("every applicable PI workflow Skill");
+    expect(PERSONAS.principal!).toContain("no Router match replaces Librarian grounding");
     expect(PERSONAS.principal!).toMatch(/Check\s+expert skill use/);
     expect(PERSONAS.experimentalist!).toContain("skills are not");
     expect(PERSONAS.experimentalist!).toContain("Find relevant skills first");