Conduct

AI Agent Orchestration Platform with Persistent Memory

Conduct is a backend-powered platform that enables AI agents to build software systematically with long-term memory, team collaboration, and verified progress tracking.

Version: 0.2.0-alpha (Backend Architecture)
Status: Alpha - Implementation Complete, Ready for Testing

What is Conduct?

Conduct transforms AI agent workflows from ad-hoc prompting into systematic, memory-driven development with:

Persistent Memory: Centralized backend stores all specs, runs, and checks
Team Collaboration: Self-hostable backend enables multi-developer workflows
Verified Progress: Three-phase workflow (spec → run → check)
Feature Memory: Automatic discovery and tracking of codebase features
Profile Management: Multi-environment support (local, staging, production)

Quick Start

1. Setup Backend (One-time)

cd backend

# Start PostgreSQL
docker-compose up -d postgres

# Run migrations & seed data
npm run db:setup

# Start backend
tsx example-server.ts

Save the API key from output!

2. Install & Configure CLI

# Install CLI (global or local)
npm install -g conduct-cli@0.2.0

# Add backend profile
conduct profile add \
  --name local \
  --url http://localhost:3000/conduct \
  --key <your-api-key> \
  --project myproject

3. Initialize Project

cd your-project
conduct init

4. Start Using

# List memory
conduct list

# Create a spec
conduct spec create spec.md

# Check progress
conduct spec list
conduct run list

Architecture

┌─────────────┐
│  AI Agent   │
└──────┬──────┘
       │
       ▼
┌──────────────────┐
│  Conduct CLI     │ 
│  + HTTP Client   │
│  + Cache         │
└──────┬───────────┘
       │ REST API
       ▼
┌──────────────────────┐
│  Conduct Backend     │
│  + API (35 endpoints)│
│  + Auth & Permissions│
│  + File Storage      │
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│  Database            │
│  (Postgres/MySQL/    │
│   SQLite)            │
└──────────────────────┘

Key Features

Backend (Self-Hostable)

REST API - 35 endpoints for complete CRUD operations
Multi-Database - PostgreSQL, MySQL, SQLite support
Authentication - API key based with permission control
File Storage - Local filesystem (extensible to S3/GCS)
Dry-Run Mode - Preview all changes before executing
Rate Limiting - Configurable request throttling
Soft Deletes - Data preservation
Docker Ready - Easy deployment with Docker Compose

CLI (Team-Friendly)

Profile Management - Multiple environments (dev/staging/prod)
Entity Commands - Manage specs, runs, checks
Smart Caching - Offline-capable with TTL cache
Dry-Run Everything - --dry-run flag on all mutations
JSON Output - Machine-readable with --json
Backward Compatible - v0.1 support via --v1 flag

Workflow

Three-Phase Development:

Spec - AI agent transforms intent into specification
Run - AI agent implements the spec
Check - AI agent verifies implementation

Commands:

# Spec phase
conduct spec create spec.md --dry-run  # Preview
conduct spec create spec.md             # Create
conduct spec get SPEC-001               # View
conduct spec update SPEC-001 --status completed

# Run phase
conduct run create run.md --spec-id SPEC-001 --dry-run
conduct run create run.md --spec-id SPEC-001
conduct run link RUN-001 42 43          # Link features
conduct run update RUN-001 --status completed

# Check phase
conduct check create check.md --run-id RUN-001 --result pass
conduct check list --run-id RUN-001

Documentation

Getting Started

Backend Quick Start - Get backend running in 2 minutes
Backend Setup Guide - Detailed setup instructions
CLI Command Reference - Complete command documentation
Testing Guide - How to test everything

Migration

Migration Guide - Migrate from v0.1 to v0.2
Release Notes - What's new in v0.2

Technical

Backend API Reference - Complete API documentation
Implementation Progress - Development status

Repository Structure

conduct/
├── backend/           # Backend service (Node.js + Express)
│   ├── src/          # Source code
│   ├── scripts/      # Migration & seed scripts
│   └── docs/         # API documentation
├── cli/              # CLI tool (Commander.js)
│   ├── client/       # HTTP client + cache
│   ├── commands/     # CLI commands
│   └── templates/    # Agent templates
├── docs/             # Documentation
└── _conduct/         # Conduct memory files (local)
    ├── specs/        # Specifications
    ├── runs/         # Run logs
    └── checks/       # Check results

Examples

Create a Specification

# Write spec in markdown
cat > spec.md << 'EOF'
# Spec AUTH-001: User Authentication

## What
Implement user authentication with email/password.

## Why
Users need secure access to the application.

## How
- Use bcrypt for password hashing
- JWT tokens for sessions
- Rate limiting on login attempts

## Acceptance Criteria
- [ ] Users can register
- [ ] Users can login
- [ ] Passwords are hashed
- [ ] Invalid attempts are rate limited
EOF

# Preview with dry-run
conduct spec create spec.md --dry-run

# Create the spec
conduct spec create spec.md --spec-id AUTH-001

# View it
conduct spec get AUTH-001

Implement the Spec

