Specifications
Reverse-engineered from the source at commit 53f8c53. Specs 001–025 describe behaviour as implemented, with numbered requirements (CLI-01, FS-30, …) that can be traced to code and tests, plus known gaps; 026 and 027 collect what’s missing — Blitz’s own gaps, and gaps against Claude Code and Antigravity — as requirements to close before new features.
Files are named spec_<name>_NNN.md, where NNN is the order of execution: each spec builds on the specs before it, so reading (or rebuilding) them in order works bottom-up, from project setup to release. Links to later specs are cross-references for context, not dependencies.
| # | Spec | Covers |
|---|---|---|
| 001 | setup | Identity, layout, toolchain, commands, conventions |
| 002 | config | .env.toml location and trust, schema and defaults, in-place editing |
| 003 | observability | Redaction, audit log, diagnostic log, OpenTelemetry |
| 004 | i18n | Catalogs, locale resolution, interface vs reply language |
| 005 | approvals | Approval gate, remembered/saved rules, unattended runs, ask_user_question |
| 006 | filetools | File sandbox, blocked paths, file tools, apply_patch, checkpoints and /undo |
| 007 | shell | run_shell_command, command policy, OS sandbox, process guard, background processes |
| 008 | web | web_fetch (SSRF-safe), web_search providers, /search |
| 009 | mcp | MCP servers: exposure, approval, timeouts, circuit breaker |
| 010 | hooks | pre_tool, post_tool, prompt_submit hooks |
| 011 | images | Attaching, preparing, storing and sending images |
| 012 | memory | Project instruction files |
| 013 | skills | Skill definitions, skills policy, script sandbox and environments |
| 014 | agents | Agent definitions, built-ins, delegation, Universal Constructor |
| 015 | models | Providers, retries and stalls, fallback chain, per-model settings |
| 016 | engine | Turns, plan/read-only modes, steering, /btw, compaction, sub-agents, usage, tracing |
| 017 | sessions | Transcripts, event log, resume, snapshots, session search |
| 018 | workspace | engine.Open, api.Backend, turn lifecycle, typed operations |
| 019 | tui | REPL, slash commands, steering, exit handling |
| 020 | cli | Commands, flags, one-shot output formats, exit codes, doctor, config |
| 021 | service | blitzd, socket, Connect API, approval broker, login item |
| 022 | client | Attaching front ends to the service |
| 023 | workers | WORKER.md, schedules, permissions, enabling, runs, scheduler |
| 024 | desktop | The desktop app and its page (the Wails shell until v0.6.5; the Electron app since, spec 038) |
| 025 | release | CI, reproducible and signed releases |
| 026 | backlog | What’s missing: unimplemented requirements, verification still owed, and deliberate limitations |
| 027 | parity | Gaps against Claude Code, Antigravity CLI and Antigravity, as requirements to close before new features |
| 028 | monorepo | Apps over shared packages, their dependency rules, and the Bazel build: generated protos, the page, packages, reproducibility |
| 029 | files | The workspace’s files in the desktop app: explorer, editor, diffs, language intelligence |
| 030 | release readiness | Licensing, headers and notices; comments; specs, docs site, README, contributing and owners |
| 031 | project configuration | .blitz/settings.toml in a workspace: tiers of what applies at once, after hash-pinned trust, or never |
| 032 | background sub-agents | invoke_agent in the background: tasks, their tools, results, the task view and approvals |
| 033 | plugins | Bundles of skills, commands, agents, hooks and MCP servers: installing, pinning by hash, marketplaces, importing Claude Code and Gemini CLI plugins |
| 034 | vscode | The VS Code extension: the desktop app’s chat in a view, attached to the service through a local proxy, approvals in the diff view, the selection and files as context |
| 035 | search | Workspace search: an index of the files, PDFs and notebooks, chats and notes, kept up by scans, searched by words (FTS5, BM25) from the desktop app, the CLI and the agent |
| 036 | windows | Blitz on Windows: the tray runs the service and serves the desktop page on a loopback port, behind a one-time link, in an Edge app window |
| 037 | visual editor | Draft: Markdown edited in its rendered form (TipTap), code blocks as CodeMirror editors, and language servers (gopls first) for the editor through a LanguageService on the service |
| 038 | electron | The desktop app in Electron (one engine on every platform, a real app on Windows) over the page and blitz-tray --serve as its host; since v0.7.0 |
| 039 | secrets | The user’s secrets in the system’s keychain, named in prompts and settings as {secrets:key}; since v0.7.1 |
| 040 | studio | What a workspace’s .agents folder holds, each kind listed and edited in the desktop app; since v0.7.1 |
| 041 | gates | Rules that gate an agent’s turn, checked before it runs and after it answers, and guardrails at every step of it; since v0.7.1 |
| 042 | evals | Cases that check an agent still answers as it should, run and scored exactly or by meaning; since v0.7.1 |
| 043 | workflows | Steps joined into a graph, run as one turn (/name) and built on a canvas; since v0.7.1 |
| 044 | health | A workspace’s dashboard: what it holds, how its runs go, and each item’s quality judged on the evidence, on request and nightly; since v0.7.1 |
| 045 | composer | A guided conversation that makes a component: asks what it needs, writes the file, checks it with the engine’s rules and hands it to the editor as a draft; for workflows since v0.7.1, the other kinds next |
Background and history: the roadmap, where to pick up, development.