Architecture

Documentation

Architecture

Understand how Conduct v0.1 works under the hood - from persistent memory to agent orchestration.

Overview

Conduct v0.1 is an AI agent orchestration platform with persistent memory that enables intelligent workflows through structured memory management.

Core Components:

Memory Database - libSQL-based persistent storage (local or remote)
CLI Tool - Command-line interface for memory operations
Agent Templates - Structured workflows for AI agents
SQL Validator - Security layer for memory updates
Discovery & Reconciliation - Automated codebase understanding

Conduct CLI Architecture

Core Components

cli/
├── api/                    # Core APIs
│   ├── spec.ts            # Spec management
│   ├── run.ts             # Run management
│   ├── check.ts           # Check management
│   ├── feature.ts         # Feature operations
│   ├── package.ts         # Package operations
│   └── issue.ts           # Issue tracker integration
├── cli/                   # Command handlers
│   ├── index.ts          # CLI entry point
│   └── commands/
│       ├── init.ts       # Project initialization
│       ├── save.ts       # SQL execution
│       ├── list.ts       # Memory queries
│       ├── health.ts     # System diagnostics
│       ├── upgrade.ts    # Template updates
│       ├── config.ts     # Configuration management
│       ├── sync.ts       # Issue tracker sync
│       ├── discover.ts   # Feature discovery
│       ├── reconcile.ts  # Drift detection
│       ├── relevancy.ts  # Score calculation
│       └── archive.ts    # Old run archival
├── db/                    # Database layer
│   ├── client.ts         # libSQL client
│   ├── credentials.ts    # Credential management
│   ├── migrations.ts     # Schema migrations
│   └── validator.ts      # SQL validation
├── utils/                 # Utilities
│   ├── config.ts         # Config helpers
│   ├── discovery.ts      # Feature discovery
│   ├── reconcile.ts      # Reconciliation
│   ├── relevancy.ts      # Relevancy scoring
│   ├── tracker.ts        # Issue tracking
│   └── agent-instructions.ts  # Template generation
├── remote/                # Remote integrations
│   ├── github.ts         # GitHub API
│   └── linear.ts         # Linear API
└── tests/                 # Test suite
    ├── unit/
    └── integration/

Memory Database Schema

Conduct uses a relational database for persistent memory:

-- Package (for monorepos)
CREATE TABLE package (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  slug TEXT UNIQUE NOT NULL,
  name TEXT,
  paths TEXT  -- JSON array: ["src/frontend", "packages/ui"]
);

-- Feature (discovered by indexing)
CREATE TABLE feature (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  slug TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  package_id INTEGER NOT NULL,
  parent_id INTEGER,  -- For nested features
  paths TEXT,  -- JSON array: ["src/auth", "lib/auth"]
  status TEXT DEFAULT 'active',  -- active|deprecated|removed
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP
);

-- Spec (work to be done)
CREATE TABLE spec (
  id TEXT PRIMARY KEY,
  location TEXT NOT NULL,
  current_version INTEGER DEFAULT 0,
  status TEXT NOT NULL,  -- pending|in-progress|completed|archived
  agent TEXT,
  loe TEXT,  -- simple|medium|complex|epic
  source_type TEXT,  -- prompt|file|github|linear|url
  source_ref TEXT  -- URL or issue ID
);

-- Run (execution of spec)
CREATE TABLE run (
  id TEXT PRIMARY KEY,
  spec_id TEXT NOT NULL,
  spec_version INTEGER,
  location TEXT NOT NULL,
  status TEXT NOT NULL,  -- pending|in-progress|completed|failed|archived
  agent TEXT,
  started_at TIMESTAMP,
  completed_at TIMESTAMP,
  relevancy_score FLOAT DEFAULT 1.0
);

