Documentation — Conduit

Getting started

Installation

The standalone binary is the recommended installation. Download the correct platform artifact from GitHub Releases, verify it against SHA256SUMS, and place it on your PATH.

Standalone persistence is supported on Linux x64 glibc, Linux ARM64 glibc, macOS ARM64, and Windows x64. Alpine/musl and Intel macOS are not currently supported standalone targets.

Linux and macOS installershell

curl -fsSL https://github.com/MartinAndreev/conduit/releases/latest/download/install.sh | sh

Windows installerpowershell

irm https://github.com/MartinAndreev/conduit/releases/latest/download/install.ps1 | iex

You can also install the development package inside a project:

pnpm add -D conduit-orchestrator
pnpm exec conduit init .

First project

Quick start

Conduit operates on an existing Git repository. Initialize the current repository, then run the bare command to open Home.

cd your-project
conduit init .
conduit

conduit init creates:

conduit.yml          # committed project configuration
.conduit/roles/      # editable role instructions
specs/               # committed feature packets

It also adds local run data, caches, worktrees, assignments, and the local .conduit/state.db database, its WAL files, and migration backups to .gitignore.

Run from another directory with --project <path>. Project resolution uses the invocation directory or this explicit path—it never uses Conduit’s package directory.

Local settings

Project configuration

The repository-root conduit.yml is the source of truth for project directories and role definitions. Commit it so every contributor and agent uses the same boundaries.

version: 1
specsDir: specs
stateDir: .conduit
roles:
  frontend:
    description: "Implements approved interface work."
    runner: opencode
    mode: subagent
    model: openai/gpt-5-mini
    owns: [apps/web, packages/ui]
    skill:
      source: file:.conduit/roles/frontend.md

  qa:
    description: "Turns approved cases into tests."
    runner: pi
    mode: subagent
    owns: [tests, e2e]
    dependsOn: [frontend]
    skill:
      source: file:.conduit/roles/qa.md

Setting	Purpose	Default
`version`	Configuration schema version.	`1`
`specsDir`	Directory containing committed feature packets.	`specs`
`stateDir`	Ignored local runtime state, logs, caches, and worktrees.	`.conduit`
`roles`	Named specialists available to refinement and runs.	Built-in role set

Machine settings

Global configuration

Conduit has two machine-wide configuration stores. The existingsettings.yml stores provider defaults and named credential-profile references. The new global.dbstores reusable role-profile defaults such as runner, model, effort, mode, ownership, and skill source.

Platform	Settings file	Profile database
Linux	`~/.config/conduit/settings.yml`	`$XDG_DATA_HOME/conduit/global.db` or `~/.local/share/conduit/global.db`
macOS	`~/Library/Application Support/conduit/settings.yml`	`~/Library/Application Support/conduit/global.db`
Windows	`%APPDATA%\conduit\settings.yml`	`%APPDATA%\conduit\global.db`

Role settings resolve from built-in defaults, then the default global profile, then project conduit.yml values. Project role guidance is loaded last as advisory content. CLI options can override project paths and provider selection for the current invocation. Conduit records provenance for resolved fields so callers can tell which layer supplied each value.

version: 1
defaultProvider: local-spec-kit
credentialProfiles:
  work:
    description: "Work account"
providerSettings:
  local-spec-kit:
    enabled: true

Current provider support: Local Spec Kit is the only selectable provider today. GitHub, Linear, Jira, and Asana providers are planned, but are not available in the current release.

Never put tokens in configuration. Provider secrets are stored in the operating-system credential vault. If it is unavailable, Conduit uses an encrypted fallback vault in the global configuration directory. Settings may reference named profiles, but never contain plaintext credentials.

Local persistence

Storage and migrations

Conduit uses embedded Turso for runtime state. The project database defaults to .conduit/state.db; the user-global database is stored in the platform application-data directory shown above. Approved feature packets remain ordinary files under specs/ and stay the Git-visible source of truth.

Project database

Local runtime state

Drafts, refinement revisions, research and architect events, run events, reviews, recovery records, and source-version metadata.

Global database

Reusable machine defaults

Role-profile defaults and metadata shared on this machine. Provider credentials remain in the OS vault or encrypted fallback.

What happens on startup

Conduit opens a blocking migration screen before application queries run.
It applies checksummed global and project migrations in order.
Before pending migrations, it checkpoints and creates a redaction-checked backup.
It imports compatible legacy drafts and run artifacts idempotently without deleting their source files.
The application then opens one shared project connection and closes it during shutdown.

A checksum mismatch or unsafe migration failure stops startup with remediation guidance. Conduit does not continue into normal commands against a partially migrated schema.

Check local storage

Run the storage doctor to verify migrations, the embedded native binding, prepared queries, transactions, and close/reopen persistence for the current project.

conduit storage-doctor
conduit storage-doctor --project /path/to/repository

Repository implementations, migrations, transaction behavior, lifecycle ownership, and extension rules are documented in thedatabase API developer guide. Spawned coding agents never receive a database path, handle, or storage helper; all access stays inside the owning Conduit process and its domain repositories.

Agent boundaries

Roles and runners

Roles live under the roles key in conduit.yml. Use conduit roles to list the configured purpose, runner, ownership, and skill source.

