adapt

Adapt

Overview

Adapt owns the adapt workflow for the exec phase. It reads the triggering request, source artifacts, local runtime state, and required command or receipt proof, then emits agent-output with a concrete decision and handoff. Use it to turn adapt input into a bounded action; return BLOCKED when the source artifact, owner approval, validator output, or runtime receipt is missing.

When to Use

• New directory in src/modules/ or src/commands/
• New major dependency in package.json/composer.json/Cargo.toml
• Files renamed/deleted that artifacts reference
• User runs /supervibe-adapt
• Plugin updated and project-level installed agent/rule/skill artifacts need refresh without manual deletion

Shared Dialogue Contract

Lifecycle: scan -> real-dry-run -> agent-plan -> review -> approved -> applied -> artifact/app/deploy verification. Persist state in .supervibe/memory/adapt/state.json before every lifecycle transition. State must use layered fields: artifactVerified, agentRuntimeVerified, appVerified, and deployVerified.

Lifecycle gates are split by phase: --dry-run is read-only and may run without host-agent telemetry; --apply requires explicit user approval for writes and zero-conflict approved artifact sync does not require host-agent telemetry; optional --verify-agents is an advanced runtime smoke diagnostic and is not part of Adapt completion.

Every interactive step asks one question at a time using Step N/M or Step N/M. Each question lists the recommended/default option first, gives a one-line tradeoff summary for every option, allows a free-form answer, and names the stop condition.

Default behavior: produce a dry-run adaptation plan and do not edit artifacts until approval. Free-form path: the user can name exact agents, rules, skills, paths, or stack changes to include or exclude.

After every material delivery, ask one explicit next-step question about the adaptation plan. Use buildPostDeliveryQuestion({ intent: "adaptation_delivery" }, { locale }) when tooling is available. Visible labels must be language-matched and domain-specific; keep internal action ids only in saved state. Never show both English and Russian in the same visible option.

English visible labels:

• Apply adaptation - recommended when the dry-run adaptation plan looks right; apply the selected artifact updates.
• Adjust adaptation plan - user gives one focused agent, rule, skill, path or stack change; rebuild the dry-run without writing files.
• Compare another scope - produce another adaptation scope with explicit tradeoffs.
• Review adaptation deeper - run audit or confidence scoring before applying.
• Stop without adapting - persist current state and exit without changing project artifacts.

Russian visible labels are supplied by <resolved-supervibe-plugin-root>/scripts/lib/supervibe-dialogue-contract.mjs to keep this skill contract ASCII-safe for validators. The ru locale must map to the same adaptation-specific actions above and must not fall back to generic apply/revise wording.

Expert Operating Standard

Follow <resolved-supervibe-plugin-root>/docs/references/skill-expert-operating-standard.md: start from source of truth, preserve context evidence, apply scope safety, use real producers with runtime evidence for durable delegated outputs, verify before completion claims, and keep confidence below gate when evidence is partial.

Swarm-First Durable Work Gate

Non-trivial durable work is swarm-first by default. The user does not need to request agents: select the smallest relevant skill-bound workers, reviewers, producers, validators, verifiers, or specialists by default. Manager/supervisor control owns graph authority, dependency order, bounded fan-out, synthesis, termination, close sweep, and hard-stop behavior. Dispatch only ready bounded work with selected skill identity, host invocation proof, runtime receipts, receipt proof, and scoped verification evidence. If work remains local because it is trivial/read-only or host dispatch is unavailable, record the exception and do not claim independent proof.

Follow <resolved-supervibe-plugin-root>/docs/references/swarm-first-skill-contract.md. Named durable worker, reviewer, producer, validator, verifier, or specialist work requires real specialist dispatch through the host/runtime path with selected skill ids, resolved SKILL.md paths, runtime receipts or receipt-ready host invocation evidence, and scoped verification evidence. Inline or controller-authored work is diagnostic or trivial-only; it cannot satisfy durable proof, reviewer proof, producer proof, validator proof, verification proof, task closure, or graph task closure.

Step 0 — Read source of truth (required)

1. Read registry.yaml for current state
2. Run git diff <verified-against>..HEAD --stat to find changes. If .git is absent, do not fail: compare against .supervibe/memory/adapt/file-manifest.json; after approved apply, write a fresh snapshot there.
3. Read changed manifest files for new deps
4. Run or consult node <resolved-supervibe-plugin-root>/scripts/supervibe-status.mjs --capabilities so proposed agent, rule and skill updates are grounded in the capability registry.
5. Resolve the canonical project root before host selection: nearest parent .supervibe/ wins over nested app host files, then workspace manifest/root .git. Resolve the active host adapter before reading or planning writes; use the same precedence as genesis: explicit override -> active runtime/current chat -> filesystem markers.
6. Read .supervibe/memory/genesis/state.json when present. Genesis decisions such as appGenerated, appVerified, appChoice=next-app, and ignoredStackTags=["vite"] are source-of-truth for Adapt stack drift.
7. For /supervibe-adapt, run node <resolved-supervibe-plugin-root>/scripts/supervibe-adapt.mjs --dry-run --summary-json --changed-only before <resolved-supervibe-plugin-root>/scripts/command-agent-plan.mjs, then pass the actual counts with --dry-run, --adds, --updates, --project-only, --conflicts, and --memory-writes.

