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

package/dist/templates/plug-in/phase-agent-override/README.md.tmpl

@@ -0,0 +1,30 @@
+# {{packageName}}
+
+Path 1 Jinn plug-in. Overrides the bundled claude-code-learner
+`{{agent}}` agent during the `{{phase}}` phase.
+
+## Install (operator)
+
+```bash
+yarn add {{packageName}}
+jinn plug-ins add {{packageName}} --entry $(node -p "require.resolve('{{packageName}}/package.json').replace(/\/package\.json$/, '')")
+```
+
+The daemon picks the override up at the next session-start: if the
+intent kind is in scope, the `{{phase}}` skill spawns this agent
+instead of the bundled `{{agent}}`.
+
+## Develop
+
+```bash
+yarn install
+yarn test
+```
+
+Edit `agents/{{phaseAgentName}}.md` — the override receives the same inputs as the
+bundled agent.
+
+## Spec
+
+`spec/2026-04-30-plug-in-surface.md` §4. Slot type:
+`phase-agent-override`.

package/dist/templates/plug-in/phase-agent-override/agents/agent.md.tmpl

@@ -0,0 +1,26 @@
+---
+name: {{phaseAgentName}}
+description: Override for the bundled claude-code-learner {{agent}} agent in the {{phase}} phase.
+---
+
+# {{phaseAgentName}}
+
+This is a stub override agent. Replace the body below with your custom
+{{phase}}/{{agent}} logic. The override receives the same inputs as the
+bundled agent — see the bundled
+`client/plugins/claude-code-learner/agents/{{agent}}.md` for the contract.
+
+## Inputs
+
+(Document what your override expects here.)
+
+## Outputs
+
+(Document what your override produces here.)
+
+## Notes
+
+- Inherits trust from the harness — no per-plug-in capability allow-list.
+- Phase skills route to this override only when `intent.spec.kind` matches
+  the `scope.matchKinds` declared in `jinn-plugin.json` (or unconditionally
+  when `scope` is absent).

package/dist/templates/plug-in/phase-agent-override/gitignore.tmpl

@@ -0,0 +1,3 @@
+node_modules/
+*.log
+.DS_Store

package/dist/templates/plug-in/phase-agent-override/jinn-plugin.json.tmpl

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Phase-agent override for {{phase}}/{{agent}}.",
+  "compatibility": {
+    "claudeCodeLearner": ">=0.1.0"
+  },
+  "slots": [
+    {
+      "type": "phase-agent-override",
+      "phase": "{{phase}}",
+      "agent": "{{agent}}",
+      "entry": "agents/{{phaseAgentName}}.md"
+    }
+  ]
+}

package/dist/templates/plug-in/phase-agent-override/package.json.tmpl

@@ -0,0 +1,14 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn Path 1 plug-in: phase-agent override for {{phase}}/{{agent}}.",
+  "type": "module",
+  "files": ["agents/", "jinn-plugin.json", "README.md"],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/dist/templates/plug-in/phase-agent-override/test/manifest.test.ts.tmpl

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+describe('{{packageName}} manifest', () => {
+  it('jinn-plugin.json declares a phase-agent-override slot', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(__dirname, '..', 'jinn-plugin.json'), 'utf8'),
+    );
+    expect(manifest.name).toBe('{{packageName}}');
+    expect(manifest.slots).toHaveLength(1);
+    expect(manifest.slots[0].type).toBe('phase-agent-override');
+    expect(manifest.slots[0].phase).toBe('{{phase}}');
+    expect(manifest.slots[0].agent).toBe('{{agent}}');
+  });
+
+  it('declared agent file exists', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(__dirname, '..', 'jinn-plugin.json'), 'utf8'),
+    );
+    const entry = manifest.slots[0].entry;
+    expect(existsSync(join(__dirname, '..', entry))).toBe(true);
+  });
+});

package/dist/templates/plug-in/skill-bundle/.claude-plugin/plugin.json.tmpl

@@ -0,0 +1,5 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Skill bundle for {{packageName}}."
+}

package/dist/templates/plug-in/skill-bundle/README.md.tmpl

