vgxness 1.5.0 → 1.5.2

package/README.md

@@ -1,6 +1,6 @@
 # VGXNESS
 
-VGXNESS is an installable CLI and MCP control plane for guided AI-agent workflows, SDD artifacts, local memory, and OpenCode integration.
+VGXNESS is an installable CLI, MCP control plane, and native code runtime for guided AI-agent workflows, SDD artifacts, local memory, and OpenCode integration.
 
 ## Release status and license
 
@@ -158,6 +158,19 @@ vgxness setup apply --yes
 
 `vgxness setup plan` and `vgxness setup status` are human-readable and read-only by default. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, and `vgxness sdd accept-artifact` are also human-readable by default. Pass `--json` when you need parseable automation output. `vgxness setup apply --yes` is the explicit provider-config write path.
 
+## Code runtime (`vgxness code`)
+
+Beyond setup and SDD control, VGXNESS ships a native code runtime for bounded agentic work in the local workspace:
+
+```bash
+vgxness code inspect "<question>"      # read-only investigation
+vgxness code plan "<task>"             # read-only implementation plan
+vgxness code craft-preview "<task>"    # show the diff you would make
+vgxness code craft "<task>"            # approval-gated, bounded edit-capable work
+```
+
+Edits, shell, network, git mutations, SDD persistence, and memory saves route through explicit permission decisions. External workspace edits are denied, destructive commands require approval, and secret-like values are redacted from prompts, transcripts, and reports. See [Code runtime](./docs/code-runtime.md) and [Safety model](./docs/safety.md) for the full contract.
+
 ## Safety model
 
 - Preview, status, and plan commands are read-only.
@@ -166,6 +179,7 @@ vgxness setup apply --yes
 - SDD artifacts are SQLite-backed through VGXNESS services. Do not create or write `openspec/`.
 - `vgxness sdd accept-artifact` records explicit human-only acceptance; saving a draft never implies acceptance.
 - OpenCode is the primary supported provider; other providers are preview/manual extension points.
+- VGXNESS exposes 38 typed MCP tools across SDD, memory, sessions, agents, skills, runs, providers, and verification. See [MCP tools](./docs/mcp.md).
 
 ## Main menu entrypoint
 
@@ -242,4 +256,11 @@ Remove any OpenCode config entries and local/global VGXNESS data manually if you
 
 - [CLI reference](./docs/cli.md)
 - [Architecture](./docs/architecture.md)
-- [System behavior](./docs/funcionamiento-del-sistema.md)
+- [Code runtime](./docs/code-runtime.md)
+- [MCP tools](./docs/mcp.md)
+- [Safety model](./docs/safety.md)
+- [Storage](./docs/storage.md)
+- [Providers](./docs/providers.md)
+- [Roadmap](./docs/roadmap.md)
+- [Contributing](./docs/contributing.md)
+- [Glossary](./docs/glossary.md)

package/dist/agents/agent-seed-service.js

@@ -1,4 +1,5 @@
 import { AgentRepository } from './repositories/agents.js';