-- Check (verification of run)
CREATE TABLE check_result (
  id TEXT PRIMARY KEY,
  run_id TEXT NOT NULL,
  location TEXT NOT NULL,
  status TEXT NOT NULL,
  result TEXT NOT NULL,  -- pass|fail|partial
  agent TEXT,
  completed_at TIMESTAMP
);

-- Run-Feature Link (many-to-many)
CREATE TABLE run_feature (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  run_id TEXT NOT NULL,
  feature_id INTEGER NOT NULL,
  type TEXT NOT NULL,  -- new|change|fix|meta
  description TEXT
);

-- Issue Tracker Connections
CREATE TABLE issue_connection (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  entity_type TEXT NOT NULL,  -- spec|run|check
  entity_id TEXT NOT NULL,
  tracker_type TEXT NOT NULL,  -- github|linear|jira|gitlab
  issue_id TEXT NOT NULL,
  url TEXT,
  status TEXT,
  last_synced TIMESTAMP,
  auto_sync BOOLEAN DEFAULT 0
);

Workflow Architecture

Spec → Run → Check Workflow

1. SPEC PHASE
   User Intent → conduct-spec template → Specification
   ├── Fetch remote context (GitHub, Linear)
   ├── Consult memory (past specs, features)
   ├── Create spec file (_conduct/specs/X.vY.spec.md)
   └── Generate SQL → conduct save → Memory updated

2. RUN PHASE
   Specification → conduct-run template → Implementation
   ├── Check for UI designs
   ├── Link to discovered features
   ├── Implement end-to-end
   ├── Create run file (_conduct/runs/X.vY.run.md)
   └── Generate SQL → conduct save → Memory updated

3. CHECK PHASE
   Implementation → conduct-check template → Verification
   ├── Compare spec vs. run
   ├── Verify code vs. spec
   ├── Detect gaps
   ├── Create check file (_conduct/checks/X.vY.check.md)
   └── Generate SQL → conduct save → Memory updated

Security Architecture

Two-Step Memory Update Process

Conduct implements security through separation of concerns:

Step 1: Agent Generates SQL (Untrusted)

-- _conduct/operations/update-run-1.sql
INSERT INTO run (id, spec_id, location, status)
VALUES ('1', 'spec-1', '_conduct/runs/1/', 'completed');

INSERT INTO run_feature (run_id, feature_id, type)
VALUES ('1', 5, 'change');

Step 2: Human Validates and Executes (Trusted)

# Review
cat _conduct/operations/update-run-1.sql

# Validate and execute
conduct save _conduct/operations/update-run-1.sql

SQL Validation

The validator enforces strict security rules:

Whitelisted:

✅ INSERT statements
✅ UPDATE statements
✅ Specific tables only (package, feature, spec, run, check_result, run_feature, issue_connection)

Blocked:

