Frequently asked questions

Spec is a governed workspace for English-first specs and the prompts that produce code: Markdown in your repo, captured sessions in .prompts, branch-level review, recorded approvals, signed runs, and drift signals. It is built for teams that already ship with Git and want accountability when AI assists implementation.

There is no separate subscription fee to use the core Spec workspace, CLI, and team feed for your bundles today. You still pay your existing AI vendors when you run models on your own machines (API keys, IDE plans, and so on). Spec Cloud stores, indexes, and links your bundles and live events; it does not run inference for you, so Light Reach does not sit in the middle of that metered spend.

Every model call runs on hardware you control (your laptop, your CI, your cloud account) with the tools you already use. Spec Cloud holds governance data: specs, captures, review state, and optional run records. It is intentionally not an inference host.

The real-time layer of Spec. Two channels, one daemon:

• Prompt feed. Every turn in Cursor / Claude Code / Codex / Compress is redacted by the CLI and broadcast to the team within seconds. Teammates subscribed via spec team watch see prompts and replies as they happen.
• Edit presence. Every ~15 s the CLI broadcasts the dirty file list. Hooks read .spec/team-presence.json and warn before an agent edits a file a teammate is in.
• Agent coordination. The same event stream materializes as .spec/team-coordination.json and .spec/team-coordination.md, showing active objectives, progress, claimed paths, and current-cohort handoffs. Both files clear when the last round finishes.
• Post-push pull hint. spec push fires one extra presence event after a successful upload with the new head_commit. Teammates’ briefs grow a “Pull needed” section and spec locks pull-status exits 2 - the canonical signal an AI IDE should git pull before its next write.

Capture and review still follow the normal Git pipeline - Live is the low-latency layer on top. Full contract: Spec Live in standards.

Two things, both designed to keep teammates’ AI IDEs from stomping on freshly-pushed work:

• Drop the lock. The CLI broadcasts a presence event with is_clean=true right after the upload succeeds - teammates’ .spec/team-presence.json immediately drops the files you were dirty on, so the Claude Code / Cursor / AGENTS.md hooks stop guarding them.
• Signal a pull. The same event carries the new head_commit. Teammates’ presence mirror compares it to their own head_commit on the same branch - mismatch means “they pushed, I’m behind”, which renders into the brief as a Pull needed section and trips spec locks pull-status exit 2.

The post-push broadcast is best-effort: if the network is down or the server is slow, the watcher’s regular 15 s tick reconciles the state. The pull hint never blocks the push itself.

Yes. team-presence.json handles teammates; a single machine registry, ~/.spec/active-edits.json (or $SPEC_HOME/active-edits.json), handles the case where one developer has multiple AI agents (Cursor + Claude Code + Codex) editing the same working tree. Every local Spec repo uses this physical file. Each lock entry is keyed by (bundle_root, agent, session_id, paths) and has a TTL (default 5 minutes, capped at 60) so a crashed agent never deadlocks the file forever.

The Claude PreToolUse hook auto-acquires a lock on every Edit / Write / MultiEdit / NotebookEdit call. PostToolUse releases it. A second agent on the same machine reading spec locks check <path> sees the row with kind: "active_edit" and either warns or refuses (depending on whether your install-claude flow used --block). Same agent + session re-acquires are renewals - they don’t conflict with themselves.

You can drive the layer manually too: spec locks acquire / release / list / prune are first-class commands. Run spec locks list --all --json from any directory to verify every repo’s namespaced rows. Legacy per-repo lock rows migrate once and the old file is left untouched. The file is local-only - never broadcast, never pushed to Cloud - because the whole point is intra-machine coordination.

Run spec discover once. Discovery is machine-wide, not tied to the current directory: an explicit ROOT is remembered, later rootless runs scan every saved workspace, and a first run scans your home folder. It marks existing Spec bundles as initialized and registers them too, then numbers only the repos available for setup. Press Enter or type all to initialize all of them, or enter a selection such as 1,3,5-7. Existing Spec repositories are never overwritten.

Use spec discover --dry-run for a read-only inventory and spec discover --all for non-interactive setup. The command skips dependency, build, cache, and hidden directories and recognizes linked worktrees and submodules. Run spec on afterward to connect and watch every registered project without uploading its files. Use the separate spec publish --all only when you intend to upload staged bundle content; spec push remains an alias.

For the normal day, use spec on when you start work, spec status to audit all local watchers, and spec off when you finish. The OFF command stops every registered local watcher and releases leftover local edit locks; it does not configure or disable separate cloud-side jobs.