+import { projectCanonicalAgentManifestToSeed } from './canonical-agent-projection.js';
 const requiredManagerName = 'vgxness-manager';
 export class AgentSeedService {
     database;
@@ -7,6 +8,15 @@ export class AgentSeedService {
         this.database = database;
         this.agents = new AgentRepository(database);
     }
+    loadBuiltInDefaults() {
+        try {
+            return this.loadManifest(projectCanonicalAgentManifestToSeed());
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            return { ok: false, error: { code: 'validation_failed', message } };
+        }
+    }
     loadManifest(manifest) {
         const validation = this.validateManifest(manifest);
         if (!validation.ok)

package/dist/agents/canonical-agent-manifest.js

@@ -0,0 +1,177 @@
+export const canonicalDefaultAgentName = 'vgxness-manager';
+export const canonicalPromptContractVersion = 6;
+export const canonicalSddSubagentNames = [
+    '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 function validateCanonicalAgentManifest(manifest) {
+    const errors = [];
+    if (manifest.version !== 1)
+        errors.push('manifest.version must be 1');
+    if (!manifest.project.trim())
+        errors.push('manifest.project is required');
+    if (manifest.scope !== 'project' && manifest.scope !== 'personal')
+        errors.push('manifest.scope must be project or personal');
+    if (!Number.isInteger(manifest.promptContractVersion) || manifest.promptContractVersion <= 0)
+        errors.push('manifest.promptContractVersion must be a positive integer');
+    if (!manifest.defaultAgentName.trim())
+        errors.push('manifest.defaultAgentName is required');
+    const ids = new Set();
+    const names = new Set();
+    const managers = manifest.agents.filter((agent) => agent.mode === 'agent');
+    if (managers.length !== 1)
+        errors.push(`manifest must declare exactly one manager agent; found ${managers.length}`);
+    if (!managers.some((agent) => agent.name === manifest.defaultAgentName))
+        errors.push(`manifest.defaultAgentName ${manifest.defaultAgentName} must match the manager agent`);
+    for (const agent of manifest.agents) {
+        const label = `agent ${agent.name || agent.id || '<unknown>'}`;
+        if (!agent.id.trim())
+            errors.push(`${label}.id is required`);
+        if (!agent.name.trim())
+            errors.push(`${label}.name is required`);
+        if (ids.has(agent.id))
+            errors.push(`duplicate canonical agent id: ${agent.id}`);
+        if (names.has(agent.name))
+            errors.push(`duplicate canonical agent name: ${agent.name}`);
+        ids.add(agent.id);
+        names.add(agent.name);
+        if (agent.builtIn !== true)
+            errors.push(`${label}.builtIn must be true`);
+        if (agent.mode === 'subagent' && !agent.parentAgentName?.trim())
+            errors.push(`${label}.parentAgentName is required for subagents`);
+        for (const [provider, support] of Object.entries(agent.providerSupport)) {
+            if (provider !== support.adapter)
+                errors.push(`${label}.providerSupport.${provider}.adapter must match provider key`);
+            if (support.level !== 'managed' && support.level !== 'preview' && support.level !== 'unsupported')
+                errors.push(`${label}.providerSupport.${provider}.level is invalid`);
+            if ((support.level === 'preview' || support.level === 'unsupported') && !support.reason?.trim())
+                errors.push(`${label}.providerSupport.${provider}.reason is required for ${support.level}`);
+        }
+    }
+    for (const agent of manifest.agents.filter((agent) => agent.mode === 'subagent')) {
+        if (agent.parentAgentName !== undefined && !names.has(agent.parentAgentName))
+            errors.push(`agent ${agent.name}.parentAgentName is missing: ${agent.parentAgentName}`);
+    }
+    return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+function commonSupport() {
+    return {
+        opencode: { adapter: 'opencode', level: 'managed' },
+        claude: { adapter: 'claude', level: 'managed' },
+    };
+}
+function managerDefinition() {
+    return {
+        id: canonicalDefaultAgentName,
+        mode: 'agent',
+        builtIn: true,
+        name: canonicalDefaultAgentName,
+        description: 'Coordinates VGXNESS MCP state and SDD sub-agents while avoiding unsafe inline execution.',
+        instructions: { kind: 'inline', value: registryManagerInstructions },
+        capabilities: ['sdd-orchestration', 'agent-routing', 'mcp-coordination', 'project-local-automation'],
+        permissions: { read: 'allow', edit: 'ask', shell: 'ask', git: 'ask', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' },
+        memory: { scopes: ['project'] },
+        workflows: ['explore', 'quickfix', 'plan', 'build', 'debug', 'sdd', 'agent-seeding', 'opencode-install'],
+        skills: ['vgxness-sdd-manager'],
+        adapters: { opencode: { model: 'openai/gpt-5.5', config: { options: { reasoningEffort: 'high', vgxnessPromptContractVersion: canonicalPromptContractVersion }, permission: { task: createCanonicalOpenCodeSddTaskPermissions() } } } },
+        providerSupport: commonSupport(),
+    };
+}
+function subagentDefinition(name) {
+    const data = subagentData[name];
+    return {
+        id: name,
+        mode: 'subagent',
+        builtIn: true,
+        parentAgentName: canonicalDefaultAgentName,
+        name,
+        description: data.seedDescription,
+        instructions: { kind: 'inline', value: data.seedInstructions },
+        capabilities: data.capabilities,
+        permissions: data.permissions,
+        memory: { scopes: ['project'] },
+        workflows: data.workflows,
+        skills: data.skills,
+        adapters: { opencode: { model: 'openai/gpt-5.5', config: { hidden: true, options: { vgxnessPromptContractVersion: canonicalPromptContractVersion } } } },
+        providerSupport: commonSupport(),
+    };
+}
+export function createCanonicalOpenCodeSddTaskPermissions() {
+    return Object.fromEntries([['*', 'deny'], ...canonicalSddSubagentNames.map((name) => [name, 'allow'])]);
+}
+export function createCanonicalOpenCodeSddSubagentPrompt(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 contract = subagentData[name].phaseContract;
+    return `${common}\n\nPhase contract: ${contract}\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.`;
+}
+export const canonicalOpenCodeManagerPrompt = `# 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.`;
+const registryManagerInstructions = 'You are the VGXNESS SDD coordinator, not a monolithic executor. Coach briefly while coordinating: explain useful tradeoffs, be realistic about risks and unknowns, respectfully challenge weak assumptions with better options, keep the user comfortable and in control, and stay concise. Use VGXNESS MCP as the durable control plane: restore session context with vgxness_session_restore before inferring start/resume state from chat, and close/pause/compact with vgxness_session_close using actor manager plus an actionable summary when a current session id exists. Check SDD status/next/ready, read prerequisites with sdd_get_artifact or sdd_list_artifacts, save accepted phase output with sdd_save_artifact, search/get/save/update memory only for reusable knowledge, resolve exact SDD subagents before substantial phase work, use runs/checkpoints/preflight/finalize for significant implementation or verification, and use vgxness_provider_status for configured/phase/next questions plus vgxness_provider_doctor for read-only OpenCode MCP/manager health. Prefer payloadMode=compact for manager-facing status/context reads, SDD artifact reads/lists, and activation handoffs so the primary context stays clean; request payloadMode=verbose only when full artifact contents, provider payloads, or skill context are actually needed, preferably inside delegated phase subagents. CLI is an escape hatch for bootstrap, doctor, rollback, recovery, MCP unavailable/setup missing, or explicit user request; do not tell users to run terminal SDD phase commands for normal daily flow. Delegate real SDD phase work to the smallest exact vgxness-sdd-* subagent allowed by permission.task, synthesize results, and persist artifacts/checkpoints. Do not perform substantial multi-file implementation inline. Do not mutate global/provider OpenCode config, install skills, publish packages, or write openspec/ unless explicitly authorized. Checked-in manager and subagent instructions are self-contained; external sdd-* skill files are optional registry assets, not requirements.';
+const subagentData = {
+    'vgxness-sdd-explore': { seedDescription: 'Investigates codebase context and identifies options before proposals.', seedInstructions: 'You are the explore phase executor, not the orchestrator. Do not delegate. Explore repository evidence for the requested SDD change. Do not implement code changes. Return concise findings, risks, and recommended next artifacts.', capabilities: ['sdd-exploration', 'codebase-research', 'discovery'], permissions: { read: 'allow', edit: 'deny', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:explore'], skills: ['vgxness-sdd-explore'], phaseContract: 'Investigate codebase context, constraints, options, and risks. Do not implement code changes. Return findings and recommended next artifacts.' },
+    'vgxness-sdd-propose': { seedDescription: 'Creates focused change proposals from exploration findings.', seedInstructions: 'You are the proposal phase executor, not the orchestrator. Do not delegate. Create a focused SDD proposal from exploration evidence. Do not implement code changes. Identify scope, tradeoffs, non-goals, and acceptance direction.', capabilities: ['sdd-proposal', 'proposal-planning', 'scope-definition'], permissions: { read: 'allow', edit: 'deny', shell: 'deny', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:proposal'], skills: ['vgxness-sdd-proposal'], phaseContract: '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': { seedDescription: 'Writes detailed requirements and acceptance criteria for SDD changes.', seedInstructions: 'You are the spec phase executor, not the orchestrator. Do not delegate. Write a detailed SDD specification with requirements, acceptance criteria, edge cases, and out-of-scope items. Do not implement code changes.', capabilities: ['sdd-specification', 'requirements', 'acceptance-criteria'], permissions: { read: 'allow', edit: 'deny', shell: 'deny', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:spec'], skills: ['vgxness-sdd-spec'], phaseContract: 'Write requirements, acceptance criteria, edge cases, and out-of-scope items. Do not implement code changes.' },
+    'vgxness-sdd-design': { seedDescription: 'Creates technical design from approved specs and proposals.', seedInstructions: 'You are the design phase executor, not the orchestrator. Do not delegate. Create a technical design grounded in the repository. Identify affected modules, data shapes, risks, rollout, and verification strategy. Do not implement code changes.', capabilities: ['sdd-design', 'technical-design', 'architecture-planning'], permissions: { read: 'allow', edit: 'deny', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:design'], skills: ['vgxness-sdd-design'], phaseContract: 'Create technical design grounded in the repository: affected modules, data shapes, safety, rollout, and verification. Do not implement code changes.' },
+    'vgxness-sdd-tasks': { seedDescription: 'Breaks specs and designs into implementation tasks.', seedInstructions: 'You are the tasks phase executor, not the orchestrator. Do not delegate. Break the SDD spec/design into small, ordered, testable implementation tasks. Do not implement code changes.', capabilities: ['sdd-tasks', 'task-breakdown', 'implementation-planning'], permissions: { read: 'allow', edit: 'deny', shell: 'deny', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:tasks'], skills: ['vgxness-sdd-tasks'], phaseContract: 'Break approved spec/design into small ordered testable implementation tasks. Do not implement code changes.' },
+    'vgxness-sdd-apply': { seedDescription: 'Implements code changes from SDD task definitions.', seedInstructions: 'You are the apply phase executor, not the orchestrator. Implement only the assigned SDD tasks directly. Do not delegate. Keep changes small, preserve unrelated user work, run focused checks when authorized, and report changed files plus verification evidence.', capabilities: ['sdd-apply', 'implementation', 'code-change'], permissions: { read: 'allow', edit: 'ask', shell: 'ask', git: 'ask', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:apply-progress'], skills: ['vgxness-sdd-apply'], phaseContract: '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': { seedDescription: 'Validates implementation against specs, tasks, and evidence.', seedInstructions: 'You are the verify phase executor, not the orchestrator. Do not delegate. Verify the implementation against SDD artifacts. Prefer focused local tests, inspect evidence, and report residual risk. Do not implement unrelated changes.', capabilities: ['sdd-verify', 'verification', 'test-review', 'risk-review'], permissions: { read: 'allow', edit: 'deny', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:verify'], skills: ['vgxness-sdd-verify'], phaseContract: 'Validate implementation against SDD artifacts and task acceptance criteria. Prefer focused local tests and evidence review. Do not implement unrelated changes.' },
+    'vgxness-sdd-archive': { seedDescription: 'Archives completed SDD change artifacts and outcomes.', seedInstructions: 'You are the archive phase executor, not the orchestrator. Do not delegate. Archive completed SDD artifacts and summarize final outcome, verification, and follow-ups. Confirm before writes beyond the requested archive artifact.', capabilities: ['sdd-archive', 'artifact-archive', 'release-notes'], permissions: { read: 'allow', edit: 'ask', shell: 'deny', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:archive'], skills: ['vgxness-sdd-archive'], phaseContract: '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': { seedDescription: 'Bootstraps SDD context and project configuration.', seedInstructions: 'You are the init phase executor, not the orchestrator. Do not delegate. Initialize SDD context and project setup safely. Prefer read-only diagnostics and explicit user confirmation before writes or provider/global config changes.', capabilities: ['sdd-init', 'setup', 'bootstrap'], permissions: { read: 'allow', edit: 'ask', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:init', 'setup'], skills: [], phaseContract: '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': { seedDescription: 'Guides users through a complete SDD cycle using their real codebase.', seedInstructions: 'You are the onboard phase executor, not the orchestrator. Do not delegate. Guide onboarding through the SDD workflow. Ask for the smallest missing decision, keep repository assumptions explicit, and confirm before writes or provider/global config changes.', capabilities: ['sdd-onboard', 'workflow-guidance', 'project-onboarding'], permissions: { read: 'allow', edit: 'ask', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:onboard', 'sdd'], skills: [], phaseContract: '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.' },
+};
+export const canonicalAgentManifest = {
+    version: 1,
+    project: 'vgxness',
+    scope: 'project',
+    promptContractVersion: canonicalPromptContractVersion,
+    defaultAgentName: canonicalDefaultAgentName,
+    agents: [managerDefinition(), ...canonicalSddSubagentNames.map(subagentDefinition)],
+};

package/dist/agents/canonical-agent-projection.js

@@ -0,0 +1,146 @@
+import { canonicalAgentManifest, canonicalDefaultAgentName, canonicalOpenCodeManagerPrompt, canonicalPromptContractVersion, canonicalSddSubagentNames, createCanonicalOpenCodeSddSubagentPrompt, createCanonicalOpenCodeSddTaskPermissions, validateCanonicalAgentManifest, } from './canonical-agent-manifest.js';
+export function canonicalManifestValidationErrors(manifest = canonicalAgentManifest) {
+    const validation = validateCanonicalAgentManifest(manifest);
+    return validation.ok ? [] : validation.errors;
+}
+export function projectCanonicalAgentManifestToSeed(manifest = canonicalAgentManifest) {
+    assertValidCanonicalManifest(manifest);
+    const agents = manifest.agents.filter((agent) => agent.mode === 'agent').map(toSeedAgent);
+    const subagents = manifest.agents.filter((agent) => agent.mode === 'subagent').map(toSeedSubagent);
+    return { version: 1, project: manifest.project, scope: manifest.scope, agents, subagents };
+}
+export function projectCanonicalAgentManifestToOpenCode(manifest = canonicalAgentManifest) {
+    assertValidCanonicalManifest(manifest);
+    const manager = manifest.agents.find((agent) => agent.name === manifest.defaultAgentName && agent.mode === 'agent');
+    if (manager === undefined)
+        throw new Error(`Canonical OpenCode projection missing manager agent: ${manifest.defaultAgentName}`);
+    const agents = {
+        [canonicalDefaultAgentName]: {
+            description: 'VGXNESS SDD Manager - coordinates MCP state and SDD sub-agents, avoids inline execution when delegation is safer',
+            mode: 'primary',
+            ...(manager.adapters?.opencode?.model !== undefined ? { model: manager.adapters.opencode.model } : {}),
+            options: { reasoningEffort: 'high', vgxnessPromptContractVersion: canonicalPromptContractVersion },
+            permission: { task: createCanonicalOpenCodeSddTaskPermissions() },
+            prompt: canonicalOpenCodeManagerPrompt,
+            reasoningEffort: 'high',
+            tools: { bash: true, delegate: true, delegation_list: true, delegation_read: true, edit: true, read: true, write: true },
+            variant: '',
+        },
+    };
+    for (const name of canonicalSddSubagentNames) {
+        const subagent = manifest.agents.find((agent) => agent.name === name && agent.mode === 'subagent');
+        if (subagent === undefined)
+            throw new Error(`Canonical OpenCode projection missing subagent: ${name}`);
+        agents[name] = {
+            description: openCodeSubagentDescriptions[name],
+            hidden: true,
+            mode: 'subagent',
+            ...(subagent.adapters?.opencode?.model !== undefined ? { model: subagent.adapters.opencode.model } : {}),
+            options: { vgxnessPromptContractVersion: canonicalPromptContractVersion },
+            prompt: createCanonicalOpenCodeSddSubagentPrompt(name),
+            tools: { bash: true, edit: true, read: true, write: true },
+        };
+    }
+    return { defaultAgent: canonicalDefaultAgentName, agents };
+}
+export function projectCanonicalAgentManifestToClaudeCode(manifest = canonicalAgentManifest) {
+    assertValidCanonicalManifest(manifest);
+    const manager = manifest.agents.find((agent) => agent.name === manifest.defaultAgentName && agent.mode === 'agent');
+    if (manager === undefined)
+        throw new Error(`Canonical Claude projection missing manager agent: ${manifest.defaultAgentName}`);
+    const agents = [
+        {
+            name: canonicalDefaultAgentName,
+            canonicalName: canonicalDefaultAgentName,
+            description: manager.description,
+            fileName: `${canonicalDefaultAgentName}.md`,
+            instructions: canonicalOpenCodeManagerPrompt,
+            promptContractVersion: canonicalPromptContractVersion,
+        },
+    ];
+    for (const mapping of claudeSddNameMappings) {
+        const subagent = manifest.agents.find((agent) => agent.name === mapping.canonical && agent.mode === 'subagent');
+        if (subagent === undefined)
+            throw new Error(`Canonical Claude projection missing subagent: ${mapping.canonical}`);
+        agents.push({
+            name: mapping.claude,
+            canonicalName: mapping.canonical,
+            description: claudeSubagentDescriptions[mapping.claude],
+            fileName: `${mapping.claude}.md`,
+            instructions: createCanonicalOpenCodeSddSubagentPrompt(mapping.canonical),
+            promptContractVersion: canonicalPromptContractVersion,
+        });
+    }
+    return { defaultAgent: canonicalDefaultAgentName, agents };
+}
+export function canonicalProviderProjection(provider, manifest = canonicalAgentManifest) {
+    assertValidCanonicalManifest(manifest);
+    const normalized = provider.trim().toLowerCase();
+    if (normalized === 'opencode')
+        return { provider: normalized, level: 'managed', manifest, projection: projectCanonicalAgentManifestToOpenCode(manifest) };
+    if (normalized === 'claude')
+        return { provider: normalized, level: 'managed', manifest, projection: projectCanonicalAgentManifestToClaudeCode(manifest) };
+    return { provider: normalized, level: 'unsupported', manifest, reason: `Unsupported provider projection: ${provider}` };
+}
+function assertValidCanonicalManifest(manifest) {
+    const errors = canonicalManifestValidationErrors(manifest);
+    if (errors.length > 0)
+        throw new Error(`Invalid canonical agent manifest: ${errors.join('; ')}`);
+}
+function toSeedAgent(agent) {
+    const seed = {
+        name: agent.name,
+        description: agent.description,
+        instructions: agent.instructions,
+    };
+    if (agent.capabilities !== undefined)
+        seed.capabilities = agent.capabilities;
+    if (agent.permissions !== undefined)
+        seed.permissions = agent.permissions;
+    if (agent.memory !== undefined)
+        seed.memory = agent.memory;
+    if (agent.workflows !== undefined)
+        seed.workflows = agent.workflows;
+    if (agent.skills !== undefined)
+        seed.skills = agent.skills;
+    if (agent.adapters !== undefined)
+        seed.adapters = agent.adapters;
+    return seed;
+}
+function toSeedSubagent(agent) {
+    if (agent.parentAgentName === undefined)
+        throw new Error(`Canonical subagent ${agent.name} is missing parentAgentName`);
+    return { ...toSeedAgent(agent), parentAgentName: agent.parentAgentName };
+}
+const openCodeSubagentDescriptions = {
+    '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',
+};
+const claudeSddNameMappings = [
+    { canonical: 'vgxness-sdd-explore', claude: 'vgxness-sdd-explore' },
+    { canonical: 'vgxness-sdd-propose', claude: 'vgxness-sdd-proposal' },
+    { canonical: 'vgxness-sdd-spec', claude: 'vgxness-sdd-spec' },
+    { canonical: 'vgxness-sdd-design', claude: 'vgxness-sdd-design' },
+    { canonical: 'vgxness-sdd-tasks', claude: 'vgxness-sdd-tasks' },
+    { canonical: 'vgxness-sdd-apply', claude: 'vgxness-sdd-apply-progress' },
+    { canonical: 'vgxness-sdd-verify', claude: 'vgxness-sdd-verify' },
+    { canonical: 'vgxness-sdd-archive', claude: 'vgxness-sdd-archive' },
+];
+const claudeSubagentDescriptions = {
+    'vgxness-sdd-explore': 'Investigate codebase context and risks for VGXNESS SDD changes.',
+    'vgxness-sdd-proposal': 'Create focused proposals for VGXNESS SDD changes.',
+    'vgxness-sdd-spec': 'Write detailed specifications for VGXNESS SDD changes.',
+    'vgxness-sdd-design': 'Create technical designs for VGXNESS SDD changes.',
+    'vgxness-sdd-tasks': 'Break accepted designs into implementation tasks.',
+    'vgxness-sdd-apply-progress': 'Implement accepted VGXNESS SDD tasks and report apply progress.',
+    'vgxness-sdd-verify': 'Verify VGXNESS SDD implementation evidence and risks.',
+    'vgxness-sdd-archive': 'Archive completed VGXNESS SDD outcomes and follow-ups.',
+};

package/dist/agents/renderers/claude-renderer.js

@@ -1,14 +1,14 @@
 import { ok, validationFailure } from './provider-adapter.js';
 const previewWarnings = [
-    'Claude rendering returns preview artifacts only; it does not install or write provider configuration.',
+    'Claude rendering returns installable preview artifacts only; it does not install or write provider configuration.',
     'VGX does not execute Claude or run Claude Code from this preview.',
-    'VGX does not install Claude Code, does not write .claude/, does not write CLAUDE.md, and does not write provider configuration.',
+    'VGXNESS does not install Claude Code, does not write CLAUDE.md, and does not write provider configuration from renderer previews.',
     'VGX does not guarantee exact Claude Code configuration compatibility; this output is a neutral preview only.',
 ];
 const previewSafety = {
     executesProvider: false,
     writesProviderConfig: false,
-    installable: false,
+    installable: true,
     previewOnly: true,
 };
 const claudeCapabilities = {
@@ -17,18 +17,19 @@ const claudeCapabilities = {
     permissionCategories: ['included as registry permission metadata in preview output'],
     memoryInjectionModes: ['included as registry memory metadata in preview output'],
     delegationModel: 'registry agents and subagents are represented in preview output without executing Claude delegation',
-    lifecycleHooks: ['preview render/export only'],
-    configFileLocations: ['rendered/claude/.../claude-preview.json'],
+    lifecycleHooks: ['preview render/export only; confirmed install is handled by MCP install service'],
+    configFileLocations: ['rendered/claude/.../.mcp.json', 'rendered/claude/.../.claude/agents/*.md'],
     limitations: [
         'Preview artifacts only; does not execute Claude or Claude Code.',
         'Does not install Claude Code or provider tooling.',
-        'Does not write .claude/, CLAUDE.md, or provider configuration.',
-        'Does not guarantee exact Claude Code configuration compatibility.',
+        'Renderer preview does not write .claude/, CLAUDE.md, or provider configuration.',
+        'Confirmed apply writes only project .mcp.json and .claude/agents/*.md.',
+        'Claude Code compatibility can drift; validate with provider doctor after confirmed install.',
     ],
     render: {
-        format: 'claude-json-preview',
-        artifactContentTypes: ['application/json'],
-        installable: false,
+        format: 'claude-code-project-preview',
+        artifactContentTypes: ['application/json', 'text/markdown'],
+        installable: true,
         previewOnly: true,
     },
 };
@@ -37,58 +38,35 @@ export class ClaudeAgentRenderer {
     capabilities = claudeCapabilities;
     render(input) {
         const agents = [input.agent, ...(input.subagents ?? [])];
-        const renderedAgents = {};
+        const artifacts = [
+            {
+                relativePath: `rendered/claude/${pathSegment(input.agent.project)}/${input.agent.scope}/${pathSegment(input.agent.name)}/.mcp.json`,
+                contentType: 'application/json',
+                contents: `${JSON.stringify({ mcpServers: { vgxness: { type: 'stdio', command: 'vgxness', args: ['mcp', 'start'] } } }, null, 2)}\n`,
+            },
+        ];
+        const renderedKeys = new Set();
         for (const agent of agents) {
             const key = claudeAgentKey(agent.name);
-            if (renderedAgents[key] !== undefined)
+            if (renderedKeys.has(key))
                 return validationFailure(`Rendered Claude agent key collision: ${key}`);
-            renderedAgents[key] = claudePreviewAgent(agent);
+            renderedKeys.add(key);
+            artifacts.push({
+                relativePath: `rendered/claude/${pathSegment(input.agent.project)}/${input.agent.scope}/${pathSegment(input.agent.name)}/.claude/agents/${key}.md`,
+                contentType: 'text/markdown',
+                contents: renderClaudeAgentMarkdown(agent, key),
+            });
         }
-        const preview = {
-            version: 1,
-            provider: 'claude',
-            installable: false,
-            compatibility: 'preview-only',
-            agents: renderedAgents,
-            safety: {
-                ...previewSafety,
-                writesClaudeDirectory: false,
-                compatibilityGuaranteed: false,
-            },
-            warnings: previewWarnings,
-        };
-        const artifact = {
-            relativePath: `rendered/claude/${pathSegment(input.agent.project)}/${input.agent.scope}/${pathSegment(input.agent.name)}/claude-preview.json`,
-            contentType: 'application/json',
-            contents: `${JSON.stringify(preview, null, 2)}\n`,
-        };
         return ok({
             provider: this.provider,
-            installable: false,
-            artifacts: [artifact],
+            installable: true,
+            artifacts,
             warnings: previewWarnings,
         });
     }
 }
-function claudePreviewAgent(agent) {
-    const adapter = claudeAdapter(agent);
-    const rendered = {
-        name: agent.name,
-        description: agent.description,
-        instructions: agent.instructions.value,
-        mode: agent.mode === 'subagent' ? 'subagent' : 'primary',
-        ...(adapter?.model !== undefined ? { model: adapter.model } : {}),
-        permissions: agent.permissions,
-        memory: agent.memory,
-        skills: agent.skills,
-    };
-    const profile = adapter?.config?.profile;
-    if (typeof profile === 'string')
-        rendered.profile = profile;
-    return rendered;
-}
-function claudeAdapter(agent) {
-    return agent.adapters.claude ?? agent.adapters['claude-code'];
+function renderClaudeAgentMarkdown(agent, key) {
+    return `---\nname: ${JSON.stringify(key)}\ndescription: ${JSON.stringify(agent.description)}\n---\n\n<!-- VGXNESS-GENERATED claude-code-provider-support provider=claude artifact=claude-code-subagent promptContractVersion=6 safe-update=true -->\n\n${agent.instructions.value.trim()}\n`;
 }
 function claudeAgentKey(value) {
     return pathSegment(value);

package/dist/cli/bun-bin.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { writeFileSync } from 'node:fs';
 import { basename } from 'node:path';
+import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames } from '../agents/canonical-agent-manifest.js';
 writeRuntimeEvidence();
 await import('./index.js');
 function writeRuntimeEvidence() {
@@ -30,6 +31,11 @@ function writeRuntimeEvidence() {
             isHelp: command.includes('--help') || command.includes('-h'),
             cwd: process.cwd(),
         },
+        canonicalAgents: {
+            defaultAgentName: canonicalDefaultAgentName,
+            promptContractVersion: canonicalPromptContractVersion,
+            sddSubagentCount: canonicalSddSubagentNames.length,
+        },
     };
     try {
         writeFileSync(evidencePath, `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');

package/dist/cli/cli-help.js

@@ -59,6 +59,8 @@ Areas:
   mcp setup --preview --provider opencode|claude [--db <path>]
   mcp install opencode --plan [--scope user|project] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
   mcp install opencode --yes [--scope user|project] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
+  mcp install claude --plan [--db <path>] [--overwrite-vgxness|--reinstall]
+  mcp install claude --yes [--db <path>] [--overwrite-vgxness|--reinstall]
   mcp doctor opencode [--scope user|project] [--project-root <path>]
   mcp doctor [--db <path>] [--project <name>] [--change <id>] [--timeout-ms <ms>]
   MCP setup preview is read-only; it does not install or write .opencode/, .claude/, or provider config.
@@ -67,6 +69,7 @@ Areas:
   Use --overwrite-vgxness (alias --reinstall) to reinstall only VGXNESS-managed OpenCode entries while preserving unrelated config; --yes is still required to write.
   It writes only after --yes. The default target is $HOME/.config/opencode/opencode.json; use --scope project to target .opencode/opencode.json explicitly.
   Project OpenCode config can override user config. Plans are read-only; applies refuse unsafe existing config and create backups before merge.
+  Claude install support is project-local only: confirmed applies write .mcp.json and .claude/agents/*.md. VGXNESS never writes ~/.claude.json, CLAUDE.md, or .claude/CLAUDE.md and does not execute/install Claude Code.
 
   skills register --project <name> --name <name> --description <text>
   skills list [--project <name>] [--scope project|personal]

package/dist/cli/commands/agent-skill-dispatcher.js

@@ -266,13 +266,14 @@ export function runAgentCommand(command, parsed, database, environment) {
     if (command === 'seed') {
         if (parsed.positionals[2] !== 'load')
             return usageFailure('agents seed requires load');
-        const file = requiredFlag(parsed.flags, 'file');
-        if (!file.ok)
-            return resultFailure(file);
-        const manifest = readJsonFile(file.value, environment);
+        const file = optionalStringFlag(parsed.flags, 'file');
+        const seed = new AgentSeedService(database);
+        if (file === undefined)
+            return jsonResult(seed.loadBuiltInDefaults());
+        const manifest = readJsonFile(file, environment);
         if (!manifest.ok)
             return resultFailure(manifest);
-        return jsonResult(new AgentSeedService(database).loadManifest(manifest.value));
+        return jsonResult(seed.loadManifest(manifest.value));
     }
     if (command === 'register') {
         const payload = registerPayload(parsed, environment, false);