nativesoul 0.1.0

package/plugins/antigravity-nativesoul/commands/nativesoul-explore.md

@@ -0,0 +1,22 @@
+# nativesoul-explore
+
+Explore the current project with NativeSoul context.
+
+Default policy: read-only and bounded. Do not edit files, install packages, start services, create schedulers, or perform external writes.
+
+1. Call MCP `life_bootstrap` with `host="antigravity"`.
+2. Inspect readiness with:
+
+```bash
+nativesoul dashboard data --host antigravity --limit 25 --json
+```
+
+3. Scope discovery to the operator request. Prefer targeted local reads:
+
+```bash
+rg --files
+rg "<specific term from the task>"
+```
+
+4. Avoid broad unbounded scans. If a write is needed, stop and ask for normal approval.
+

package/plugins/antigravity-nativesoul/commands/nativesoul-heartbeat.md

@@ -0,0 +1,9 @@
+# nativesoul-heartbeat
+
+Run a heartbeat tick without creating a hidden scheduler:
+
+1. Claim a lease with host `antigravity`.
+2. If the result is `HEARTBEAT_OK`, stay silent.
+3. Complete only leases won by Antigravity.
+
+Native schedule status remains `native_schedule_supported=false` until Antigravity documents an official scheduler surface.

package/plugins/antigravity-nativesoul/commands/nativesoul-plan.md

@@ -0,0 +1,23 @@
+# nativesoul-plan
+
+Build a NativeSoul-aware plan for the current Antigravity task.
+
+Default policy: read-only.
+
+1. Call MCP `life_bootstrap` with `host="antigravity"` and the current working directory.
+2. Read dashboard state:
+
+```bash
+nativesoul dashboard data --host antigravity --limit 25 --json
+```
+
+3. Read commitments and capabilities when relevant:
+
+```bash
+nativesoul commitments list --project <project-id> --status open --limit 25 --json
+nativesoul capabilities list --host antigravity --limit 25 --json
+```
+
+4. Separate implemented, degraded/fallback, and approval-required work.
+5. Do not mutate schedules, memory, policy, or files without explicit approval.
+

package/plugins/antigravity-nativesoul/commands/nativesoul-recall.md

@@ -0,0 +1,16 @@
+# nativesoul-recall
+
+Recall NativeSoul project memory and capability context for the current Antigravity task.
+
+Default policy: read-only.
+
+1. Prefer MCP `life_recall` with `host="antigravity"` and the current working directory.
+2. If MCP is unavailable, run:
+
+```bash
+nativesoul memory recall-hook --host antigravity --cwd "$PWD" --prompt "<task query>" --limit 8 --json
+```
+
+3. Treat recovered memory as advisory and verify against files.
+4. Report readiness honestly as `ready`, `full native capability`, `official-fallback`, or `degraded`.
+

package/plugins/antigravity-nativesoul/commands/nativesoul-start.md

@@ -0,0 +1,9 @@
+# nativesoul-start
+
+Call MCP `life_bootstrap` with `host="antigravity"` and the current working directory.
+
+If MCP is unavailable, run:
+
+```bash
+nativesoul bootstrap --host antigravity --cwd "$PWD" --format inject --json
+```

package/plugins/antigravity-nativesoul/hooks.json

@@ -0,0 +1,59 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"shared/hooks/host-hook.cjs\" session-start --host antigravity --project-env GEMINI_CWD",
+            "timeout": 9
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"shared/hooks/host-hook.cjs\" prompt-bootstrap --host antigravity --project-env GEMINI_CWD",
+            "timeout": 9
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"shared/hooks/host-hook.cjs\" pre-tool-use --host antigravity --project-env GEMINI_CWD",
+            "timeout": 9
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"shared/hooks/host-hook.cjs\" memory-flush --host antigravity --project-env GEMINI_CWD",
+            "timeout": 9
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"shared/hooks/host-hook.cjs\" memory-flush --host antigravity --project-env GEMINI_CWD",
+            "timeout": 9
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/antigravity-nativesoul/mcp_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "nativesoul": {
+      "command": "nativesoul-mcp",
+      "args": []
+    }
+  }
+}