@@ -0,0 +1,28 @@
+# {{packageName}}
+
+Path 1 Jinn plug-in. Bundles additional Claude Code skills into the
+claude-code-learner harness.
+
+## Install (operator)
+
+```bash
+yarn add {{packageName}}
+jinn plug-ins add {{packageName}} --entry $(node -p "require.resolve('{{packageName}}/package.json').replace(/\/package\.json$/, '')")
+```
+
+The daemon adds this package root to Claude Code's `--plugin-dir` list
+at session-start. Skills under `skills/` become discoverable by phase
+agents via the `Skill` tool.
+
+## Develop
+
+```bash
+yarn install
+yarn test
+```
+
+Add or replace skills under `skills/<name>/SKILL.md`.
+
+## Spec
+
+`spec/2026-04-30-plug-in-surface.md` §4. Slot type: `skill-bundle`.

package/dist/templates/plug-in/skill-bundle/gitignore.tmpl

@@ -0,0 +1,3 @@
+node_modules/
+*.log
+.DS_Store

package/dist/templates/plug-in/skill-bundle/jinn-plugin.json.tmpl

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Skill bundle: extra skills loadable by claude-code-learner.",
+  "compatibility": {
+    "claudeCodeLearner": ">=0.1.0"
+  },
+  "slots": [
+    {
+      "type": "skill-bundle",
+      "skillsDir": "skills"
+    }
+  ]
+}

package/dist/templates/plug-in/skill-bundle/package.json.tmpl

@@ -0,0 +1,14 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn Path 1 plug-in: skill bundle.",
+  "type": "module",
+  "files": ["skills/", ".claude-plugin/", "jinn-plugin.json", "README.md"],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/dist/templates/plug-in/skill-bundle/skills/example/SKILL.md.tmpl

@@ -0,0 +1,14 @@
+---
+name: example
+description: Stub skill shipped with {{packageName}}. Replace with your actual skill content.
+allowed-tools: Read, Write
+---
+
+# {{packageName}} — example skill
+
+This is a placeholder skill. Replace with the technique / playbook / tool
+your skill bundle wants to surface to phase agents.
+
+When the daemon loads this plug-in, Claude Code adds the package root to
+its `--plugin-dir` list, and skills under `skills/` become available via
+the `Skill` tool.

package/dist/templates/plug-in/skill-bundle/test/manifest.test.ts.tmpl

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+describe('{{packageName}} skill-bundle plug-in', () => {
+  it('declares a skill-bundle slot', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(__dirname, '..', 'jinn-plugin.json'), 'utf8'),
+    );
+    expect(manifest.name).toBe('{{packageName}}');
+    expect(manifest.slots[0].type).toBe('skill-bundle');
+    expect(manifest.slots[0].skillsDir).toBe('skills');
+  });
+
+  it('skills directory + Claude Code plugin manifest exist', () => {
+    expect(existsSync(join(__dirname, '..', 'skills'))).toBe(true);
+    expect(
+      existsSync(join(__dirname, '..', '.claude-plugin', 'plugin.json')),
+    ).toBe(true);
+  });
+});

package/dist/templates/plug-in/topic-explorer/README.md.tmpl

@@ -0,0 +1,24 @@
+# {{packageName}}
+
+Path 1 Jinn plug-in. Adds the topic `{{topic}}` to the bundled
+claude-code-learner `{{phase}}` phase fan-out.
+
+## Install (operator)
+
+```bash
+yarn add {{packageName}}
+jinn plug-ins add {{packageName}} --entry $(node -p "require.resolve('{{packageName}}/package.json').replace(/\/package\.json$/, '')")
+```
+
+## Develop
+
+```bash
+yarn install
+yarn test
+```
+
+Edit `agents/{{topic}}-explorer.md` to define the gathering behaviour.
+
+## Spec
+
+`spec/2026-04-30-plug-in-surface.md` §4. Slot type: `topic-explorer`.

package/dist/templates/plug-in/topic-explorer/agents/explorer.md.tmpl

