Thinking tools made operational.

Inquiry treats your AI coding assistant as a finite state machine with a declarative transition contract. The CLI enforces pre- and post-conditions. The point is not to deny model quality, but to make AI-assisted work legible through explicit thinking tools, orchestration, and memory.

This page is a public explainer. For the canonical repository doctrine, see docs/architecture.md and docs/spec/finite-ape-machine.md.

The operational cycle

The current operational model is a six-state cycle. IDLE is the entry and exit, and DEWEY owns its bounded triage mission. ANALYZE, PLAN, and EXECUTE are the core work phases. END is the explicit PR gate. EVOLUTION is opt-in. The forward flow is linear; backward edges from PLAN and EXECUTE to ANALYZE exist because re-analysis is legal, not a recovery hack.

Inquiry finite state machine diagram showing IDLE → ANALYZE → PLAN → EXECUTE → END → IDLE cycle, with backward transitions from PLAN and EXECUTE to ANALYZE, and an opt-in EVOLUTION state after END.
IDLE · DEWEY
Bounded issue triage. DEWEY determines whether the situation is ready to become or select a GitHub issue; inquiry-start performs the explicit handoff into ANALYZE.
ANALYZE · SOCRATES
Clarifies the problem through dialog. Produces diagnosis.md.
PLAN · DESCARTES
Divide, order, verify, enumerate. Produces plan.md.
EXECUTE · ADA
Programming as explicit construction under a coding manifesto. Produces code and commits.
END · PR gate
Opens and merges the pull request via gh. No agent; the CLI orchestrates.
EVOLUTION · DARWIN opt-in
Reads the cycle's artifacts and proposes mutations to Inquiry itself. Off by default.

The transition contract

Transitions aren't code — they're data. A YAML file declares every legal transition, its trigger event, its prechecks, and its effects. The CLI reads this file at runtime and refuses any transition the contract doesn't permit. 

# code/cli/assets/transition_contract.yaml (excerpt)
transitions:
  - from: ANALYZE
    to: PLAN
    event: complete_analysis
    prechecks:
      - diagnosis_exists
      - issue_linked
    effects:
      - set_state: PLAN
      - invoke_agent: DESCARTES

  - from: PLAN
    to: ANALYZE
    event: start_analyze
    # backward transition: re-analysis is legal
    prechecks:
      - human_approval

This is the core artifact. It's what makes Inquiry portable across hosts and tools: every agent reads the same contract and can only produce the transitions it permits. If a future host (Claude, Codex, Gemini) processes a different prompt, the contract constrains the output shape identically.

Memory as code

Inquiry keeps repository knowledge in plain files, not a hosted memory service. Repo-scoped configuration lives in .inquiry/; cycle-scoped state and artifacts live in cleanrooms/<branch>/.

.inquiry/ — repo-scoped configuration

  • config.yaml — feature flags and runtime preferences
  • metrics*.yaml — repository-scoped metrics surfaces when enabled
  • Settings shared across cycles, hosts, and future runs

cleanrooms/<branch>/ + docs/ — cycle state and project knowledge

  • .iq.state.yaml — current FSM state and last transition for the active cycle
  • analyze/diagnosis.md, plan.md, run_trace.yaml, and mutations.md hold the cycle evidence
  • ADRs, specs, and runbooks in docs/ hold the long-term project memory
  • Indexed by the agents via the doc-read skill
  • index.md per directory acts as a primary index
  • Structured YAML and durable markdown keep the same evidence legible to the host, the agent, and the reviewer

Database-inspired indexing without a database. Directories are tables. Files are rows. Frontmatter is the schema. index.md is the primary index. An agent with grep is more than an agent with a vector store for this scale of knowledge. Dual legibility: the same file an agent reads is the same file you review in GitHub. No translation layer.

The risk matrix

Spec-only today. The idea: iq fsm transition should gate on human approval only when the engineering risk warrants it. Low-risk mechanical transitions (scaffolding, formatting, test scaffolding) proceed silently. High-risk ones (schema changes, production deploys, external API mutations) demand explicit approval.

Roadmap item. Until the matrix is implemented, every state transition requires operator confirmation. The default is safe but verbose. See the roadmap under long-term items.

Why thinking tools matter

AI makes philosophical discipline operational again.

Inquiry is not trying to prove that a weaker local model can beat a frontier hosted one. The aim is stricter: make AI-assisted engineering legible, auditable, and portable by grounding it in explicit thinking tools. If providers change, prices move, or hosts churn, the doctrine should survive because the discipline lives in the method, not in one vendor surface.

The thesis Inquiry exists to test is philosophical and methodological: AI-assisted software work improves when questioning, decomposition, verification, and evolutionary learning are turned into operational method. The evidence lives in a metrics.yaml dataset that doesn't fully exist yet — the reproducibility score sits at 2/10 until 30 clean cycles and a multi-host test matrix land. See the historical bootstrap thesis, APE builds APE →.

Go deeper

Meet the agents →

The five active agents in the live roster, and the larger cast that collapsed.

Bootstrap thesis: APE builds APE →

The historical bootstrap story and the evidence it produced, without making APE the current product name.

Read the architecture →

The canonical system-level explanation of APE as the orchestrating methodology.

Read the spec →

The formal specification, referenced throughout this page.