quint-code

First Steps

You've installed quint-code and run init. Now what?

Ask the agent to explain itself

The fastest way to learn quint-code is to ask your AI agent:

/q-reason explain how to work with quint-code
effectively — what commands exist, when to use
each one, and what's the recommended workflow

The agent has full knowledge of all quint-code tools and will walk you through them in context of your specific project. This is not a canned tutorial — it's a live conversation with an agent that understands both quint-code and your codebase.

Existing project? Run onboarding

If you're adding quint-code to a project that already has code, architecture docs, or ADRs: 

/q-onboard

The agent will:

  • Scan your README, architecture docs, ADR directories
  • Record discovered decisions as notes
  • Frame unresolved architectural tensions as problems
  • Run module coverage analysis (which parts of your codebase have decisions, which don't)
  • Suggest what to tackle first

Have existing specs or design docs in a gitignored folder? Point the agent to them: "scan the docs in .specs/ and record what you find." The agent can read any file in your project — it's not limited to git-tracked files.

Set up a project prompt for better results

quint-code works without any project-level prompts. But adding a prompt file with Quint-aware instructions makes the agent significantly better at using the tools proactively. See Agent Prompt Setup for details. 

# Claude Code
curl -fsSL https://raw.githubusercontent.com/m0n0x41d/quint-code/main/CLAUDE.md > CLAUDE.md

# Cursor → .cursorrules, Codex → AGENTS.md (same content, different filename)

This file teaches the agent: communication style (direct, no cheerleading), thinking principles (weakest link analysis, reversibility checks), the FPF decision workflow, and key concepts like R_eff and evidence decay.

Adapt it to your project — remove sections that don't apply, add project-specific context. The Quint-specific sections (FPF Mode, Commands, Glossary) are the important parts.

Two ways to make decisions

Quick mode: /q-reason

The fastest way. Describe your problem, the agent handles the rest: 

/q-reason we need to add caching to our API.
Latency matters, team is 3 people, we're on AWS.

The agent frames the problem, generates options, compares them, and records the decision — all in one conversation. Good for getting started and for decisions where speed matters more than thoroughness.

Honest trade-off: /q-reason runs the entire cycle in one conversation. With long context, the agent can lose focus — comparison criteria may blur, variant generation may become superficial, the verification gate may get rushed. This is not a quint-code limitation; it's how LLMs work with large prompts. The context fills up, and quality at each step can degrade.

Full manual cycle (recommended for important decisions)

For decisions that are hard to reverse, affect the team, or have real consequences if wrong — drive each step yourself: 

/q-frame  → /q-char  → /q-explore → /q-compare → /q-decide

Each command loads its own focused prompt with specific guidance for that step. The context stays clean. You think through each step deliberately — and the structured process works for your brain too, not just the AI's. Defining the problem forces clarity. Setting criteria before seeing options prevents bias. The verification gate catches weak reasoning.

This is where quint-code delivers the best results. Start here for anything that matters. See the full cycle walkthrough for details on each step.

What happens after a decision?

This is the part most people ask about. After the agent records a decision:

  • A markdown file appears in .quint/decisions/ — commit it with your code
  • The decision tracks affected files — if those files change later, drift detection flags it
  • Evidence can be attached — test results, benchmarks, user feedback. Evidence has an expiry date.
  • R_eff (trust score) is computed — based on evidence quality. Expired evidence degrades the score.
  • Stale decisions surface — /q-status and quint-code board show what needs review

You don't need to do anything extra. The system is self-correcting: when decisions go stale, they surface. When you work on files covered by a decision, the agent can mention it. The decide → measure → reframe loop runs naturally as part of your workflow.

See your project at a glance

Run quint-code board in a side terminal. It shows decision health, module coverage, problems pipeline, drift alerts — and refreshes automatically every 3 seconds as you work with the agent in another terminal. No agent session required.

Day-to-day usage

Situation What to do
Big feature, architectural choice /q-reason [describe the problem]
Quick tech choice during coding The agent auto-records notes when it notices decisions
Start of a work session quint-code board or /q-status
"Why did we do it this way?" /q-search [topic]
Reviewing a PR with decisions Read the .quint/decisions/ markdown files in the diff
Decision feels outdated /q-refresh — scan, waive, reopen, or supersede

Next steps