@@ -0,0 +1,26 @@
+---
+name: {{topic}}-explorer
+description: Topic explorer for "{{topic}}" — runs during the {{phase}} phase, gathers findings, writes them under workingDir/.{{phase}}/{{topic}}.json.
+---
+
+# {{topic}}-explorer
+
+Topic-explorer subagent. Add your gathering logic below — the {{phase}}
+skill spawns one of these per registered topic and merges the results
+into the phase summary.
+
+## Inputs
+
+- `topic` — `"{{topic}}"`
+- `intent` — copy of the intent body
+- `scope` — topic-specific scope (you choose what to expect)
+- `workingDir` — write your findings under `workingDir/.{{phase}}/{{topic}}.json`
+- `implStateDir` — read-only
+- `outputPath` — equals `workingDir/.{{phase}}/{{topic}}.json`
+- `msUntilEndTs` — remaining time
+
+## Output
+
+Write a JSON file at `outputPath` shaped however the consumer skill
+expects. The bundled fan-out summary aggregator will include it under
+`topics[]` keyed on `topic`.

package/dist/templates/plug-in/topic-explorer/gitignore.tmpl

@@ -0,0 +1,3 @@
+node_modules/
+*.log
+.DS_Store

package/dist/templates/plug-in/topic-explorer/jinn-plugin.json.tmpl

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Topic explorer: {{topic}} during {{phase}}.",
+  "compatibility": {
+    "claudeCodeLearner": ">=0.1.0"
+  },
+  "slots": [
+    {
+      "type": "topic-explorer",
+      "phase": "{{phase}}",
+      "topic": "{{topic}}",
+      "entry": "agents/{{topic}}-explorer.md"
+    }
+  ]
+}

package/dist/templates/plug-in/topic-explorer/package.json.tmpl

@@ -0,0 +1,14 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn Path 1 plug-in: topic explorer for {{phase}}/{{topic}}.",
+  "type": "module",
+  "files": ["agents/", "jinn-plugin.json", "README.md"],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/dist/templates/plug-in/topic-explorer/test/manifest.test.ts.tmpl

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+describe('{{packageName}} manifest', () => {
+  it('jinn-plugin.json declares a topic-explorer slot', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(__dirname, '..', 'jinn-plugin.json'), 'utf8'),
+    );
+    expect(manifest.name).toBe('{{packageName}}');
+    expect(manifest.slots[0].type).toBe('topic-explorer');
+    expect(manifest.slots[0].phase).toBe('{{phase}}');
+    expect(manifest.slots[0].topic).toBe('{{topic}}');
+  });
+
+  it('declared explorer agent exists', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(__dirname, '..', 'jinn-plugin.json'), 'utf8'),
+    );
+    expect(existsSync(join(__dirname, '..', manifest.slots[0].entry))).toBe(true);
+  });
+});

package/dist/templates/restorer/alternative-harness/README.md.tmpl

@@ -0,0 +1,44 @@
+# {{packageName}}
+
+Jinn external restorer for `{{kindString}}` running the **seven-phase
+learning pipeline** (Orient -> Strategize -> Plan -> Execute -> Debrief
+-> Improve -> Memory) against a non-Claude-Code harness.
+
+This package owns the phase orchestration; the harness is a swappable
+runtime. Tests use a deterministic in-process mock harness; production
+builders swap `createMockHarness` for a real harness (Pi.dev, Codex,
+Gemini CLI, custom).
+
+## Quickstart
+
+```bash
+yarn install
+yarn test
+```
+
+## Plugging in your real harness
+
+Implement the `HarnessAdapter` interface (see `src/harness.ts`):
+
+```ts
+import type { HarnessAdapter } from '{{packageName}}';
+
+export const myHarness: HarnessAdapter = {
+  name: 'my-harness',
+  async promptForJson({ systemPrompt, userPrompt, budgetMs, abort }) {
+    // Spawn / call your harness; parse its JSON response; return.
+  },
+};
+```
+
+Then construct the restorer with your factory:
+
+```ts
+import createRestorer from '{{packageName}}';
+const impl = createRestorer(env, { harnessFactory: () => myHarness });
+```
+
+## Spec
+
+- `spec/2026-04-30-plug-in-surface.md` §3.3.3 (alternative-harness pattern).
+- `docs/superpowers/specs/2026-04-23-default-learning-restorer-design.md` §2 (phase pipeline definition).

package/dist/templates/restorer/alternative-harness/gitignore.tmpl

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+.DS_Store

