@stackmemoryai/stackmemory 1.10.4 → 1.12.0

package/dist/src/orchestrators/multimodal/harness.js

@@ -51,6 +51,45 @@ function heuristicPlan(input) {
     ]
   };
 }
+function deterministicCritique(args) {
+  const issues = [];
+  const suggestions = [];
+  if (!args.ok) {
+    issues.push("Implementer command failed");
+    suggestions.push("Fix the command invocation before retrying");
+  }
+  if (args.diff.includes("<<<<<<<") || args.diff.includes(">>>>>>>")) {
+    issues.push("Merge conflict markers detected in diff");
+    suggestions.push("Resolve conflict markers before approval");
+  }
+  if (args.checks && !args.checks.lintOk) {
+    issues.push("Lint checks failed");
+    suggestions.push("Address lint failures before approval");
+  }
+  if (args.checks && !args.checks.testsOk) {
+    issues.push("Tests failed");
+    suggestions.push("Fix failing tests before approval");
+  }
+  const failedVerifications = args.checks?.verifications.filter((verification) => !verification.ok) || [];
+  if (failedVerifications.length > 0) {
+    issues.push(
+      `Verification command failed: ${failedVerifications[0]?.command}`
+    );
+    suggestions.push(
+      "Use the verification output as the primary repro signal and fix the root cause"
+    );
+  }
+  if (!args.diff || args.diff.startsWith("(no changes detected)")) {
+    suggestions.push(
+      "No code changes detected; verify the task can be satisfied without edits"
+    );
+  }
+  return {
+    approved: issues.length === 0,
+    issues,
+    suggestions
+  };
+}
 async function runSpike(input, options = {}) {
   const plannerSystem = `You write concise, actionable implementation plans. Output raw JSON only (no markdown code fences). Schema: { "summary": "string", "steps": [{ "id": "step-1", "title": "string", "rationale": "string", "acceptanceCriteria": ["string"] }], "risks": ["string"] }`;
   const contextSummary = getLocalContextSummary(input.repoPath);
@@ -61,23 +100,28 @@ ${contextSummary}
 Constraints: Keep the plan minimal and implementable in a single PR.`;
   const t0 = Date.now();
   let plan;
-  try {
-    const raw = await callClaude(plannerPrompt, {
-      model: options.plannerModel,
-      system: plannerSystem
-    });
+  if (options.deterministicFixture) {
+    plan = heuristicPlan(input);
+  } else {
     try {
-      const cleaned = raw.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "").trim();
-      plan = JSON.parse(cleaned);
+      const raw = await callClaude(plannerPrompt, {
+        model: options.plannerModel,
+        system: plannerSystem
+      });
+      try {
+        const cleaned = raw.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "").trim();
+        plan = JSON.parse(cleaned);
+      } catch {
+        plan = heuristicPlan(input);
+      }
     } catch {
       plan = heuristicPlan(input);
     }
-  } catch {
-    plan = heuristicPlan(input);
   }
   const planLatencyMs = Date.now() - t0;
   const implementer = options.implementer || "codex";
   const maxIters = Math.max(1, options.maxIters ?? 2);
+  const verificationCommands = options.verificationCommands || [];
   const iterations = [];
   let approved = false;
   let lastCommand = "";
@@ -89,10 +133,14 @@ Constraints: Keep the plan minimal and implementable in a single PR.`;
   };
   for (let i = 0; i < maxIters; i++) {
     const stepsList = plan.steps.map((s, idx) => `${idx + 1}. ${s.title}`).join("\n");
+    const verificationPrompt = verificationCommands.length > 0 ? `
+
+Verification commands that must pass:
+${verificationCommands.map((command) => `- ${command}`).join("\n")}` : "\n\nIf this task fixes uncertain behavior, first create or identify a deterministic repro/test/trace that fails for the current behavior, then use it to guide the fix.";
     const basePrompt = `Implement the following plan:
 ${stepsList}
 
-Keep changes minimal and focused. Avoid unrelated edits.`;
+Keep changes minimal and focused. Avoid unrelated edits.${verificationPrompt}`;
     const refine = i === 0 ? "" : `
 Incorporate reviewer suggestions: ${lastCritique.suggestions.join("; ")}`;
     const implPrompt = basePrompt + refine;
@@ -116,14 +164,20 @@ Incorporate reviewer suggestions: ${lastCritique.suggestions.join("; ")}`;
       _lastOutput = impl.output;
     }
     const diff = options.dryRun !== false ? "(dry run \u2014 no diff)" : captureGitDiff(input.repoPath);