Decision tree

Stack drift is only tooling or a minor dependency inside the selected app
  -> Update affected context references and verification notes.

Stack drift indicates a new app, framework, service, or runtime boundary
  -> Suggest supervibe:genesis or a component plan before changing agents broadly.

Host instruction file or managed block changed
  -> Use the context migrator and preserve user-owned sections.

Deleted or renamed files are referenced by agents, skills, rules, or commands
  -> Update the artifact or flag the stale reference with grep evidence.

Adapt apply would write project artifacts
  -> Require dry-run evidence and explicit approval before mutation.

Provider runtime config drift is detected
  -> Modify only the selected user provider home with add-missing-only semantics; project runtime config files are detection-only and must not be created, modified, or deleted.

Practice matrix

Scenario	Evidence	Action	Stop condition
Plugin or managed artifact drift	supervibe-adapt --dry-run --summary-json --changed-only counts	Propose add/update/defer plan	Conflicts or missing approval
Host instruction drift	context migrator dry-run plus managed-block diff	Preserve user-owned sections and update managed block only	User-owned content would be overwritten
Stack or deploy drift	manifests, Genesis state, capability registry	Update context or route to Genesis/component plan	Service evidence is missing or unsupported

Procedure

Operational runbook before any mutation:

1. Read registry, host adapter state, genesis state, capability registry, and the dry-run summary for the exact project root.

2. Run stale-reference and stack-drift checks; record changed files, add/update/remove counts, conflicts, project-only writes, and memory-write candidates.

3. Write only the approved adapt plan or approved artifact updates. If approval is missing, emit BLOCKED with the dry-run evidence path and stop.

4. Verify with the same scoped dry-run/check command after every repair. If verification fails, repair the smallest changed slice, rerun the command, and keep applied=false until the rerun passes.

5. Diff analysis — what changed since last verified-against commit

6. Stale references — grep deleted/renamed paths in artifacts; update or flag

7. New modules — determine which agent should cover; update Project Context

8. New deps:

   • Minor (new lib in existing stack) → update agent context
   • Major (new framework / new layer) → suggest supervibe:genesis for new component

9. Deleted files — remove references from artifacts

10. Host context migration — if the active host instruction file, AGENTS.md, GEMINI.md, .cursor/rules or opencode.json changes, use <resolved-supervibe-plugin-root>/scripts/lib/supervibe-context-migrator.mjs dry-run planning and never overwrite user-owned sections.

11. Capability registry — propose affected agents, rules and skills together, including registry evidence and confidence for each linked artifact.

12. Related-rule closure - when installed rules reference upstream related-rules that are missing from the selected profile, surface them as explicit ADD candidates with mandatory: true/false instead of leaving validator-only failures.

13. Version marker — after approved writes, update .supervibe/memory/.supervibe-version so future sessions know the project artifacts match the plugin version.

14. User-requested project fit - when the user asks to adapt rules or agents to the project, compare stack tags, selected install profile, existing host artifacts, and capability registry links; then produce an add/keep/defer plan with reasons.

15. Bump versions + update last-verified + verified-against

16. Run supervibe:audit to verify clean state

17. For deploy scope, keep add-ons separate from base scaffold. --scope deploy --target docker|dokploy may create compose/Docker/env/docs artifacts, but must not auto-migrate or claim deployVerified without a real deploy health check.

Additional drift policy:

• vite inside an existing Genesis next-app is an ambiguity, not an automatic stack switch. Classify it as accidental, tooling-only, or a separate Vite SPA.
• next inside an existing vite-spa is migration/new-app evidence and needs a Genesis/component plan.
• Dependency drift blocks npm audit fix --force when it downgrades a framework major/minor line. Compatible nested dependency repair must surface overrides/resolutions, remediation reason, and the rerun sequence: npm install, npm audit, lint, build, and dependency-health.
• Deploy drift is service-evidence based, not folder-name based. Detect any number of supported services from manifests: next-only, laravel-postgres, or laravel-next-postgres. Generate service-local Dockerfiles only for detected supported services. Never create a Laravel/backend service, Postgres, queue, scheduler, or php artisan command without Laravel evidence; never create a Next/frontend service without Next.js evidence. Unsupported services must be listed as unsupported and require a new stack pack or explicit user approval before Dockerfiles are generated.

Anti-patterns

• Ignoring the boundary: Do not use this skill to bypass the command or workflow that owns durable artifacts.
• Accepting the rationalization: "This is small, so no source check is needed" - reject when the skill changes code, config, or durable artifacts.
• Proceeding despite this red flag: A durable artifact changes without a command, approval, or verification path.
• Letting the known failure mode happen: Inline emulation replaces a required producer or reviewer.

Examples

