vgxness 1.5.1 → 1.5.2

package/dist/mcp/opencode-default-agent-config.js

@@ -1,23 +1,11 @@
-export const vgxnessOpenCodeDefaultAgent = 'vgxness-manager';
-export const vgxnessOpenCodePromptContractVersion = 6;
+import { projectCanonicalAgentManifestToOpenCode, } from '../agents/canonical-agent-projection.js';
+import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames, createCanonicalOpenCodeSddTaskPermissions, } from '../agents/canonical-agent-manifest.js';
+export const vgxnessOpenCodeDefaultAgent = canonicalDefaultAgentName;
+export const vgxnessOpenCodePromptContractVersion = canonicalPromptContractVersion;
 export const vgxnessOpenCodeInstructionsPath = 'AGENTS.md';
-export const vgxnessOpenCodeSddSubagents = [
-    'vgxness-sdd-explore',
-    'vgxness-sdd-propose',
-    'vgxness-sdd-spec',
-    'vgxness-sdd-design',
-    'vgxness-sdd-tasks',
-    'vgxness-sdd-apply',
-    'vgxness-sdd-verify',
-    'vgxness-sdd-archive',
-    'vgxness-sdd-init',
-    'vgxness-sdd-onboard',
-];
+export const vgxnessOpenCodeSddSubagents = canonicalSddSubagentNames;
 export function createOpenCodeSddTaskPermissions() {
-    const taskPermissions = { '*': 'deny' };
-    for (const subagent of vgxnessOpenCodeSddSubagents)
-        taskPermissions[subagent] = 'allow';
-    return taskPermissions;
+    return createCanonicalOpenCodeSddTaskPermissions();
 }
 export function createOpenCodeDefaultAgentInstallPlan(input = {}) {
     if (input.mcpOnly === true)
@@ -25,99 +13,5 @@ export function createOpenCodeDefaultAgentInstallPlan(input = {}) {
     return { installsAgents: true, agentNames: [vgxnessOpenCodeDefaultAgent, ...vgxnessOpenCodeSddSubagents], defaultAgent: vgxnessOpenCodeDefaultAgent };
 }
 export function createOpenCodeDefaultAgentConfig() {
-    const agents = {
-        [vgxnessOpenCodeDefaultAgent]: {
-            description: 'VGXNESS SDD Manager - coordinates MCP state and SDD sub-agents, avoids inline execution when delegation is safer',
-            mode: 'primary',
-            model: 'openai/gpt-5.5',
-            options: { reasoningEffort: 'high', vgxnessPromptContractVersion: vgxnessOpenCodePromptContractVersion },
-            permission: { task: createOpenCodeSddTaskPermissions() },
-            prompt: vgxnessManagerPrompt,
-            reasoningEffort: 'high',
-            tools: { bash: true, delegate: true, delegation_list: true, delegation_read: true, edit: true, read: true, write: true },
-            variant: '',
-        },
-    };
-    const descriptions = {
-        'vgxness-sdd-explore': 'Investigate codebase and think through ideas',
-        'vgxness-sdd-propose': 'Create change proposals from explorations',
-        'vgxness-sdd-spec': 'Write detailed specifications from proposals',
-        'vgxness-sdd-design': 'Create technical design from proposals',
-        'vgxness-sdd-tasks': 'Break down specs and designs into implementation tasks',
-        'vgxness-sdd-apply': 'Implement code changes from task definitions',
-        'vgxness-sdd-verify': 'Validate implementation against specs',
-        'vgxness-sdd-archive': 'Archive completed change artifacts',
-        'vgxness-sdd-init': 'Bootstrap SDD context and project configuration',
-        'vgxness-sdd-onboard': 'Guide user through a complete SDD cycle using their real codebase',
-    };
-    for (const name of vgxnessOpenCodeSddSubagents) {
-        agents[name] = {
-            description: descriptions[name],
-            hidden: true,
-            mode: 'subagent',
-            model: 'openai/gpt-5.5',
-            options: { vgxnessPromptContractVersion: vgxnessOpenCodePromptContractVersion },
-            prompt: createSddSubagentPrompt(name),
-            tools: { bash: true, edit: true, read: true, write: true },
-        };
-    }
-    return { defaultAgent: vgxnessOpenCodeDefaultAgent, agents };
+    return projectCanonicalAgentManifestToOpenCode();
 }
-function createSddSubagentPrompt(name) {
-    const phase = name.replace('vgxness-sdd-', '');
-    const common = `You are the VGXNESS SDD ${phase} executor, not the orchestrator. Do this phase's work yourself. Do NOT delegate, do NOT call task/delegate, and do NOT launch sub-agents. Use provided SDD artifacts, VGXNESS MCP state, and local repository evidence as needed. Retrieve full artifact content through MCP when the phase requires it; do not expect the manager to paste verbose artifacts into your prompt. Do not depend on external local skill files; this inline contract is sufficient. Preserve unrelated user work, keep output concise, and report evidence.`;
-    const contracts = {
-        'vgxness-sdd-explore': 'Investigate codebase context, constraints, options, and risks. Do not implement code changes. Return findings and recommended next artifacts.',
-        'vgxness-sdd-propose': 'Create or refine a focused SDD proposal from exploration evidence. Do not implement code changes. Include scope, tradeoffs, non-goals, and acceptance direction.',
-        'vgxness-sdd-spec': 'Write requirements, acceptance criteria, edge cases, and out-of-scope items. Do not implement code changes.',
-        'vgxness-sdd-design': 'Create technical design grounded in the repository: affected modules, data shapes, safety, rollout, and verification. Do not implement code changes.',
-        'vgxness-sdd-tasks': 'Break approved spec/design into small ordered testable implementation tasks. Do not implement code changes.',
-        'vgxness-sdd-apply': 'Implement only assigned SDD tasks. Preserve unrelated dirty files and user work. Use focused tests when authorized. Report changed files, tests/evidence, and residual risks.',
-        'vgxness-sdd-verify': 'Validate implementation against SDD artifacts and task acceptance criteria. Prefer focused local tests and evidence review. Do not implement unrelated changes.',
-        'vgxness-sdd-archive': 'Archive completed SDD outcome with summary, verification evidence, follow-ups, and residual risks. Confirm before any repository writes beyond the requested archive artifact.',
-        'vgxness-sdd-init': 'Bootstrap SDD context and project setup safely. Prefer diagnostics/read-only inspection and require explicit confirmation before writes or provider/global config changes.',
-        'vgxness-sdd-onboard': 'Guide the user through the SDD cycle with the smallest missing decision at each step. Keep assumptions explicit and confirm before writes or provider/global config changes.',
-    };
-    return `${common}\n\nPhase contract: ${contracts[name]}\n\nSDD governance v1: SDD artifact acceptance is human-only. Do not mark, describe, or persist generated phase output as accepted unless the user explicitly accepts it or an MCP acceptance record shows a human actor. Before advancing phases, use VGXNESS MCP readiness/status tools so draft, rejected, superseded, or legacy artifacts are not treated as accepted prerequisites. For risky VGX-managed side effects, use VGXNESS run preflight/reporting and include runId, phase, and agent context when available. OpenCode native/provider tools are audit-only and non-hard-blocking in governance v1; do not claim they are hard-blocked by OpenCode config.\n\nProvider-native daily progression: daily SDD progression happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not instruct the user to run terminal SDD phase commands for normal daily flow. Return phase output, decisions, changed files, and evidence so the manager can persist artifacts and advance through MCP. Preserve confirmation/preflight requirements for apply, verify, init, archive, edits, shell, git, provider-tool, secrets, destructive, privileged, or ambiguous operations.`;
-}
-const vgxnessManagerPrompt = `# VGXNESS Manager - compact SDD orchestrator
-
-Bind only to the primary \`vgxness-manager\` agent. Executor agents (for example \`vgxness-sdd-apply\`) use their own prompts.
-
-## Role
-Coordinate SDD; do not become a monolithic executor. Keep the chat thin, use VGXNESS MCP as durable state, delegate phase work to the smallest exact hidden SDD subagent, then synthesize concise evidence for the user. Be direct, practical, repository-grounded, user-controlled, and willing to challenge unsafe or weak assumptions.
-
-Coach while coordinating: teach briefly when helpful, explain practical tradeoffs, stay realistic about risk/effort/unknowns, respectfully challenge weak assumptions, keep the user comfortable and in control, and avoid lectures or unnecessary verbosity.
-
-## Non-negotiable governance
-- SDD artifact acceptance is human-only. Never infer acceptance from generated output, file presence, confidence, or legacy artifacts. Treat draft/rejected/superseded/unaccepted artifacts as not accepted until a human acceptance record exists.
-- Before phase advancement, call readiness/status tools: \`vgxness_sdd_status\`/\`vgxness_sdd_next\` and \`vgxness_sdd_ready\` or \`vgxness_sdd_get_readiness\`.
-- Before risky VGX-managed side effects (edit, shell/tests, git, network, provider-tool, secrets, external-directory, destructive, privileged, ambiguous), call \`vgxness_run_preflight\` with runId/workflow/phase/agent context when available. If approval/block is required, stop; do not invent approval.
-- OpenCode native/provider tools are governance-v1 audit-only/non-hard-blocking. Report warnings; do not say native OpenCode tools are hard-blocked by config.
-- Do not mutate provider/global OpenCode config unless explicitly requested. Do not write to \`openspec/\`. Never revert/overwrite unrelated user work. Preserve \`permission.task\` deny-by-default with only exact known SDD subagents allowed.
-- Do not publish packages unless explicitly requested.
-- Do not change model or reasoning effort.
-
-## Provider-native daily flow
-Normal SDD progression happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not tell users to run terminal SDD phase commands for daily flow. CLI is an escape hatch only for bootstrap, doctor, rollback/recovery, MCP unavailable/setup missing, provider-native repair out of scope, or explicit user request.
-
-## MCP playbook
-- For starting, resuming, or recovering context: prefer \`vgxness_context_cockpit\` with project + workspace; treat \`vgxness_session_restore\` as one signal inside the cockpit, not authoritative truth. If cockpit is unavailable, use \`vgxness_session_restore\` with project + workspace before inferring state. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with current session id and actor \`manager\`; if no id, do not invent one, say so and include summary in final response.
-- SDD artifacts: list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; use \`payloadMode: "compact"\` by default for manager-facing reads/lists so the primary context stays clean. Use \`payloadMode: "verbose"\` only when full content is truly required, preferably inside the delegated phase subagent rather than the manager context. Save phase output with \`vgxness_sdd_save_artifact\` only after the appropriate flow. SDD artifacts are not generic memory.
-- Acceptance/readiness: confirm explicit human acceptance, use \`vgxness_sdd_accept_artifact\` only for explicit human acceptance, then \`vgxness_sdd_get_readiness\`/readiness tools before reporting state. Use \`vgxness_governance_report\` for readiness, artifact states, preflight posture, and audit warnings before risky/ambiguous transitions and in apply/verify summaries.
-- Memory: call \`vgxness_memory_search\`/\`vgxness_memory_get\` when prior work or unclear project context is referenced; call \`vgxness_memory_save\` for durable discoveries, decisions, bug fixes, config, patterns, or preferences; use \`vgxness_memory_update\` only to correct/evolve a known id. Do not duplicate full SDD artifacts as memory.
-- Agents/profile/payloads: resolve exact phase with \`vgxness_agent_resolve\`. \`vgxness_agent_activate\`, \`vgxness_opencode_manager_payload\`, and \`vgxness_skill_payload\` prepare/read preview context only; agent_activate does not execute a provider or write provider config. Use \`vgxness_manager_profile_get\` before behavior changes; \`vgxness_manager_profile_set\` requires explicit human authorization.
-- Runs: use \`vgxness_run_start\`/\`vgxness_run_list\`/\`vgxness_run_get\` for significant implementation/verification or multi-step delegated work; checkpoint with \`vgxness_run_checkpoint\`, preflight with \`vgxness_run_preflight\`, and close with \`vgxness_run_finalize\`.
-- Provider diagnostics: \`vgxness_provider_status\` and \`vgxness_provider_doctor\` are read-only reports.
-
-## Minimum flows
-- Simple answer: respond inline; memory only if prior context is referenced; no run by default.
-- Proposal/spec/design/tasks: status/next -> readiness -> read prerequisites -> resolve exact subagent -> delegate -> persist returned output only according to acceptance/governance.
-- Apply/verify: require tasks/apply-progress as appropriate -> read artifacts -> resolve exact subagent -> recover/start run -> preflight writes/shell/git/tests -> delegate -> checkpoint -> save apply-progress/verify -> finalize when clear.
-- Config/provider/prompt change: inspect manager/profile or payload first; persistent changes require explicit human authorization.
-
-## Delegation thresholds
-Inline only small decisions, 1-3 file reads, status commands, and atomic one-file mechanical edits. Delegate broad exploration (4+ files), substantial implementation, writes with analysis/new logic, and execution-heavy verification. Never delegate to unknown agents; use exact SDD phase mapping: explore/propose/spec/design/tasks/apply/verify/archive/init/onboard.
-
-## Output
-Be concise: what was delegated, what came back, files/decisions changed, evidence/tests, risks, and next step.`;

package/dist/mcp/provider-canonical-agent-manifest.js

@@ -0,0 +1,39 @@
+import { canonicalAgentManifest } from '../agents/canonical-agent-manifest.js';
+import { canonicalManifestValidationErrors, canonicalProviderProjection } from '../agents/canonical-agent-projection.js';
+const diagnosticProviders = ['opencode', 'claude'];
+export function buildCanonicalAgentManifestDiagnostic(manifest = canonicalAgentManifest) {
+    const validationErrors = canonicalManifestValidationErrors(manifest);
+    const managerCount = manifest.agents.filter((agent) => agent.mode === 'agent').length;
+    const subagentCount = manifest.agents.filter((agent) => agent.mode === 'subagent').length;
+    return {
+        status: validationErrors.length === 0 ? 'pass' : 'fail',
+        version: manifest.version,
+        project: manifest.project,
+        scope: manifest.scope,
+        defaultAgentName: manifest.defaultAgentName,
+        promptContractVersion: manifest.promptContractVersion,
+        agentCount: manifest.agents.length,
+        managerCount,
+        subagentCount,
+        validationErrors,
+        providerSupport: diagnosticProviders.map((provider) => providerSupportFor(provider, manifest)),
+    };
+}
+function providerSupportFor(provider, manifest) {
+    try {
+        const projection = canonicalProviderProjection(provider, manifest);
+        return {
+            provider: projection.provider,
+            level: projection.level,
+            ...(projection.reason === undefined ? {} : { reason: projection.reason }),
+        };
+    }
+    catch {
+        const fallback = manifest.agents.find((agent) => agent.providerSupport[provider] !== undefined)?.providerSupport[provider];
+        return {
+            provider,
+            level: fallback?.level ?? 'unsupported',
+            ...(fallback?.reason === undefined ? {} : { reason: fallback.reason }),
+        };
+    }
+}

package/dist/mcp/provider-change-plan.js

@@ -1,4 +1,5 @@
 import { resolveMemoryDatabasePath } from '../memory/storage-paths.js';
+import { planClaudeCodeMcpInstall } from './client-install-claude-code-contract.js';
 import { planOpenCodeMcpInstall } from './client-install-opencode-contract.js';
 import { ProviderDoctorService } from './provider-doctor.js';
 import { ProviderStatusService } from './provider-status.js';
@@ -22,8 +23,10 @@ export class ProviderChangePlanService {
     }
     getPlan(input) {
         const normalized = normalizeInput(input);
-        if (normalized.provider !== 'opencode')
+        if (normalized.provider !== 'opencode' && normalized.provider !== 'claude')
             return { ok: true, value: unsupportedProviderEnvelope(normalized) };
+        if (normalized.provider === 'claude')
+            return this.getClaudePlan(normalized);
         const status = (this.deps.providerStatus ?? new ProviderStatusService()).getStatus({
             project: normalized.project,
             scope: normalized.scope,
@@ -65,6 +68,19 @@ export class ProviderChangePlanService {
             value: opencodeEnvelope(normalized, status.value, doctor.value, installPlan, databasePath.value.source),
         };
     }
+    getClaudePlan(normalized) {
+        const status = (this.deps.providerStatus ?? new ProviderStatusService()).getStatus({ project: normalized.project, scope: normalized.scope, providerAdapter: 'claude', workspaceRoot: normalized.workspaceRoot, env: this.deps.env ?? process.env, payloadMode: normalized.payloadMode });
+        if (!status.ok)
+            return status;
+        const doctor = (this.deps.providerDoctor ?? new ProviderDoctorService()).getDoctor({ project: normalized.project, scope: normalized.scope, providerAdapter: 'claude', workspaceRoot: normalized.workspaceRoot, env: this.deps.env ?? process.env, payloadMode: normalized.payloadMode });
+        if (!doctor.ok)
+            return doctor;
+        const databasePath = resolveMemoryDatabasePath({ cwd: normalized.workspaceRoot, env: this.deps.env ?? process.env });
+        if (!databasePath.ok)
+            return { ok: true, value: blockedPlanEnvelope(normalized, status.value, doctor.value, databasePath.error.message) };
+        const installPlan = planClaudeCodeMcpInstall({ cwd: normalized.workspaceRoot, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source });
+        return { ok: true, value: claudeEnvelope(normalized, status.value, doctor.value, installPlan, databasePath.value.source) };
+    }
 }
 function normalizeInput(input) {
     return {
@@ -156,6 +172,28 @@ function opencodeEnvelope(input, status, doctor, installPlan, source) {
         }
         : envelope;
 }
+function claudeEnvelope(input, status, doctor, installPlan, source) {
+    const backupRequired = installPlan.status === 'would_install' ? installPlan.backupRequired : false;
+    const warnings = [...statusWarnings(status), ...doctor.recommendations, ...installPlan.warnings];
+    const envelope = {
+        ...baseEnvelope(input),
+        supported: true,
+        status: installPlan.status === 'refused' ? 'blocked' : 'planned',
+        ...(installPlan.status === 'refused' ? { code: 'PLAN_UNAVAILABLE' } : {}),
+        summary: installPlan.status === 'refused' ? `Read-only Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}` : `Read-only Claude ${input.changeType} planning completed; future confirmed write would update project .mcp.json and ${installPlan.agentNames.length} agent file(s).`,
+        providerIdentity: { provider: 'claude', adapter: 'claude', support: 'supported' },
+        statusSummary: statusSummary(status),
+        statusFindings: status.config,
+        doctorSummary: doctorSummary(doctor),
+        doctorFindings: doctor.checks,
+        previewEffects: previewEffectsClaude(installPlan),
+        backupRollback: descriptiveBackupPolicy(backupRequired),
+        confirmations: confirmationPolicy(),
+        risks: risksForClaude(status, doctor, installPlan, source),
+        warnings,
+    };
+    return input.payloadMode === 'verbose' ? { ...envelope, rawSources: { status, doctor, claudeCodeMcpInstallPlan: installPlan } } : envelope;
+}
 function baseEnvelope(input) {
     return {
         version: 1,
@@ -223,6 +261,12 @@ function previewEffects(plan) {
         ...(plan.defaultAgent === undefined ? {} : { defaultAgent: plan.defaultAgent }),
     };
 }
+function previewEffectsClaude(plan) {
+    if (plan.status === 'refused')
+        return { action: 'refused', targetPath: plan.targetPath, backupRequired: false, preservedTopLevelKeys: plan.preservedTopLevelKeys, serverCommand: ['vgxness', ...plan.server.args], installsAgents: true, agentNames: plan.agentNames, installPlanStatus: 'refused', refusalReason: plan.reason, refusalMessage: plan.message };
+    const mcpTarget = plan.targets.find((target) => target.kind === 'mcp-json');
+    return { action: mcpTarget?.action === 'create' ? 'would-create' : 'would-merge', targetPath: plan.targetPath, backupRequired: plan.backupRequired, preservedTopLevelKeys: plan.preservedTopLevelKeys, serverCommand: ['vgxness', ...plan.server.args], installsAgents: true, agentNames: plan.agentNames, installPlanStatus: 'would_install' };
+}
 function descriptiveBackupPolicy(backupRequired) {
     return {
         policy: 'descriptive-only',
@@ -255,6 +299,18 @@ function risksForOpenCode(status, doctor, plan, source) {
         risks.push('Future MCP server command would rely on the global default VGXNESS database path.');
     return risks;
 }
+function risksForClaude(status, doctor, plan, source) {
+    const risks = ['Claude project .mcp.json may affect collaborators if committed; review before committing.', 'Claude Code runtime MCP approval happens in Claude Code; this plan does not prove runtime connection.'];
+    if (status.status !== 'ready')
+        risks.push(`Provider status is ${status.status}; future writes should review status findings first.`);
+    if (doctor.status !== 'healthy')
+        risks.push(`Provider doctor is ${doctor.status}; future writes should review doctor findings first.`);
+    if (plan.status === 'refused')
+        risks.push(`Future install planner refused the operation: ${plan.reason}.`);
+    if (source === 'global-default')
+        risks.push('Future MCP server command would rely on the global default VGXNESS database path.');
+    return risks;
+}
 function summaryForOpenCode(input, plan) {
     if (plan.status === 'refused')
         return `Read-only OpenCode ${input.changeType} planning completed; future install is currently refused: ${plan.message}`;

package/dist/mcp/provider-doctor.js

@@ -1,15 +1,25 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
+import { inspectClaudeCodeAgents } from './claude-code-agent-config.js';
+import { claudeAdvisoryPaths, inspectClaudeCodeMcpConfig } from './claude-code-config.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
+import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
 import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, providerHealthFailure, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, rollupProviderDoctor, } from './provider-health-types.js';
 import { inspectOpenCodeConfigPaths } from './provider-status.js';
 export class ProviderDoctorService {
+    deps;
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
     runDoctor(input = {}) {
         return this.getDoctor(input);
     }
     getDoctor(input = {}) {
         const normalized = normalizeProviderHealthInput(input);
+        if (normalized.providerAdapter === 'claude')
+            return this.getClaudeDoctor(normalized);
         if (normalized.providerAdapter !== 'opencode')
             return providerHealthFailure(`Unsupported provider adapter: ${normalized.providerAdapter}`);
+        const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
         const paths = inspectOpenCodeConfigPaths(normalized.workspaceRoot, normalized.env);
         const before = snapshotPaths(paths.map((path) => path.path), normalized.workspaceRoot);
         const readableJson = paths.filter((path) => path.parsed);
@@ -21,6 +31,7 @@ export class ProviderDoctorService {
                 detail: `Workspace root ${existsSync(normalized.workspaceRoot) ? 'exists' : 'does not exist'}: ${normalized.workspaceRoot}`,
             },
             { id: 'provider-supported', status: 'pass', detail: 'OpenCode provider adapter selected.' },
+            canonicalAgentManifestCheck(canonicalAgentManifest, normalized.payloadMode),
             configReadableCheck(readableJson.length, paths.filter((path) => path.exists).length),
             mcpEntryCheck(config),
             defaultAgentCheck(config),
@@ -71,6 +82,35 @@ export class ProviderDoctorService {
             },
         };
     }
+    getClaudeDoctor(normalized) {
+        const mcp = inspectClaudeCodeMcpConfig(normalized.workspaceRoot);
+        const agents = inspectClaudeCodeAgents(normalized.workspaceRoot);
+        const advisoryPaths = claudeAdvisoryPaths(normalized.workspaceRoot);
+        const checkedPathList = [mcp.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), ...advisoryPaths];
+        const before = snapshotPaths(checkedPathList, normalized.workspaceRoot);
+        const missingAgents = agents.agents.filter((agent) => agent.status === 'missing');
+        const badFrontmatter = agents.agents.filter((agent) => agent.frontmatter === 'invalid' || agent.frontmatter === 'missing');
+        const badMarkers = agents.agents.filter((agent) => agent.exists && !agent.generatedMarker);
+        const memoryFiles = advisoryPaths.filter((path) => existsSync(path));
+        const checks = [
+            { id: 'workspace-root', status: existsSync(normalized.workspaceRoot) ? 'pass' : 'fail', detail: `Workspace root ${existsSync(normalized.workspaceRoot) ? 'exists' : 'does not exist'}: ${normalized.workspaceRoot}` },
+            { id: 'provider-supported', status: 'pass', detail: 'Claude provider adapter selected for project-local .mcp.json and .claude/agents support.' },
+            { id: 'claude-project-mcp-readable', status: mcp.status === 'invalid' ? 'fail' : mcp.status === 'missing' ? 'not-configured' : 'pass', detail: mcp.message, ...(mcp.status === 'invalid' ? { remediation: 'Fix malformed .mcp.json before installing VGXNESS Claude support.' } : {}) },
+            { id: 'claude-vgxness-mcp-entry', status: mcp.status === 'configured' ? 'pass' : mcp.status === 'conflicting' ? 'fail' : 'not-configured', detail: mcp.message, ...(mcp.status === 'conflicting' ? { remediation: 'Manually reconcile mcpServers.vgxness before applying VGXNESS Claude support.' } : {}) },
+            { id: 'claude-agents-directory', status: agents.directoryExists ? 'pass' : 'not-configured', detail: agents.directoryExists ? 'Claude project agents directory exists.' : 'Claude project agents directory is missing; confirmed apply may create it.' },
+            { id: 'claude-vgxness-agents', status: missingAgents.length === 0 && agents.agents.every((agent) => agent.status !== 'conflicting' && agent.status !== 'invalid') ? 'pass' : missingAgents.length > 0 ? 'not-configured' : 'fail', detail: missingAgents.length > 0 ? `Missing VGXNESS Claude agents: ${missingAgents.map((agent) => agent.agentName).join(', ')}.` : 'Expected VGXNESS Claude agent targets were inspected.' },
+            { id: 'claude-agent-frontmatter', status: badFrontmatter.length === 0 ? 'pass' : 'fail', detail: badFrontmatter.length === 0 ? 'Expected Claude agent frontmatter is valid.' : `Invalid or missing frontmatter for: ${badFrontmatter.map((agent) => agent.agentName).join(', ')}.` },
+            { id: 'claude-agent-generated-metadata', status: badMarkers.length === 0 ? 'pass' : 'fail', detail: badMarkers.length === 0 ? 'Existing VGXNESS Claude agent files include generated metadata markers.' : `Missing VGXNESS generated marker for: ${badMarkers.map((agent) => agent.agentName).join(', ')}.` },
+            { id: 'claude-project-memory-advisory', status: memoryFiles.length === 0 ? 'pass' : 'warn', detail: memoryFiles.length === 0 ? 'No Claude project memory/settings advisory files were found.' : `Advisory only; VGXNESS will not modify: ${memoryFiles.join(', ')}.` },
+            readonlySafetyCheck(before, snapshotPaths(checkedPathList, normalized.workspaceRoot)),
+        ];
+        const status = rollupProviderDoctor(checks.map((check) => check.status));
+        const compactChecksValue = compactChecks(checks, normalized.payloadMode);
+        const checkedPaths = normalized.payloadMode === 'verbose' ? checkedPathList : checkedPathList.filter((path) => existsSync(path) || path === mcp.path);
+        const failedChecks = checks.filter((check) => check.status === 'fail').map((check) => check.id);
+        const recommendations = checks.flatMap((check) => (check.remediation === undefined ? [] : [check.remediation]));
+        return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: PROVIDER_HEALTH_SAFETY } };
+    }
 }
 function summarizeDoctor(status, failedCount, recommendationCount) {
     if (status === 'healthy')
@@ -115,6 +155,20 @@ function configReadableCheck(readableCount, existingCount) {
         detail: `Found ${existingCount} OpenCode config path(s), ${readableCount} readable JSON config(s). Project config can override user/global config.`,
     };
 }
+function canonicalAgentManifestCheck(diagnostic, mode) {
+    if (diagnostic.status === 'pass') {
+        const detail = mode === 'verbose'
+            ? `Canonical agent manifest validates: defaultAgent=${diagnostic.defaultAgentName}, promptContractVersion=${diagnostic.promptContractVersion}, agents=${diagnostic.agentCount}, managers=${diagnostic.managerCount}, subagents=${diagnostic.subagentCount}, providerSupport=${diagnostic.providerSupport.map((support) => `${support.provider}:${support.level}${support.reason === undefined ? '' : ` (${support.reason})`}`).join(', ')}.`
+            : `Canonical agent manifest validates: defaultAgent=${diagnostic.defaultAgentName}, promptContractVersion=${diagnostic.promptContractVersion}, agents=${diagnostic.agentCount}, managers=${diagnostic.managerCount}, subagents=${diagnostic.subagentCount}.`;
+        return { id: 'canonical-agent-manifest', status: 'pass', detail };
+    }
+    return {
+        id: 'canonical-agent-manifest',
+        status: 'fail',
+        detail: `Canonical agent manifest validation failed: ${diagnostic.validationErrors.join('; ') || 'unknown validation failure'}.`,
+        remediation: 'Fix the canonical agent manifest validation errors before relying on provider projection or provider setup.',
+    };
+}
 function mcpEntryCheck(config) {
     const mcp = isRecord(config?.mcp) ? config.mcp : undefined;
     const entry = mcp?.vgxness;

package/dist/mcp/provider-status.js

@@ -1,7 +1,10 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { inspectClaudeCodeAgents } from './claude-code-agent-config.js';
+import { claudeAdvisoryPaths, claudeMcpConfigPathStatus, claudeMcpEntryStatus, inspectClaudeCodeMcpConfig } from './claude-code-config.js';
 import { resolveOpenCodeMcpInstallTarget } from './client-install-opencode-contract.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodePromptContractVersion, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
+import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
 import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, providerHealthFailure, REQUIRED_PROVIDER_MCP_TOOLS, rollupProviderHealth, } from './provider-health-types.js';
 const projectConfigTargets = ['.opencode/opencode.json', 'opencode.json', '.opencode/opencode.jsonc', 'opencode.jsonc'];
 export class ProviderStatusService {
@@ -11,8 +14,11 @@ export class ProviderStatusService {
     }
     getStatus(input = {}) {
         const normalized = normalizeProviderHealthInput(input);
+        if (normalized.providerAdapter === 'claude')
+            return this.getClaudeStatus(normalized);
         if (normalized.providerAdapter !== 'opencode')
             return providerHealthFailure(`Unsupported provider adapter: ${normalized.providerAdapter}`);
+        const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
         const paths = inspectOpenCodeConfigPaths(normalized.workspaceRoot, normalized.env);
         const mcpEntry = inspectOpenCodeMcpEntry(paths);
         const providerConfig = readFirstParsedConfig(paths);
@@ -20,7 +26,7 @@ export class ProviderStatusService {
         const subagentsConfigured = hasConfiguredSubagents(providerConfig);
         const tools = requiredToolPresence();
         const configStatus = resolveConfigStatus(paths, mcpEntry, managerConfigured, subagentsConfigured);
-        const status = rollupProviderHealth([configStatus, ...tools.map((tool) => (tool.present ? 'pass' : 'fail'))]);
+        const status = rollupProviderHealth([canonicalAgentManifest.status, configStatus, ...tools.map((tool) => (tool.present ? 'pass' : 'fail'))]);
         const sdd = normalized.change.length > 0 ? this.readSdd(normalized.project, normalized.change) : undefined;
         const generatedAt = 'read-only-snapshot';
         const checkedPaths = normalized.payloadMode === 'verbose'
@@ -28,17 +34,19 @@ export class ProviderStatusService {
             : paths.filter((path) => path.exists || path.status !== 'not-configured').map((path) => path.path);
         const verboseShape = {
             config: { status: configStatus, paths, mcpEntry },
+            canonicalAgentManifest,
             sdd,
             mcpRequiredTools: tools,
         };
         const compactShape = {
             config: { status: configStatus, paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') },
+            canonicalAgentManifest,
             sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'),
             mcpRequiredTools: tools,
         };
         const originalBytes = Buffer.byteLength(JSON.stringify(verboseShape), 'utf8');
         const compactBytes = Buffer.byteLength(JSON.stringify(compactShape), 'utf8');
-        const issueCount = [configStatus, ...tools.map((tool) => (tool.present ? 'pass' : 'fail'))].filter((item) => item === 'fail' || item === 'not-configured').length;
+        const issueCount = [canonicalAgentManifest.status, configStatus, ...tools.map((tool) => (tool.present ? 'pass' : 'fail'))].filter((item) => item === 'fail' || item === 'not-configured').length;
         const warningCount = [configStatus, mcpEntry.status, ...paths.map((path) => path.status)].filter((item) => item === 'warn').length;
         return {
             ok: true,
@@ -58,6 +66,7 @@ export class ProviderStatusService {
                 summary: summarizeStatus(status, mcpEntry),
                 nextAction: nextActionFor(status, mcpEntry, sdd?.next),
                 checkedPaths,
+                canonicalAgentManifest,
                 config: { status: configStatus, paths: compactPaths(paths, normalized.payloadMode), mcpEntry: compactMcpEntry(mcpEntry, normalized.payloadMode) },
                 ...(sdd === undefined ? {} : { sdd: compactSdd(sdd, normalized.payloadMode) }),
                 mcpRequiredTools: tools,
@@ -77,6 +86,68 @@ export class ProviderStatusService {
         const next = this.deps.sdd.getNext({ project, change });
         return { change, ...(status.ok ? { status: status.value } : {}), ...(next.ok ? { next: next.value } : {}) };
     }
+    getClaudeStatus(normalized) {
+        const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
+        const mcpState = inspectClaudeCodeMcpConfig(normalized.workspaceRoot);
+        const agents = inspectClaudeCodeAgents(normalized.workspaceRoot);
+        const paths = [claudeMcpConfigPathStatus(mcpState)];
+        const mcpEntry = claudeMcpEntryStatus(mcpState);
+        const agentStatuses = agents.agents.map((agent) => (agent.status === 'managed' ? 'pass' : agent.status === 'missing' ? 'not-configured' : 'fail'));
+        const advisory = claudeAdvisoryPaths(normalized.workspaceRoot).filter((path) => existsSync(path));
+        const configStatus = claudeConfigHealthStatus([paths[0]?.status ?? 'not-configured', ...agentStatuses]);
+        const status = rollupProviderHealth([canonicalAgentManifest.status, configStatus]);
+        const sdd = normalized.change.length > 0 ? this.readSdd(normalized.project, normalized.change) : undefined;
+        const checkedPaths = normalized.payloadMode === 'verbose' ? [mcpState.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), ...claudeAdvisoryPaths(normalized.workspaceRoot)] : [mcpState.path, ...agents.agents.filter((agent) => agent.exists || agent.status !== 'missing').map((agent) => agent.path), ...advisory];
+        const tools = requiredToolPresence();
+        const verboseShape = { config: { status: configStatus, paths, mcpEntry }, canonicalAgentManifest, agents, advisory, sdd, mcpRequiredTools: tools };
+        const compactShape = { config: { status: configStatus, paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, agentSummary: summarizeClaudeAgents(agents), advisory, sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'), mcpRequiredTools: tools };
+        const originalBytes = Buffer.byteLength(JSON.stringify(verboseShape), 'utf8');
+        const compactBytes = Buffer.byteLength(JSON.stringify(compactShape), 'utf8');
+        const issueCount = [canonicalAgentManifest.status, configStatus, ...agentStatuses].filter((item) => item === 'fail' || item === 'not-configured').length;
+        const warningCount = advisory.length;
+        return {
+            ok: true,
+            value: {
+                version: 1,
+                kind: 'provider-status',
+                project: normalized.project,
+                providerAdapter: 'claude',
+                scope: normalized.scope,
+                workspaceRoot: normalized.workspaceRoot,
+                status,
+                payloadMode: normalized.payloadMode,
+                overallStatus: status,
+                inspectedPaths: checkedPaths,
+                issueCount,
+                warningCount,
+                summary: summarizeClaudeStatus(status, mcpEntry),
+                nextAction: nextActionFor(status, mcpEntry, sdd?.next),
+                checkedPaths,
+                canonicalAgentManifest,
+                config: { status: configStatus, paths: compactPaths(paths, normalized.payloadMode), mcpEntry: compactMcpEntry(mcpEntry, normalized.payloadMode) },
+                ...(sdd === undefined ? {} : { sdd: compactSdd(sdd, normalized.payloadMode) }),
+                mcpRequiredTools: tools,
+                originalBytes,
+                compactBytes,
+                verboseAvailable: normalized.payloadMode === 'compact',
+                fullContentRef: `provider-status:claude:${normalized.workspaceRoot}`,
+                generatedAt: 'read-only-snapshot',
+                safety: PROVIDER_HEALTH_SAFETY,
+            },
+        };
+    }
+}
+function summarizeClaudeAgents(agents) {
+    return { expected: agents.agents.length, managed: agents.agents.filter((agent) => agent.status === 'managed').length, missing: agents.agents.filter((agent) => agent.status === 'missing').length, conflicting: agents.agents.filter((agent) => agent.status === 'conflicting' || agent.status === 'invalid').length };
+}
+function claudeConfigHealthStatus(statuses) {
+    if (statuses.some((status) => status === 'fail'))
+        return 'fail';
+    if (statuses.some((status) => status === 'not-configured'))
+        return 'not-configured';
+    if (statuses.some((status) => status === 'warn'))
+        return 'warn';
+    return 'pass';
 }
 function compactPaths(paths, mode) {
     if (mode === 'verbose')
@@ -212,6 +283,15 @@ function summarizeStatus(status, mcpEntry) {
         return 'OpenCode provider config has warnings; no changes were made.';
     return 'OpenCode provider status check found a blocking issue; no changes were made.';
 }
+function summarizeClaudeStatus(status, mcpEntry) {
+    if (status === 'ready')
+        return 'Claude project .mcp.json and VGXNESS agent files are readable and configured.';
+    if (status === 'not-configured')
+        return mcpEntry.detail;
+    if (status === 'warning')
+        return 'Claude provider project config has warnings; no changes were made.';
+    return 'Claude provider status check found a blocking issue; no changes were made.';
+}
 function nextActionFor(status, mcpEntry, sddNext) {
     if (sddNext !== undefined)
         return { kind: 'advance-sdd', message: 'Continue the next SDD phase inside OpenCode using MCP status/ready/artifact tools and hidden SDD subagents.' };

package/dist/mcp/schema.js

@@ -430,7 +430,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         .object({
         project: z.string().min(1).optional(),
         scope: z.enum(scopes).optional(),
-        providerAdapter: z.literal('opencode').optional(),
+        providerAdapter: z.enum(['opencode', 'claude']).optional(),
         workspaceRoot: z.string().min(1).optional(),
         change: z.string().min(1).optional(),
         payloadMode: z.enum(payloadModes).optional(),
@@ -440,7 +440,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         .object({
         project: z.string().min(1).optional(),
         scope: z.enum(scopes).optional(),
-        providerAdapter: z.literal('opencode').optional(),
+        providerAdapter: z.enum(['opencode', 'claude']).optional(),
         workspaceRoot: z.string().min(1).optional(),
         expectedPromptContractVersion: z.number().int().positive().optional(),
         payloadMode: z.enum(payloadModes).optional(),

package/dist/mcp/validation.js

@@ -187,7 +187,7 @@ function validateProviderHealthInput(input, tool) {
         return scope;
     if (scope.value !== undefined)
         result.scope = scope.value;
-    const providerAdapter = readOptionalOneOf(record.value, 'providerAdapter', ['opencode'], tool);
+    const providerAdapter = readOptionalOneOf(record.value, 'providerAdapter', ['opencode', 'claude'], tool);
     if (!providerAdapter.ok)
         return providerAdapter;
     if (providerAdapter.value !== undefined)

package/dist/memory/memory-service.js

@@ -161,6 +161,10 @@ export class MemoryService {
         const result = this.artifacts.listByTopicPrefix(project, topicPrefix);
         return this.record(result, context, { operation: 'artifact.list', targetType: 'artifact', topicKey: topicPrefix });
     }
+    /** Read artifacts for read-only/status projections without writing provenance traces. */
+    listArtifactsByTopicPrefixNoTrace(project, topicPrefix) {
+        return this.artifacts.listByTopicPrefix(project, topicPrefix);
+    }
     close() {
         this.database.close();
     }