-    const checks = options.dryRun !== false ? null : runPostImplChecks(input.repoPath);
+    const checks = options.dryRun !== false ? null : runPostImplChecks(input.repoPath, verificationCommands);
+    const verificationSection = checks && checks.verifications.length > 0 ? `
+  Custom verification:
+${checks.verifications.map(
+      (verification) => `  - ${verification.ok ? "PASS" : "FAIL"} ${verification.command}
+${verification.output}`
+    ).join("\n")}` : "";
     const checksSection = checks ? `
 
 Post-implementation checks:
   Lint: ${checks.lintOk ? "PASS" : "FAIL"}
 ${checks.lintOutput}
   Tests: ${checks.testsOk ? "PASS" : "FAIL"}
-${checks.testOutput}` : "";
+${checks.testOutput}${verificationSection}` : "";
     const criticSystem = `You are a strict code reviewer. Review the git diff against the plan. Check for: correctness, missing steps, unrelated changes, bugs, security issues. Also review lint and test results if provided. Return raw JSON only (no markdown fences): { "approved": boolean, "issues": ["string"], "suggestions": ["string"] }`;
     const criticPrompt = `Plan: ${plan.summary}
 Acceptance criteria:
@@ -134,25 +188,35 @@ Implementer exit: ${ok ? "success" : "failed"}
 
 Git diff:
 ${diff}${checksSection}`;
-    try {
-      const raw = await callClaude(criticPrompt, {
-        model: options.reviewerModel,
-        system: criticSystem
+    if (options.deterministicFixture) {
+      lastCritique = deterministicCritique({
+        plan,
+        ok,
+        diff,
+        checks
       });
-      const cleaned = raw.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "").trim();
-      lastCritique = JSON.parse(cleaned);
-    } catch {
-      lastCritique = {
-        approved: ok,
-        issues: ok ? [] : ["Critique failed"],
-        suggestions: []
-      };
+    } else {
+      try {
+        const raw = await callClaude(criticPrompt, {
+          model: options.reviewerModel,
+          system: criticSystem
+        });
+        const cleaned = raw.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "").trim();
+        lastCritique = JSON.parse(cleaned);
+      } catch {
+        lastCritique = {
+          approved: ok,
+          issues: ok ? [] : ["Critique failed"],
+          suggestions: []
+        };
+      }
     }
     iterations.push({
       command: lastCommand,
       ok,
       outputPreview: diff.slice(0, 2e3),
-      critique: lastCritique
+      critique: lastCritique,
+      checks
     });
     if (lastCritique.approved) {
       approved = true;
@@ -177,62 +241,64 @@ ${diff}${checksSection}`;
     editFuzzyFallbacks: editMetrics.editFuzzyFallbacks,
     contextTokens: Math.ceil(finalDiff.length / 4)
   };
