START HERE · 8 MIN READ
Build your first verified brief.
Specz gives your team one place to turn a feature idea into clear, reviewed context that people and coding agents can trust.
01 / QUICK START
From idea to handoff
Start in the web app. You can add the CLI or MCP connection when the brief is ready for implementation.
- 1Create your workspaceOpen the app ↗
Sign in, name the workspace, and choose the coding agent your team uses most often.
- 2Create one feature
Use a real piece of upcoming work. Add the outcome, owner, and why it matters.
- 3Make the brief testable
Add user stories, acceptance criteria, design references, and technical constraints.
- 4Review, then publish
Resolve open decisions and publish an immutable revision for the agent.
02 / THE MENTAL MODEL
One feature, one shared room
A feature room is the working space for a single product change. Conversation is useful, but only promoted content becomes part of the brief your agent reads.
Feature room
Where people and agents discuss questions, attach references, and shape the work together.
Verified brief
The structured stories, criteria, constraints, decisions, and evidence approved by your team.
Revision
An immutable handoff available as hosted HTML, a CLI bundle, or through MCP.
03 / BUILD A BRIEF
Create a feature with a clear outcome
Choose New feature from your workspace. A useful starting feature states the change and the result, without prescribing implementation too early.
Bulk CSV contact import
- Outcome
- Admins can onboard existing contacts without entering them one at a time.
- Business value
- Reduce customer setup time and data-entry mistakes.
- Owner
- One person accountable for moving the feature through review.
04 / ADD CONTEXT
Give the agent what it cannot infer
Build the brief from explicit pieces. The goal is not more documentation—it is fewer hidden assumptions.
Stories
Name the user, desired outcome, business value, risk, and dependencies.
Acceptance criteria
Describe observable behavior with concrete given, when, and then conditions.
Design references
Attach the relevant frame or asset and explain the states that matter.
Technical context
Point to code boundaries, symbols, contracts, and constraints worth preserving.
Verification
Connect test scenarios and persisted results to the criteria they prove.
05 / REVIEW & PUBLISH
Publish only what the team trusts
Use the feature review to find missing context, unresolved blockers, and incomplete verification. Publishing creates a stable revision; it does not erase the working draft.
Approvers inspect context and raise blockers.
Required evidence and approvals are complete.
A revision is available to people and agents.
06 / AGENT HANDOFF
Pull a brief with the CLI
Install the CLI, authenticate in your browser, then select and pull the published feature into the repository where your agent is working.
Install on macOS
brew install specz-ai/tap/speczLinux or Windows
uv tool install "specz-cli @ git+https://github.com/heberuriegas/specz.git#subdirectory=cli"Connect your repository
specz loginspecz set your-feature-slugspecz pull your-feature-slug --format bundle --output .specz/context
07 / LIVE CONNECTION
Let your coding agent read Specz
Connect the hosted MCP server when you want a compatible coding agent to discover Specz tools and fetch approved context directly.
codex mcp add specz --url https://mcp.specz.ai/mcp --oauth-client-id specz-mcp --oauth-resource https://mcp.specz.ai/mcp- 1
Run the command from your terminal.
- 2
Approve the Specz authorization request in your browser.
- 3
Confirm Specz appears in your agent's MCP tools.
Using Cursor, Claude Code, GitHub Copilot, Gemini CLI, or OpenCode? Open CLI & Agents settings for a command tailored to your harness.
08 / CLI ACTION REFERENCE
Every CLI action
Generated from the same canonical descriptions used by specz help. Arguments, options, examples, availability, and side effects update automatically during every deployment build.
09 / MCP ACTION REFERENCE
Every MCP action
Generated from the transport-neutral operation registry that FastMCP uses to publish tool names, descriptions, JSON inputs, scopes, effects, and result contracts.