Workflow Modes

Snipara offers workflow modes optimized for different task sizes. Choose LITE for focused edits, STANDARD for normal agent work, FULL for multi-phase changes, and the explicit ORCHESTRATED path only when production validation or multi-agent coordination is justified.

Run With snipara-companion

You can follow the workflow manually through MCP tools, or use the optional snipara-companion npm package as a local workflow shortcut. The installed command is snipara-companion; there is no separate snipara-workflow binary.

npx -y snipara-companion@latest workflow run --mode standard --query "who imports the auth middleware"

npx -y snipara-companion@latest workflow run --mode auto --query "what context should I load for this task?"

npx -y snipara-companion@latest workflow run --mode full --include-session-context --query "plan the billing refactor"

npx -y snipara-companion@latest plan --query "plan the billing refactor" --write-plan-file ./plan.json

npx -y snipara-companion@latest workflow run --mode orchestrate --query "map the production rollout risks"

npx -y snipara-companion@latest doctor

standard runs a context query and automatically executes a recommended structural tool when Snipara returns one. auto resolves the task intent to an effective lite, standard, full, or orchestrate mode; it is not a compatibility alias for STANDARD. full adds durable memory bootstrap, optional session carryover, shared context, execution-memory continuity, a visible phase plan, and phase commits. When phase ids must stay stable, keep the machine plan in JSON even if you also keep a Markdown plan for humans.

Exact CLI mode values

The guide labels below are descriptive. The value passed to --mode is the lowercase CLI value in the first column.

Spec-driven feature plans

For a feature that needs a durable specification, use Companion to keep the human review artifacts and the managed execution plan together:

npx -y snipara-companion@latest feature init auth-hardening --goal "Harden authentication"
npx -y snipara-companion@latest feature plan auth-hardening
npx -y snipara-companion@latest feature tasks auth-hardening
npx -y snipara-companion@latest feature start auth-hardening

feature plan uses Hosted Snipara's snipara_plan. A team can instead edit docs/specs/auth-hardening/plan.md with a numbered ## Phases section and run feature tasks auth-hardening --from-plan. Both paths produce the same stable chunks, and feature start registers them in the existing .snipara/workflow/current.json state. The chunk query remains the unit used by the normal context, impact, verification, and phase-commit loop.

For FULL, orchestrated, or execution-heavy tasks, companion prints Snipara Sandbox and orchestrator hints when local validation or production gates would help. Use --no-runtime-hint for scripted output, and use snipara-companion doctor to check Snipara auth, Sandbox CLI availability, Sandbox MCP wiring, provider keys, Docker, and optional orchestrator availability.

Companion does not run Snipara Sandbox by itself. If the workflow needs sandboxed execution via execute_python, install and expose Snipara Sandbox with npx create-snipara repair --with-runtime, the create-snipara full-stack profile, or the Snipara Sandbox MCP server. For runtime-bound phases, use workflow runtime-checkpoint <phase_id> to capture compact rehydratable state after material sandbox progress. Then workflow resume restores workflow/memory continuity plus the recorded Sandbox binding and prints a reattach or rehydrate plan. It still does not snapshot or exactly restore a live Snipara Sandbox or REPL process.

Companion also does not spawn workers through snipara-orchestrator by default. Install orchestrator only for explicit production gates, proof-based validation, drift checks, or hierarchical task coordination.

API Keys and Snipara Sandbox Execution

Snipara context and Snipara Sandbox execution use different credentials. Keep them separate:

npx -y snipara-companion@latest task-commit --summary "Implemented the billing refactor and validated checkout tests" --files apps/web/src/lib/billing.ts

Use task-commit at the end of substantial work to persist durable outcomes. For Codex, companion remains optional: hosted MCP plus AGENTS.md is still the primary integration.

Command names and aliases

Similar names do not always mean the same operation. Use the canonical forms below when writing new automation; the listed aliases remain supported for compatibility.

Execution Loop

For coding agents, Snipara workflows are strongest when they separate resume state from durable memory:

Observe

Retrieve

Plan

Act

Test

Summarize

Write Memory

In practice, execution memory carries the active session trace between phases through a replayable runtime history, while task commits and reviewed memory store only the durable outcome that should shape future behavior.

Quick Decision

Ask yourself these 5 questions:

Score 0 = LITE | Score 1 = STANDARD | Score 2+ = FULL. Use --mode orchestrate for explicit production validation, htask coordination, or multi-agent work. Use --mode auto when the task should be routed from its intent instead of selecting one of these values manually.

LITE Mode (Default)

Use for bug fixes, small features, single-session work, and tasks where you know exactly which files to modify.

LITE Mode Example

snipara_context_query(query="fix null check authentication")

# Read the specific file

# Edit to add null check

pnpm test

STANDARD Mode (Normal Agent Work)

Use for most single-session coding work that may need source context, structural code graph follow-up, and a final durable outcome if the task teaches something reusable.

STANDARD Mode Example

snipara_context_query(query="who imports the auth middleware", return_references=true)

# Follow recommended snipara_code_* tool if returned

# Edit files locally

pnpm test

snipara_end_of_task_commit(summary="Captured durable outcome", persist_types=["learning"])  # only when useful

FULL Mode (Complex Features)

Use for multi-day features, architectural changes, team coordination, and documentation-heavy work that spans multiple sessions.

FULL Mode Example

# Phase 1: Context

snipara_shared_context(categories=["BEST_PRACTICES"])

snipara_recall(query="rate limiting decisions")

snipara_context_query(query="API middleware", max_tokens=8000)

# Phase 2: Plan

snipara_plan(query="implement rate limiting for API")

snipara_remember(type="decision", text="Using Redis sliding window")

# Phase 4: Implement

snipara_inject(context="Working on rate limiting, Redis backend")

snipara_multi_query(queries=[{query: "Redis patterns"}, ...])

# Phase 5: Persist durable outcome

snipara_end_of_task_commit(summary="Implemented Redis sliding-window rate limiting and left tests as the next step")

Mode Selection Examples

ORCHESTRATED (--mode orchestrate)

Use this only when FULL mode is not enough: production validation needs proof contracts, release drift checks must gate progress, or a coordinator must split work across hierarchical tasks. In that case, snipara-companion keeps the local workflow state while snipara-orchestrator handles the advanced validation or htask surface explicitly. The guide may call this “FULL + ORCHESTRATED,” but the exact CLI value is orchestrate.

npx create-snipara repair --with-orchestrator

snipara-orchestrator check-drift --route /api/billing --route /api/auth

snipara-orchestrator htask-next --swarm-id <swarm> --limit 3

Session Continuity (FULL Mode)

FULL mode enables work that spans multiple sessions through the memory system.

Starting a New Session

snipara_recall(query="feature-name progress status")

snipara_context_query(query="feature-name")

Ending a Session

snipara_end_of_task_commit(
  summary="Feature X: Completed steps 1-3. Next: implement Y. Blocker: Z",
  outcome="partial",
  persist_types=["decision", "learning", "workflow"]
)

Tools Reference