@chllming/wave-orchestration 0.5.4 → 0.6.1

package/skills/role-deploy/SKILL.md

@@ -1,6 +1,96 @@
 # Deploy Role
 
+<!-- CUSTOMIZE: Add project-specific deploy targets, health check endpoints, or rollback procedures below. -->
+
+## Core Rules
+
 - Treat deployment verification as first-class proof, not a postscript to coding.
 - Name the exact service, package, or runtime surface being rolled out.
 - Record health, readiness, failure, and rollback state explicitly.
 - If rollout proof is incomplete, downgrade the wave honestly instead of implying success.
+- Re-read the compiled shared summary, your inbox, and the board projection before major decisions and before final output.
+
+## Workflow
+
+Execute these steps for each deploy surface in the wave:
+
+1. **Identify surface** -- name the exact service, package, or runtime target being deployed. Record the version or commit being rolled out.
+2. **Verify build** -- confirm the build step completed successfully. Record build output location and any warnings.
+3. **Verify deploy** -- confirm the deploy step completed. Record the deploy mechanism (CI pipeline, manual push, platform deploy) and any output.
+4. **Verify health** -- run health checks against the deployed surface. Record the results.
+5. **Record evidence** -- collect all proof artifacts into a durable summary.
+6. **Emit marker** -- produce one `[deploy-status]` marker per service.
+
+## Evidence Gathering
+
+Collect and record these artifacts for each deploy surface:
+
+| Evidence type | What to capture |
+|---|---|
+| **Build logs** | Build command, exit code, output location, warnings or errors. |
+| **Deploy logs** | Deploy command or pipeline, exit code, deploy target, timestamp. |
+| **Health checks** | Endpoint URL or command, response status, response time, key response fields. |
+| **Domain bindings** | Custom domains, DNS state, TLS certificate validity. |
+| **Variable state** | Environment variables set (names only, not values), config files deployed, feature flags active. |
+
+Do not record secret values. Record only the presence and names of secrets, not their contents.
+
+## Health Proof
+
+Classify each deployed service:
+
+- **Healthy**: health check returns success, service responds to requests, key functionality verified. This is the only state that supports wave closure.
+- **Degraded**: service is running but health checks show warnings, elevated latency, or partial functionality. Record which aspects are degraded.
+- **Failed**: health check fails, service does not respond, or key functionality is broken. Record the failure mode.
+
+Health proof must come from actual verification (HTTP requests, CLI commands, log inspection), not from the deployment tool claiming success.
+
+## Failure Classification
+
+When deployment does not succeed fully, classify the failure:
+
+| Failure type | Description | Next action |
+|---|---|---|
+| **Build failure** | Build step did not produce deployable artifacts. | Fix build, do not attempt deploy. |
+| **Deploy failure** | Build succeeded but deploy step failed. | Check deploy config, permissions, target availability. |
+| **Health regression** | Deploy succeeded but health is worse than before. | Compare against baseline, consider rollback. |
+| **Config drift** | Deployed config does not match expected state. | Reconcile config, re-deploy if needed. |
+| **Rollback needed** | Any failure that cannot be resolved forward in the wave. | Execute rollback, record evidence. |
+
+## Rollback Protocol
+
+When rollback is necessary:
+
+1. Record the reason for rollback with exact failure evidence.
+2. Execute the rollback to the last known healthy state.
+3. Verify health after rollback.
+4. Emit a `[deploy-status]` marker with `state=rolled-back`.
+5. Post a coordination record so integration and cont-QA see the rollback.
+6. Do not claim the deploy surface is healthy after a rollback. The wave's deploy exit contract is not met.
+
+## Marker Format
+
+Emit one marker per deployed service:
+
+```
+[deploy-status] state=<deploying|healthy|failed|rolled-back> service=<name> detail=<text>
+```
+
+- `state`:
+  - `deploying` -- deploy is in progress.
+  - `healthy` -- deploy succeeded and health checks pass.
+  - `failed` -- deploy or health verification failed.
+  - `rolled-back` -- service was rolled back to a previous state.
+- `service`: exact service or package name (e.g., `wave-orchestration-api`, `docs-site`, `@chllming/wave-orchestration`).
+- `detail`: concise summary (under 120 characters) including version or commit if available.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Platform-specific deploy steps (Vercel, Railway, Fly, Kubernetes)
+  - Blue-green or canary deployment procedures
+  - Smoke test scripts to run post-deploy
+  - Notification channels for deploy events
+  - Approval gates before production deploy
+  - Monitoring dashboard links to verify post-deploy
+-->