package/plugins/antigravity-nativesoul/nativesoul-package.json

@@ -0,0 +1,22 @@
+{
+  "name": "antigravity-nativesoul",
+  "version": "0.1.0",
+  "nativeSoul": {
+    "host": "antigravity",
+    "packageKind": "native-plugin",
+    "nativeHooksSupported": true,
+    "nativeSchedulerSupported": false,
+    "mcpServer": {
+      "name": "nativesoul",
+      "command": "nativesoul-mcp",
+      "args": []
+    },
+    "commands": [
+      "nativesoul-start",
+      "nativesoul-heartbeat",
+      "nativesoul-recall",
+      "nativesoul-plan",
+      "nativesoul-explore"
+    ]
+  }
+}

package/plugins/antigravity-nativesoul/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "nativesoul",
+  "version": "0.1.0",
+  "description": "NativeSoul continuity, memory, policy, and MCP bootstrap for Antigravity."
+}

package/plugins/claude-nativesoul/.claude-plugin/plugin.json

@@ -0,0 +1,90 @@
+{
+  "name": "nativesoul",
+  "version": "0.1.0",
+  "description": "NativeSoul continuity bootstrap for Claude Code sessions.",
+  "mcpServers": {
+    "nativesoul": {
+      "command": "nativesoul-mcp",
+      "args": []
+    }
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/session-start.cjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/memory-flush.cjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/memory-flush.cjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/user-prompt-submit.cjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/pre-tool-use.cjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
+  "skills": [
+    {
+      "name": "life:start",
+      "path": "skills/life-start/SKILL.md"
+    },
+    {
+      "name": "life:heartbeat",
+      "path": "skills/life-heartbeat/SKILL.md"
+    },
+    {
+      "name": "life:recall",
+      "path": "skills/life-recall/SKILL.md"
+    },
+    {
+      "name": "life:plan",
+      "path": "skills/life-plan/SKILL.md"
+    },
+    {
+      "name": "life:explore",
+      "path": "skills/life-explore/SKILL.md"
+    }
+  ]
+}

package/plugins/claude-nativesoul/hooks/loader.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+function sharedRoots(fromDir) {
+  return [
+    path.join(fromDir, '..', 'shared', 'hooks'),
+    path.join(fromDir, '..', '..', 'shared', 'hooks')
+  ];
+}
+
+function loadShared(fromDir, name) {
+  for (const root of sharedRoots(fromDir)) {
+    const candidate = path.join(root, name);
+    if (fs.existsSync(candidate)) {
+      return require(candidate);
+    }
+  }
+  throw new Error(`NativeSoul shared hook module not found: ${name}`);
+}
+
+module.exports = { loadShared, sharedRoots };

package/plugins/claude-nativesoul/hooks/memory-flush.cjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+'use strict';
+
+const { loadShared } = require('./loader.cjs');
+const lib = loadShared(__dirname, 'lib.cjs');
+
+const HOOK_TIMEOUT_MS = lib.DEFAULT_HOOK_TIMEOUT_MS;
+const HOST = 'claude';
+const PROJECT_ENV = 'CLAUDE_PROJECT_DIR';
+
+function flushArgs(input) {
+  const cwd = lib.resolveProjectDir(input, PROJECT_ENV);
+  const event = input.hook_event_name || input.event || 'Stop';
+  return lib.appendHomeArg(['memory', 'flush-hook', '--host', HOST, '--cwd', cwd, '--event', event, '--json']);
+}
+
+function runNativeSoul(input) {
+  return lib.spawnNativeSoul(flushArgs(input), {
+    input: `${JSON.stringify(input)}\n`,
+    timeout: HOOK_TIMEOUT_MS
+  });
+}
+
+async function main() {
+  const input = await lib.readStdin();
+  runNativeSoul(input);
+}
+
+function run() {
+  lib.runNonBlocking(main, HOOK_TIMEOUT_MS);
+}
+
+if (require.main === module) {
+  run();
+}
+
+module.exports = {
+  HOOK_TIMEOUT_MS,
+  HOST,
+  flushArgs,
+  readStdin: lib.readStdin,
+  runNativeSoul,
+  main,
+  run
+};

package/plugins/claude-nativesoul/hooks/pre-tool-use.cjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+'use strict';
+
+const { loadShared } = require('./loader.cjs');
+const lib = loadShared(__dirname, 'lib.cjs');
+const policy = loadShared(__dirname, 'policy-fail-closed.cjs');
+
+const HOOK_TIMEOUT_MS = lib.DEFAULT_HOOK_TIMEOUT_MS;
+const HOST = 'claude';
+const PROJECT_ENV = 'CLAUDE_PROJECT_DIR';
+
+function policyArgs(input) {
+  const cwd = lib.resolveProjectDir(input, PROJECT_ENV);
+  return lib.appendHomeArg(['policy', 'pretooluse-hook', '--host', HOST, '--cwd', cwd, '--json']);
+}
+
+function runNativeSoul(input) {
+  const result = lib.spawnNativeSoul(policyArgs(input), {
+    input: `${JSON.stringify(input)}\n`,
+    timeout: HOOK_TIMEOUT_MS
+  });
+  const parsed = lib.parseJsonStdout(result);
+  return parsed ?? policy.buildFailClosedPreToolUseResult(input);
+}
+
+async function main() {
+  const input = await lib.readStdin({ fallback: (raw) => ({ raw }) });
+  const result = runNativeSoul(input);
+  const output = lib.buildPreToolUseHookOutput(result);
+  if (output) {
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+  }
+}
+
+function run() {
+  lib.runNonBlocking(main, HOOK_TIMEOUT_MS);
+}
+
+if (require.main === module) {
+  run();
+}
+
+module.exports = {
+  HOOK_TIMEOUT_MS,
+  HOST,
+  buildHookOutput: lib.buildPreToolUseHookOutput,
+  fallbackPolicyResult: policy.buildFailClosedPreToolUseResult,
+  policyArgs,
+  readStdin: lib.readStdin,
+  runNativeSoul,
+  main,
+  run
+};

package/plugins/claude-nativesoul/hooks/session-start.cjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+const { loadShared } = require('./loader.cjs');
+const lib = loadShared(__dirname, 'lib.cjs');
+
+const HOOK_TIMEOUT_MS = lib.DEFAULT_HOOK_TIMEOUT_MS;
+const HOST = 'claude';
+const PROJECT_ENV = 'CLAUDE_PROJECT_DIR';
+
+function bootstrapArgs(input, format) {
+  const cwd = lib.resolveProjectDir(input, PROJECT_ENV);
+  return lib.appendHomeArg(['bootstrap', '--host', HOST, '--cwd', cwd, '--format', format, '--json']);
+}
+
+function capabilityRefreshArgs() {
+  const args = ['capabilities', 'refresh', '--host', HOST, '--delta', '--json'];
+  lib.appendHomeArg(args);
+  const ttl = process.env.NATIVESOUL_CAPABILITY_REFRESH_TTL_SECONDS;
+  if (ttl && ttl.trim().length > 0) {
+    args.push('--ttl-seconds', ttl.trim());
+  }
+  return args;
+}
+
+function runCapabilityRefresh() {
+  const result = lib.spawnNativeSoul(capabilityRefreshArgs(), {
+    timeout: 1900,
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  if (result.status !== 0) {
+    return { stale: true };
+  }
+  try {
+    const parsed = JSON.parse(result.stdout);
+    const stale = Array.isArray(parsed) && parsed.some((item) => item && item.status === 'degraded');
+    const skipped = Array.isArray(parsed) && parsed.every((item) => item && item.skipped === true);
+    return { stale, skipped };
+  } catch {
+    return { stale: true };
+  }
+}
+
+function runCapabilityLearn() {
+  lib.spawnNativeSoul(lib.appendHomeArg(['capabilities', 'learn', '--host', HOST, '--json']), {
+    timeout: 1900,
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+}
+
+function runNativeSoul(input, format) {
+  const result = lib.spawnNativeSoul(bootstrapArgs(input, format), {
+    timeout: HOOK_TIMEOUT_MS,
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  return lib.parseJsonStdout(result);
+}
+
+function buildHookOutput(context) {
+  const additionalContext = context.capabilityRefreshStale
+    ? `${context.content}\n\nwarnings:\n- CAPABILITY_REFRESH_STALE`
+    : context.content;
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext
+    }
+  };
+}
+
+async function main() {
+  const input = await lib.readStdin({ fallback: () => ({}) });
+  const capabilityRefresh = runCapabilityRefresh();
+  if (!capabilityRefresh.stale && !capabilityRefresh.skipped) {
+    runCapabilityLearn();
+  }
+  const injected = runNativeSoul(input, 'inject');
+  const context = injected && typeof injected.content === 'string'
+    ? injected
+    : runNativeSoul(input, 'cache');
+
+  if (!context || typeof context.content !== 'string') {
+    return;
+  }
+
+  process.stdout.write(`${JSON.stringify(buildHookOutput({ ...context, capabilityRefreshStale: capabilityRefresh.stale }))}\n`);
+}
+
+function run() {
+  lib.runNonBlocking(main, HOOK_TIMEOUT_MS);
+}
+
+if (require.main === module) {
+  run();
+}
+
+module.exports = {
+  HOOK_TIMEOUT_MS,
+  bootstrapArgs,
+  capabilityRefreshArgs,
+  buildHookOutput,
+  readStdin: lib.readStdin,
+  runCapabilityRefresh,
+  runCapabilityLearn,
+  runNativeSoul,
+  main,
+  run
+};

package/plugins/claude-nativesoul/hooks/user-prompt-submit.cjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+
+const { loadShared } = require('./loader.cjs');
+const lib = loadShared(__dirname, 'lib.cjs');
+
+const HOOK_TIMEOUT_MS = lib.DEFAULT_HOOK_TIMEOUT_MS;
+const HOST = 'claude';
+const PROJECT_ENV = 'CLAUDE_PROJECT_DIR';
+
+function recallArgs(input) {
+  const cwd = lib.resolveProjectDir(input, PROJECT_ENV);
+  return lib.appendHomeArg(['memory', 'recall-hook', '--host', HOST, '--cwd', cwd, '--json']);
+}
+
+function runNativeSoul(input) {
+  const result = lib.spawnNativeSoul(recallArgs(input), {
+    input: `${JSON.stringify(input)}\n`,
+    timeout: HOOK_TIMEOUT_MS
+  });
+  return lib.parseJsonStdout(result);
+}
+
+function buildHookOutput(result) {
+  if (!result || typeof result.context !== 'string' || result.context.length === 0) {
+    return null;
+  }
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: result.context
+    }
+  };
+}
+
+async function main() {
+  const input = await lib.readStdin({ fallback: (raw) => ({ prompt: raw }) });
+  const result = runNativeSoul(input);
+  const output = buildHookOutput(result);
+  if (output) {
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+  }
+}
+
+function run() {
+  lib.runNonBlocking(main, HOOK_TIMEOUT_MS);
+}
+
+if (require.main === module) {
+  run();
+}
+
+module.exports = {
+  HOOK_TIMEOUT_MS,
+  HOST,
+  buildHookOutput,
+  recallArgs,
+  readStdin: lib.readStdin,
+  runNativeSoul,
+  main,
+  run
+};

package/plugins/claude-nativesoul/skills/life-explore/SKILL.md

@@ -0,0 +1,19 @@
+# life:explore
+
+Use this skill when the operator asks to explore a codebase, find current implementation boundaries, or map what exists.
+
+Default policy: read-only and bounded. Never edit files, run migrations, install packages, start background services, or trigger external writes from this skill.
+
+1. Load context with MCP `life_bootstrap` using `host="claude"` and the current working directory.
+2. Inspect capability readiness using `nativesoul dashboard data --host claude --limit 25 --json` or MCP capability tools.
+3. Scope exploration to the operator's request. Prefer targeted file discovery such as:
+
+```sh
+rg --files
+rg "<specific term from the task>"
+```
+
+4. Avoid broad unbounded scans. If the task is vague, inspect only high-signal files first: README, package metadata, docs, stories, ADRs, and nearby source modules.
+5. Report findings with file paths and distinguish verified code facts from memory-derived or inferred context.
+6. If a write, install, network call, scheduler mutation, or policy change seems needed, stop and ask for normal approval instead of performing it inside this skill.
+

package/plugins/claude-nativesoul/skills/life-heartbeat/SKILL.md

@@ -0,0 +1,16 @@
+# life:heartbeat
+
+Use this skill only when invoked by a Claude Scheduled Task for NativeSoul heartbeat checks.
+
+Default policy: read-only. Do not edit workspace files, memories, `SOUL.md`, `POLICY.md`, scheduler state, or host configuration unless the operator explicitly approves a follow-up change.
+
+1. Determine the project from the Scheduled Task context. If it is missing, use the current working directory.
+2. Claim a local heartbeat lease through MCP `life_heartbeat_claim` with `host="claude"`, the project id or directory, and the Scheduled Task slot/time as `slot`.
+3. If the claim response says another host owns the lease, the lease is already completed, or no work is needed, stop and return only `HEARTBEAT_OK`.
+4. Read NativeSoul context through MCP/read-only commands and inspect heartbeat guidance such as `HEARTBEAT.md`.
+5. If no operator-visible action is required, complete the lease with MCP `life_heartbeat_complete` and `result="HEARTBEAT_OK"`, then return only `HEARTBEAT_OK`.
+6. If action is required, complete the lease with concise evidence, then report the action request without secrets or raw credentials.
+
+`HEARTBEAT_OK` is a silent acknowledgement token. Do not notify the user for it.
+
+Never create a cron fallback. If Claude Scheduled Tasks are unavailable, the adapter must report unsupported and leave local schedule state as unsupported.

package/plugins/claude-nativesoul/skills/life-plan/SKILL.md

@@ -0,0 +1,23 @@
+# life:plan
+
+Use this skill when the operator asks for a NativeSoul-aware plan before execution.
+
+Default policy: read-only. Do not apply schedules, policy packs, onboarding changes, memory transitions, or workspace edits unless the operator explicitly approves the next action.
+
+1. Load context with MCP `life_bootstrap` using `host="claude"` and the current working directory.
+2. Read local dashboard state:
+
+```sh
+nativesoul dashboard data --host claude --limit 25 --json
+```
+
+3. Read open commitments if needed:
+
+```sh
+nativesoul commitments list --project <project-id> --status open --limit 25 --json
+```
+
+4. Read capability readiness with `nativesoul capabilities list --host claude --limit 25 --json`.
+5. Produce a plan that separates implemented state, degraded/fallback state, and approval-required actions.
+6. Do not claim a host feature is native unless the capability evidence says `full native capability`.
+

package/plugins/claude-nativesoul/skills/life-recall/SKILL.md

@@ -0,0 +1,18 @@
+# life:recall
+
+Use this skill when the operator asks for prior context, project memory, or continuity before a Claude Code task.
+
+Default policy: read-only. Do not create, promote, reject, forget, or edit memories unless the operator explicitly asks for that policy flow.
+
+1. Determine the current working directory and concise task query.
+2. Prefer MCP `life_recall` with `host="claude"`, the current project/cwd, and the task query.
+3. If MCP is unavailable, run:
+
+```sh
+nativesoul memory recall-hook --host claude --cwd "$PWD" --prompt "<task query>" --limit 8 --json
+```
+
+4. If recall output is empty, say no durable memory was found; do not invent context.
+5. Treat recovered memory as advisory and verify against repository files before making code decisions.
+6. Include capability readiness honestly when relevant: `ready`, `full native capability`, `official-fallback`, or `degraded`.
+

package/plugins/claude-nativesoul/skills/life-start/SKILL.md

@@ -0,0 +1,13 @@
+# life:start
+
+Use this skill at the start of a Claude Code session when NativeSoul context is needed.
+
+1. Prefer the SessionStart hook output if it is already present.
+2. If context is missing, call MCP `life_bootstrap` with `host="claude"` and the current working directory.
+3. If MCP is unavailable, run:
+
+```sh
+nativesoul bootstrap --host claude --cwd "$PWD" --format cache
+```
+
+Follow the injected `soul_summary`, `agents_operating_summary`, policy hints, and project context. Do not edit `SOUL.md` or `POLICY.md` directly; propose changes for approval.