Before starting watchers, spec on checks the shared CLI login once, resolves or creates each fresh project, stamps its immutable cloud.bundle_id, and starts the watcher. Connecting transfers no bundle files. If the session has expired, run spec login once and repeat spec on.

Finer controls remain available:

• Per bundle - spec live off writes spec.yaml so the whole team gets the quiet contract on commit.
• Per machine - spec live mute stops your CLI from broadcasting but keeps the receive channel.
• Per session - spec activity shows prose without expanding long tool traces; add --show-tool-runs when those details matter.

spec status prints the machine-wide state from any directory. spec live status explains the detailed policy for the current bundle.

Opens the existing workspace-wide spec team watch stream under a simpler name: every prompt and reply from Codex, Claude Code, Cursor, and Compress across every bundle you can see. It reconnects automatically and resumes after a network blip. Assistant prose is visible by default; structured tool calls and large code blocks expand only with spec activity --show-tool-runs.

Each header carries the role badge (USER / AI / ERROR), the source adapter, the branch, the bundle, and the time. The chip row underneath shows the working directory (cwd ~/code/widgets), the files touched by that turn (touched billing.py, auth.py), and a short session id so concurrent sessions stay separable.

Run spec prs from any directory. It queries every unique GitHub repository in the machine-wide Spec registry and lists your open PRs; add --all-authors for the team queue. Then run spec review, or identify one explicitly with --pr owner/repository#123.

spec review --with cloud adds the explicit agent-review consent label. Actionairy authorizes the reviewer profile, memory grant, policy, and cost; Compress performs a read-only review bound to the current head SHA and publishes through the GitHub App. spec review --with @alice resolves Alice from the project's Spec team and uses GitHub's native reviewer request. GitHub remains canonical for PR state and teammate review assignment.

Yes - type slash-commands while the stream scrolls.

• /flag <id> <kind> [note] - warn, block, ack, or ask.
• /summarize 2h - format the last window for the agent already running in this terminal to synthesise.
• /focus @handle, /mute @handle - filter the stream.
• /replay 10m - re-emit the last window so the critic and flag rendering fire again.
• /search <term> - grep the in-memory buffer for body, file, handle, or event id.
• /critic on|off, /status, /help.

Full reference: in-pane commands in standards.

A rule-based auto-critic runs locally in spec team watch. Every user and assistant turn is matched against a small catalogue - destructive verbs (rm -rf, DROP TABLE), test-bypass language (--no-verify, “disable CI”), leaked secrets (Stripe/GitHub/AWS/Slack tokens, private RSA blocks, JWTs), vague intent, multi-task prompts. Each firing rule prints inline with the exact spec team flag command to escalate.

Run with --notify to ring the terminal bell (and fire a macOS banner) on block-severity hits when you can’t keep eyes on the pane. No LLM round-trips, no extra services. Toggle at runtime with /critic off. See Catching AI mistakes.

Your bundle is the same tree Git already tracks: Markdown under docs/, prompts under prompts/, and a single spec.yaml. When you push, Spec resolves the bundle for that branch so review, history, and approvals align with the branch workflow you already use.

A bundle is one versioned unit of intent for a project: the Markdown specs, the .prompts narrative for that branch, and settings. It is what reviewers open in the workspace and what the compiler and CLI operate on together.

Teams group people who share bundles and permissions. You invite colleagues, manage access, and keep Spec Live and review activity scoped to the right collaborators instead of treating every repo as a flat list of individuals.

Yes. The workspace, teams, and bundles require sign-in so approvals, audit trails, and live events map to real people. Sign in from the app, or complete the device flow if the CLI sends you to a verification URL.

Follow the supported install path in the standards: Install and update the spec CLI.

spec compile reads your bundle and emits a prompt artifact (for example under .spec/) that you run locally in Claude Code, Cursor, or any agent you trust. It is the bridge between governed Markdown plus captures and the implementation pass, without moving inference into Spec Cloud.

Yes. The Spec CLI and the Spec compiler are open-source tools you run locally. Spec Cloud is the hosted control plane for storage, review, collaboration, and (for Live) fan-out of events your CLI uploads.

Review treats the prompt as the artifact under inspection, not only generated code. Another engineer reads, challenges, and approves in the workspace before you treat the implementation as settled. When the prompt is accepted, approval is recorded so later runs can be tied back to that decision.

Captures turn local agent transcripts into a durable narrative your team can review. The CLI is the supported writer of .prompts files (for example via capture on commit). See Capture workflow in the standards for the full lifecycle.

Drift signals highlight when shipped work diverges from the governed spec or approved prompt narrative your team agreed on, so you can catch silent rewrites before they compound. Exact mechanics are described alongside metrics in the standards document.