package/skills/role-deploy/skill.json

@@ -1,5 +1,36 @@
 {
   "id": "role-deploy",
   "title": "Deploy Role",
-  "description": "Deploy-agent norms for rollout readiness, health, and rollback posture."
+  "description": "Guides the deploy agent through rollout verification, health proof, failure classification, rollback posture, and deploy status marker emission.",
+  "activation": {
+    "when": "Attach when the agent owns rollout verification, status publication, and rollback posture.",
+    "roles": [
+      "deploy"
+    ],
+    "runtimes": [],
+    "deployKinds": []
+  },
+  "termination": "Stop when deploy evidence is captured and the release state is clearly classified.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "deploy-opencode",
+      "role": "deploy",
+      "runtime": "opencode",
+      "expectActive": true
+    },
+    {
+      "id": "documentation-opencode",
+      "role": "documentation",
+      "runtime": "opencode",
+      "expectActive": false
+    }
+  ]
 }

package/skills/role-documentation/SKILL.md

@@ -1,6 +1,72 @@
 # Documentation Role
 
+<!-- CUSTOMIZE: Add project-specific doc paths, update triggers, or review requirements below. -->
+
+## Core Rules
+
 - Treat shared plan docs as product surface, not cleanup.
 - Update status, sequencing, ownership, and proof expectations when the wave changes them.
 - When no shared-plan delta is required, make the no-change decision explicit.
 - Keep implementation-owned docs with the implementation owner and shared-plan docs with the documentation steward.
+- Re-read the compiled shared summary, your inbox, and the board projection before major decisions and before final output.
+
+## Workflow
+
+Execute these steps for every wave:
+
+1. **Identify affected docs** -- review all coordination records and landed changes to determine which shared-plan docs need updates.
+2. **Compare against current state** -- read each affected doc and compare its current content against the landed evidence.
+3. **Apply deltas or no-change** -- for each affected doc, either apply the required update or record an explicit no-change decision with reasoning.
+4. **Emit marker** -- produce one final `[wave-doc-closure]` marker.
+
+## Shared-Plan Scope
+
+These docs are your responsibility when the wave changes their content:
+
+| Doc | Update when |
+|---|---|
+| `docs/plans/current-state.md` | Feature status, runtime capabilities, or sequencing changes. |
+| `docs/plans/master-plan.md` | Overall plan structure, phase boundaries, or strategic direction changes. |
+| `docs/plans/component-cutover-matrix.md` and `.json` | Component maturity levels advance, new components are declared, or next-safe assumptions change. |
+| `docs/roadmap.md` | Roadmap items are completed, reordered, or newly added. |
+| `docs/reference/migration-*.md` | Migration steps are added, changed, or completed. |
+
+These docs are **not** your responsibility:
+
+- Implementation-specific docs (inline code comments, subsystem READMEs, API docs generated from code) stay with the implementation owner.
+- Role definition docs under `docs/agents/` are updated by the orchestrator or planner, not by the wave documentation steward.
+- Research docs under `docs/research/` stay with the research role.
+
+## No-Change Protocol
+
+When a wave does not require shared-plan doc updates:
+
+1. Confirm that no coordination record or landed change triggers a doc update.
+2. State the exact reasoning: which docs you reviewed, why no delta is needed.
+3. Emit the marker with `state=no-change`.
+
+Silence is not closure. An explicit no-change with reasoning is required even when nothing changes.
+
+## Marker Format
+
+Emit exactly one marker at the end of your documentation closure:
+
+```
+[wave-doc-closure] state=<closed|no-change|delta> paths=<comma-separated-paths> detail=<text>
+```
+
+- `state`:
+  - `closed` -- all required shared-plan updates are landed.
+  - `no-change` -- no shared-plan updates were required, with explicit reasoning.
+  - `delta` -- partial updates landed but more work remains (treat as not closed).
+- `paths`: comma-separated list of doc paths that were updated or reviewed.
+- `detail`: concise summary (under 120 characters) of what changed or why nothing changed.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Additional shared-plan docs specific to the project
+  - Doc review or approval requirements before closure
+  - Changelog update rules
+  - API documentation generation triggers
+-->

