Architecture

Understand how Conduct works under the hood and how it orchestrates AI agents.

Overview

Conduct consists of two main components:

Conduct CLI - Command-line tool for specification management
Conduct Desktop App (Coming Soon) - Multi-agent orchestration interface

Conduct CLI Architecture

Core Components

conduct-cli/
├── Commands
│   ├── init      - Project initialization
│   ├── list      - Hierarchy visualization
│   └── upgrade   - Instruction updates
├── Templates
│   ├── Spec templates
│   ├── Agent commands
│   └── Root instructions
└── Utils
    ├── Version tracking
    ├── File operations
    └── Issue tracker config

Specification Structure

Conduct uses a hierarchical folder structure for managing specifications:

conduct/
├── spec.v0.md              # Root specification
├── AGENTS.md               # AI agent instructions
├── track.json              # Version & config tracking
├── features/               # Feature specifications
│   └── feature-name/
│       ├── spec.v0.md      # Feature spec (version 0)
│       ├── spec.v1.md      # Updated spec (version 1)
│       ├── features/       # Nested sub-features
│       │   └── sub-feature/
│       │       └── spec.v0.md
│       └── changes/        # Change specifications
│           ├── change-1.spec.md
│           └── change-2.spec.md
└── changes/                # Root-level changes
    └── root-change.spec.md

Version Management

Conduct automatically manages specification versions:

Initial State: New features start at spec.v0.md
Change Created: When a change is added, parent spec is versioned
Version Increment: spec.v0.md → spec.v1.md → spec.v2.md
Audit Trail: Old versions are preserved for history
Tracking: track.json records current versions

Example Flow:

1. Create feature:
   features/auth/spec.v0.md

2. Add change "Add OAuth":
   features/auth/changes/add-oauth.spec.md
   features/auth/spec.v1.md (created)

3. Add change "Fix session bug":
   features/auth/changes/fix-session.spec.md
   features/auth/spec.v2.md (created)

Result:
features/auth/
├── spec.v0.md (original)
├── spec.v1.md (after OAuth)
├── spec.v2.md (after bug fix, current)
└── changes/
    ├── add-oauth.spec.md
    └── fix-session.spec.md

Agent Integration System

Conduct generates agent-specific command files during initialization:

Command File Structure

Each agent receives two command files:

feature.md - Instructions for creating features
change.md - Instructions for creating changes

Root Instruction Files

Some agents (Claude, Warp) receive root-level files:

CLAUDE.md - Automatically loaded by Claude Code
WARP.md - Automatically loaded by Warp Agent Mode

These files contain:

Overview of Conduct structure
Links to command files
Project-specific conventions

Command Execution Flow

User invokes command (/feature or /change)
         ↓
AI Agent reads command file
         ↓
Agent follows step-by-step instructions
         ↓
Agent creates/modifies files
         ↓
Conduct structure is updated
         ↓
track.json is updated (for changes)

Issue Tracker Integration

Conduct stores issue tracker configuration in track.json:

{
  "version": "1.0.0",
  "trackers": {
    "github": "https://github.com/org/repo/issues/",
    "jira": "https://company.atlassian.net/browse/",
    "linear": "https://linear.app/company/issue/"
  },
  "features": {
    "authentication": {
      "version": 2,
      "path": "features/authentication"
    }
  }
}

Agent commands dynamically inject tracker links into spec templates.

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 Code
│       ├── 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 Code CLI
const pty = spawn('claude-code', [], {
  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 Code (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

AI Agent Integration