package/dist/templates/restorer/alternative-harness/jinn.manifest.json.tmpl

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Alternative-harness restorer for {{kindString}}.",
+  "supportedKinds": ["{{kindString}}>=1.0.0"],
+  "entry": "./dist/index.js",
+  "package": {
+    "cid": "bafy-PLACEHOLDER",
+    "hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "capabilities": {
+    "rpc": [
+      { "chainId": {{networkChainId}}, "methods": ["eth_call", "eth_blockNumber"] }
+    ]
+  },
+  "signature": {
+    "alg": "ed25519",
+    "publicKey": "PLACEHOLDER",
+    "sig": "PLACEHOLDER"
+  }
+}

package/dist/templates/restorer/alternative-harness/package.json.tmpl

@@ -0,0 +1,26 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn external restorer running the seven-phase learning pipeline against a non-Claude-Code harness. {{kindString}} only.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist/", "jinn.manifest.json", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@jinn-network/restorer-sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/dist/templates/restorer/alternative-harness/src/coordinator.ts.tmpl

@@ -0,0 +1,50 @@
+import type {
+  RestorationContext,
+  RestorationOutput,
+} from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter } from './harness.js';
+import { runOrient } from './phases/orient.js';
+import { runStrategize } from './phases/strategize.js';
+import { runPlan } from './phases/plan.js';
+import { runExecute } from './phases/execute.js';
+import { runDebrief } from './phases/debrief.js';
+import { runImprove } from './phases/improve.js';
+import { runMemory } from './phases/memory.js';
+
+export interface CoordinatorArgs {
+  ctx: RestorationContext;
+  harness: HarnessAdapter;
+}
+
+/**
+ * Sequence the seven phases (orient, strategize, plan, execute,
+ * debrief, improve, memory). Mirrors `spec/2026-04-30-plug-in-surface.md`
+ * §3.3.3 and `docs/superpowers/specs/2026-04-23-default-learning-restorer-design.md` §2.
+ */
+export async function runCoordinator({
+  ctx,
+  harness,
+}: CoordinatorArgs): Promise<RestorationOutput> {
+  const orient = await runOrient({ ctx, harness });
+  const strategy = await runStrategize({ ctx, harness, orient });
+  const plan = await runPlan({ ctx, harness, strategy, orient });
+  const execute = await runExecute({ ctx, harness, plan, strategy });
+  const debrief = await runDebrief({ ctx, harness, execute, strategy });
+  await runImprove({ ctx, harness, debrief });
+  await runMemory({ ctx, harness, debrief });
+
+  return {
+    venueRef: { name: harness.name },
+    gating: {
+      timingPosture: strategy.timingPosture,
+      executeReturnReason: execute.returnReason,
+      debriefVerdict: debrief.successCriteriaMet,
+    },
+    informational: {
+      strategyApproach: strategy.approach,
+      planSteps: plan.steps.length,
+      stepsCompleted: execute.stepsCompleted.length,
+      stepsFailed: execute.stepsFailed.length,
+    },
+  };
+}

package/dist/templates/restorer/alternative-harness/src/harness.ts.tmpl

@@ -0,0 +1,31 @@
+// HarnessAdapter contract — the impl talks to the harness through this
+// interface. The package owns this type; it does NOT depend on
+// `claude-code-learner/types.ts` (which is internal to that package).
+//
+// Production builders implement this around their own runtime
+// (Pi.dev, Codex CLI, Gemini CLI, custom subprocess, etc.).
+
+export interface HarnessPromptArgs {
+  promptId: string;
+  systemPrompt: string;
+  userPrompt: string;
+  /** Per-phase budget in ms. Caller honours abort. */
+  budgetMs: number;
+  abort: AbortSignal;
+}
+
+export interface HarnessAdapter {
+  readonly name: string;
+
+  /**
+   * Send a prompt to the harness's underlying agent runtime; receive a
+   * structured JSON result. Used by every phase.
+   */
+  promptForJson<T>(args: HarnessPromptArgs): Promise<T>;
+
+  /**
+   * Optional: signal that a phase has finished, for harnesses that
+   * persist conversation state across calls (e.g. Pi.dev's session model).
+   */
+  closePhase?(phaseId: string): Promise<void>;
+}

package/dist/templates/restorer/alternative-harness/src/index.ts.tmpl

