create-snipara 2.0.3 → 2.0.4

package/README.md

@@ -171,6 +171,7 @@ The advanced flow asks for:
 
 The generated agent templates cover:
 
+- Snipara skill pack under `.snipara/templates/skills/`
 - Codex `AGENTS.md`
 - Claude Code `CLAUDE.md`
 - Cursor `.cursor/rules/snipara.mdc`
@@ -179,6 +180,13 @@ The generated agent templates cover:
 - Mistral Le Chat connector, Vibe config, and LangChain `ChatMistralAI.bindTools` snippets
 - Gemini, VS Code, Continue, and custom HTTP MCP reference snippets
 
+The generated skill pack includes portable, client-neutral skills for Snipara
+onboarding, context workflow, safe parallel work, agent security, and proof
+gates. Clients with native skill support can copy each folder from
+`.snipara/templates/skills/` into the client's skill location. Clients without
+native skills should keep using `AGENTS.md`, `CLAUDE.md`, or project rules as the
+shared instruction surface.
+
 For Codex, `SNIPARA_API_KEY` is the only generated bearer token environment
 variable. If Codex lazily exposes only a minimal Snipara MCP surface after
 restart, force exact discovery for `snipara_recall`, `snipara_context_query`,

package/dist/index.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "2.0.3",
+  version: "2.0.4",
   description: "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   main: "dist/index.js",
   type: "module",
@@ -1360,6 +1360,7 @@ async function createAgentTemplates(answers) {
     fs.writeFileSync(template.path, template.content);
   }
   console.log(chalk.green("   Created .snipara/templates agent snippets"));