• Worked example: /supervibe-adapt reports adds=0 updates=3 conflicts=0 projectOnly=0; emit an approved plan naming the three managed artifacts, apply only after approval, rerun the same dry-run, and keep deployVerified=false until a real deploy health check exists.
• Anti-example: package.json contains next and vite; do not rewrite agents as a Next migration until Genesis state or user input proves whether this is a separate Vite app, accidental dependency, or intentional migration.

When not to use

• Do not use this skill to bypass the command or workflow that owns durable artifacts.
• Do not use it when source evidence, CodeGraph, or required verification is missing.
• Do not use it to replace a specialist producer, worker, or reviewer that must issue runtime evidence.

Common rationalizations

• "Adapt can proceed from a vague trigger" fails because the adapt packet must name the triggering request, source artifact, owner, and expected agent-output before durable work starts.
• "Skipping adapt command proof is fine" fails when the output affects graph, release, design, security, memory, or user-visible workflow state; collect the named command, receipt, or artifact first.
• "Adapt can finish with a general summary" fails because the handoff must include status, evidence, confidence, blockers, and nextAction tied to the adapt decision.

Red flags

• Adapt receives a trigger but no source artifact, owner, approval, validator output, or receipt; return BLOCKED and request the missing proof.
• Adapt changes or approves agent-output while status, evidence, confidence, or nextAction is absent; rerun the skill and repair the output contract.
• Adapt crosses graph, release, design, security, provider, or memory boundaries without the owning command or reviewer receipt; stop and hand off to that owner.

Checklist

• Source of truth read.
• Scope and owner confirmed.
• CodeGraph/memory requirement decided.
• Evidence artifact or command recorded.
• Stop condition and next handoff clear.

Failure modes

• Inline emulation replaces a required producer or reviewer.
• Broad use of the skill slows delivery without improving evidence.
• Missing verification lets stale assumptions pass as production-ready.

Output contract

Return a parseable adaptReport:

{
  "status": "PASS | PARTIAL | BLOCKED | ADVISORY",
  "dryRun": {"adds": 0, "updates": 0, "projectOnly": 0, "conflicts": 0, "memoryWrites": 0},
  "updatedArtifacts": ["path or empty"],
  "recommendations": [{"artifact": "path", "action": "add | update | keep | defer", "evidence": "command or source path"}],
  "genesisNeeded": [{"reason": "major component or unsupported service", "evidence": "manifest or state path"}],
  "verification": {"command": "exact command", "exitCode": 0, "rerun": "exact rerun command"},
  "blockers": ["missing approval, conflict, unsupported service, or empty"],
  "confidence": 0,
  "nextAction": "apply | repair | rerun-dry-run | route-genesis | stop"
}

Guard rails

• DO NOT: delete agent/skill files (rename/archive instead)
• DO NOT: tell the user to delete all generated project artifacts after plugin updates; use diff-gated adapt instead
• DO NOT: write .supervibe/memory/index.json during dry-run unless the user requested --refresh-memory-index
• DO NOT: treat no .git as fatal; use the Adapt file-manifest snapshot fallback.
• DO NOT: let package tags override Genesis app choice without a frontend target decision.
• DO NOT: assume a project has exactly frontend/ and backend/; service discovery must support multiple service directories and must block unknown technologies instead of guessing.
• DO NOT: claim optional real-agent diagnostics completed when host-agent telemetry is absent
• DO NOT: invent new agent (suggest genesis for new components)
• ALWAYS: re-audit after adapt to verify clean

Verification

• Confirm every emitted artifact exists and matches the Output contract.
• Run the validator, test, dry-run, or audit command named by this skill when one exists.
• For dry-run/apply repair, rerun node <resolved-supervibe-plugin-root>/scripts/supervibe-adapt.mjs --dry-run --summary-json --changed-only and record exit code plus counts.
• Include concrete command/output evidence before claiming the skill completed successfully.
• If verification cannot run, state the blocker and keep confidence below the passing gate.

Supporting references

Resource tree hardening

• references/practice-pack.md - Load when adapt needs deeper load rules, local evidence anchors, gotchas, or the final checklist.

• scripts/self-check.mjs - Run with --check before claiming the adapt resource tree is complete; add --json when machine-readable evidence is needed.

• evals/regression.json - Use when tuning the adapt trigger boundary or checking should-trigger and should-not-trigger prompts.

• examples/workflow.md - Load when a concrete Adapt execution example or anti-example would clarify the next action.

• templates/output-contract.md - Use when emitting agent-output so status, evidence, blockers, confidence, and nextAction stay consistent.

• <resolved-supervibe-plugin-root>/scripts/supervibe-adapt.mjs - deterministic dry-run/apply runner.

• <resolved-supervibe-plugin-root>/scripts/lib/supervibe-adapt.mjs - adapt planning helper used by the CLI.

• <resolved-supervibe-plugin-root>/tests/supervibe-adapt.test.mjs - regression eval coverage for adapt behavior.

• <resolved-supervibe-plugin-root>/docs/references/skill-expert-operating-standard.md - freshness, evidence, and confidence practice pack.

• Worked example and anti-example in this SKILL.md are the local examples pack.

Related

• supervibe:audit — pre + post check
• supervibe:genesis — invoked for new major components