❌ DELETE, DROP, ALTER, TRUNCATE
❌ Subqueries
❌ Function calls
❌ SQL injection patterns (’, –, /*, ;)
❌ Unauthorized tables

Agent Integration System

Agent Template Architecture

Conduct provides 9 agent templates deployed to _conduct/templates/:

_conduct/templates/
├── conduct-spec.md         # Create specification
├── conduct-design.md       # Create UI design
├── conduct-run.md          # Execute specification
├── conduct-check.md        # Verify implementation
├── conduct.md              # Lightweight mode
├── conduct-index.md        # Discover features
├── conduct-reconcile.md    # Sync memory
├── conduct-dry-run.md      # Plan without implementing
└── conduct-dry-check.md    # Verify plan

These templates are copied to agent-specific directories:

.cursor/commands/conduct-*.md
.claude/commands/conduct-*.md
.warp/commands/conduct-*.md
.factory/commands/conduct-*.md

Command Execution Flow

User invokes Conduct command
         ↓
AI Agent reads template file
         ↓
Agent follows structured workflow:
  1. Consult memory (conduct list)
  2. Fetch context (GitHub, Linear)
  3. Perform work (spec/run/check)
  4. Generate SQL for memory update
         ↓
Human reviews and executes SQL
         ↓
Memory database updated
         ↓
Future agents benefit from context

Discovery & Reconciliation Architecture

Feature Discovery

Three-strategy approach for automated feature discovery:

1. Directory Structure Analysis
   src/features/auth/ → feature: "auth" [confidence: 0.8]
   
2. Export Analysis (TypeScript/JavaScript)
   Parse index.ts/js files → extract exports → detect feature [confidence: 0.7]
   
3. package.json Hints
   Read "conduct.features" config → explicit features [confidence: 0.9]

Deduplication: Features found by multiple strategies are merged with boosted confidence.

Reconciliation System

Git-based drift detection:

1. Load features from memory
   ↓
2. Analyze git log (configurable time range)
   ↓
3. Detect changes:
   - Deleted files → suggest "removed"
   - Renamed files → suggest "renamed"
   - Moved files → suggest "moved"
   - Large deletions → suggest "deprecated"
   ↓
4. Calculate confidence scores
   ↓
5. Generate SQL update suggestions
   ↓
6. Human review and apply

Relevancy Scoring Architecture

Time-decay algorithm with reference boost:

function calculateRelevancy(run) {
  const baseScore = 1.0;
  const days = daysSince(run.completed_at);
  const halfLife = config.relevancy.halfLife; // default: 180
  const boost = config.relevancy.referenceBoost; // default: 0.1
  const references = countReferences(run.id);
  
  const timeDecay = Math.exp(-days / halfLife);
  const referenceBoost = 1 + (boost * references);
  
  return baseScore * timeDecay * referenceBoost;
}

Parameters:

halfLife: Days until score = 0.5 (default: 180)
referenceBoost: Boost per reference (default: 0.1 = 10%)
archiveThreshold: Archive below this score (default: 0.1 = 10%)

Database Modes

Local Mode (Embedded libSQL)

Profile: default
URL: file://_conduct/memory.db
Token: (empty)

✅ No network required
✅ Fast performance
✅ Good for solo development
❌ No team collaboration

Remote Mode (Turso)

Profile: production
URL: libsql://conduct.turso.io
Token: eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...

✅ Team collaboration
✅ Centralized memory
✅ Backup and sync
❌ Requires network

Conduct Desktop App Architecture (Coming Soon)

Overview

The desktop app provides a unified interface for managing multiple AI agents (CLI-based and web-based).

Technology Stack

Electron - Desktop application framework
SvelteKit - UI framework (renderer process)
Node.js - Main process backend
TypeScript - Primary language

Key Libraries

node-pty - Terminal/PTY management for CLI agents
BrowserView - Embedded web agent control (Electron API)
IPC - Inter-process communication

Process Architecture

Main Process (Node.js)
├── PTY Manager (node-pty)
│   └── Manages CLI agent processes
│       ├── Claude
│       ├── Aider
│       └── Other CLI tools
├── Web Agent Manager (BrowserView)
│   └── Manages embedded web agents
│       ├── Perplexity
│       ├── ChatGPT
│       └── Claude Web
└── IPC Bridge
    └── Communicates with renderer

Renderer Process (SvelteKit)
└── User Interface
    ├── Agent cards/panels
    ├── Output displays
    ├── Prompt interface
    └── Control interfaces

Communication Flow

User Input
    ↓
SvelteKit UI
    ↓
IPC Message
    ↓
Main Process
    ↓
Agent (CLI or Web)
    ↓
Output Stream
    ↓
Main Process
    ↓
IPC Message
    ↓
SvelteKit UI
    ↓
Display to User

CLI Agent Management

Using node-pty:

Spawn Process: Create pseudo-terminal for CLI agent
Capture Output: Stream stdout/stderr in real-time
Send Input: Programmatically send commands to agent
Lifecycle Management: Handle start, stop, restart, kill

Example Flow:

// Spawn Claude CLI
const pty = spawn('claude', [], {
  name: 'xterm-color',
  cwd: projectPath
});

// Capture output
pty.on('data', (data) => {
  // Send to renderer via IPC
  mainWindow.webContents.send('agent-output', data);
});

// Send input
pty.write('Hello, Claude!\n');

Web Agent Management

Using BrowserView:

Embed Browser: Load web-based AI interface
Inject Scripts: Control web UI programmatically
Capture Responses: Extract output from web pages
Session Management: Handle authentication state

Example Flow:

// Create BrowserView for Perplexity
const view = new BrowserView();
mainWindow.setBrowserView(view);
view.webContents.loadURL('https://perplexity.ai');

// Inject control script
view.webContents.executeJavaScript(`
  // Find input field and submit prompt
  document.querySelector('textarea').value = 'Your prompt';
  document.querySelector('button[type="submit"]').click();
`);

Multi-Agent Orchestration

The desktop app enables coordinated workflows:

Broadcast Prompts: Send same prompt to multiple agents
Sequential Execution: Chain prompts across agents
Parallel Processing: Run multiple agents simultaneously
Dependency Management: Coordinate agent interactions

Example Workflow:

1. User enters prompt: "Implement authentication"

2. Desktop app broadcasts to:
   - Claude (CLI): Generate code
   - Perplexity (Web): Research best practices
   - ChatGPT (Web): Create documentation

3. Results displayed in unified interface

4. User reviews and refines based on outputs

Development Phases

Phase 1: Foundation ✅

Set up Electron + SvelteKit
Implement IPC communication
Create basic UI shell

Phase 2: CLI Agent Support (In Progress)

Integrate node-pty
Spawn and control CLI agents
Display real-time output
Send input to agents

Phase 3: Web Agent Support (Planned)

Implement BrowserView integration
Load web-based AI tools
Inject control scripts
Capture web agent outputs

Phase 4: Multi-Agent Orchestration (Planned)

Support multiple simultaneous agents
Unified prompt broadcasting
Agent coordination logic
Status monitoring

Phase 5: Polish (Planned)

Error handling and recovery
Session persistence
Configuration management
Performance optimization

Design Principles

1. Specification-First

All features and changes are documented before implementation, creating:

Clear audit trail
Better AI-assisted development
Team alignment
Historical context

2. Multi-Agent Compatibility

Conduct works with any AI coding tool:

Agent-agnostic specification format
Consistent commands across platforms
Team members can use different tools
Easy switching between agents

3. Hierarchical Organization

Infinitely nested feature hierarchies:

Organize complex systems naturally
Group related features together
Scale from small to large projects
Maintain clear structure

4. Automatic Version Management

No manual version tracking:

Specs versioned automatically
Old versions preserved
Clear change history
Audit trail maintained

5. Minimal Configuration

Works out of the box:

Interactive setup
Sensible defaults
Optional issue tracker integration
Simple commands

Security Considerations

CLI Security

No external API calls
All data stored locally
No telemetry or tracking
Open source and auditable

Desktop App Security

Sandboxed web agents (BrowserView)
Isolated CLI processes (node-pty)
No credentials stored in plain text
Secure IPC communication

Issue Tracker Integration

URLs stored in local track.json
No API keys required
Links only, no data sent to trackers
Optional integration

Performance

CLI Performance

Fast file operations
Minimal dependencies
No network calls
Instant command execution

Desktop App Performance

Efficient process management
Streaming output (no buffering)
Lazy-loaded web agents
Optimized IPC communication

Extensibility

Future Extensions

Plugin system for custom agents
Custom spec templates
Workflow automation
API for external tools

Current Extensibility

Manual agent command customization
Custom spec formats
Project-specific conventions
Issue tracker templates

Comparison with Other Tools

See our detailed comparison blog post for how Conduct compares to spec-kit and OpenSpec.

Next Steps

Explore Getting Started
Learn about AI Agent Integration
Read the CLI Reference

AI Agent Templates