just-vibe 0.7.0

package/plugins/just-vibe/scripts/toolkit.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+import { readFileSync, statSync } from 'node:fs';
+import { isDirectRun } from './lib/entrypoint.mjs';
+import { loadCatalog, getCommand, skillFile, invocation, HOSTS, MODES } from './lib/catalog.mjs';
+import { inspectProject } from './lib/project.mjs';
+import { discoverCapabilities, readCapabilityReport, listTools, recommend } from './lib/discovery.mjs';
+import { createRun, startStage, recordStage, finishRun, resumeRun, amendStage, supersedeStage, setRunProfiles } from './lib/run.mjs';
+import { loadProfiles, getProfile, searchProfiles } from './lib/profiles.mjs';
+import { createQuiz, presentQuestion, answerQuestion, reviewFreeText, quizReport } from './lib/teaching.mjs';
+import { main as installerMain, HELP as INSTALLER_HELP } from './installer.mjs';
+import { routeContext, starterIds } from './lib/routing.mjs';
+import { continuity } from './lib/continuity.mjs';
+import { collectEvidence } from './lib/evidence.mjs';
+import { manageHooks } from './lib/automation.mjs';
+
+export const HELP = `${INSTALLER_HELP}
+Workflow utilities:
+  tools [query]          Browse/search shipped workflows and prerequisites
+  show <workflow>        Read a workflow's full instructions
+  profiles [query]       Browse engineering profiles (not capability grants)
+  profile <id>           Read a role's priorities, decisions and verification
+  inspect               Inspect project manifests and Git identity
+  discover              Report local capabilities; never log in or call services
+  route <goal>           Suggest candidates for the host agent, not execute them
+  workflow <id> <brief>  Produce a context/run record for the host agent
+  session <operation>   Transform a run record from JSON on stdin
+                        Operations: create, start, amend, supersede, profile,
+                        record, finish, resume
+  quiz <operation>      Native-dialog quiz state from JSON on stdin
+                        Operations: create, present, answer, review, report
+  project <operation>   Explicit project preferences, notes and checkpoints
+                        init, show, configure, remember, forget, checkpoint,
+                        resume, list; writes use JSON on stdin
+  evidence <collector>  github, vercel, browser, migrations
+  hooks <operation>     status, configure, trust, untrust, disable, recover
+                        Inactive until configured and explicitly trusted
+
+Options:
+  --root <directory>    Project to inspect (default: current directory)
+  --target codex|claude Invocation format (default: claude for examples)
+  --pack <id>           Filter tools by pack
+  --available          Show only workflows with verified prerequisites
+  --all                Also include uninstalled/planned/unsupported entries
+  --json               Machine-readable output
+  --limit <number>     Bound tools/route results (route defaults to 3)
+  --capabilities <file> Host-observed capability report, valid for 15 minutes
+  --mode inspect|plan|apply
+  --scope <path>        Restrict workflow scope within the project
+  --profile <id>        Pin a task profile when creating a workflow record
+  --brief-file <file>   Preserve a UTF-8 brief verbatim (max 1 MiB)
+  --stdin              Read the brief or session/quiz JSON from stdin
+  -- <brief>           Treat all remaining arguments as context, not flags
+
+Evidence options: --repo owner/name --pr NUMBER; --deployment ID/URL
+  --team TEAM; --url URL --steps FILE; --directory DIR --applied FILE
+Project checkpoint/resume takes a name after the operation. JSON updates
+include the current revision (0 to create). Project writes go in .just-vibe.
+Browser steps may interact with the chosen site; other collectors only read.
+
+Commands such as fix, React, database and ML workflows execute as skills in
+the active Codex/Claude agent. This CLI does not launch a model or execute
+candidate workflows. Use show to inspect a workflow and invoke it in your host.
+`;
+
+const operations = new Set(['tools', 'show', 'profiles', 'profile', 'inspect', 'discover', 'route', 'workflow', 'session', 'quiz', 'project', 'evidence', 'hooks']);
+const booleans = new Set(['--json', '--available', '--all', '--stdin']);
+const values = new Set(['--root', '--target', '--pack', '--capabilities', '--mode', '--scope', '--profile', '--brief-file', '--limit', '--repo', '--pr', '--deployment', '--team', '--url', '--steps', '--directory', '--applied']);
+
+export function parseToolkitArgs(args) {
+  const [operation, ...rest] = args;
+  if (!operations.has(operation)) throw new Error(`Unknown utility: ${operation}`);
+  const options = { operation, root: process.cwd(), target: 'claude', positionals: [] };
+  const seen = new Set();
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--') { options.positionals.push(...rest.slice(i + 1)); break; }
+    if (!arg.startsWith('--')) { options.positionals.push(arg); continue; }
+    if (!booleans.has(arg) && !values.has(arg)) throw new Error(`Unknown option: ${arg}. Put literal context after --.`);
+    if (seen.has(arg)) throw new Error(`Duplicate option: ${arg}`);
+    seen.add(arg);
+    const key = arg.slice(2);
+    if (booleans.has(arg)) options[key] = true;
+    else {
+      const value = rest[++i];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value.`);
+      options[key] = value;
+    }
+  }
+  if (!HOSTS.includes(options.target)) throw new Error('target must be codex or claude.');
+  if (options.mode && !MODES.includes(options.mode)) throw new Error('mode must be inspect, plan, or apply.');
+  if (options.stdin && options['brief-file']) throw new Error('Use only one brief source.');
+  if (options.limit !== undefined) { options.limit = Number(options.limit); if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 1000) throw Error('limit must be between 1 and 1000.'); }
+  const allowed = {
+    tools: ['json', 'available', 'all', 'root', 'target', 'pack', 'capabilities', 'limit'],
+    show: ['json', 'target'], inspect: ['json', 'root'], discover: ['json', 'root', 'capabilities'],
+    profiles: ['json'], profile: ['json'],
+    route: ['json', 'root', 'target', 'capabilities', 'stdin', 'brief-file', 'limit'],
+    workflow: ['json', 'root', 'target', 'mode', 'scope', 'profile', 'stdin', 'brief-file'], session: ['json', 'target', 'stdin'], quiz: ['json', 'stdin'],
+    project: ['json', 'root', 'stdin'], hooks: ['json', 'root', 'stdin'],
+    evidence: ['json', 'root', 'repo', 'pr', 'deployment', 'team', 'url', 'steps', 'directory', 'applied'],
+  };
+  for (const flag of seen) if (!allowed[operation].includes(flag.slice(2))) throw new Error(`${flag} does not apply to ${operation}.`);
+  if (['inspect', 'discover'].includes(operation) && options.positionals.length) throw new Error(`${operation} takes no positional arguments.`);
+  if (['show', 'profile', 'session', 'quiz'].includes(operation) && options.positionals.length !== 1) throw new Error(`${operation} requires exactly one name.`);
+  if (['hooks', 'evidence'].includes(operation) && options.positionals.length !== 1) throw Error(`${operation} requires exactly one operation.`);
+  if (operation === 'project' && options.positionals.length !== (['checkpoint', 'resume'].includes(options.positionals[0]) ? 2 : 1)) throw Error('project checkpoint/resume requires a name; other project operations take one operation.');
+  if (operation === 'evidence') {
+    const valid = { github: ['repo', 'pr'], vercel: ['deployment', 'team'], browser: ['url', 'steps'], migrations: ['directory', 'applied'] }[options.positionals[0]];
+    if (!valid || [...seen].some(flag => !['root', 'json', ...valid].includes(flag.slice(2)))) throw Error('Invalid collector or options for this collector.');
+  }
+  if (['project', 'hooks'].includes(operation)) {
+    const writes = operation === 'project' ? ['init', 'configure', 'remember', 'forget', 'checkpoint'] : ['configure'];
+    if (writes.includes(options.positionals[0]) && !options.stdin) throw Error('This operation requires --stdin JSON.');
+    if (!writes.includes(options.positionals[0]) && options.stdin) throw Error('--stdin does not apply to this operation.');
+  }
+  return options;
+}
+
+export function readStdin(limit = 1024 * 1024) {
+  // Read in bounded chunks; do not buffer an arbitrarily large pipe before checking size.
+  const chunks = []; let size = 0;
+  return new Promise((done, fail) => {
+    process.stdin.on('data', chunk => {
+      size += chunk.length;
+      if (size > limit) { process.stdin.destroy(); fail(new Error('stdin exceeds 1 MiB.')); }
+      else chunks.push(chunk);
+    });
+    process.stdin.on('end', () => done(Buffer.concat(chunks).toString('utf8')));
+    process.stdin.on('error', fail);
+  });
+}
+
+async function getBrief(options, words, input) {
+  if ((options.stdin || options['brief-file']) && words.length) throw new Error('Use context arguments or a brief source, not both.');
+  if (options.stdin) return input();
+  if (options['brief-file']) {
+    const stat = statSync(options['brief-file']);
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error('Brief must be a regular file up to 1 MiB.');
+    return readFileSync(options['brief-file'], 'utf8');
+  }
+  return words.join(' ');
+}
+
+function formatTools(result) {
+  if (!result.tools.length) return 'No matching workflows with the requested filters. Try tools --all or a broader scenario.';
+  return [result.note, '', ...result.tools.map(c => `${c.id} [${c.pack}; ${c.status}; ${c.defaultMode}]${c.aliasOf ? ` → ${c.aliasOf}` : ''}\n  ${c.summary}\n  ${c.invocation} ${c.example.brief}${c.reasons.length ? `\n  Needs: ${c.reasons.join('; ')}` : ''}`)].join('\n');
+}
+
+function formatRoute(result) {
+  if (!result.recommendations.length) return 'No clear workflow match. Describe the outcome or use tools to browse.';
+  return [`Suggested path: ${result.strategy.suggested}. ${result.strategy.reasons.join('; ')}.`,
+    result.confidence === 'ambiguous' ? 'Several workflows fit; choose using the scope below.' : 'Best matching candidates:',
+    ...result.recommendations.map(c => `\n${c.id} [${c.status}] — ${c.summary}\n  ${c.selectionReasons.join('; ')}\n  ${c.invocation}`),
+    '\nSuggestions only. Preserve the complete request and verify task-specific access before execution. Use --json for full context.'].join('\n');
+}
+
+export async function main(args, { log = console.log, error = console.error, input = readStdin, catalog = loadCatalog } = {}) {
+  try {
+    if (!args.length || ['--help', '-h'].includes(args[0]) || (args[0] === 'help' && args.length === 1)) { log(HELP); return 0; }
+    if (['setup', 'doctor', 'update', 'uninstall', '--version'].includes(args[0])) return installerMain(args, { log, error });
+    if (args[0] === 'help') args = ['tools', ...args.slice(1)];
+    const options = parseToolkitArgs(args);
+    const data = catalog();
+    let result;
+    const discovery = () => discoverCapabilities(options.root, {
+      report: options.capabilities ? readCapabilityReport(options.capabilities, options.root) : undefined,
+    });
+    if (options.operation === 'tools') {
+      const found = discovery();
+      let tools = listTools(data, found, { query: options.positionals.join(' '), pack: options.pack,
+        available: options.available, all: options.all, host: options.target });
+      const starter = !options.all && !options.available && !options.pack && !options.positionals.length;
+      if (starter) { const ids = starterIds(routeContext(options.root)); tools = ids.flatMap(id => tools.filter(t => t.id === id)); }
+      result = { tools: tools.slice(0, options.limit || 1000), total: data.commands.length, starter, integrations: found.integrations,
+        note: starter ? 'Start here, search tools <scenario>, or use tools --all for the full catalog. Status reports observed prerequisites, not executed model behavior.' : 'Shipped workflow inventory; host enablement and permissions still apply. Available means declared task prerequisites were observed, not that a model has executed the workflow.' };
+    } else if (options.operation === 'show') {
+      const command = getCommand(data, options.positionals[0]);
+      result = { ...command, invocation: invocation(command, options.target), instructions: readFileSync(skillFile(data, command), 'utf8') };
+    } else if (options.operation === 'profiles') result = { profiles: searchProfiles(loadProfiles(), options.positionals.join(' ')), note: 'Role priorities for the task; search matches are candidates, not automatic selections.' };
+    else if (options.operation === 'profile') result = getProfile(loadProfiles(), options.positionals[0]);
+    else if (options.operation === 'inspect') result = inspectProject(options.root);
+    else if (options.operation === 'discover') result = discovery();
+    else if (options.operation === 'route') result = recommend(data, discovery(), await getBrief(options, options.positionals, input), { host: options.target, ...(options.limit ? { limit: options.limit } : {}) });
+    else if (options.operation === 'project') result = continuity(options.root, options.positionals[0], options.stdin ? JSON.parse(await input()) : {}, options.positionals[1]);
+    else if (options.operation === 'hooks') result = manageHooks(options.root, options.positionals[0], options.stdin ? JSON.parse(await input()) : {});
+    else if (options.operation === 'evidence') result = await collectEvidence(options.positionals[0], { ...options, scope: options.team });
+    else if (options.operation === 'workflow') {
+      const [id, ...words] = options.positionals;
+      if (!id) throw new Error('workflow requires a command ID.');
+      result = createRun(data, id, { ...options, brief: await getBrief(options, words, input) });
+    } else if (options.operation === 'quiz') {
+      const payload = JSON.parse(await input());
+      const op = options.positionals[0];
+      if (op === 'create') result = createQuiz(payload);
+      else if (op === 'present') result = presentQuestion(payload.quiz, payload.question, payload.dialog);
+      else if (op === 'answer') result = answerQuestion(payload.quiz, payload.response);
+      else if (op === 'review') result = reviewFreeText(payload.quiz, payload.judgment);
+      else if (op === 'report') result = quizReport(payload.quiz);
+      else throw new Error(`Unknown quiz operation: ${op}`);
+    } else if (options.operation === 'session') {
+      const payload = JSON.parse(await input());
+      const op = options.positionals[0];
+      if (op === 'create') result = createRun(data, payload.command, payload);
+      else if (op === 'start') {
+        const found = discoverCapabilities(payload.run.root, { report: payload.capabilityReport });
+        result = startStage(data, payload.run, payload.stage, found.capabilities, options.target);
+      } else if (op === 'amend') result = amendStage(payload.run, payload.action);
+      else if (op === 'supersede') result = supersedeStage(payload.run, payload.resolution);
+      else if (op === 'profile') result = setRunProfiles(payload.run, payload.selection);
+      else if (op === 'record') result = recordStage(payload.run, payload.outcome);
+      else if (op === 'finish') result = finishRun(payload.run, payload.outcome);
+      else if (op === 'resume') result = resumeRun(payload.run, payload.observation);
+      else throw new Error(`Unknown session operation: ${op}`);
+    }
+    if (options.operation === 'tools' && !options.json) log(formatTools(result));
+    else if (options.operation === 'route' && !options.json) log(formatRoute(result));
+    else if (options.operation === 'profiles' && !options.json) log([result.note, ...result.profiles.map(p => `${p.id} [${p.family}]\n  ${p.summary}`)].join('\n\n'));
+    else if (options.operation === 'profile' && !options.json) log(`${result.name}\n${result.summary}\n\nPriorities:\n${result.priorities.map(p => `- ${p}`).join('\n')}\n\nDecision: ${result.decision}\n\nVerify:\n${result.verification.map(p => `- ${p}`).join('\n')}\n\nBoundary: ${result.boundary}\nWorkflows: ${result.workflows.join(', ')}\nExample: ${result.example}`);
+    else if (options.operation === 'show' && !options.json) log(result.instructions);
+    else log(JSON.stringify(result, null, 2));
+    return options.operation === 'evidence' && ['failed', 'stale', 'incomplete', 'drift'].includes(result.result) ? 2 : 0;
+  } catch (failure) { error(`just-vibe: ${failure.message}`); return 1; }
+}
+
+if (isDirectRun(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/plugins/just-vibe/skills/a11y/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: a11y
+description: "Inspect semantics, keyboard access, focus, contrast, and announcements Alias for ui-accessibility."
+---
+
+# a11y
+
+Read [ui-accessibility](../ui-accessibility/SKILL.md) and execute that single canonical workflow. It owns selection, inputs, mode, scope, methods, outputs, recovery, and verification. Preserve the complete appended request and original invoked name (a11y); use ui-accessibility as the canonical command in run records. Do not add a routing stage, change permissions, or reset counters for an alias. This entry deliberately contains no independent behavioral contract.

package/plugins/just-vibe/skills/api-breaking/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: api-breaking
+description: "Identify backward-incompatible API changes Use to assess consumer impact of a change; api-design creates the intended contract."
+---
+
+# api-breaking
+
+Identify backward-incompatible API changes
+
+## Choose this workflow
+
+Use to assess consumer impact of a change; api-design creates the intended contract.
+
+Read [shared execution](../../references/execution.md) for context/mode/authority handling and [APIs methods](../../references/packs/api.md) for tool selection and operational details. Resolve these paths from this skill file; all runtime assets ship inside the plugin.
+
+## Input and mode
+
+Use the complete request appended to this invocation, preserving all constraints and references. Default mode: **inspect**. Inspect; old/new contracts or revisions, consumer expectations, and compatibility policy.
+
+interface definitions, producer/consumer source, authentication model, versioning constraints, and isolated test endpoints. External API calls must respect environment, credentials, rate limits, and side-effect scope.
+
+Declared evidence requirements: `project.read`. Use actual host discovery or adequate supplied artifacts; unavailable evidence remains blocked/unknown.
+
+## Scope
+
+Backward compatibility across schemas, semantics, authentication, errors, and timing/order guarantees.
+
+None by default. Plan artifacts may be saved when requested.
+
+## Execute
+
+- Diff interfaces, inspect behavioral changes, identify affected consumers, classify compatibility impact, and propose rollout/deprecation steps.
+- Compare field presence/types, enum values, validation, defaults, error/status behavior, pagination and timing guarantees against identified consumers.
+
+## Decision branches
+
+- **When a syntactically additive change affects strict decoders or behavior:** Classify its actual consumer impact and propose rollout/deprecation evidence.
+
+## Deliver and verify
+
+- Breaking-change report with examples and migration options.
+- Change/consumer/impact matrix with compatibility bridge and unknown consumers.
+
+Verify these observable conditions when applicable to the actual task; do not claim they were exercised from merely reading this file:
+
+- Narrowed validation is recognized as potentially breaking; an additive field is evaluated against actual strict-client behavior.
+
+## Stop and recover
+
+- Missing consumer information prevents universal compatibility claims. Do not equate schema compatibility with semantic compatibility.
+
+## Example requests
+
+- **Normal (inspect):** Compare these API versions for validation and response-contract breaks.
+- **edge (inspect):** Review a new enum value and a stricter validation rule for old clients.
+- **blocked (inspect):** Assess compatibility without consumer source; avoid declaring universal backward compatibility.

package/plugins/just-vibe/skills/api-client/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: api-client
+description: "Build a typed client with authentication and error handling Use for a typed transport boundary to a known API; integrate handles wider product wiring."
+---
+
+# api-client
+
+Build a typed client with authentication and error handling
+
+## Choose this workflow
+
+Use for a typed transport boundary to a known API; integrate handles wider product wiring.
+
+Read [shared execution](../../references/execution.md) for context/mode/authority handling and [APIs methods](../../references/packs/api.md) for tool selection and operational details. Resolve these paths from this skill file; all runtime assets ship inside the plugin.
+
+## Input and mode
+
+Use the complete request appended to this invocation, preserving all constraints and references. Default mode: **apply**. Apply; API specification, language/runtime, authentication source, and consumer needs.
+
+interface definitions, producer/consumer source, authentication model, versioning constraints, and isolated test endpoints. External API calls must respect environment, credentials, rate limits, and side-effect scope.
+
+Declared evidence requirements: `project.read`. Use actual host discovery or adequate supplied artifacts; unavailable evidence remains blocked/unknown.
+
+## Scope
+
+Typed client boundary, serialization, errors, pagination, and permitted retries.
+
+Only the requested local changes; external actions require their exact action and target in session authorization.
+
+## Execute
+
+- Verify contract/version, generate or write a narrow client, isolate credentials, preserve useful errors, and exercise controlled successful and failed responses.
+- Resolve version/auth/schema, validate runtime response shape and preserve actionable status, retry-after and request IDs without leaking credentials.
+
+## Decision branches
+
+- **When a mutating request times out:** Retry only under a supported idempotency/reconciliation contract, not generic automatic retry.
+
+## Deliver and verify
+
+- Client, usage/configuration documentation, and contract checks.
+- Client interface, configuration names and timeout/refusal/malformed-response checks.
+
+Verify these observable conditions when applicable to the actual task; do not claim they were exercised from merely reading this file:
+
+- Valid responses decode correctly; rate limits/timeouts produce bounded behavior without duplicating unsafe requests.
+
+## Stop and recover
+
+- Do not embed tokens or assume generated types prove runtime validity. Live paid or mutating requests need explicit scope.
+
+## Example requests
+
+- **Normal (apply):** Build a typed API client with bounded retries and useful errors.
+- **edge (apply):** Build a client for paginated responses and retry-after throttling.
+- **blocked (inspect):** Implement against supplied contracts without paid or mutating live requests.

package/plugins/just-vibe/skills/api-contract-test/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: api-contract-test
+description: "Verify provider and consumer expectations Use to implement consumer/provider contract checks; test-integration exercises broader dependency behavior."
+---
+
+# api-contract-test
+
+Verify provider and consumer expectations
+
+## Choose this workflow
+
+Use to implement consumer/provider contract checks; test-integration exercises broader dependency behavior.
+
+Read [shared execution](../../references/execution.md) for context/mode/authority handling and [APIs methods](../../references/packs/api.md) for tool selection and operational details. Resolve these paths from this skill file; all runtime assets ship inside the plugin.
+
+## Input and mode
+
+Use the complete request appended to this invocation, preserving all constraints and references. Default mode: **apply**. Apply; provider/consumer expectations, versions, fixtures, and test environment.
+
+interface definitions, producer/consumer source, authentication model, versioning constraints, and isolated test endpoints. External API calls must respect environment, credentials, rate limits, and side-effect scope.
+
+Declared evidence requirements: `project.read`. Use actual host discovery or adequate supplied artifacts; unavailable evidence remains blocked/unknown.
+
+## Scope
+
+Observable cross-boundary contracts; no reliance on live production state.
+
+Only the requested local changes; external actions require their exact action and target in session authorization.
+
+## Execute
+
+- Identify important assumptions, build provider/consumer assertions, control fixtures, verify valid and invalid exchanges, and integrate with relevant checks.
+- Derive assertions from actual consumer assumptions, control fixture identity and verify the real provider boundary when a safe environment exists.
+
+## Decision branches
+
+- **When only mocks can run:** Report consumer behavior and mocked assumptions separately from provider conformance.
+
+## Deliver and verify
+
+- Contract tests, fixture provenance, and execution results.
+- Contract cases, schema/semantic assertions and provider verification coverage.
+
+Verify these observable conditions when applicable to the actual task; do not claim they were exercised from merely reading this file:
+
+- Removing a required response field fails; implementation changes preserving the contract remain valid.
+
+## Stop and recover
+
+- Do not make mocks the sole evidence that the real provider conforms. Missing provider execution is a stated coverage gap.
+
+## Example requests
+
+- **Normal (apply):** Test invoice producer and consumer contracts against isolated fixtures.
+- **edge (apply):** Test an API returning an optional field as null versus omitting it.
+- **blocked (inspect):** Design contract checks with no provider runtime; do not equate a mock pass with compatibility.

package/plugins/just-vibe/skills/api-design/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: api-design
+description: "Define endpoints, resources, validation, and response contracts Use to design consumer-visible operations; backend-service implements business behavior."
+---
+
+# api-design
+
+Define endpoints, resources, validation, and response contracts
+
+## Choose this workflow
+
+Use to design consumer-visible operations; backend-service implements business behavior.
+
+Read [shared execution](../../references/execution.md) for context/mode/authority handling and [APIs methods](../../references/packs/api.md) for tool selection and operational details. Resolve these paths from this skill file; all runtime assets ship inside the plugin.
+
+## Input and mode
+
+Use the complete request appended to this invocation, preserving all constraints and references. Default mode: **plan**. Plan; resources/actions, consumers, access rules, and compatibility requirements.
+
+interface definitions, producer/consumer source, authentication model, versioning constraints, and isolated test endpoints. External API calls must respect environment, credentials, rate limits, and side-effect scope.
+
+Resolve any task-specific tools, target identity and evidence before dependent actions. No external connection is assumed.
+
+## Scope
+
+Endpoint/interface shape, validation, response/error contracts, and evolution.
+
+None by default. Plan artifacts may be saved when requested.
+
+## Execute
+
+- Inspect domain conventions and existing APIs, define consistent resources and operations, specify normal/error behavior, and check consumer usability and migration needs.
+- Define resource identity, method semantics, validation, authorization, errors and versioning from actual consumer journeys; include one success and failure exchange.
+
+## Decision branches
+
+- **When a proposed endpoint hides several independently failing effects:** Expose operation state or explicit partial-failure semantics instead of implying atomic success.
+
+## Deliver and verify
+
+- API proposal with request/response examples, invariants, and acceptance scenarios.
+- Request/response examples, status/error meanings and consumer compatibility notes.
+
+Verify these observable conditions when applicable to the actual task; do not claim they were exercised from merely reading this file:
+
+- Invalid and unauthorized requests have defined outcomes; new behavior does not silently break an existing consumer.
+
+## Stop and recover
+
+- Do not choose unresolved business policy or implement endpoints during a design-only request.
+
+## Example requests
+
+- **Normal (plan):** Design invitation endpoints with explicit expiry and conflict responses.
+- **edge (plan):** Design an asynchronous export API that can fail after acceptance.
+- **blocked (inspect):** Draft an API with unknown consumer constraints; mark compatibility assumptions.

package/plugins/just-vibe/skills/api-errors/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: api-errors
+description: "Standardize useful error responses and propagation Use to standardize error behavior without changing business policy; api-design defines a new contract."
+---
+
+# api-errors
+
+Standardize useful error responses and propagation
+
+## Choose this workflow
+
+Use to standardize error behavior without changing business policy; api-design defines a new contract.
+
+Read [shared execution](../../references/execution.md) for context/mode/authority handling and [APIs methods](../../references/packs/api.md) for tool selection and operational details. Resolve these paths from this skill file; all runtime assets ship inside the plugin.
+
+## Input and mode
+
+Use the complete request appended to this invocation, preserving all constraints and references. Default mode: **apply**. Apply; API scope, current error format, consumers, and logging requirements.
+
+interface definitions, producer/consumer source, authentication model, versioning constraints, and isolated test endpoints. External API calls must respect environment, credentials, rate limits, and side-effect scope.
+
+Declared evidence requirements: `project.read`. Use actual host discovery or adequate supplied artifacts; unavailable evidence remains blocked/unknown.
+
+## Scope
+
+Error status, machine-readable codes, safe messages, propagation, and trace correlation.
+
+Only the requested local changes; external actions require their exact action and target in session authorization.
+
+## Execute
+
+- Inventory errors, preserve required compatibility, map domain failures deliberately, redact internals, and test representative client/server failures.
+- Inventory existing client-visible codes and shapes, map domain failures intentionally and preserve safe correlation IDs while redacting internal details.
+
+## Decision branches
+
+- **When changing a code would break a known consumer:** Add a compatibility path or a versioned transition instead of silently normalizing it.
+
+## Deliver and verify
+
+- Consistent error handling, documented contract, and checks.
+- Error taxonomy, mapping locations and validation/auth/dependency failure cases.
+
+Verify these observable conditions when applicable to the actual task; do not claim they were exercised from merely reading this file:
+
+- Validation errors identify usable field problems; unexpected failures do not leak stack traces or credentials.
+
+## Stop and recover
+
+- Do not turn all failures into success responses or change public codes silently. Unknown consumer reliance needs compatibility handling.
+
+## Example requests
+
+- **Normal (apply):** Standardize safe API errors while preserving published machine-readable codes.
+- **edge (apply):** Standardize errors while preserving a client's retry behavior on conflict.
+- **blocked (inspect):** Review errors from source without provoking real service failures.

package/plugins/just-vibe/skills/api-openapi/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: api-openapi
+description: "Create or reconcile OpenAPI documentation with implementation Use to maintain an OpenAPI contract; api-breaking assesses compatibility between versions."
+---
+
+# api-openapi
+
+Create or reconcile OpenAPI documentation with implementation
+
+## Choose this workflow
+
+Use to maintain an OpenAPI contract; api-breaking assesses compatibility between versions.
+
+Read [shared execution](../../references/execution.md) for context/mode/authority handling and [APIs methods](../../references/packs/api.md) for tool selection and operational details. Resolve these paths from this skill file; all runtime assets ship inside the plugin.
+
+## Input and mode
+
+Use the complete request appended to this invocation, preserving all constraints and references. Default mode: **apply**. Apply; existing OpenAPI/schema, implementation, and source-of-truth convention.
+
+interface definitions, producer/consumer source, authentication model, versioning constraints, and isolated test endpoints. External API calls must respect environment, credentials, rate limits, and side-effect scope.
+
+Declared evidence requirements: `project.read`. Use actual host discovery or adequate supplied artifacts; unavailable evidence remains blocked/unknown.
+
+## Scope
+
+Reconcile documented paths, schemas, authentication, responses, and examples with actual intended behavior.
+
+Only the requested local changes; external actions require their exact action and target in session authorization.
+
+## Execute
+
+- Inspect routes and serializers, compare schema coverage, resolve documentation-versus-code discrepancies, update the correct source, and validate references/examples.
+- Identify the authoritative schema source, compare serializers and route validators, then check references, required/null distinctions and representative examples.
+
+## Decision branches
+
+- **When generated schema disagrees with runtime behavior:** Correct the source of generation or document a deliberate contract change; do not patch generated output alone.
+
+## Deliver and verify
+
+- Validated specification and a list of remaining behavior discrepancies.
+- Covered routes, schema/example validation and unresolved runtime discrepancies.
+
+Verify these observable conditions when applicable to the actual task; do not claim they were exercised from merely reading this file:
+
+- Examples conform to declared schemas; missing error responses are represented accurately.
+
+## Stop and recover
+
+- Do not silently change runtime behavior to match stale documentation or overwrite generated files without updating their source.
+
+## Example requests
+
+- **Normal (apply):** Reconcile the existing specification with actual request and error schemas.
+- **edge (apply):** Document nullable fields and a rate-limit response omitted from generated output.
+- **blocked (inspect):** Review supplied schema without running the provider; do not claim runtime conformance.

package/plugins/just-vibe/skills/api-pagination/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: api-pagination
+description: "Design stable pagination, filtering, and sorting Use for stable bounded collection traversal; db-query handles result correctness below it."
+---
+
+# api-pagination
+
+Design stable pagination, filtering, and sorting
+
+## Choose this workflow
+
+Use for stable bounded collection traversal; db-query handles result correctness below it.
+
+Read [shared execution](../../references/execution.md) for context/mode/authority handling and [APIs methods](../../references/packs/api.md) for tool selection and operational details. Resolve these paths from this skill file; all runtime assets ship inside the plugin.
+
+## Input and mode
+
+Use the complete request appended to this invocation, preserving all constraints and references. Default mode: **plan**. Plan; dataset/order, concurrent-write behavior, filters, consumer contract, and scale.
+
+interface definitions, producer/consumer source, authentication model, versioning constraints, and isolated test endpoints. External API calls must respect environment, credentials, rate limits, and side-effect scope.
+
+Declared evidence requirements: `project.read`. Use actual host discovery or adequate supplied artifacts; unavailable evidence remains blocked/unknown.
+
+## Scope
+
+Stable pagination and sorting semantics; implement when requested.
+
+None by default. Plan artifacts may be saved when requested.
+
+## Execute
+
+- Choose deterministic ordering and tie-breakers, assess offset/cursor tradeoffs, bind cursors to filters/scope, and test inserts, deletes, ties, and end conditions.
+- Define deterministic ordering with a unique tie-breaker, scope cursor identity to filters/tenant and specify consistency under concurrent inserts/deletes.
+
+## Decision branches
+
+- **When the product requires a stable snapshot across pages:** Choose an actual snapshot/version mechanism or explicitly narrow the guarantee.
+
+## Deliver and verify
+
+- Pagination contract or implementation with concurrency-aware tests.
+- Ordering/cursor contract and tie, mutation, invalid-cursor and end-of-list checks.
+
+Verify these observable conditions when applicable to the actual task; do not claim they were exercised from merely reading this file:
+
+- Equal sort values do not create accidental duplication; invalid or mismatched cursors fail predictably.
+
+## Stop and recover
+
+- Do not promise snapshot consistency without a mechanism. Preserve public response shape when constrained.
+
+## Example requests
+
+- **Normal (plan):** Plan stable cursor pagination when concurrent inserts share sort values.
+- **edge (plan):** Add cursor pagination with equal timestamps and deleted records between pages.
+- **blocked (inspect):** Design pagination without a declared consistency requirement; show the decision explicitly.