-  try {
-    const dir = options.auditDir || path.join(input.repoPath, ".stackmemory", "build");
-    fs.mkdirSync(dir, { recursive: true });
-    const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const file = path.join(dir, `spike-${stamp}.json`);
-    fs.writeFileSync(
-      file,
-      JSON.stringify(
-        {
-          input,
-          options: { ...options, auditDir: void 0 },
-          plan,
-          iterations,
-          metrics: runMetrics
-        },
-        null,
-        2
-      )
-    );
-    const metricsFile = path.join(dir, "harness-metrics.jsonl");
-    fs.appendFileSync(metricsFile, JSON.stringify(runMetrics) + "\n");
+  if (options.persistAudit !== false) {
     try {
-      const lines = fs.readFileSync(metricsFile, "utf-8").split("\n").filter((l) => l.trim());
-      const recent = lines.slice(-10).map((l) => JSON.parse(l));
-      if (recent.length >= 3) {
-        const summary = summarizeRuns(recent);
-        if (summary.approvalRate < HARNESS_TARGETS.firstPassApprovalRate) {
-          feedbackLoops.fire(
-            "harnessRegression",
-            "metrics_append",
-            {
-              metric: "approvalRate",
-              current: summary.approvalRate,
-              target: HARNESS_TARGETS.firstPassApprovalRate,
-              window: recent.length
-            },
-            "regression_alert"
-          );
-        }
-        if (summary.p95TotalLatencyMs > HARNESS_TARGETS.totalLatencyP95Ms) {
-          feedbackLoops.fire(
-            "harnessRegression",
-            "metrics_append",
-            {
-              metric: "totalLatencyP95",
-              current: summary.p95TotalLatencyMs,
-              target: HARNESS_TARGETS.totalLatencyP95Ms,
-              window: recent.length
-            },
-            "regression_alert"
-          );
+      const dir = options.auditDir || path.join(input.repoPath, ".stackmemory", "build");
+      fs.mkdirSync(dir, { recursive: true });
+      const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+      const file = path.join(dir, `spike-${stamp}.json`);
+      fs.writeFileSync(
+        file,
+        JSON.stringify(
+          {
+            input,
+            options: { ...options, auditDir: void 0 },
+            plan,
+            iterations,
+            metrics: runMetrics
+          },
+          null,
+          2
+        )
+      );
+      const metricsFile = path.join(dir, "harness-metrics.jsonl");
+      fs.appendFileSync(metricsFile, JSON.stringify(runMetrics) + "\n");
+      try {
+        const lines = fs.readFileSync(metricsFile, "utf-8").split("\n").filter((l) => l.trim());
+        const recent = lines.slice(-10).map((l) => JSON.parse(l));
+        if (recent.length >= 3) {
+          const summary = summarizeRuns(recent);
+          if (summary.approvalRate < HARNESS_TARGETS.firstPassApprovalRate) {
+            feedbackLoops.fire(
+              "harnessRegression",
+              "metrics_append",
+              {
+                metric: "approvalRate",
+                current: summary.approvalRate,
+                target: HARNESS_TARGETS.firstPassApprovalRate,
+                window: recent.length
+              },
+              "regression_alert"
+            );
+          }
+          if (summary.p95TotalLatencyMs > HARNESS_TARGETS.totalLatencyP95Ms) {
+            feedbackLoops.fire(
+              "harnessRegression",
+              "metrics_append",
+              {
+                metric: "totalLatencyP95",
+                current: summary.p95TotalLatencyMs,
+                target: HARNESS_TARGETS.totalLatencyP95Ms,
+                window: recent.length
+              },
+              "regression_alert"
+            );
+          }
         }
+      } catch {
       }
     } catch {
     }
-  } catch {
   }
   if (options.record) {
     void recordContext(
@@ -265,7 +331,8 @@ ${diff}${checksSection}`;
       commands: iterations.map((it) => it.command)
     },
     critique: lastCritique,
-    iterations
+    iterations,
+    verification: iterations.at(-1)?.checks || null
   };
 }
 const runPlanAndCode = runSpike;
@@ -341,6 +408,9 @@ Repo: ${input.repoPath}
 Notes: ${input.contextNotes || "(none)"}
 ${contextSummary}
 Constraints: Keep the plan minimal and implementable in a single PR.`;
+  if (options.deterministicFixture) {
+    return heuristicPlan(input);
+  }
   try {
     const raw = await callClaude(plannerPrompt, {
       model: options.plannerModel,

package/dist/src/orchestrators/multimodal/providers.js

@@ -115,7 +115,7 @@ ${newFiles.join("\n")}`;
     return "(git diff failed)";
   }
 }
-function runPostImplChecks(cwd) {
+function runPostImplChecks(cwd, verificationCommands = []) {
   const maxOutput = 2e3;
   function truncate(s) {
     if (s.length <= maxOutput) return s;
@@ -152,7 +152,47 @@ function runPostImplChecks(cwd) {
   } catch (e) {
     testOutput = truncate(e instanceof Error ? e.message : String(e));
   }
-  return { lintOk, lintOutput, testsOk, testOutput };
+  return {
+    lintOk,
+    lintOutput,
+    testsOk,
+    testOutput,
+    verifications: runVerificationCommands(cwd, verificationCommands)
+  };
+}
+function runVerificationCommands(cwd, commands, options = {}) {
+  const timeout = options.timeoutMs ?? 12e4;
+  const maxOutput = options.maxOutput ?? 4e3;
+  const truncate = (value) => {
+    if (value.length <= maxOutput) return value;
+    return value.slice(0, maxOutput) + `
+... (truncated, ${value.length} total chars)`;
+  };
+  return commands.map((command) => command.trim()).filter(Boolean).map((command) => {
+    try {
+      const result = spawnSync(command, {
+        cwd,
+        encoding: "utf8",
+        shell: true,
+        timeout,
+        maxBuffer: Math.max(maxOutput * 4, 1024 * 1024)
+      });
+      const output = truncate((result.stdout || "") + (result.stderr || ""));
+      return {
+        command,
+        ok: result.status === 0,
+        output: output || (result.status === 0 ? "(command completed with no output)" : `(command failed with exit ${result.status ?? "unknown"})`)
+      };
+    } catch (error) {
+      return {
+        command,
+        ok: false,
+        output: truncate(
+          error instanceof Error ? error.message : String(error)
+        )
+      };
+    }
+  });
 }
 function parseEditMetrics(diff) {
   if (!diff || diff.startsWith("(")) {
@@ -204,5 +244,6 @@ export {
   captureGitDiff,
   implementWithClaude,
   parseEditMetrics,
-  runPostImplChecks
+  runPostImplChecks,
+  runVerificationCommands
 };

package/dist/src/utils/hook-installer.js

@@ -32,14 +32,6 @@ const CANONICAL_HOOKS = [
     commandPrefix: "node",
     required: true
   },
-  {
-    scriptName: "cord-trace.js",
-    eventType: "PostToolUse",
-    matcher: "mcp__.*__cord_(spawn|fork|complete|ask|tree)",
-    timeout: 2,
-    commandPrefix: "node",
-    required: true
-  },
   {
     scriptName: "theory-capture.js",
     eventType: "PostToolUse",
@@ -89,6 +81,14 @@ const CANONICAL_HOOKS = [
     timeout: 10,
     commandPrefix: "node",
     required: false
+  },
+  {
+    scriptName: "doc-ingest.js",
+    eventType: "PostToolUse",
+    matcher: "WebFetch",
+    timeout: 15,
+    commandPrefix: "node",
+    required: false
   }
 ];
 const DEAD_HOOKS = ["sms-response-handler.js"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackmemoryai/stackmemory",
-  "version": "1.10.4",
+  "version": "1.12.0",
   "description": "Lossless, project-scoped memory for AI coding tools. Durable context across sessions with 56 MCP tools, FTS5 search, conductor orchestrator, loop/watch monitoring, snapshot capture, pre-flight overlap checks, Claude/Codex/OpenCode wrappers, Linear sync, and automatic hooks.",
   "engines": {
     "node": ">=20.0.0",
@@ -45,6 +45,7 @@
     "scripts/verify-dist.cjs",
     "scripts/smoke-init-db.sh",
     "templates",
+    "packs",
     "README.md",
     "LICENSE"
   ],
@@ -114,6 +115,11 @@
     "test:run": "vitest run",
     "test:pre-publish": "./scripts/test-pre-publish-quick.sh",
     "test:pre-commit": "vitest related --run --reporter=dot --silent --bail=1",
+    "determinism:smoke": "node --import tsx src/cli/index.ts bench determinism --task \"Determinism probe\" --runs 5",
+    "determinism:watch": "node --import tsx src/cli/index.ts bench determinism --task \"Determinism probe\" --runs 3 --watch",
+    "determinism:latest": "node --import tsx src/cli/index.ts bench determinism --latest --json",
+    "determinism:test": "npx vitest run src/orchestrators/multimodal/__tests__/determinism.test.ts --reporter=dot",
+    "determinism:pre-commit": "bash scripts/determinism-pre-commit.sh",
     "prepublishOnly": "npm run build && npm run verify:dist && npm run test:pre-publish",
     "quality": "npm run lint && npm run test:run && npm run build",
     "dev": "tsx watch src/integrations/mcp/server.ts",
@@ -136,6 +142,9 @@
     "sync:start": "node scripts/background-sync-manager.js",
     "sync:setup": "./scripts/setup-background-sync.sh",
     "eval:cord": "npx tsx scripts/evals/cord-vs-flat-eval.ts",
+    "gepa:eval": "node scripts/gepa/eval-phases.js",
+    "gepa:eval:json": "node scripts/gepa/eval-phases.js --json",
+    "gepa:mine": "node scripts/gepa/gold/mine-traces.js",
     "prepare": "echo 'Prepare step completed'",
     "verify:dist": "node scripts/verify-dist.cjs",
     "test:smoke-db": "bash scripts/smoke-init-db.sh",

package/packs/coding/python-fastapi/instructions.md

@@ -0,0 +1,60 @@
+# coding/python-fastapi
+
+## Python Conventions
+
+- **Python 3.11+.** Use modern syntax: `match/case`, `type` aliases, `ExceptionGroup`.
+- **Type hints everywhere.** All function signatures, return types, and class attributes. Use `from __future__ import annotations` for forward references.
+- **Pydantic v2 for data validation.** `BaseModel` for schemas, `model_validator` for complex validation. Never use raw dicts for API I/O.
+- **Async by default.** Use `async def` for route handlers and DB operations. Use `asyncio.gather` for concurrent I/O.
+- **No global mutable state.** Use dependency injection via FastAPI's `Depends()`.
+- **Naming.** snake_case for functions/variables. PascalCase for classes. UPPER_SNAKE for constants.
+
+## FastAPI Patterns
+
+- **Router per domain.** `app/routers/users.py`, `app/routers/items.py`. Mount with `app.include_router()`.
+- **Pydantic schemas for I/O.** Separate `Create`, `Update`, `Response` schemas. Never expose ORM models directly.
+- **Dependency injection.** DB sessions, auth, config — all via `Depends()`. Define in `app/dependencies.py`.
+- **Status codes.** Use `status.HTTP_201_CREATED` for creates, `HTTP_204_NO_CONTENT` for deletes. Raise `HTTPException` with proper codes.
+- **Background tasks.** Use `BackgroundTasks` for fire-and-forget. Use Celery/ARQ for durable jobs.
+- **Middleware.** CORS, request logging, error handling. Define in `app/middleware.py`.
+
+## Project Structure
+
+```
+app/
+  main.py           # FastAPI app instance + startup
+  core/
+    config.py       # Settings via pydantic-settings
+    security.py     # Auth utilities
+  routers/          # APIRouter modules
+  models/           # SQLAlchemy/SQLModel ORM models
+  schemas/          # Pydantic request/response models
+  dependencies.py   # Shared Depends() callables
+  middleware.py      # Middleware stack
+tests/
+  conftest.py       # Fixtures (test client, DB)
+  test_*.py         # Test modules
+```
+
+## Database
+
+- **SQLAlchemy 2.0 style.** `select()` not `query()`. Mapped classes with `Mapped[]` annotations.
+- **Alembic for migrations.** Auto-generate with `alembic revision --autogenerate`. Never edit the DB schema manually.
+- **Session management.** Async sessions via `async_sessionmaker`. Yield in dependency.
+- **Connection pooling.** Configure `pool_size`, `max_overflow` in production.
+
+## Testing
+
+- **pytest + httpx.** Use `AsyncClient` with `app` for integration tests.
+- **Fixtures for DB.** Create test database, run migrations, yield session, rollback.
+- **Factory pattern for test data.** Use `factory_boy` or simple fixture functions.
+- **Test the API, not internals.** Call endpoints via client, assert response shape + status.
+
+## Common Anti-Patterns to Catch
+
+- Synchronous DB calls in async handlers → blocks the event loop
+- Raw SQL without parameterization → SQL injection risk
+- Returning ORM models from endpoints → use Pydantic response models
+- Missing `async` on route handlers with I/O → blocks worker threads
+- Hardcoded secrets → use environment variables via pydantic-settings
+- Missing input validation → always validate via Pydantic schemas

package/packs/coding/python-fastapi/pack.yaml

@@ -0,0 +1,28 @@
+name: coding/python-fastapi
+version: 1.0.0
+description: Python + FastAPI conventions, patterns, and guardrails for AI coding agents
+author: stackmemory
+license: MIT
+runtime:
+  type: local
+ingestion:
+  sources: []
+ontology:
+  entities:
+    - endpoint
+    - model
+    - schema
+    - dependency
+    - middleware
+  relations:
+    - handles
+    - validates
+    - depends-on
+mcp:
+  tools: []
+examples:
+  - input: "Create a CRUD API endpoint"
+    output: "Use Pydantic models for request/response, dependency injection for DB session, proper HTTP status codes, async handlers"
+  - input: "How should I structure a FastAPI project?"
+    output: "app/ with routers/, models/, schemas/, dependencies/, core/ (config, security). Use APIRouter per domain."
+instructions: instructions.md

package/packs/coding/typescript-react/instructions.md

@@ -0,0 +1,47 @@
+# coding/typescript-react
+
+## TypeScript Conventions
+
+- **Strict mode always.** `"strict": true` in tsconfig.json. No `any` unless genuinely unavoidable — use `unknown` and narrow.
+- **ESM imports.** Always add `.js` extension to relative imports in ESM projects. Use `type` imports for type-only references.
+- **Prefer interfaces** for object shapes. Use `type` for unions, intersections, and mapped types.
+- **No enums.** Use `as const` objects or union types instead. Enums have runtime cost and poor tree-shaking.
+- **Error handling.** Return `undefined` over throwing. If you must throw, use typed error classes. Never `catch (e: any)`.
+- **Naming.** PascalCase for types/interfaces/components. camelCase for variables/functions. UPPER_SNAKE for constants.
+
+## React Patterns
+
+- **Functional components only.** No class components.
+- **Custom hooks for data fetching.** Extract `useQuery`/`useMutation` patterns into `use*` hooks. Never fetch in component body.
+- **State management.** useState for local, useReducer for complex local, Context for cross-tree, Zustand/Jotai for global.
+- **Memoization.** Don't prematurely memo. Use `React.memo` only when profiler shows re-render cost. `useMemo`/`useCallback` for referential stability when passed to children.
+- **Keys.** Never use array index as key. Use stable IDs from data.
+- **Error boundaries.** Wrap route-level components. Use `react-error-boundary` library.
+
+## File Structure
+
+```
+src/
+  components/     # Shared UI components
+  features/       # Feature-scoped modules (components + hooks + types)
+  hooks/          # Shared custom hooks
+  lib/            # Non-React utilities
+  types/          # Shared type definitions
+  routes/         # Route components (if not using file-based routing)
+```
+
+## Testing
+
+- **Vitest or Jest** for unit tests. React Testing Library for component tests.
+- **Test behavior, not implementation.** Query by role/text, not test-id.
+- **No snapshot tests** unless testing serialized output.
+- **Mock at boundaries.** Mock API calls (MSW), not internal modules.
+
+## Common Anti-Patterns to Catch
+
+- `useEffect` with missing dependencies → use ESLint exhaustive-deps rule
+- Prop drilling > 2 levels → extract to Context or composition
+- Giant components > 200 lines → split into smaller components
+- Inline styles → use CSS modules, Tailwind, or styled-components
+- `any` type assertions → narrow with type guards
+- Non-null assertions (`!`) → handle the null case explicitly

package/packs/coding/typescript-react/pack.yaml

@@ -0,0 +1,28 @@
+name: coding/typescript-react
+version: 1.0.0
+description: TypeScript + React conventions, patterns, and guardrails for AI coding agents
+author: stackmemory
+license: MIT
+runtime:
+  type: local
+ingestion:
+  sources: []
+ontology:
+  entities:
+    - component
+    - hook
+    - context
+    - route
+    - api-endpoint
+  relations:
+    - renders
+    - depends-on
+    - provides
+mcp:
+  tools: []
+examples:
+  - input: "Create a React component that fetches data"
+    output: "Use a custom hook with useEffect + useState, handle loading/error states, return typed JSX"
+  - input: "How should I structure my TypeScript types?"
+    output: "Prefer interfaces for object shapes, use type for unions/intersections, export from a types.ts barrel file"
+instructions: instructions.md

package/packs/core/commands/capture.md

@@ -0,0 +1,32 @@
+# /capture — Save session context via StackMemory
+
+Run `stackmemory capture` to commit current work and generate a handoff prompt for the next session.
+
+## Usage
+
+`$ARGUMENTS` — optional flags passed directly to `stackmemory capture`.
+
+## Behavior
+
+1. Run `stackmemory capture $ARGUMENTS`
+2. Display the generated handoff prompt
+3. If `--copy` flag is present, confirm the prompt was copied to clipboard
+
+## Common flags
+
+| Flag | Effect |
+|------|--------|
+| `-m "message"` | Custom commit message |
+| `--no-commit` | Skip git commit, just generate handoff |
+| `--copy` | Copy handoff prompt to clipboard |
+| `--format ultra` | Ultra-compact pipe-delimited format |
+| `--format verbose` | Full markdown format |
+
+## Examples
+
+```
+/capture                          # Default capture with auto-format
+/capture -m "privacy policy PR"   # With custom message
+/capture --copy                   # Capture and copy to clipboard
+/capture --no-commit --copy       # Just generate handoff, no commit
+```