@@ -0,0 +1,44 @@
+import type {
+  RestorerImpl,
+  ExternalRestorerEnv,
+  RestorationContext,
+  RestorationOutput,
+} from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter } from './harness.js';
+import { runCoordinator } from './coordinator.js';
+import { createMockHarness } from './mock-harness.js';
+
+export interface AlternativeHarnessConfig {
+  /** The harness to drive. Defaults to the deterministic mock for tests. */
+  harnessFactory?: (env: ExternalRestorerEnv) => HarnessAdapter;
+}
+
+export default function createRestorer(
+  env: ExternalRestorerEnv,
+  config: AlternativeHarnessConfig = {},
+): RestorerImpl {
+  const factory = config.harnessFactory ?? createMockHarness;
+  const harness = factory(env);
+  return {
+    name: env.implName,
+    version: env.implVersion,
+    supports({ kind, type }) {
+      return kind === '{{kindString}}' && type !== 'evaluation';
+    },
+    async isReady() {
+      return env.stub
+        ? { ready: false, reason: 'stub mode' }
+        : { ready: true };
+    },
+    async run(ctx: RestorationContext): Promise<RestorationOutput> {
+      env.log({
+        level: 'info',
+        msg: 'alternative-harness.start',
+        data: { intentId: ctx.intent.id },
+      });
+      return runCoordinator({ ctx, harness });
+    },
+  };
+}
+
+export type { HarnessAdapter, HarnessPromptArgs } from './harness.js';

package/dist/templates/restorer/alternative-harness/src/mock-harness.ts.tmpl

@@ -0,0 +1,41 @@
+import type { ExternalRestorerEnv } from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter, HarnessPromptArgs } from './harness.js';
+
+/**
+ * Deterministic in-process mock harness. Returns canned per-phase
+ * shapes so tests run offline. Real builders replace this with a
+ * subprocess wrapper around their actual harness (Pi.dev, Codex, etc.).
+ */
+export function createMockHarness(_env: ExternalRestorerEnv): HarnessAdapter {
+  return {
+    name: 'mock-harness',
+    async promptForJson<T>({ promptId }: HarnessPromptArgs): Promise<T> {
+      switch (promptId) {
+        case 'orient':
+          return { topics: [{ name: 'intent-parse', summary: 'parsed' }] } as T;
+        case 'strategize':
+          return {
+            approach: 'mock approach',
+            successCriteria: 'always succeed',
+            timingPosture: 'early-return',
+          } as T;
+        case 'plan':
+          return { steps: [{ id: 's1', description: 'do the thing' }] } as T;
+        case 'execute':
+          return {
+            stepsCompleted: ['s1'],
+            stepsFailed: [],
+            returnReason: 'all-steps-completed',
+          } as T;
+        case 'debrief':
+          return { successCriteriaMet: 'yes', rationale: 'mock rationale' } as T;
+        case 'improve':
+          return { mutations: [] } as T;
+        case 'memory':
+          return { kept: 0, pruned: 0 } as T;
+        default:
+          throw new Error(`mock-harness: unknown promptId ${promptId}`);
+      }
+    },
+  };
+}

package/dist/templates/restorer/alternative-harness/src/phases/debrief.ts.tmpl

@@ -0,0 +1,28 @@
+import type { RestorationContext } from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter } from '../harness.js';
+import type { ExecuteResult } from './execute.js';
+import type { StrategyResult } from './strategize.js';
+
+export type DebriefVerdict = 'yes' | 'no' | 'partial';
+
+export interface DebriefResult {
+  successCriteriaMet: DebriefVerdict;
+  rationale: string;
+}
+
+export async function runDebrief(args: {
+  ctx: RestorationContext;
+  harness: HarnessAdapter;
+  execute: ExecuteResult;
+  strategy: StrategyResult;
+}): Promise<DebriefResult> {
+  const { ctx, harness, execute, strategy } = args;
+  return harness.promptForJson<DebriefResult>({
+    promptId: 'debrief',
+    systemPrompt:
+      'Decide whether the frozen success criteria were met. Be honest.',
+    userPrompt: JSON.stringify({ intent: ctx.intent, strategy, execute }),
+    budgetMs: Math.min(ctx.msUntilEndTs(), 15_000),
+    abort: ctx.abort,
+  });
+}