From zero to your first signal in 30 minutes
Most frameworks ask you to restructure your team before you see value. Intent asks you to notice one thing, record it, and watch what happens. The tooling does the rest.
You need three things to get started. Two are required. One is optional until you want agents running autonomously.
git — for repo operations and signal persistencePython 3.10+ — for CLI tooling and agent executionClaude API key — optional for signal capture; required for agent execution (optional)You can capture signals without an API key. The CLI works fully offline for signal capture, review, and promotion. Agent execution (Step 6 and beyond) requires a Claude API key for autonomous spec execution.
Clone the repo and run the setup script. Three commands, sixty seconds.
git clone https://github.com/theparlor/intent my-intent-workspace cd my-intent-workspace python setup.py install intent --version
Setup creates a .intent/ directory in your workspace root, installs CLI tools (intent-signal, intent-spec, intent-status), and enables git hooks for automatic signal persistence. Every signal you capture is version-controlled from the start.
You can adopt the Knowledge Engine independently—compile domain knowledge into structured artifacts without committing to the full Intent loop. Install the intent-knowledge CLI and start with ingest/query/lint operations.
pip install intent-knowledge intent-knowledge --version
intent-knowledge CLI Reference
The Knowledge Engine is a separate product. It compiles domain knowledge into queryable artifacts and validates them against quality gates. Use it standalone for knowledge management, or integrate it into the full Intent loop for agent-driven spec generation. Most teams start here or run it in parallel with the full loop.
Notice something. Record it. A signal is an observation backed by evidence—something you saw, measured, or heard that might matter.
intent-signal capture "Sign-up takes 12 taps on mobile"
The CLI opens your default editor. You record the signal: what you observed, where you observed it, and why it might matter. On save, it writes to .intent/signals/ as frontmatter + markdown.
--- trace_id: null source: cli-manual confidence: 0.7 tags: [ux, onboarding] --- # Signal: Sign-up takes 12 taps on mobile Observed in user testing with 3 users. Each needed 12 tap sequences to complete signup. Expected flow was 5 taps max.
Signals are opinions backed by evidence. They don't need to be right—they need to be noticed. The .intent/ directory auto-commits on save, so every signal is immediately part of your project's git history.
Find patterns in your signals. The review command groups related signals by keyword and semantic similarity, surfacing clusters that might represent real intents.
intent-signal review
Review runs entirely locally. No server calls, no API key required. It uses simple keyword matching and semantic similarity to find related signals. Clusters with 3+ signals are strong candidates for promotion to intents.
Turn a signal into a working outcome. Promotion assigns a trace ID, moves the signal from .intent/signals/ to .intent/intents/, and asks you to define falsifiable success criteria.
intent-signal promote <signal-id>
--- trace_id: INTENT-001 status: hypothesis success_criteria: [sign-up completes in <5 taps on mobile] impact: [user acquisition, retention] --- # Intent: Reduce mobile sign-up complexity Promoted from signal sig-001. Three users tested, all exceeded expected tap count by 2.4x.
An Intent is a signal with a falsifiable outcome. It stays open until validated or invalidated by real observations. This is the bridge between "we noticed something" and "we're going to do something about it." Learn more about the full Intent methodology.
Define the desired behavior. A spec is what agents execute against—it declares the shape (what's in and out of scope), contracts (verifiable outcomes), and constraints. Specs replace user stories.
intent-spec create --from-intent INTENT-001
The CLI scaffolds a spec template linked to your intent. You edit it to define scope, contracts, and constraints.
# spec/mobile-signup-v2.md ## Intent INTENT-001: Reduce mobile sign-up complexity ## Shape Reshape the signup flow: email → password → optional MFA → done. Out of scope: profile completeness (belongs to onboarding). ## Contracts - contract/signup-entry.md: Given mobile device, flow completes in <5 taps - contract/mfa-optional.md: MFA checkbox is optional, pre-unchecked
Specs replace user stories. Agents pick them up and execute against the contracts. Each contract is independently verifiable—it either passes or fails. No ambiguity, no "done when the PM says so." See schemas for the full spec data model.
Watch the outcome happen. The status dashboard shows the full Intent lifecycle: spec status, execution progress, and observations flowing in. As agents execute and contracts pass, the Intent moves toward validated.
intent-status
The observation loop is what makes Intent different from task trackers. Observations aren't status updates—they're evidence. When enough contracts pass, the Intent validates. When observations contradict the hypothesis, it invalidates. Either way, you learn. See the full Observe narrative →
This is the loop closing. Signal → Intent → Spec → Execute → Observe. Each observation can become a new signal, starting the cycle again. That's why Intent doesn't need sprints—the loop is continuous.
You've completed the full loop: notice → capture → review → promote → spec → observe. Now go deeper in the direction that matters most to you.
Understand why Intent works. The notice → spec → execute → observe loop explained phase-by-phase, with the theory and tradeoffs behind each stage.
See the full methodology →See the operational dashboard. Every Intent, every spec, every execution—all in one place. The Jira-replacement view that shows how Intent runs day-to-day.
See the work system dashboard →Understand the architecture. MCP servers, trust model, agent topology, observability stack. How the tooling is built and how to extend it.
See the architecture →Once you've tried Intent in your workspace, you can adopt it incrementally in existing repositories. The native-repos adoption model defines four tiers—start where you are, advance when you're ready.
.intent/ structure and CLI. Signals, intents, and specs live alongside your code.Each tier is self-contained. You get value at every level—you don't need to reach Tier 4 to benefit. Most teams start at Instrumented (Tier 2) after completing this guide.
See adoption tiers for existing repos →
This guide got you to Instrumented. You have a .intent/ directory, CLI tools, and your first signal-to-observation loop. From here, explore native repos adoption tiers to scale across your codebase, or read the deployment guide to set up four MCP servers for agent execution.