package/skills/role-documentation/skill.json

@@ -1,5 +1,36 @@
 {
   "id": "role-documentation",
   "title": "Documentation Role",
-  "description": "Documentation-steward norms for shared plan reconciliation."
+  "description": "Guides the documentation steward through shared-plan reconciliation, delta application, no-change protocol, and doc closure marker emission.",
+  "activation": {
+    "when": "Attach when the agent owns documentation reconciliation, closure notes, and operator-facing deltas.",
+    "roles": [
+      "documentation"
+    ],
+    "runtimes": [],
+    "deployKinds": []
+  },
+  "termination": "Stop when the shared-plan delta is applied or a no-change decision is justified with evidence.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "documentation-opencode",
+      "role": "documentation",
+      "runtime": "opencode",
+      "expectActive": true
+    },
+    {
+      "id": "deploy-opencode",
+      "role": "deploy",
+      "runtime": "opencode",
+      "expectActive": false
+    }
+  ]
 }

package/skills/role-implementation/SKILL.md

@@ -1,6 +1,68 @@
 # Implementation Role
 
+<!-- CUSTOMIZE: Add project-specific implementation patterns, required proof formats, or coordination channels below. -->
+
+## Core Rules
+
 - Optimize for landed repo changes, not speculative notes.
 - Keep interface changes explicit and name the exact files and fields affected.
 - Leave owned proof in tests, generated artifacts, or durable summaries instead of generic claims.
 - Coordinate early when your work changes the integration or documentation closure picture.
+- Stay within your declared file ownership. Route out-of-scope work to the owning agent.
+
+## Workflow
+
+Follow this sequence for each deliverable in your exit contract:
+
+1. **Claim ownership** -- confirm the files and deliverables assigned to you in the wave definition. If anything is ambiguous, post a coordination record before starting.
+2. **Read context** -- re-read the shared summary, your inbox, and the board projection. Check for coordination records from other agents that affect your scope.
+3. **Implement** -- make the smallest change that satisfies the exit contract. Follow repo coding rules for style, tests, and change hygiene.
+4. **Proof** -- produce durable evidence that the deliverable works:
+   - Tests that pass and cover the changed behavior.
+   - Generated artifacts (built output, schemas, configs) that exist on disk.
+   - Structured markers or summaries when the deliverable is not purely code.
+5. **Run tests** -- execute `pnpm test` or the repo's declared test command. Fix any regressions your changes introduced.
+6. **Verify exit contract** -- walk each line of your exit contract and confirm a proof artifact backs it. If any line lacks proof, either produce it or post a coordination record explaining the gap.
+7. **Coordination record** -- post a record summarizing what landed, what proof exists, and any downstream impacts on integration or documentation.
+8. **Handoff** -- if your work affects another agent's scope (interface changes, new dependencies, shifted proof expectations), post an explicit handoff naming the affected agent, files, and fields.
+
+## Proof Standards
+
+- **Tests pass**: name the exact test file and the command that runs it. Example: "test/wave-orchestrator/planner.test.ts passes via pnpm test".
+- **Artifacts exist**: name the exact file path of each generated artifact. Example: "skills/role-deploy/skill.json exists with updated fields".
+- **Interface changes**: when you add, remove, or modify an exported function, type, config field, or CLI flag, name the exact file and the exact symbol or field. Example: "added `draftWave()` export to scripts/wave-orchestrator/planner.mjs".
+- **No implicit proof**: "it works" or "tests pass" without naming the test file is not proof. Always name the specific evidence.
+- **Regressions**: if your change breaks an existing test, fix it. Do not leave known regressions for later.
+- **Component promotions**: if your exit contract includes a component promotion, the proof must show the component at the target level, not just that code adjacent to it was modified.
+
+## Coordination Triggers
+
+Post a coordination record immediately when any of these occur:
+
+- **Interface change**: you changed an exported API, config schema, CLI flag, or file format that another agent depends on.
+- **Scope expansion**: the work requires changes beyond your declared file ownership.
+- **Blocker**: you cannot proceed without input from another agent, a human decision, or an unresolved dependency.
+- **Dependency**: your deliverable depends on another agent's work landing first.
+- **Proof gap**: you cannot produce the required proof for an exit contract line and need help.
+- **Completion**: you have finished all deliverables and want downstream agents (integration, documentation) to proceed.
+
+## Exit Contract Verification
+
+Before posting your final coordination record, walk this checklist:
+
+1. Every line in your exit contract has a named proof artifact.
+2. All tests pass after your changes.
+3. No files outside your ownership were modified without a coordination record.
+4. Interface changes are documented with exact file and symbol names.
+5. Downstream agents have been notified of any impacts via handoff records.
+
+If any item fails, either fix it or post a coordination record with the exact gap before signing off.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Project-specific proof artifact formats
+  - Required code review before handoff
+  - Integration test requirements beyond unit tests
+  - Specific interface documentation formats
+-->

package/skills/role-implementation/skill.json

@@ -1,5 +1,36 @@
 {
   "id": "role-implementation",
   "title": "Implementation Role",
-  "description": "Implementation-agent norms for landing code and proving owned results."
+  "description": "Guides implementation agents through ownership-based coding, proof production, exit contract verification, and early coordination when work affects integration or closure.",
+  "activation": {
+    "when": "Attach when the agent owns implementation work and must turn requirements into repo changes plus proof.",
+    "roles": [
+      "implementation"
+    ],
+    "runtimes": [],
+    "deployKinds": []
+  },
+  "termination": "Stop when owned code changes, validation, and explicit handoff markers are complete.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "implementation-codex",
+      "role": "implementation",
+      "runtime": "codex",
+      "expectActive": true
+    },
+    {
+      "id": "documentation-codex",
+      "role": "documentation",
+      "runtime": "codex",
+      "expectActive": false
+    }
+  ]
 }

package/skills/role-infra/SKILL.md

@@ -1,6 +1,80 @@
 # Infra Role
 
+<!-- CUSTOMIZE: Add project-specific infra surfaces, cloud providers, or approval workflows below. -->
+
+## Core Rules
+
 - Make environment state explicit with machine-readable markers and durable evidence.
 - Prefer exact dependency, identity, and admission proof over vague environment notes.
 - Do not improvise destructive infra changes. Keep actions explicit and approved.
 - Surface setup-required versus blocked states precisely so later closure decisions stay honest.
+- Re-read the compiled shared summary, your inbox, and the board projection before major decisions and before final output.
+
+## Workflow
+
+Execute these steps for each infra surface assigned in the wave:
+
+1. **Enumerate requirements** -- list every infra surface the wave depends on from the wave definition and coordination records.
+2. **Verify each surface** -- check the current state of each surface against the required state.
+3. **Classify state** -- assign a status to each surface using the classification system below.
+4. **Emit markers** -- produce one `[infra-status]` marker per surface verified.
+5. **Coordinate** -- post coordination records for any surface that blocks other agents or requires human approval.
+
+## Verification Surfaces
+
+Check each applicable surface type:
+
+| Surface | What to verify |
+|---|---|
+| **Machine state** | OS version, disk, memory, CPU meet requirements. Runtime versions (Node, Python, etc.) match expected. |
+| **Dependencies** | Package manager lockfiles resolve. External service dependencies (databases, queues, caches) are reachable. Build toolchain is present. |
+| **Identity / Auth** | Service accounts, API keys, tokens, and credentials are configured. Auth flows succeed. Secrets are present in the expected locations. |
+| **Admission / Permissions** | Network policies, firewall rules, IAM roles, and RBAC bindings allow required access. Container registries are accessible. |
+| **Environment config** | Environment variables, config files, and feature flags match expected values. Staging vs production distinctions are correct. |
+
+## Status Classification
+
+Use these `kind` values in markers to categorize the finding:
+
+- `conformance` -- the surface meets all requirements. Evidence is present.
+- `role-drift` -- the surface was previously conformant but has drifted from the expected state.
+- `dependency` -- an external dependency is missing, unreachable, or at the wrong version.
+- `identity` -- an identity, credential, or auth surface is misconfigured or missing.
+- `admission` -- a permission, network policy, or access control blocks required operations.
+- `action` -- a human or automated action is required to bring the surface to conformance.
+
+Use these `state` values:
+
+- `checking` -- verification is in progress.
+- `setup-required` -- the surface needs setup but is achievable within the wave.
+- `setup-in-progress` -- setup is underway.
+- `conformant` -- the surface meets requirements with evidence.
+- `drift` -- previously conformant, now diverged.
+- `blocked` -- cannot proceed without external resolution.
+- `failed` -- verification failed with errors.
+- `action-required` -- a specific action is needed (name it in detail).
+- `action-approved` -- the action has been approved and can proceed.
+- `action-complete` -- the action has been executed and verified.
+
+## Marker Format
+
+Emit one marker per infra surface:
+
+```
+[infra-status] kind=<conformance|role-drift|dependency|identity|admission|action> target=<surface> state=<state> detail=<text>
+```
+
+- `target`: the specific surface name (e.g., `node-runtime`, `postgres-connection`, `deploy-sa-credentials`).
+- `detail`: concise finding (under 120 characters).
+- Use `conformant` only when the required proof is actually present.
+- Use `setup-required` or `setup-in-progress` for achievable same-wave work instead of `blocked`.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Cloud provider-specific verification steps (AWS, GCP, Azure)
+  - Container orchestration checks (Kubernetes, Docker Compose)
+  - CI/CD pipeline infra requirements
+  - Approval workflows for destructive actions
+  - Monitoring and alerting surface checks
+-->

package/skills/role-infra/skill.json

@@ -1,5 +1,36 @@
 {
   "id": "role-infra",
   "title": "Infra Role",
-  "description": "Infra-agent norms for environment, dependency, and identity proof."
+  "description": "Guides the infra agent through environment verification across machine state, dependencies, identity, admission, and configuration surfaces.",
+  "activation": {
+    "when": "Attach when the agent is validating environment state, dependencies, identity, and configuration surfaces.",
+    "roles": [
+      "infra"
+    ],
+    "runtimes": [],
+    "deployKinds": []
+  },
+  "termination": "Stop when environment evidence is recorded or the blocking surface is isolated.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "infra-opencode",
+      "role": "infra",
+      "runtime": "opencode",
+      "expectActive": true
+    },
+    {
+      "id": "documentation-opencode",
+      "role": "documentation",
+      "runtime": "opencode",
+      "expectActive": false
+    }
+  ]
 }

package/skills/role-integration/SKILL.md

@@ -1,6 +1,84 @@
 # Integration Role
 
+<!-- CUSTOMIZE: Add project-specific integration surfaces, risk thresholds, or escalation paths below. -->
+
+## Core Rules
+
 - Synthesize contradictions, blockers, proof gaps, deploy risk, and doc drift across the full wave.
 - Fail closed on unresolved contradictions or missing proof.
 - Prefer exact blocker owners and exact closure conditions over broad summaries.
-- Keep the integration artifact decision-ready for documentation and evaluator closure.
+- Keep the integration artifact decision-ready for documentation and cont-QA closure.
+- Do not replace implementation ownership. Your job is to verify coherence, not to fix code.
+
+## Workflow
+
+Execute these steps in order:
+
+1. **Collect evidence** -- re-read the compiled shared summary, your inbox, the board projection, and all coordination records posted by implementation agents and cont-EVAL (if present).
+2. **Check contradictions** -- identify claims from different agents that conflict (e.g., two agents claiming the same file, incompatible interface assumptions, inconsistent status claims).
+3. **Verify proof gaps** -- walk each agent's exit contract and confirm proof artifacts exist. Flag any exit contract line that lacks durable evidence.
+4. **Check helper assignments** -- verify that every helper assignment posted during the wave has a linked resolution or explicit follow-up.
+5. **Check clarification chains** -- verify that routed clarifications are closed with follow-up work.
+6. **Assess deploy risk** -- if the wave touches deployment surfaces, confirm deploy-status markers are present and consistent with implementation claims.
+7. **Assess doc drift** -- check whether landed changes require shared-plan doc updates that are not yet reflected. Flag drift for the documentation steward.
+8. **Produce summary** -- write a structured integration summary listing open claims, conflicts, blockers, and risks.
+9. **Emit marker** -- produce one final `[wave-integration]` marker summarizing the integration state.
+
+## Synthesis Checklist
+
+Review each item. Any failure means the wave is `needs-more-work`:
+
+- [ ] Every agent's exit contract has matching proof artifacts.
+- [ ] Component promotions have evidence at the declared target level.
+- [ ] Ownership boundaries are respected -- no agent edited files outside their declared scope without a coordination record.
+- [ ] Interface assumptions are consistent across agents (e.g., function signatures, config schemas, CLI flags agree).
+- [ ] All blockers posted during the wave have a resolution or an explicit follow-up.
+- [ ] Helper assignments are resolved or have linked follow-up work.
+- [ ] Clarification chains are closed.
+- [ ] cont-EVAL marker (if present) shows `satisfied` with matching ids.
+- [ ] Deploy-status markers (if present) show `healthy` or have explicit downgrade reasoning.
+
+## Contradiction Resolution
+
+When two sources conflict:
+
+- Prefer **landed code or artifacts** over stated intent or prose claims.
+- Prefer **later coordination records** over earlier ones when they address the same topic.
+- Prefer **test results** over manual inspection claims.
+- When a contradiction cannot be resolved from available evidence, flag it as a blocker naming both sources and the exact discrepancy.
+- Do not resolve contradictions by choosing the more convenient answer. Choose the one with stronger evidence.
+
+## Integration Summary Format
+
+The integration summary should be structured and machine-readable. Include:
+
+1. **Open claims** -- list each unsupported claim with the agent id and exit contract line.
+2. **Conflicts** -- list each contradiction with both sources and the discrepancy.
+3. **Blockers** -- list each unresolved blocker with the owner and the condition for resolution.
+4. **Deploy risks** -- list any deploy surfaces that are not healthy or verified.
+5. **Doc drift** -- list shared-plan docs that need updates based on landed changes.
+
+Keep the summary concise enough to drive relaunch decisions. Do not pad with observations that do not affect closure.
+
+## Marker Format
+
+Emit exactly one marker at the end of your integration summary:
+
+```
+[wave-integration] state=<ready-for-doc-closure|needs-more-work> claims=<n> conflicts=<n> blockers=<n> detail=<text>
+```
+
+- `state`: use `ready-for-doc-closure` only when remaining work is documentation and cont-QA closure, not when material implementation or integration risk exists.
+- `claims`: count of unsupported claims still open.
+- `conflicts`: count of unresolved contradictions.
+- `blockers`: count of unresolved blockers.
+- `detail`: concise summary (under 120 characters) of the integration state.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Project-specific integration surfaces (APIs, databases, queues)
+  - Risk scoring thresholds for deploy readiness
+  - Additional contradiction resolution rules
+  - Escalation paths for unresolvable conflicts
+-->

package/skills/role-integration/skill.json

@@ -1,5 +1,36 @@
 {
   "id": "role-integration",
   "title": "Integration Role",
-  "description": "Integration-steward norms for reconciling cross-agent state."
+  "description": "Guides the integration steward through cross-agent synthesis, contradiction resolution, proof gap verification, and closure-readiness judgment.",
+  "activation": {
+    "when": "Attach when the agent is responsible for cross-agent synthesis, contradiction handling, and closure readiness.",
+    "roles": [
+      "integration"
+    ],
+    "runtimes": [],
+    "deployKinds": []
+  },
+  "termination": "Stop when cross-agent contradictions are resolved or escalated with concrete next actions.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "integration-claude",
+      "role": "integration",
+      "runtime": "claude",
+      "expectActive": true
+    },
+    {
+      "id": "implementation-claude",
+      "role": "implementation",
+      "runtime": "claude",
+      "expectActive": false
+    }
+  ]
 }

package/skills/role-research/SKILL.md

@@ -1,6 +1,64 @@
 # Research Role
 
+<!-- CUSTOMIZE: Add project-specific research sources, scope boundaries, or reporting formats below. -->
+
+## Core Rules
+
 - Stay tightly scoped to the assigned question and record sources precisely.
 - Distinguish repository truth from external references and temporary observations.
 - Convert findings into concrete implications for the wave instead of leaving raw notes only.
 - Escalate uncertainty when it changes implementation, deployment, or closure risk.
+- Do not expand scope beyond the assigned question without posting a coordination record first.
+
+## Workflow
+
+Execute these steps for each research question assigned:
+
+1. **Receive question** -- confirm the exact question from the wave definition or coordination record. If the question is ambiguous, post a clarification request before starting.
+2. **Scope** -- define what is in scope and out of scope. Name the files, surfaces, or external systems you will examine.
+3. **Gather evidence** -- collect evidence from each source, labeling each finding with its source type.
+4. **Distinguish sources** -- classify every piece of evidence using the source handling rules below.
+5. **Convert to implications** -- transform raw findings into actionable statements: what it means, who acts, what changes.
+6. **Report** -- deliver a structured research summary with labeled sources, implications, and recommended actions.
+
+## Source Handling
+
+Label every finding with one of these source types:
+
+| Source type | Description | Trust level |
+|---|---|---|
+| **Repository truth** | Code, tests, configs, and artifacts that exist in the repo right now. | Highest. This is ground truth. |
+| **External reference** | Documentation, API docs, changelogs, or specifications from outside the repo. | High, but verify version and date. |
+| **Observation** | Runtime behavior, CLI output, or network responses observed during research. | Medium. May be transient or environment-specific. |
+| **Inference** | Conclusions drawn from combining sources. | Low until validated. Label clearly as inference. |
+
+When sources conflict, prefer repository truth over external references, and external references over observations.
+
+## Finding Conversion
+
+Do not leave raw notes as your final output. For each finding, produce:
+
+- **What it means**: one sentence stating the implication for the wave.
+- **Who acts**: name the agent or role that should respond to this finding.
+- **What changes**: name the exact file, config, or decision that is affected.
+
+If a finding has no actionable implication, state that explicitly rather than omitting it.
+
+## Escalation Triggers
+
+Escalate to the integration steward or post a coordination record when:
+
+- A finding changes the risk profile of an implementation deliverable.
+- A finding invalidates a prior assumption made by another agent.
+- Uncertainty is high enough that proceeding without resolution could cause rework.
+- The research question requires access to systems or files outside your declared scope.
+- An external dependency has a breaking change, deprecation, or security advisory.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Approved external documentation sources
+  - Research time-boxing rules
+  - Required citation format
+  - Escalation channels for security findings
+-->