Conduct

Quick Start

What is Conduct?

Conduct v0.2 helps AI agents (Claude, Factory, etc.) manage specifications, plans, and implementation tracking.

The workflow:

  1. YOU integrate Conduct SDK into YOUR app
  2. AI agent uses Conduct CLI (via templates)
  3. Specs/plans stored as mdJson in YOUR database
  4. AI agent tracks all work via runs

For Developers: Integrate Conduct SDK

Step 1: Install Conduct in YOUR App

# In YOUR existing app
npm install conduct-backend @superfunctions/db @superfunctions/http-express
npm install drizzle-orm postgres

Step 2: Add Conduct Routes

// conduct.ts
import { createConductBackend } from 'conduct-backend';
import { drizzleAdapter } from '@superfunctions/db/adapters';
import { db } from './db'; // Your existing database
 
const adapter = drizzleAdapter({ db, dialect: 'postgres' });
 
export const conduct = createConductBackend({
  database: adapter,
  auth: {
    apiKeys: async (key) => {
      // Your validation
      return { apiKeyId: 'user', projectIds: ['proj_123'] };
    },
  },
});
// server.ts  
import { toExpressRouter } from '@superfunctions/http-express';
import { conduct } from './conduct';
 
app.use('/api/conduct', toExpressRouter(conduct.router));

Step 3: Generate Migrations

Use @superfunctions/cli to extract Conduct's schema and generate migrations:

# Install CLI
npm install -D @superfunctions/cli
 
# Create superfunctions.config.js pointing to your conduct.ts
echo "import { defineConfig } from '@superfunctions/cli';
export default defineConfig({
  adapter: { type: 'drizzle', drizzle: { dialect: 'postgres' } },
  libraries: ['./src/conduct.ts'],
  migrationsDir: './migrations',
});" > superfunctions.config.js
 
# Generate migrations (reads conduct.ts, extracts schema)
npx superfunctions generate
 
# Apply migrations
npx drizzle-kit push

Done! Your app now has /api/conduct/* endpoints and Conduct tables in your database.

See Backend Setup for other frameworks (Hono, Next.js, etc.)

For Teams/AI Agents: Setup CLI

Step 1: Install CLI

npm install -g conduct-cli

Step 2: Initialize Project

In your code repository:

conduct init

This will:

  1. Prompt for backend URL (YOUR app's URL)
  2. Prompt for API key
  3. Create or select a project
  4. Save conduct.config.json
  5. Update agent instruction files

Example:

$ conduct init
 
Backend URL: https://your-app.com/api/conduct
API Key: ck_your_key_123
 
✓ Connected to backend
✓ Project selected: proj_abc123
✓ Configuration saved

AI Agent Workflow

How AI Agents Use Conduct

AI agents don't manually create specs. They use agent templates that guide them through the workflow:

Human: "Add dark mode to settings"
   ↓
AI Agent: Uses template from https://templates.conduct.sh/generate-spec
   ↓
AI Agent: Calls `conduct run start --type spec --agent "Claude"`
   ↓
AI Agent: Generates mdJson (Markdown AST) specification
   ↓
AI Agent: Calls `conduct spec save --json '{"mdJson": ..., ...}'`
   ↓
AI Agent: Calls `conduct run end <run-id>`
   ↓
Done: Spec stored in YOUR database

Agent Templates

AI agents use these templates:

Example: AI Agent Using Templates

<!-- In Claude.md or agent instructions -->
 
When user requests a feature:
 
1. Use @https://templates.conduct.sh/generate-spec
2. Follow the template to:
   - Start run tracking
   - Generate spec with mdJson
   - Save via CLI
   - End run tracking
 
All data gets stored in the backend automatically.

Example AI Agent Workflow

1. Generate Spec

Human: "Add user login feature"

AI Agent (following template):

# Start tracking
$ conduct run start --type spec --agent "Claude Sonnet 4"
Started run: run_abc123
 
# Generate spec JSON (AI creates this)
{
  "mdJson": {
    "type": "root",
    "children": [
      {"type": "heading", "depth": 1, "children": [{"type": "text", "value": "User Login"}]},
      {"type": "paragraph", "children": [{"type": "text", "value": "Implement login with email/password"}]}
    ]
  },
  "intent": "Add user login feature",
  "effort": "simple",
  "requirements": [
    {
      "title": "User can log in with email",
      "mdJson": {"type": "root", "children": [...]}
    }
  ]
}
 
# Save it
$ conduct spec save --json '...'
Created spec: spec_xyz789
 
# Complete tracking
$ conduct run end run_abc123

2. Generate Plan

AI Agent (following template):

$ conduct run start --type plan --spec-id spec_xyz789 --agent "Claude"
$ conduct plan save spec_xyz789 --json '{"tasks": [...]}'
$ conduct run end run_def456

3. Execute

AI Agent implements the code, then:

$ conduct run start --type execution --spec-id spec_xyz789 --task-id task_1 --agent "Claude"
# ... AI writes code ...
$ conduct run end run_ghi789

Verify It's Working

Check Backend

curl https://your-app.com/api/conduct/health

Should return:

{"status": "ok", "version": "0.2.0"}

Check CLI

conduct spec list

Should show your specs.

Check Database

SELECT * FROM specs LIMIT 5;

You'll see mdJson stored in your database.

Next Steps

For Developers

  1. Backend Integration Guide - Framework-specific examples
  2. API Reference - Endpoint documentation
  3. Authentication Setup - Secure your API

For AI Agents

  1. Review agent templates at https://templates.conduct.sh/
  2. Add templates to your agent instructions (CLAUDE.md, WARP.md, etc.)
  3. Start using: @https://templates.conduct.sh/generate-spec

For Teams

  1. CLI Commands Reference - All commands
  2. Profile Management - Multiple backends
  3. Workflow Guide - Best practices

Common Questions

Q: Where is my data stored?
A: In YOUR database as mdJson. No separate storage needed.

Q: Do AI agents use plain markdown?
A: No, they use mdJson (Markdown AST in JSON). Templates handle conversion.

Q: Can I use my existing database?
A: Yes! Conduct creates its own tables alongside your existing ones.

Q: Do I need to deploy Conduct separately?
A: No! It's part of YOUR app. Deploy normally.

Q: How do AI agents know to use templates?
A: You add template URLs to agent instructions (CLAUDE.md, etc.). The conduct init command helps with this.

Need Help?

Previous

Introduction

Next

Installation

On this page