@longtable/provider-claude 0.1.9 → 0.1.11

package/dist/index.d.ts

@@ -1,9 +1,20 @@
+import type { ProviderCapabilities, QuestionRecord } from "@longtable/core";
 import type { CheckpointSignal, ResearcherProfile, ResolvedCheckpointPolicy, RuntimeGuidance } from "@longtable/checkpoints";
 import type { NumberedCheckpointSpec, SetupPersistedOutput } from "@longtable/setup";
 export interface ClaudeChoice {
     id: string;
     label: string;
 }
+export interface ClaudeAskUserQuestionInput {
+    questions: Array<{
+        question: string;
+        header: string;
+        options: Array<{
+            label: string;
+        }>;
+        multiSelect: boolean;
+    }>;
+}
 export interface ClaudeStructuredCheckpoint {
     title: string;
     instructions?: string;
@@ -24,8 +35,15 @@ export interface ClaudeCheckpointResult {
     policy: ResolvedCheckpointPolicy;
     guidance: RuntimeGuidance;
     structuredPrompt: ClaudeStructuredCheckpoint;
+    askUserQuestionInput: ClaudeAskUserQuestionInput;
     blocking: boolean;
 }
+export interface ClaudeRenderedQuestionRecord {
+    questionId: string;
+    checkpointKey: string;
+    structuredPrompt: ClaudeStructuredCheckpoint;
+    askUserQuestionInput: ClaudeAskUserQuestionInput;
+}
 export interface ClaudeRuntimeDefaults {
     askAtLeastTwoQuestionsInExplore: boolean;
     preserveNarrativeTraceInDraft: boolean;
@@ -40,7 +58,13 @@ export interface ClaudeRuntimeBridge {
     profile: SetupPersistedOutput["profileSeed"];
     runtimeDefaults: ClaudeRuntimeDefaults;
 }
+export declare const CLAUDE_PROVIDER_CAPABILITIES: ProviderCapabilities;
+export declare function getClaudeProviderCapabilities(): ProviderCapabilities;
 export declare function renderStructuredCheckpoint(spec: NumberedCheckpointSpec, guidance?: RuntimeGuidance): ClaudeStructuredCheckpoint;
+export declare function renderAskUserQuestionInput(checkpoint: ClaudeStructuredCheckpoint): ClaudeAskUserQuestionInput;
+export declare function renderStructuredQuestionRecord(record: QuestionRecord): ClaudeStructuredCheckpoint;
+export declare function renderQuestionRecordInput(record: QuestionRecord): ClaudeRenderedQuestionRecord;
 export declare function createClaudeCheckpoint(context: ClaudeCheckpointContext): ClaudeCheckpointResult;
 export declare function createClaudeRuntimeBridge(setup: SetupPersistedOutput): ClaudeRuntimeBridge;
 export * from "./config.js";
+export * from "./skills.js";

package/dist/index.js

@@ -1,5 +1,22 @@
 import { resolveCheckpointPolicy } from "@longtable/checkpoints";
 import { resolveRuntimeGuidance } from "@longtable/checkpoints";
+export const CLAUDE_PROVIDER_CAPABILITIES = {
+    provider: "claude",
+    nativeStructuredQuestions: true,
+    generatedSkills: "stable",
+    promptAliases: "unavailable",
+    nativeParallelSubagents: "session_dependent",
+    sequentialFallback: true,
+    mcpTransport: "planned",
+    notes: [
+        "Claude should prefer native structured questions when the runtime exposes them.",
+        "Generated LongTable skills are adapter output from the shared role registry.",
+        "Sequential panel fallback remains required so Claude and Codex share one semantic contract."
+    ]
+};
+export function getClaudeProviderCapabilities() {
+    return CLAUDE_PROVIDER_CAPABILITIES;
+}
 function buildRequiredSections(guidance) {
     const sections = [];
     if (guidance.preferQuestionsFirst || guidance.minimumQuestions > 0) {
@@ -41,13 +58,63 @@ export function renderStructuredCheckpoint(spec, guidance) {
             : undefined
     };
 }
+export function renderAskUserQuestionInput(checkpoint) {
+    return {
+        questions: [
+            {
+                header: checkpoint.title,
+                question: checkpoint.instructions || checkpoint.title,
+                options: checkpoint.choices.map((choice) => ({
+                    label: choice.label
+                })),
+                multiSelect: false
+            }
+        ]
+    };
+}
+export function renderStructuredQuestionRecord(record) {
+    const choices = [
+        ...record.prompt.options.map((option) => ({
+            id: option.value,
+            label: option.description ? `${option.label} — ${option.description}` : option.label
+        })),
+        ...(record.prompt.allowOther
+            ? [{
+                    id: "other",
+                    label: record.prompt.otherLabel ?? "Other"
+                }]
+            : [])
+    ];
+    return {
+        title: record.prompt.title,
+        instructions: [
+            record.prompt.question,
+            ...record.prompt.rationale.map((entry) => `Why now: ${entry}`),
+            `Question id: ${record.id}`,
+            `Checkpoint: ${record.prompt.checkpointKey ?? "manual"}`,
+            `Required: ${record.prompt.required ? "yes" : "no"}`
+        ].join(" "),
+        choices
+    };
+}
+export function renderQuestionRecordInput(record) {
+    const structuredPrompt = renderStructuredQuestionRecord(record);
+    return {
+        questionId: record.id,
+        checkpointKey: record.prompt.checkpointKey ?? "manual",
+        structuredPrompt,
+        askUserQuestionInput: renderAskUserQuestionInput(structuredPrompt)
+    };
+}
 export function createClaudeCheckpoint(context) {
     const policy = resolveCheckpointPolicy(context.profile, context.signal);
     const guidance = resolveRuntimeGuidance(context.profile, context.signal, policy);
+    const structuredPrompt = renderStructuredCheckpoint(context.spec, guidance);
     return {
         policy,
         guidance,
-        structuredPrompt: renderStructuredCheckpoint(context.spec, guidance),
+        structuredPrompt,
+        askUserQuestionInput: renderAskUserQuestionInput(structuredPrompt),
         blocking: policy.blocking
     };
 }
@@ -67,3 +134,4 @@ export function createClaudeRuntimeBridge(setup) {
     };
 }
 export * from "./config.js";
+export * from "./skills.js";

package/dist/skills.d.ts

@@ -0,0 +1,17 @@
+import type { RoleDefinition } from "@longtable/core";
+export interface ClaudeSkillSpec {
+    name: string;
+    description: string;
+    triggers: string[];
+    body: string[];
+}
+export interface InstalledClaudeSkill {
+    name: string;
+    path: string;
+    description: string;
+}
+export declare function resolveClaudeSkillsDir(customDir?: string): string;
+export declare function buildClaudeSkillSpecs(roles: RoleDefinition[]): ClaudeSkillSpec[];
+export declare function installClaudeSkills(roles: RoleDefinition[], customDir?: string): Promise<InstalledClaudeSkill[]>;
+export declare function removeClaudeSkills(roles: RoleDefinition[], customDir?: string): Promise<string[]>;
+export declare function listInstalledClaudeSkills(roles: RoleDefinition[], customDir?: string): Promise<InstalledClaudeSkill[]>;

package/dist/skills.js

@@ -0,0 +1,207 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export function resolveClaudeSkillsDir(customDir) {
+    return customDir ? resolve(customDir) : join(homedir(), ".claude", "skills");
+}
+function skillNameForRole(role) {
+    return `longtable-${role.key.replaceAll("_", "-")}`;
+}
+function yamlString(value) {
+    return JSON.stringify(value);
+}
+function renderSkillFile(spec) {
+    return [
+        "---",
+        `name: ${spec.name}`,
+        `description: ${yamlString(spec.description)}`,
+        "triggers:",
+        ...spec.triggers.map((trigger) => `  - ${yamlString(trigger)}`),
+        "---",
+        "",
+        `# ${spec.name}`,
+        "",
+        ...spec.body
+    ].join("\n");
+}
+function baseSkillSpecs() {
+    return [
+        {
+            name: "longtable",
+            description: "Use for LongTable research conversations, project memory, checkpointing, and role routing.",
+            triggers: ["longtable", "lt ", "research workspace", "research checkpoint"],
+            body: [
+                "## Purpose",
+                "",
+                "Act as the LongTable adapter inside Claude Code. LongTable is a researcher-centered workspace, not a replacement for the researcher.",
+                "",
+                "## Invocation",
+                "",
+                "Use this skill when the user says things like:",
+                "",
+                "- `longtable: help me narrow this project`",
+                "- `lt explore: ...`",
+                "- `lt review: ...`",
+                "- `lt panel: ...`",
+                "",
+                "## Rules",
+                "",
+                "- Treat `.longtable/` state as the project source of truth when present.",
+                "- Prefer natural language over asking the researcher to run shell role commands.",
+                "- If a Researcher Checkpoint is needed, ask a short structured question with meaningful options and wait for the researcher.",
+                "- If changing LongTable product language, README positioning, or checkpoint policy, ask a Meta-Decision Checkpoint first.",
+                "- If a checkpoint allows `other`, make `other` visible instead of hiding it in state.",
+                "- Treat Claude's structured question surface as transport; LongTable state records are the source of truth.",
+                "- When the `longtable` CLI is available in a workspace, use `longtable question --print --provider claude --prompt \"...\"` to create a canonical checkpoint payload before invoking Claude's structured question surface.",
+                "- If `CURRENT.md` shows a pending required checkpoint, do not proceed until `longtable decide --question <id> --answer <value>` records the researcher's choice.",
+                "- Preserve open tensions and authorship instead of forcing closure.",
+                "- Disclose consulted roles with `LongTable consulted: ...` when a role is foregrounded.",
+                "- Label unsupported external claims as inference or estimate.",
+                "",
+                "## Optional CLI Bridge",
+                "",
+                "If the `longtable` command is available and canonical prompt rendering would help, use `longtable ask --print --prompt \"...\"` or `longtable panel --print --prompt \"...\"` as an adapter aid. Do not make shell commands the user's primary interface."
+            ]
+        },
+        {
+            name: "longtable-panel",
+            description: "Use when a research decision needs visible disagreement from multiple LongTable roles.",
+            triggers: ["lt panel", "longtable panel", "panel review", "team review", "disagreement", "conflict"],
+            body: [
+                "## Purpose",
+                "",
+                "Run a LongTable panel-style review in Claude Code.",
+                "",
+                "## Output Contract",
+                "",
+                "Return:",
+                "",
+                "1. LongTable synthesis",
+                "2. Panel opinions by role",
+                "3. Conflict summary",
+                "4. Decision prompt for the researcher",
+                "5. Evidence or file references used",
+                "",
+                "## Rules",
+                "",
+                "- Use multiple research perspectives when the request touches methods, theory, measurement, venue fit, ethics, or authorship.",
+                "- Do not collapse disagreement too early.",
+                "- Use a Researcher Checkpoint before treating panel synthesis as settled.",
+                "- If the CLI is available, prefer `longtable question --print --provider claude --prompt \"...\"` before invoking a structured question surface.",
+                "- Do not expose hidden reasoning or tool logs.",
+                "- If `.longtable/` exists, align the panel with `CURRENT.md` and project state.",
+                "- If `longtable panel --print --prompt \"...\"` is available, it may be used to obtain the canonical fallback prompt."
+            ]
+        },
+        {
+            name: "longtable-explore",
+            description: "Use for early-stage research exploration before the question is settled.",
+            triggers: ["lt explore", "explore research", "narrow research question", "problem framing"],
+            body: [
+                "## Purpose",
+                "",
+                "Help the researcher keep the problem open long enough to find a defensible question.",
+                "",
+                "## Rules",
+                "",
+                "- Ask at least two clarifying or tension questions before recommending a direction.",
+                "- Surface candidate boundaries, not just answers.",
+                "- Keep unresolved tensions visible.",
+                "- Avoid generic literature-search advice unless evidence discovery is actually requested."
+            ]
+        },
+        {
+            name: "longtable-review",
+            description: "Use for critical review of a claim, paragraph, study design, or plan.",
+            triggers: ["lt review", "review this", "criticize this", "what is weak"],
+            body: [
+                "## Purpose",
+                "",
+                "Review a research object without smoothing over its weaknesses.",
+                "",
+                "## Rules",
+                "",
+                "- Start with the most important risk or objection.",
+                "- Separate sourced facts, interpretation, and speculation.",
+                "- Preserve the researcher's own language where possible.",
+                "- Ask a checkpoint question before treating a high-stakes decision as settled."
+            ]
+        }
+    ];
+}
+function roleSkillSpec(role) {
+    const label = role.label;
+    return {
+        name: skillNameForRole(role),
+        description: `Use the LongTable ${label} role: ${role.shortDescription}`,
+        triggers: [
+            ...role.synonyms.slice(0, 8),
+            `longtable ${role.key.replaceAll("_", " ")}`,
+            `lt ${role.key.replaceAll("_", " ")}`
+        ],
+        body: [
+            "## Purpose",
+            "",
+            `Foreground the LongTable ${label} role.`,
+            "",
+            "## Role Focus",
+            "",
+            role.shortDescription,
+            "",
+            "## Rules",
+            "",
+            `- Disclose: \`LongTable consulted: ${label}\`.`,
+            "- Keep the role grounded in the user's research object and project state.",
+            "- Do not invent a separate role definition; this skill is an adapter generated from the LongTable role registry.",
+            "- If evidence is needed, ask whether the researcher wants scholarly search or citation verification.",
+            "- If the role's judgment would change the project direction, ask a Researcher Checkpoint before closure."
+        ]
+    };
+}
+export function buildClaudeSkillSpecs(roles) {
+    return [...baseSkillSpecs(), ...roles.map(roleSkillSpec)];
+}
+export async function installClaudeSkills(roles, customDir) {
+    const skillsDir = resolveClaudeSkillsDir(customDir);
+    await mkdir(skillsDir, { recursive: true });
+    const installed = [];
+    for (const spec of buildClaudeSkillSpecs(roles)) {
+        const skillDir = join(skillsDir, spec.name);
+        await mkdir(skillDir, { recursive: true });
+        const path = join(skillDir, "SKILL.md");
+        await writeFile(path, renderSkillFile(spec), "utf8");
+        installed.push({
+            name: spec.name,
+            path,
+            description: spec.description
+        });
+    }
+    return installed;
+}
+export async function removeClaudeSkills(roles, customDir) {
+    const skillsDir = resolveClaudeSkillsDir(customDir);
+    const removed = [];
+    for (const spec of buildClaudeSkillSpecs(roles)) {
+        const skillDir = join(skillsDir, spec.name);
+        if (existsSync(skillDir)) {
+            await rm(skillDir, { recursive: true, force: true });
+            removed.push(skillDir);
+        }
+    }
+    return removed;
+}
+export async function listInstalledClaudeSkills(roles, customDir) {
+    const skillsDir = resolveClaudeSkillsDir(customDir);
+    if (!existsSync(skillsDir)) {
+        return [];
+    }
+    const entries = new Set(await readdir(skillsDir));
+    return buildClaudeSkillSpecs(roles)
+        .filter((spec) => entries.has(spec.name) && existsSync(join(skillsDir, spec.name, "SKILL.md")))
+        .map((spec) => ({
+        name: spec.name,
+        path: join(skillsDir, spec.name, "SKILL.md"),
+        description: spec.description
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtable/provider-claude",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "private": false,
   "description": "Claude adapter surface for LongTable",
   "type": "module",
@@ -21,9 +21,9 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@longtable/checkpoints": "0.1.9",
-    "@longtable/core": "0.1.9",
-    "@longtable/setup": "0.1.9"
+    "@longtable/checkpoints": "0.1.11",
+    "@longtable/core": "0.1.11",
+    "@longtable/setup": "0.1.11"
   },
   "devDependencies": {
     "typescript": "^5.6.0"