# Create run
cat > run.md << 'EOF'
# Run: Implementing AUTH-001

## Changes Made
- Created auth controller
- Added bcrypt password hashing
- Implemented JWT token generation
- Added rate limiting middleware

## Files Modified
- src/auth/controller.ts (new)
- src/auth/service.ts (new)
- src/middleware/rateLimit.ts (updated)

## Testing
- Unit tests: 15/15 passing
- Manual testing: All flows working
EOF

conduct run create run.md --spec-id AUTH-001

Verify Implementation

# Create check
cat > check.md << 'EOF'
# Check: AUTH-001 Verification

## Test Results
✓ Registration works
✓ Login works  
✓ Passwords hashed
✓ Rate limiting active

## Verdict
All acceptance criteria met. Ready for deployment.
EOF

conduct check create check.md \
  --run-id RUN-001 \
  --result pass

Multi-Environment Setup

# Local development
conduct profile add \
  --name local \
  --url http://localhost:3000/conduct \
  --key sk_dev_xxx

# Staging
conduct profile add \
  --name staging \
  --url https://staging.company.com/conduct \
  --key sk_staging_xxx

# Production (read-only)
conduct profile add \
  --name production \
  --url https://api.company.com/conduct \
  --key sk_prod_readonly_xxx

# Switch profiles
conduct profile use staging
conduct list  # Now accessing staging backend

conduct profile use local
conduct list  # Now accessing local backend

Development

Backend Development

cd backend

# Install dependencies
pnpm install

# Setup database
docker-compose up -d postgres
npm run db:setup

# Development
tsx example-server.ts

# Build
pnpm build

# Test
pnpm test

CLI Development

cd cli

# Install dependencies
pnpm install

# Build
pnpm build

# Test locally
./dist/cli/index.js --help

# Run tests
pnpm test

Contributing

We welcome contributions! See our Contributing Guide for details.

Areas We Need Help

Testing with different databases (MySQL, SQLite)
Performance optimization
Documentation improvements
Bug reports and fixes
Feature requests

Roadmap

v0.2.0 (Current - Alpha)

✅ Self-hostable backend
✅ REST API (35 endpoints)
✅ CLI refactor with profiles
✅ Multi-database support
⏳ Testing & bug fixes

v0.2.1 (Next)

Offline queue for mutations
Enhanced conflict resolution
Performance optimizations
Bug fixes from alpha feedback

v0.3.0 (Future)

Organizations & multi-tenancy
OAuth authentication
Admin dashboard (web UI)
S3/GCS storage support
Webhook integrations
Plugin system

v1.0.0 (Stable)

Production-ready
Full enterprise features
SLA guarantees
Professional support

FAQ

Q: Do I need to migrate from v0.1?
A: Not immediately. v0.1 still works with --v1 flag. Migrate when ready.

Q: Can I use both v0.1 and v0.2?
A: Yes! Use --v1 flag for old commands, default for new.

Q: Do I have to self-host?
A: Yes, v0.2 requires a backend. But it's easy with Docker Compose (< 5 minutes).

Q: What about Turso?
A: v0.2 focuses on self-hosting. Turso support may return in future versions.

Q: Is this production-ready?
A: Alpha quality. Use in development, test thoroughly before production.

Q: How do I backup my data?
A: Backend uses standard databases. Use standard backup tools (pg_dump, etc.).

License

MIT License - see LICENSE for details.

Support

Documentation: docs.conduct.run
Issues: GitHub Issues
Discord: Join our community

Acknowledgments

Built with:

Express.js - Web framework
Drizzle ORM - Database toolkit
PostgreSQL - Primary database
Commander.js - CLI framework
TypeScript - Type safety

Conduct v0.2.0 - AI Agent Orchestration with Persistent Memory
Status: Alpha - Ready for Testing
Released: 2025-12-08

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
.vscode		.vscode
app		app
backend		backend
cli		cli
docs		docs
templates-server		templates-server
tests/e2e		tests/e2e
.dev-server.pid		.dev-server.pid
.gitignore		.gitignore
CNAME		CNAME
INSTALLATION-SETUP.md		INSTALLATION-SETUP.md
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md
conduct-v01.sh		conduct-v01.sh
conduct.json		conduct.json
conduct.track.json		conduct.track.json
install.sh		install.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
test-workflow.sh		test-workflow.sh
tsconfig.json		tsconfig.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

Conduct

What is Conduct?

Quick Start

1. Setup Backend (One-time)

2. Install & Configure CLI

3. Initialize Project

4. Start Using

Architecture

Key Features

Backend (Self-Hostable)

CLI (Team-Friendly)

Workflow

Documentation

Getting Started

Migration

Technical

Repository Structure

Examples

Create a Specification

Implement the Spec

Verify Implementation

Multi-Environment Setup

Development

Backend Development

CLI Development

Contributing

Areas We Need Help

Roadmap

v0.2.0 (Current - Alpha)

v0.2.1 (Next)

v0.3.0 (Future)

v1.0.0 (Stable)

FAQ

License

Support

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages