@jinn-network/client 0.1.2 → 0.1.3-canary.262e5cda

package/plugins/claude-code-learner/skills/coordinator/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: coordinator
+description: Use when running a Jinn restoration intent end-to-end. Sequences the seven-phase pipeline (Orient → Strategize → Plan → Execute → Debrief → Improve → Memory consolidation) by loading each phase's skill in order.
+allowed-tools: Bash, Read, Write, Skill
+---
+
+# Coordinator — claude-code-learner entry point
+
+You are running one Jinn restoration intent end-to-end. This skill is the entry point. Each phase's skill is loaded into your session in turn; each phase skill does its own thin orchestration — meaning each phase skill's job is to launch a specialized subagent via the Agent tool and collect its output, not to do the deep reasoning itself.
+
+## Inputs (from the daemon)
+
+- `intent` — `{ id, description, kind, window: { startTs, endTs }, spec, eligibility? }`
+- `workingDir` — ephemeral; the engine harvests for delivery when you return
+- `implStateDir` — operator-private durable self; persists across runs
+- `msUntilEndTs` — function returning remaining time in the window
+- An abort signal that fires at `window.endTs`
+
+## Boot
+
+The session-start hook (`hooks/session-start`) has already run with `IMPL_STATE_DIR` set, so:
+- `implStateDir` is a git repo
+- The claude-code-learner git author identity is configured
+- HEAD sha is the implStateDir state at run start
+
+Capture it for the constitution span:
+
+```bash
+IMPL_STATE_DIR_SHA=$(git -C "$IMPL_STATE_DIR" rev-parse HEAD)
+SKILL_BUNDLE_CID=$(find "${CLAUDE_PLUGIN_ROOT:-$PLUGIN_ROOT}" -type f \( -name '*.md' -o -name '*.sh' -o -name '*.mjs' \) | sort | xargs sha256sum | sha256sum | cut -d' ' -f1)
+```
+
+The plugin root is provided by Claude Code as `${CLAUDE_PLUGIN_ROOT}`. Other harnesses may set `$PLUGIN_ROOT` from their session-start hook (the claude-code-learner hook does both for portability — sets and exports `PLUGIN_ROOT`). If neither is set, hash the loaded skills from their loaded paths.
+
+Write `workingDir/.coordinator/boot.json` (downstream phases — particularly Strategize — read it for the constitution span). The shape is:
+
+```json
+{
+  "implStateDirShaAtStart": "<git HEAD sha of implStateDir at run start>",
+  "skillBundleCid": "sha256:<plugin bundle digest>",
+  "intentId": "<intent.id>",
+  "windowEndTs": <window.endTs as milliseconds since epoch>
+}
+```
+
+The daemon hands you `intent`, `workingDir`, and `implStateDir` as session inputs (not POSIX env vars). Bind them to the variables this section uses, then write the file:
+
+```bash
+# Bind session inputs into shell variables (substitute your harness's
+# mechanism — e.g., values pulled from the initial prompt context or a
+# harness-provided JSON input):
+WORKING_DIR="<workingDir from session inputs>"
+INTENT_ID="<intent.id from session inputs>"
+WINDOW_END_TS="<intent.window.endTs from session inputs>"
+
+mkdir -p "$WORKING_DIR/.coordinator"
+cat > "$WORKING_DIR/.coordinator/boot.json" <<EOF
+{
+  "implStateDirShaAtStart": "$IMPL_STATE_DIR_SHA",
+  "skillBundleCid": "sha256:$SKILL_BUNDLE_CID",
+  "intentId": "$INTENT_ID",
+  "windowEndTs": $WINDOW_END_TS
+}
+EOF
+```
+
+`windowEndTs` is the intent window's end timestamp in milliseconds since epoch.
+
+## Pipeline
+
+*Phase-range hint:* if the env var `JINN_CLAUDE_CODE_LEARNER_PHASE_RANGE` is set, run only the corresponding subset:
+- `all` (or unset) — run all seven phases.
+- `pre-execute` — run only phases 1–3 (Orient, Strategize, Plan), then return. The daemon-side wrapper will run Execute itself and invoke the coordinator again with `post-execute`.
+- `post-execute` — run only phases 5–7 (Debrief, Improve, Memory consolidation). The daemon-side wrapper has already populated `workingDir/.execute/` from a kind-specific specialist before invoking this pass.
+
+This protocol exists so the daemon's first-match wrapper can wrap kind-specific specialist Execute paths in the learning envelope without the specialist needing to know about the wrapper.
+
+For each phase below, in order:
+
+1. Load the phase skill via the `Skill` tool. Skills are namespaced by plugin: invoke as `claude-code-learner:<phase-name>` (e.g., `Skill claude-code-learner:orient`).
+2. The skill loads into your session; follow its instructions. It will typically launch one or more specialized subagents via the Agent tool, collect their outputs, and write artifacts under `workingDir/.<phase>/`.
+3. Append a JSONL entry to `workingDir/.coordinator/log.jsonl` after each phase: `{ ts, phase, status, summary }`.
+
+Phases in order (full skill names shown):
+
+1. `claude-code-learner:orient` — gather intent + world-state + history
+2. `claude-code-learner:strategize` — pick approach, freeze success criteria + timing posture
+3. `claude-code-learner:plan` — concrete steps, optionally time-anchored
+4. `claude-code-learner:execute` — walk plan, spawn step-workers, decide stuck
+5. `claude-code-learner:debrief` — post-execution analysis
+6. `claude-code-learner:improve` — mutate `implStateDir`, commit
+7. `claude-code-learner:memory-consolidation` — curate, separate commit
+
+## Plug-in slot registry
+
+If `workingDir/.coordinator/slots.json` exists, the daemon has supplied a Path 1 plug-in registry (see spec/2026-04-30-plug-in-surface.md §4). Phase skills consult their relevant slot category as they run; the coordinator itself only needs to surface the `hooks` slot.
+
+## Plug-in hooks
+
+Read `workingDir/.coordinator/slots.json` (if present). For each `hooks[]` entry, retain it for invocation:
+
+- `session-start` hooks run **once** before the first phase. The bundled `hooks/session-start` shell hook already ran during boot — these are *additional* hooks the plug-in author registered.
+- `pre-phase` / `post-phase` hooks run before / after each phase. If `slot.phase` is set, only run for that phase.
+- `session-end` hooks run after `memory-consolidation` (the last phase), regardless of failure.
+
+Invoke each hook via `Bash`: `bash <packageRoot>/<entry>` with environment variables set:
+
+- `JINN_INTENT_ID`, `JINN_INTENT_KIND`
+- `JINN_PHASE` (for `pre-phase` / `post-phase` only)
+- `JINN_WORKING_DIR`, `JINN_IMPL_STATE_DIR`
+
+Failures in hooks log a warning to `workingDir/.errors/hooks.log` but do not abort the session. The coordinator's failure handling continues unchanged.
+
+## Constitution span
+
+After Strategize, read `workingDir/.strategize/constitution.json` and emit its fields as attributes on a `jinn.state_transition` span. If your harness exposes an OTel tracer, do this; otherwise the file itself is the constitution record (Debrief reads it from there).
+
+## Returning
+
+When the pipeline finishes — whether all seven phases completed cleanly, an abort signal fired, or a phase reported failure — return. The Jinn daemon's walkArtifacts packaging handles delivery. Never modify anything outside `implStateDir/**` or `workingDir/**`.
+
+## Failure handling
+
+- Within Execute: that skill judges `continue / retry-step / replan / abort` per its own rules.
+- Execute reporting `abort` is not a coordinator-level abort — continue to Debrief / Improve / Memory consolidation as normal so partial work is analyzed and curated. The Execute skill writes `workingDir/.errors/execute.json` itself.
+- Other phases: if a phase reports a hard problem, write `workingDir/.errors/<phase>.json` and abort the pipeline. Still invoke `memory-consolidation` so partial work gets curated.
+- Abort signal fired (window expired): stop the current phase cleanly, write `workingDir/.errors/abort.json`, invoke `memory-consolidation`, return.
+
+## Cross-reference
+
+Spec: `docs/superpowers/specs/2026-04-23-default-learning-restorer-design.md` v1.1, sections §2, §10.

package/plugins/claude-code-learner/skills/debrief/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: debrief
+description: Use when the coordinator reaches the Debrief phase. Optionally launch explorer subagents for cross-operator / outcome reads, then launch one analyst subagent with all evidence to produce the analysis Improve consumes.
+allowed-tools: Bash, Read, Write, Agent
+---
+
+# Debrief skill
+
+Mirrors Orient — gather + sense-make in hindsight. You may launch explorers (for cross-operator reads or fresh world-state probes) and always launch the analyst.
+
+## Inputs
+
+- All `workingDir/.<prior-phase>/` outputs through Execute
+- Strategy + constitution from `workingDir/.strategize/`
+- Plan from `workingDir/.plan/`
+- `implStateDir/runs/` for own history
+- The intent
+
+## Optional: launch explorers
+
+If the operator's policy enables cross-operator reads or fresh-world-state probes, spawn `explorer` subagents in parallel for each post-execution topic:
+
+- `outcome-probe` — re-pull venue / market / on-chain state to see post-execution outcome
+- `cross-operator-comparison` — knowledge-tree query for similar runs by other operators (only if policy allows)
+
+Same Agent-tool spawn pattern as Orient. Outputs land under `workingDir/.debrief/<topic>.json`.
+
+## Plug-in topic explorers
+
+In addition to the topics above, consult `workingDir/.coordinator/slots.json` (if present). For each entry in `topicExplorers` matching `slot.phase === "debrief"` AND (`slot.scope` absent OR `intent.spec.kind` ∈ `slot.scope.matchKinds`), treat it as an additional topic to gather. Topic name is `slot.topic`; explorer agent is at `<entry.packageRoot>/<entry.slot.entry>`. Inputs match the bundled explorer (topic, intent, scope, workingDir, implStateDir, outputPath = `workingDir/.debrief/<topic>.json`, msUntilEndTs). Topic-name collisions: a plug-in's explorer replaces the bundled fan-out for that topic; surface a one-line note in the analyst's input bundle.
+
+## Consult slot registry
+
+Before spawning the bundled analyst, check `workingDir/.coordinator/slots.json` (if present) for a `phase-agent-override` entry where `slot.phase === "debrief"` AND `slot.agent === "analyst"` AND (`slot.scope` absent OR `intent.spec.kind` ∈ `slot.scope.matchKinds`). If a match exists, spawn the agent at `<entry.packageRoot>/<entry.slot.entry>` with the same inputs as the bundled analyst. Otherwise proceed with the bundled `analyst` agent.
+
+## Launch the analyst
+
+```
+Use the Agent tool to spawn a fresh-context subagent with role `analyst`.
+Pass it inputs:
+  intent             = <copy of intent>
+  strategyPath       = workingDir/.strategize/strategy.json
+  constitutionPath   = workingDir/.strategize/constitution.json
+  planPath           = workingDir/.plan/plan.json
+  executeSummaryPath = workingDir/.execute/summary.json
+  executeLogPath     = workingDir/.execute/log.jsonl
+  orientSummaryPath  = workingDir/.orient/summary.json
+  debriefExplorerPaths = [workingDir/.debrief/<topic>.json, ...]
+  ownHistoryPath     = implStateDir/runs/index.json (or null)
+  workingDir         = <path>
+  implStateDir       = <path, read-only>
+  outputPath         = workingDir/.debrief/analysis.json
+  msUntilEndTs       = <current value>
+The subagent loads its `analyst` role and writes analysis.json. Return its summary.
+```
+
+## After it returns
+
+Verify `workingDir/.debrief/analysis.json` exists. If not, write `workingDir/.errors/debrief.json` and abort.
+
+Return to the coordinator: a one-paragraph plain-English summary plus the path to `analysis.json`.
+
+## Boundaries
+
+- Do not change success criteria — frozen in Strategize
+- Do not modify `implStateDir` — Improve does that
+- Do not invent recommendations — every recommendation must be grounded in the evidence
+
+## Cross-reference
+
+Spec: §4.5.

package/plugins/claude-code-learner/skills/execute/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: execute
+description: Use when the coordinator reaches the Execute phase. Walk the plan, launch one step-worker subagent per work step, honor wait steps, decide at runtime when stuck.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, Skill
+---
+
+# Execute skill
+
+Walk the plan and drive it. Workers are spawned by you (the coordinator session via this skill); they do not nest further.
+
+## Inputs
+
+- `workingDir/.plan/plan.json` — the steps
+- `workingDir/.strategize/strategy.json` — success criteria + timing posture
+- `workingDir/.orient/summary.json` — grounding
+- The intent + window + remaining time budget
+
+## Consult slot registry
+
+Before spawning the bundled `step-worker`, check `workingDir/.coordinator/slots.json` (if present) for a `phase-agent-override` entry where `slot.phase === "execute"` AND `slot.agent === "step-worker"` AND (`slot.scope` absent OR `intent.spec.kind` ∈ `slot.scope.matchKinds`). If a match exists, each step-worker spawn in the loop below uses the override agent at `<entry.packageRoot>/<entry.slot.entry>` instead of the bundled `step-worker`. Inputs are unchanged. See spec/2026-04-30-plug-in-surface.md §4 for slot routing rules.
+
+## Walk the plan
+
+For each step in order, respecting `concurrency` markings:
+
+### Work steps
+
+Spawn a `step-worker` subagent via the Agent tool:
+
+```
+Use the Agent tool to spawn a fresh-context subagent with role `step-worker`.
+Pass it inputs:
+  stepSpec     = <the entire step object from plan.json>
+  intent       = <copy of intent>
+  workingDir   = <path>
+  implStateDir = <path, read-only>
+  msUntilEndTs = <current value>
+```
+
+For parallel-batch steps (steps sharing a `concurrency: parallel-batch-X` label), spawn the whole batch concurrently if your harness supports it; wait for all to return before advancing.
+
+After a worker returns:
+- The worker's self-reported `status` and `blockers` are evidence; the authoritative verdict is your re-check of the step's `successSignal` against actual outputs on disk.
+- Check `successSignal` — did the step succeed?
+- If yes: append to `workingDir/.execute/log.jsonl` (carrying the worker's `status` and `blockers` into the log entry) and advance.
+- If no: see "When stuck."
+
+### Wait steps
+
+Use the harness's wait primitive (per spec §8 harness-adapter contract). Plan-emitted wait steps may include any combination of `durationMs`, `untilTs`, and `condition`; treat absent and explicit `null` identically as "not set." When multiple wakers are set, wake on the first to fire (per spec §5: `wait` wakes when any of duration / deadline / condition fires). The abort signal from the daemon (`window.endTs`) always overrides any wait.
+
+### When stuck
+
+When a step fails its success signal or a worker returns without expected outputs, judge:
+
+- **Continue** — accept partial; advance.
+- **Retry-step** — spawn a fresh worker for the same step. Cap at 2 retries unless step `abortCondition` says otherwise.
+- **Replan** — archive the current plan and re-invoke the plan skill, then continue Execute on the new plan. Concretely: rename `workingDir/.plan/plan.json` to `workingDir/.plan/plan-v<N>.json` where N is the next unused integer (start at 1), then load `Skill claude-code-learner:plan` again. The plan skill writes a fresh `plan.json` based on what's now in `workingDir/` (including the archived prior plans, the execute log up to the failure, and a new `workingDir/.plan/replan-context.json` you write with `{ failedStepId, blockers, partialOutputs[] }`). Continue Execute on the new `plan.json`.
+- **Abort** — write `workingDir/.errors/execute.json` with failure context; exit Execute. Coordinator continues to Debrief / Improve / Memory consolidation so partial work is harvested.
+
+Explain your judgment in `workingDir/.execute/log.jsonl`.
+
+## Outputs
+
+Throughout the phase:
+- `workingDir/.execute/log.jsonl` — one entry per step boundary: `{ ts, stepId, decision, summary, retryCount, workerStatus, workerBlockers }`. `workerStatus` and `workerBlockers` come directly from the step-worker's return shape so Debrief sees both the worker's self-assessment and Execute's verdict.
+- Per-step outputs as the plan declared
+
+At end:
+- `workingDir/.execute/summary.json`:
+  ```json
+  {
+    "stepsCompleted": ["step-1", "step-2"],
+    "stepsFailed": [],
+    "decisions": ["continue", "retry-step", "continue"],
+    "elapsedMs": 0,
+    "returnReason": "all-steps-completed | early-return | hold-and-revise-window-end | continuous-observation-window-end | abort"
+  }
+  ```
+
+## Boundaries
+
+- Do not invoke Strategize — strategy is frozen
+- Do not write to `implStateDir` — Improve does that
+- Do not run Debrief / Improve / Memory consolidation — coordinator does that next
+- Do not call wait for arbitrarily long with no plan justification
+- Do not spawn agents that themselves spawn agents (your workers are one level deep)
+
+## Cross-reference
+
+Spec: §4.4, §5.

package/plugins/claude-code-learner/skills/improve/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: improve
+description: Use when the coordinator reaches the Improve phase. Launch one promoter subagent with the analysis; commit each accepted mutation to implStateDir as a separate git commit; emit promotion records.
+allowed-tools: Bash, Read, Write, Edit, Agent
+---
+
+# Improve skill
+
+Launch the promoter; commit its mutations. Changes take effect NEXT run.
+
+## Inputs
+
+- `workingDir/.debrief/analysis.json`
+- `implStateDir/policy.json` if present (operator policy on what Improve may touch)
+- `implStateDir/` (current durable self)
+
+## Consult slot registry
+
+Before spawning the bundled promoter, check `workingDir/.coordinator/slots.json` (if present) for a `phase-agent-override` entry where `slot.phase === "improve"` AND `slot.agent === "promoter"` AND (`slot.scope` absent OR `intent.spec.kind` ∈ `slot.scope.matchKinds`). If a match exists, spawn the agent at `<entry.packageRoot>/<entry.slot.entry>` with the same inputs as the bundled promoter. Otherwise proceed with the bundled `promoter` agent.
+
+## Launch the promoter
+
+```
+Use the Agent tool to spawn a fresh-context subagent with role `promoter`.
+Pass it inputs:
+  analysisPath       = workingDir/.debrief/analysis.json
+  policyPath         = implStateDir/policy.json (or null)
+  implStateDir       = <path, read-write for the promoter>
+  workingDir         = <path>
+  outputDir          = workingDir/.improve/
+  msUntilEndTs       = <current value>
+The promoter writes mutations directly into implStateDir, commits each as
+a separate git commit (the session-start hook configured the author
+identity already), and writes one promotion_record per mutation under
+workingDir/.improve/promotions/.
+```
+
+## After it returns
+
+Read `workingDir/.improve/summary.json`. Verify:
+- `implStateDirShaAfter` matches `git -C <implStateDir> rev-parse HEAD`
+- One `promotion_record` per accepted change
+- Operator-access requests under `workingDir/.operator-requests/` if any
+
+If anything is inconsistent, write `workingDir/.errors/improve.json` and abort.
+
+Return to the coordinator: a one-paragraph summary of what changed (or didn't) and why.
+
+## Boundaries
+
+- Do not pre-judge what to mutate — that's the promoter's reasoning
+- Do not commit yourself — the promoter commits as it goes
+- Do not modify anything outside `workingDir/.improve/` from this skill
+
+## Cross-reference
+
+Spec: §4.6, §6.2, §6.4, §7.

package/plugins/claude-code-learner/skills/memory-consolidation/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: memory-consolidation
+description: Use when the coordinator reaches the Memory consolidation phase. Launch one consolidator subagent that curates implStateDir (prune unused, revert regressions) and workingDir (set public/private boundary); commits durable curation as one separate commit.
+allowed-tools: Bash, Read, Write, Edit, Agent
+---
+
+# Memory consolidation skill
+
+Launch the consolidator; verify outputs.
+
+## Inputs
+
+- `workingDir/.debrief/analysis.json` (trend signals, regression flags)
+- `workingDir/.improve/summary.json` + `promotions/` (Improve's mutations)
+- `implStateDir/` and `workingDir/` (full)
+- `implStateDir/policy.json` (retention rules, size caps)
+
+## Consult slot registry
+
+Before spawning the bundled consolidator, check `workingDir/.coordinator/slots.json` (if present) for a `phase-agent-override` entry where `slot.phase === "memory-consolidation"` AND `slot.agent === "consolidator"` AND (`slot.scope` absent OR `intent.spec.kind` ∈ `slot.scope.matchKinds`). If a match exists, spawn the agent at `<entry.packageRoot>/<entry.slot.entry>` with the same inputs as the bundled consolidator. Otherwise proceed with the bundled `consolidator` agent.
+
+## Plug-in memory backends
+
+Also consult `slots.json.memoryBackends`. Each entry exposes MCP tools `embed(text)`, `query(vector, k)`, and `prune(maxAgeDays)` under the namespace `memory-<plugInName>` (per `client/src/restorer/impls/claude-code-learner/mcp-config.ts`). During curation, if a backend is the policy match for this kind (consult `implStateDir/policy.json`'s `memoryBackend.default` or `memoryBackend.perKind[kind]`), call `mcp__memory-<plugInName>__embed` to index relevant artifacts and `mcp__memory-<plugInName>__query` to retrieve analogous prior cases. Multiple backends can coexist; each is a distinct MCP namespace. If no `memoryBackends` entries are present, fall back to the bundled file-based curation (the existing behaviour).
+
+## Launch the consolidator
+
+```
+Use the Agent tool to spawn a fresh-context subagent with role `consolidator`.
+Pass it inputs:
+  analysisPath        = workingDir/.debrief/analysis.json
+  improveSummaryPath  = workingDir/.improve/summary.json
+  improvePromotionsDir = workingDir/.improve/promotions/
+  policyPath          = implStateDir/policy.json (or null)
+  implStateDir        = <path, read-write>
+  workingDir          = <path, read-write>
+  outputPath          = workingDir/.memory-consolidation/consolidation_record.json
+  msUntilEndTs        = <current value>
+The consolidator does both workstreams (durable + ephemeral), writes a
+single git commit on implStateDir for the durable curation, and produces
+the consolidation_record.
+```
+
+## After it returns
+
+Verify the consolidation_record exists. If the consolidator made a commit, `implStateDirShaAfter` must match `git -C <implStateDir> rev-parse HEAD`. If no commit was made (empty curation set), `implStateDirShaAfter` must equal `implStateDirShaBefore` and HEAD remains at that sha.
+
+Return to the coordinator: a one-paragraph summary.
+
+## Boundaries
+
+- Do not promote new content — Improve already did
+- Do not modify success criteria, plan, or analysis
+
+## Cross-reference
+
+Spec: §4.7, §6.1.

package/plugins/claude-code-learner/skills/orient/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: orient
+description: Use when the coordinator reaches the Orient phase. Decide what topics to gather; launch one explorer subagent per topic; collate findings into a summary Strategize will consume.
+allowed-tools: Bash, Read, Write, Agent
+---
+
+# Orient skill
+
+You are coordinating the Orient phase. Your only jobs are: decide what topics need gathering for this intent, launch an `explorer` subagent for each topic, and collate their results.
+
+## Inputs
+
+- The intent and paths from the coordinator session
+- `workingDir` — write findings here
+- `implStateDir` — read-only in this phase
+
+## Decide what topics to gather
+
+Choose from these typical categories; add or omit based on the intent:
+
+1. **intent-parse** — what's the goal, kind, window, spec, eligibility? Always include.
+2. **world-state** — for kinds with a venue (portfolio.v0, prediction.v0, etc.), pull current relevant state. Include if the kind has a venue.
+3. **own-history** — list prior runs of this kind by this operator. Include if `implStateDir/runs/index.json` exists or the harness exposes a knowledge-tree query.
+4. **others-history** — recent runs of this kind by other operators. Include only if `implStateDir/policy.json` sets `allowCrossOperatorReads: true` AND the harness exposes the query tool.
+
+## Plug-in topic explorers
+
+In addition to the bundled topic categories above, consult `workingDir/.coordinator/slots.json` (if present). For each entry in `topicExplorers` matching `slot.phase === "orient"` AND (`slot.scope` absent OR `intent.spec.kind` ∈ `slot.scope.matchKinds`):
+
+- Treat it as an additional topic to gather. Topic name is `slot.topic`.
+- Spawn an explorer subagent (same shape as the bundled explorer, but with the explorer-role file at `<entry.packageRoot>/<entry.slot.entry>` instead of the bundled `explorer` role).
+- Inputs to the explorer are unchanged (topic, intent, scope, workingDir, implStateDir, outputPath = `workingDir/.orient/<topic>.json`, msUntilEndTs).
+- Include the topic's results in the collation (`workingDir/.orient/summary.json`'s `topics[]` array).
+
+Topic-name collisions: if a plug-in declares a topic that matches a bundled name (`intent-parse`, `world-state`, `own-history`, `others-history`), the plug-in's explorer replaces the bundled fan-out for that topic. Surface a one-line note in `summary.json.flags`. See spec/2026-04-30-plug-in-surface.md §4.
+
+## Launch explorers
+
+For each topic chosen, spawn an `explorer` subagent via the Agent tool:
+
+```
+Use the Agent tool to spawn a fresh-context subagent with role `explorer`.
+Pass it inputs:
+  topic        = <topic name, e.g. "world-state">
+  intent       = <copy of intent>
+  scope        = <topic-specific scope; explorer's role definition explains what it expects>
+  workingDir   = <path>
+  implStateDir = <path, read-only>
+  outputPath   = workingDir/.orient/<topic>.json
+  msUntilEndTs = <current value>
+The subagent will load its `explorer` role definition, gather, write findings, return a summary.
+```
+
+Spawn explorers in parallel if your harness supports it; otherwise spawn sequentially. The explorers themselves do not spawn further agents (no nesting).
+
+## Collate
+
+After all explorers return, read each `workingDir/.orient/<topic>.json` and write `workingDir/.orient/summary.json`:
+
+```json
+{
+  "intent": { "id": "...", "kind": "...", "window": { "startTs": 0, "endTs": 0 } },
+  "topics": [
+    { "topic": "intent-parse", "artifact": "workingDir/.orient/intent-parse.json", "summary": "...", "flags": [] },
+    { "topic": "world-state", "artifact": "workingDir/.orient/world-state.json", "summary": "...", "flags": ["stale"] }
+  ],
+  "openQuestions": ["string — anything Strategize needs to know was uncertain or unavailable"]
+}
+```
+
+Return to the coordinator: a one-paragraph summary and the path to `summary.json`.
+
+## Boundaries
+
+- Do not pick an approach — Strategize's job
+- Do not write a plan — Plan's job
+- Do not execute work — Execute's job
+- Do not modify `implStateDir`
+
+## Cross-reference
+
+Spec: §4.1.

package/plugins/claude-code-learner/skills/plan/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: plan
+description: Use when the coordinator reaches the Plan phase. Launch one planner subagent with the strategy; receive the plan; persist it under workingDir/.plan/.
+allowed-tools: Bash, Read, Write, Agent
+---
+
+# Plan skill
+
+Launch the planner; persist its output.
+
+## Inputs
+
+- `workingDir/.strategize/strategy.json`
+- `workingDir/.orient/summary.json` for grounding
+- `implStateDir/plans/<kind>/` if any prior promoted plan templates
+- The intent
+- On replan: `workingDir/.plan/replan-context.json` (failure context written by Execute) and any prior `workingDir/.plan/plan-v<N>.json` archives. Read these to ground the new plan in what just failed.
+
+## Consult slot registry
+
+Before spawning the bundled planner, check `workingDir/.coordinator/slots.json` (if present) for a `phase-agent-override` entry where `slot.phase === "plan"` AND `slot.agent === "planner"` AND (`slot.scope` absent OR `intent.spec.kind` ∈ `slot.scope.matchKinds`). If a match exists, spawn the agent at `<entry.packageRoot>/<entry.slot.entry>` with the same inputs as the bundled planner. Otherwise proceed with the bundled `planner` agent. See spec/2026-04-30-plug-in-surface.md §4 for slot routing rules.
+
+## Launch the planner
+
+```
+Use the Agent tool to spawn a fresh-context subagent with role `planner`.
+Pass it inputs:
+  intent              = <copy of intent>
+  strategyPath        = workingDir/.strategize/strategy.json
+  orientSummaryPath   = workingDir/.orient/summary.json
+  priorPlanTemplatesPath = implStateDir/plans/<kind>/ (or null)
+  replanContextPath   = workingDir/.plan/replan-context.json (or null on first plan)
+  priorPlanArchives   = [workingDir/.plan/plan-v1.json, ...] (or empty on first plan)
+  workingDir          = <path>
+  implStateDir        = <path, read-only>
+  outputPath          = workingDir/.plan/plan.json
+  msUntilEndTs        = <current value>
+```
+
+## After it returns
+
+Verify `workingDir/.plan/plan.json` exists. If not, write `workingDir/.errors/plan.json` and abort.
+
+Return to the coordinator: a one-line summary ("plan with N steps, M parallel batches, K wait checkpoints") and the path to `plan.json`.
+
+## Boundaries
+
+- Do not change success criteria or timing posture — frozen in Strategize
+- Do not execute — Execute does that
+- Do not modify `implStateDir`
+
+## Cross-reference
+
+Spec: §4.3, §5.

package/plugins/claude-code-learner/skills/strategize/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: strategize
+description: Use when the coordinator reaches the Strategize phase. Launch one strategist subagent with the Orient summary; receive a strategy + constitution; persist them under workingDir/.strategize/.
+allowed-tools: Bash, Read, Write, Agent
+---
+
+# Strategize skill
+
+Launch the strategist; persist its outputs.
+
+## Inputs
+
+- `workingDir/.orient/summary.json` (and per-topic files for context)
+- `implStateDir/strategies/<kind>/` if any prior promoted strategies exist
+- The intent
+
+## Consult slot registry
+
+Before spawning the bundled strategist, check whether an installed Path 1 plug-in declares a `phase-agent-override` for this phase + agent + intent kind. Read `workingDir/.coordinator/slots.json` if present. If absent, no overrides — proceed with the bundled `strategist` agent.
+
+When present, look in `phaseAgentOverrides` for an entry where `slot.phase === "strategize"` AND `slot.agent === "strategist"` AND (`slot.scope` is absent OR `intent.spec.kind` is in `slot.scope.matchKinds`). The first match wins (the registry already enforces last-installed-wins on collisions; see spec/2026-04-30-plug-in-surface.md §8 open question 8).
+
+If a match exists, the agent file to spawn is at `<entry.packageRoot>/<entry.slot.entry>` — substitute that path for the bundled `claude-code-learner:strategist` reference in the next step. The override agent receives the same inputs as the bundled strategist (intent, orientSummaryPath, priorStrategiesPath, outputDir, skillBundleCid, implStateDirShaAtStart, msUntilEndTs).
+
+If no match, proceed with the bundled strategist as before.
+
+## Launch the strategist
+
+```
+Use the Agent tool to spawn a fresh-context subagent with role `strategist`.
+Pass it inputs:
+  intent                 = <copy of intent>
+  orientSummaryPath      = workingDir/.orient/summary.json
+  priorStrategiesPath    = implStateDir/strategies/<kind>/   (or null if absent)
+  workingDir             = <path>
+  implStateDir           = <path, read-only>
+  outputDir              = workingDir/.strategize/
+  skillBundleCid         = <from coordinator boot>
+  implStateDirShaAtStart = <from coordinator boot>
+  msUntilEndTs           = <current value>
+The subagent loads its `strategist` role, does the divergent/convergent
+selection, and writes strategy.json + constitution.json. Return its summary.
+```
+
+## After it returns
+
+Verify both files exist:
+- `workingDir/.strategize/strategy.json`
+- `workingDir/.strategize/constitution.json`
+
+If either is missing, write `workingDir/.errors/strategize.json` with the failure context and abort.
+
+Return to the coordinator: a one-paragraph summary of the chosen approach + success criteria + timing posture, plus paths to both files.
+
+## Boundaries
+
+- Do not generate the strategy yourself — that's the strategist agent's job in fresh context
+- Do not modify `implStateDir`
+- Never run a second strategist after the first has committed (no re-strategizing mid-run)
+
+## Cross-reference
+
+Spec: §4.2, §10.