Field	Meaning
`description`	Human-readable responsibility shown during role selection.
`runner`	Execution adapter: `codex`, `opencode`, `pi`, or `kilo`.
`mode`	`primary` for coordinating roles or `subagent` for bounded workers.
`model`	Optional runner-specific model ID. Omit it to use the runner default.
`effort`	Optional reasoning effort from `minimal` through `max`, when supported.
`readOnly`	Marks evidence-gathering or review roles that must not modify the worktree.
`owns`	Paths the role is explicitly allowed to change.
`dependsOn`	Roles that should complete before this role starts.
`skill`	Instruction source defining inputs, boundaries, verification, and reporting.

The default role set is intentionally narrow:

architect creates the approved specification and contracts.
researcher gathers repository evidence without editing.
frontend and backend implement owned product paths.
qa converts approved cases into tests.
documentation owns user and developer documentation.
reviewer independently checks the integrated result.

Role instructions

Role skills

A role entry in conduit.yml answerswho runs, with which model, and which paths they own. The role’s skill file answers how that agent should work. It is the durable instruction contract supplied to the runner alongside the approved feature assignment.

conduit.yml

Execution configuration

Runner, model, mode, read-only state, owned paths, dependencies, and skill location.

.conduit/roles/*.md

Behavioral contract

Purpose, required inputs, working rules, forbidden changes, verification, and handoff format.

Project role files

conduit init materializes the default role skills in.conduit/roles/. They are normal Markdown files, intended to be edited for the repository and committed withconduit.yml. This lets a team review agent behavior with the same process it uses for code and specifications.

.conduit/roles/
  architect.md
  researcher.md
  frontend.md
  backend.md
  qa.md
  documentation.md
  reviewer.md

What a useful skill contains

Keep the role narrow and operational. A worker should be able to read the skill and determine what evidence to load, what it may change, which checks it must run, and what a complete handoff looks like without inventing missing policy.

# Frontend role

## Purpose
Implement approved user-interface tasks from the feature packet.

## Required inputs
- Read spec.md, plan.md, the assigned task, and test-cases.md.
- Inspect relevant contracts before changing code.

## Boundaries
- Change only paths listed in the assignment.
- Do not change API contracts or add provider integrations.
- Stop and report a blocker when the packet is ambiguous.

## Workflow
1. Confirm the assigned acceptance criteria.
2. Inspect the existing implementation and tests.
3. Implement the smallest contract-complete change.
4. Run the checks required by the task packet.

## Handoff
Report changed files, verification commands, failures, and contract risks.

Avoid duplicating the feature specification.Skills define stable role behavior; the assignment and feature packet define the current work. Keeping those concerns separate prevents an old role prompt from overriding an approved spec.

Skill sources

A role skill can resolve from one of three sources:

skill:
  source: builtin:frontend

skill:
  source: file:.conduit/roles/frontend.md

skill:
  source: https://example.com/roles/frontend.md
  sha256: <reviewed-content-hash>

Source	Resolution behavior
`builtin:<name>`	Loads the role template bundled with the installed Conduit release.
`file:<path>`	Loads a project-relative Markdown file. Initialization uses this form so role instructions remain editable.
`https://…`	Requires an exact SHA-256 pin. Conduit rejects redirects and verifies content before caching it locally.

Local file sources resolve from the project root. Remote HTTPS skills require a SHA-256 pin, reject redirects, and are cached only after explicit fetching under the ignored local cache.

conduit role resolve frontend
conduit role resolve frontend --fetch-skills

The first command validates an already available built-in, local, or cached skill. The second explicitly permits fetching a pinned remote skill after its URL and hash have been reviewed. A missing file, unknown built-in, unpinned remote URL, or hash mismatch stops the role before an agent launches.

Execution

Running agents

# Validate role selection and worktree setup
conduit run 001 --roles frontend,backend --dry-run

# Open the interactive worker monitor
conduit run 001 --roles frontend,backend

# Use spinner-style CLI progress
conduit run 001 --roles frontend,backend --compact

Writing workers run in isolated Git worktrees. The monitor presents normalized runner events, role state, changed files, split diffs, cancellation, and review results. Local transcripts and run artifacts remain under the ignored state directory.

Committed source of truth

Feature packets

specs/001-team-invitations/
  story.md
  spec.md
  plan.md
  tasks.md
  test-cases.md
  clarifications.md
  contracts/

Packet files are intended to be reviewed and committed. Drafts, run logs, caches, worktrees, assignments, and the local database are runtime state and stay out of Git.

Reference

Command line

Command	Purpose
`conduit`	Open the interactive Home workspace.
`conduit init [path]`	Initialize an existing Git repository.
`conduit version`	Print the installed Conduit version.
`conduit storage-doctor`	Verify migrations, persistence, and the native database runtime.
`conduit feature <title>`	Create a new feature packet.
`conduit refine <id> [story]`	Open refinement or provide a non-interactive story.
`conduit roles`	List configured specialist roles.
`conduit role resolve <name>`	Validate a role skill source.
`conduit run <id> --roles <roles>`	Plan or execute isolated role work.
`conduit status --tui`	Open the recent run dashboard.

Set up Conduit.