+  writeAgentSkillPackTemplates(path.join(templatesDir, "skills"), answers);
   writeIfMissing(
     path.join(process.cwd(), "AGENTS.md"),
     buildAgentsMdTemplate(answers),
@@ -1406,6 +1407,320 @@ function writeIfMissing(filePath, content, label) {
 function buildHostedMcpEndpoint(answers) {
   return `${API_URL}/mcp/${answers.projectSlug}`;
 }
+function writeAgentSkillPackTemplates(skillsDir, answers) {
+  const skills = buildSniparaSkillPackTemplates(answers);
+  for (const skill of skills) {
+    const skillDir = path.join(skillsDir, skill.name);
+    const agentsDir = path.join(skillDir, "agents");
+    fs.mkdirSync(agentsDir, { recursive: true });
+    fs.writeFileSync(path.join(skillDir, "SKILL.md"), skill.skillMd);
+    fs.writeFileSync(path.join(agentsDir, "openai.yaml"), buildSkillOpenAiYaml(skill, answers));
+  }
+  console.log(chalk.green("   Created .snipara/templates/skills Snipara skill pack"));
+}
+function buildSkillOpenAiYaml(skill, answers) {
+  return [
+    "interface:",
+    `  display_name: ${JSON.stringify(skill.displayName)}`,
+    `  short_description: ${JSON.stringify(skill.shortDescription)}`,
+    `  default_prompt: ${JSON.stringify(skill.defaultPrompt)}`,
+    "",
+    "dependencies:",
+    "  tools:",
+    '    - type: "mcp"',
+    '      value: "snipara"',
+    '      description: "Snipara Hosted MCP"',
+    '      transport: "streamable_http"',
+    `      url: ${JSON.stringify(buildHostedMcpEndpoint(answers))}`,
+    "",
+    "policy:",
+    "  allow_implicit_invocation: true",
+    ""
+  ].join("\n");
+}
+function buildSniparaSkillPackTemplates(answers) {
+  const endpoint = buildHostedMcpEndpoint(answers);
+  const companionPrefix = answers.installCompanion ? "snipara-companion" : "npx -y snipara-companion@latest";
+  return [
+    {
+      name: "snipara-onboarding",
+      displayName: "Snipara Onboarding",
+      shortDescription: "Connect agents to Snipara safely",
+      defaultPrompt: "Use $snipara-onboarding to connect this project to Snipara Hosted MCP.",
+      skillMd: buildSniparaOnboardingSkill(endpoint, companionPrefix)
+    },
+    {
+      name: "snipara-context-workflow",
+      displayName: "Snipara Context Workflow",
+      shortDescription: "Use context, memory, and workflows",
+      defaultPrompt: "Use $snipara-context-workflow to ground this task in Snipara context.",
+      skillMd: buildSniparaContextWorkflowSkill(endpoint, companionPrefix)
+    },
+    {
+      name: "snipara-safe-parallel-work",
+      displayName: "Snipara Safe Parallel Work",
+      shortDescription: "Coordinate agents without collisions",
+      defaultPrompt: "Use $snipara-safe-parallel-work before editing shared files in parallel.",
+      skillMd: buildSniparaSafeParallelWorkSkill(companionPrefix)
+    },
+    {
+      name: "snipara-agent-security",
+      displayName: "Snipara Agent Security",
+      shortDescription: "Protect secrets, logs, and memory",
+      defaultPrompt: "Use $snipara-agent-security to review this agent workflow for secret and auth risks.",
+      skillMd: buildSniparaAgentSecuritySkill(endpoint, companionPrefix)
+    },
+    {
+      name: "snipara-proof-gates",
+      displayName: "Snipara Proof Gates",
+      shortDescription: "Verify work before calling it done",
+      defaultPrompt: "Use $snipara-proof-gates to define the proof needed before this task is done.",
+      skillMd: buildSniparaProofGatesSkill(companionPrefix)
+    }
+  ];
+}
+function buildSniparaOnboardingSkill(endpoint, companionPrefix) {
+  return [
+    "---",
+    "name: snipara-onboarding",
+    'description: "Set up Snipara Hosted MCP for an AI agent workspace, validate tool availability, configure API keys through environment variables, generate or merge agent instruction files, and run create-snipara or snipara-companion doctor checks. Use when onboarding a user, repository, assistant, or MCP-capable client to Snipara."',
+    "---",
+    "",
+    "# Snipara Onboarding",
+    "",
+    "## Start Gate",
+    "",
+    `Use the Hosted MCP endpoint: \`${endpoint}\`. Keep the API key in \`SNIPARA_API_KEY\` or the client secret store. Never paste keys into tracked files, prompts, logs, screenshots, or durable memory.`,
+    "",
+    "Validate availability with a tool-oriented call such as `snipara_help(list_all=true)`, `snipara_settings`, or a lightweight `snipara_context_query`. Empty MCP resources or resource templates do not prove an outage because Snipara may be exposed as a tool-only MCP server.",
+    "",
+    "## Setup Steps",
+    "",
+    "1. Detect the target client: Codex, Claude Code, Cursor, VS Code, Continue, ChatGPT/OpenAI MCP, Claude Desktop, Mistral, Gemini, Orca-style MCP clients, or a generic HTTP MCP client.",
+    "2. Prefer `npx create-snipara@latest` for initial setup. It generates Hosted MCP config, `AGENTS.md`, client-specific snippets, and the Snipara skill pack under `.snipara/templates/skills`.",
+    "3. Merge generated instructions into existing files instead of replacing project-specific guidance.",
+    `4. Run \`${companionPrefix} doctor\` when Companion is installed or available through npx.`,
+    "5. Restart or reload the client after MCP configuration changes, then verify tool discovery again.",
+    "",
+    "## Client Notes",
+    "",
+    "- Codex: merge `.snipara/templates/codex-config.toml` into the user or project Codex config if the app does not load project config automatically.",
+    "- Claude Code: keep `AGENTS.md` as the shared source and use `CLAUDE.md` as compatibility guidance.",
+    "- Cursor: use `.cursor/rules/snipara.mdc` for always-applied project guidance.",
+    "- Generic MCP clients: use the generated HTTP MCP reference and the shared `AGENTS.md` rules.",
+    "- Clients with native skills: copy each folder under `.snipara/templates/skills` into the client's skill location.",
+    "",
+    "## Failure Handling",
+    "",
+    "If broad discovery shows only a partial tool surface, call `snipara_help(list_all=true)` before concluding a tool is unavailable. If the client still lags after config changes, use Companion commands as a local fallback for recall, query, and task commit until the MCP session refreshes.",
+    ""
+  ].join("\n");
+}
+function buildSniparaContextWorkflowSkill(endpoint, companionPrefix) {
+  return [
+    "---",
+    "name: snipara-context-workflow",
+    'description: "Use Snipara Hosted MCP for project context, reviewed memory, source-grounded answers, code graph context, workflow mode selection, and durable task closeout. Use when an agent starts a task, resumes work, answers project-specific questions, edits code, or needs to distinguish source truth from memory."',
+    "---",
+    "",
+    "# Snipara Context Workflow",
+    "",
+    "## Source Order",
+    "",
+    `Start from Hosted MCP at \`${endpoint}\`, then local files and tests for exact current state.`,
+    "",
+    "1. Validate Snipara tool availability with `snipara_help`, `snipara_settings`, or a lightweight context query.",
+    "2. Use `snipara_recall` for durable decisions, preferences, validated learnings, and session carryover.",
+    "3. Use `snipara_context_query` for documents, product truth, runbooks, architecture notes, source material, and answer packs.",
+    "4. Use `snipara_get_chunk` before relying on precise wording from returned references.",
+    "5. Use local `rg`, file reads, git commands, lint, type-checks, and tests for exact working-tree truth.",
+    "",
+    "## Workflow Modes",
+    "",
+    "- LITE: small known-file work with low risk.",
+    "- STANDARD: normal project work that benefits from context and code graph follow-up.",
+    "- FULL: multi-file, risky, release/deploy, auth, billing, schema, migration, architectural, or compaction-prone work.",
+    "- Orchestrated FULL: work that needs htasks, production proof gates, routing, or parallel workers.",
+    "",
+    "Use Companion for managed workflow state when available:",
+    "",
+    "```bash",
+    `${companionPrefix} workflow start --goal "<goal>" --plan-file <plan.json>`,
+    `${companionPrefix} workflow phase-start <phase_id>`,
+    `${companionPrefix} workflow phase-commit <phase_id> --summary "<outcome>" --files <files...>`,
+    `${companionPrefix} workflow resume --include-session-context`,
+    "```",
+    "",
+    "## Code Graph And Impact",
+    "",
+    "Use exposed `snipara_code_*` tools for structural questions such as callers, imports, neighbors, paths, symbol cards, and impact. When Companion is installed and the local worktree may be dirty or ahead, prefer Companion code commands because they can select a local overlay and report `sourceSelection`.",
+    "",
+    "Run impact before risky multi-file changes, PR reviews, route/service/job changes, auth, billing, deployment, schema, migrations, or explicit gap analysis.",
+    "",
+    "## Memory Closeout",
+    "",
+    "End substantial work with `snipara_end_of_task_commit` or a managed Companion phase/final commit. Store only durable decisions, learnings, preferences, todos, and reusable context. Never store secrets, raw logs, transient command output, or guesses.",
+    ""
+  ].join("\n");
+}
+function buildSniparaSafeParallelWorkSkill(companionPrefix) {
+  return [
+    "---",
+    "name: snipara-safe-parallel-work",
+    'description: "Coordinate safe parallel work with Snipara Team Sync, collaboration sessions, claims, leases, guard checks, handoffs, and conflict outcomes. Use before editing shared files, taking over work, resuming a dirty workspace, committing, pushing, deploying, or running migrations in a team or multi-agent environment."',
+    "---",
+    "",
+    "# Snipara Safe Parallel Work",
+    "",
+    "## Start Or Resume",
+    "",
+    "Before editing in a shared repository, check what changed and whether another human or agent owns the same surface.",
+    "",
+    "```bash",
+    `${companionPrefix} workflow resume --include-session-context`,
+    `${companionPrefix} team-sync what-changed`,
+    `${companionPrefix} collaboration status`,
+    "```",
+    "",
+    "For new work, leave a visible breadcrumb:",
+    "",
+    "```bash",
+    `${companionPrefix} team-sync start-work --summary "<task>" --files <files...>`,
+    "```",
+    "",
+    "## Guard Before Risk",
+    "",
+    "Run collaboration guards before large edits, commits, pushes, deploys, migrations, schema work, package releases, or work on files likely to be touched by others.",
+    "",
+    "```bash",
+    `${companionPrefix} collaboration guard --files <files...>`,
+    `${companionPrefix} collaboration guard --profile pre-commit --enforce`,
+    `${companionPrefix} collaboration guard --profile pre-push --enforce`,
+    `${companionPrefix} collaboration guard --profile pre-deploy --enforce`,
+    "```",
+    "",
+    "Treat outcomes as follows:",
+    "",
+    "- `CLEAR`: proceed.",
+    "- `WATCH`: proceed, but leave a handoff and watch the surface.",
+    "- `REQUIRES_ACK` or `REVIEW_REQUIRED`: coordinate explicitly before proceeding.",
+    "- `BLOCKED`: stop until the conflict, lease, or ownership issue is resolved.",
+    "",
+    "## Claims And Leases",
+    "",
+    "Use exclusive claims only for genuinely risky surfaces such as schema, migrations, deployment scripts, auth, billing, package publication, or production data handling. Release claims when work finishes or becomes blocked.",
+    "",
+    "## Handoff",
+    "",
+    "End multi-agent work with a concise handoff:",
+    "",
+    "```bash",
+    `${companionPrefix} team-sync handoff --summary "<changed>" --next "<recommended next action>" --files <files...> --attention watch`,
+    "```",
+    "",
+    "Do not treat stale local warnings as final truth. Verify hosted active sessions and leases before blocking useful work.",
+    ""
+  ].join("\n");
+}
+function buildSniparaAgentSecuritySkill(endpoint, companionPrefix) {
+  return [
+    "---",
+    "name: snipara-agent-security",
+    'description: "Apply security guardrails to Snipara-enabled agent workflows, including API key handling, secret storage, memory hygiene, logging, webhook/OAuth callback review, URL handling, and fail-open versus fail-closed decisions. Use for onboarding, automation, reviews, and any task that touches credentials or sensitive project data."',
+    "---",
+    "",
+    "# Snipara Agent Security",
+    "",
+    "## Trust Boundary",
+    "",
+    `Hosted MCP endpoint: \`${endpoint}\`. The API key belongs in environment variables or the client secret store, not in tracked files.`,
+    "",
+    "Before changing an agent workflow, identify:",
+    "",
+    "- caller identity and auth mode",
+    "- project or team ownership boundary",
+    "- input source and whether it is user-controlled",
+    "- side effects such as writes, webhooks, deploys, memory writes, or package publication",
+    "- logs, telemetry, returned errors, and persisted artifacts",
+    "",
+    "## Secrets",
+    "",
+    "- Never commit API keys, OAuth tokens, private keys, database URLs, cookies, raw headers, or session secrets.",
+    "- Never store secrets in Snipara memory, handoff summaries, task commits, answer captures, or examples.",
+    "- Use `.env`, `.env.local`, OS keychains, launch agents, CI secrets, or MCP client secret fields.",
+    "- If a secret was committed or pasted into a durable artifact, treat it as compromised and rotate it.",
+    "",
+    "## Memory And Logs",
+    "",
+    "Persist durable reasoning, not sensitive payloads. Store decisions, workflows, and validated learnings. Do not store raw logs, transient command output, customer data dumps, credentials, or unreviewed guesses.",
+    "",
+    "Sanitize logs before sharing them with agents. Keep identifiers bounded and avoid raw request bodies unless the user explicitly approves and the data is safe.",
+    "",
+    "## Agent Automation",
+    "",
+    "For agent hooks, collaboration guards, and deploy gates, preserve the intended fail-open or fail-closed behavior. Security-critical writes should fail closed; developer-assist hints may fail open with a visible warning.",
+    "",
+    "Use Companion checks when available:",
+    "",
+    "```bash",
+    `${companionPrefix} doctor`,
+    `${companionPrefix} collaboration guard --profile pre-commit --enforce`,
+    `${companionPrefix} stuck-guard status`,
+    "```",
+    "",
+    "## Review Hotspots",
+    "",
+    "Review OAuth/device flows, GitHub App callbacks, webhooks, internal API secrets, generated MCP configs, URL path encoding, JSON embedded into script contexts, CORS/CSP changes, rate limits, and package hooks.",
+    "",
+    "State the threat reduced, files or configuration changed, tests run, and any deferred security work. Do not imply broad security coverage from a narrow patch.",
+    ""
+  ].join("\n");
+}
+function buildSniparaProofGatesSkill(companionPrefix) {
+  return [
+    "---",
+    "name: snipara-proof-gates",
+    'description: "Define and run proof gates before an agent calls Snipara-enabled work done, including local tests, lint/type-checks, code impact, package surface checks, deploy smoke tests, registry verification, and task commit evidence. Use for releases, package updates, production changes, risky edits, and user-visible workflow changes."',
+    "---",
+    "",
+    "# Snipara Proof Gates",
+    "",
+    "## Done Means Proven",
+    "",
+    "Do not call work complete just because code was edited. Match proof to blast radius and report gaps honestly.",
+    "",
+    "## Common Gates",
+    "",
+    "- Small code change: focused unit test, lint/type-check for touched package, and local behavior check.",
+    "- Route/service/job/auth/billing/schema/deploy change: code impact, focused tests, type-check, and environment-specific smoke.",
+    "- Package change: package tests, build, pack dry-run or pack smoke, registry comparison if publishing, and `npx` or clean install verification after publish.",
+    "- Production deploy: health checks, route-specific probes, live version marker when available, and log scan for the changed behavior.",
+    "- Documentation/template change: generated artifact inspection plus the smallest test proving the generator still emits the expected files.",
+    "",
+    "## Snipara-Specific Gates",
+    "",
+    "Use context and impact before risky conclusions:",
+    "",
+    "```bash",
+    `${companionPrefix} brief --task "<task>" --changed-files <files...> --diff-summary "<summary>"`,
+    `${companionPrefix} code impact --changed-files <files...> --diff-summary "<summary>"`,
+    "```",
+    "",
+    "Use managed workflow commits for durable proof:",
+    "",
+    "```bash",
+    `${companionPrefix} workflow phase-commit <phase_id> --summary "<outcome>" --files <files...>`,
+    `${companionPrefix} final-commit --summary "<final outcome>" --files <files...>`,
+    "```",
+    "",
+    "If Companion is unavailable, use hosted `snipara_code_impact` when exposed and `snipara_end_of_task_commit` for durable closeout.",
+    "",
+    "## Reporting",
+    "",
+    "Report commands run, files changed, published or deployed versions, smoke results, and anything not verified. Keep package-release status separate from app-deploy status.",
+    ""
+  ].join("\n");
+}
 function buildAgentsMdTemplate(answers) {
   return `# AGENTS.md
 
@@ -1432,6 +1747,9 @@ This project uses Snipara Hosted MCP for project context and reviewed memory.
   \`snipara-companion recall\`, \`snipara-companion query\`, and
   \`snipara-companion task-commit\` as the reliable local fallback, then restart
   or reload Codex after MCP config changes.
+- If the client supports native skills, install the generated Snipara skill pack
+  from \`.snipara/templates/skills\`. Keep this \`AGENTS.md\` file as the shared
+  fallback for clients without native skill support.
 
 ${EXPERIENCE_GOAL_SECTION}
 
@@ -1502,6 +1820,7 @@ Use Snipara Hosted MCP before answering project-specific questions.
 - Auth: use \`SNIPARA_API_KEY\` from the environment. Never commit keys.
 - At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`tools/list\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
 - If a session exposes only a subset of expected Snipara tools, call \`snipara_help(list_all=true)\` and compare exact tool names before concluding a tool is unavailable. If only a partial surface remains after exact discovery, use \`snipara-companion recall\`, \`snipara-companion query\`, and \`snipara-companion task-commit\` as a reliable local fallback.
+- If the client supports native skills, install the generated Snipara skill pack from \`.snipara/templates/skills\`. Keep \`AGENTS.md\` as the shared fallback for clients without native skill support.
 
 ${EXPERIENCE_GOAL_SECTION}
 
@@ -1541,6 +1860,7 @@ This workspace uses Snipara Hosted MCP for current project context, business/cli
 - Endpoint: \`${buildHostedMcpEndpoint(answers)}\`
 - At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`tools/list\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
 - If a session exposes only a subset of expected Snipara tools, call \`snipara_help(list_all=true)\` and compare exact tool names before concluding a tool is unavailable. If only a partial surface remains after exact discovery, use \`snipara-companion recall\`, \`snipara-companion query\`, and \`snipara-companion task-commit\` as a reliable local fallback.
+- If the client supports native skills, install the generated Snipara skill pack from \`.snipara/templates/skills\`. Keep \`AGENTS.md\` as the shared fallback for clients without native skill support.
 
 ${EXPERIENCE_GOAL_SECTION}
 
@@ -2941,6 +3261,11 @@ async function runValidation(answers, includeHostedCheck, options = {}) {
     status: detection.files.sniparaTemplates && detection.files.cursorRule && detection.files.codexConfig ? "pass" : "warn",
     detail: detection.files.sniparaTemplates && detection.files.cursorRule && detection.files.codexConfig ? ".snipara/templates, .cursor/rules/snipara.mdc, and .codex/config.toml present" : "Agent templates, Cursor rule, or Codex config missing"
   });
+  checks.push({
+    name: "snipara_skill_pack",
+    status: detection.files.sniparaSkillPack ? "pass" : "warn",
+    detail: detection.files.sniparaSkillPack ? ".snipara/templates/skills contains the Snipara skill pack" : "Snipara skill pack missing from .snipara/templates/skills"
+  });
   if (targetClient === "codex") {
     checks.push(getCodexConfigCheck());
   }
@@ -3502,7 +3827,8 @@ function detectEnvironment() {
       cursorDir: fs.existsSync(path.join(homedir(), ".cursor")),
       mistralVibeConfig: fs.existsSync(path.join(process.cwd(), ".vibe", "config.toml")) || fs.existsSync(path.join(homedir(), ".vibe", "config.toml")),
       sniparaCompanionPack: fs.existsSync(path.join(process.cwd(), ".snipara", "companion")),
-      sniparaTemplates: fs.existsSync(path.join(process.cwd(), ".snipara", "templates"))
+      sniparaTemplates: fs.existsSync(path.join(process.cwd(), ".snipara", "templates")),
+      sniparaSkillPack: fs.existsSync(path.join(process.cwd(), ".snipara", "templates", "skills"))
     },
     tooling: {
       node: commandExists("node"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-snipara",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   "main": "dist/index.js",
   "type": "module",