Package Exports

conduct-cli
conduct-cli/dist/cli/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (conduct-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Conduct

Specification management for AI agents

Conduct v0.2 is a complete rewrite as a modular SDK system that enables AI agents to create, manage, and execute specifications with proper tracking and verification.

Overview

Conduct v0.2 consists of three integrated components:

Backend SDK - Framework-agnostic backend that works with Express, Hono, Next.js, Cloudflare Workers, and more
CLI - Command-line interface for managing specs, plans, and runs
Agent Templates - Workflow guides for AI agents (spec generation, planning, execution, verification)

Components

Backend SDK

The backend is an SDK (similar to better-auth, Auth.js) that consumers integrate into their applications.

Package: conduct-backend (coming to npm)

Features:

Framework-agnostic router using @superfunctions/http
Database adapter pattern via @superfunctions/db
Full API for specs, plans, runs, and admin operations
Authentication and project isolation
Type-safe throughout

Installation:

npm install conduct @superfunctions/db @superfunctions/http-express drizzle-orm postgres

Quick Start:

import { createConductBackend } from 'conduct';
import { drizzleAdapter } from '@superfunctions/db/adapters';
import { toExpressRouter } from '@superfunctions/http-express';

// Consumer sets up adapter
const adapter = drizzleAdapter({ db, dialect: 'postgres' });

// Initialize Conduct SDK
const conduct = createConductBackend({ database: adapter, auth: {...} });

// Mount in Express
app.use('/api/conduct', toExpressRouter(conduct.router));

See Backend README for full documentation.

CLI

Command-line interface for interacting with the Conduct backend.

Package: conduct-cli

Features:

Project initialization with conduct init
Profile management for multiple backends
Spec management (create, update, get, list)
Plan management (create, update, get)
Run tracking (start, end)
Type-safe API client
Interactive prompts

Installation:

npm install -g conduct-cli

Quick Start:

# Initialize project
conduct init

# Create a spec
conduct spec save --json '{...}'

# Create a plan
conduct plan save <spec-id> --json '{...}'

# Track a run
conduct run start --type spec --agent "Claude"
conduct run end <run-id>

See CLI README for full documentation.

Agent Templates

Workflow guides for AI agents to follow standard processes.

Available Templates:

generate-spec - Generate specification from user intent
generate-plan - Create execution plan from spec
execute - Implement tasks from plan
verify-plan - Verify plan quality
verify-execution - Verify implementation
auto - End-to-end automated workflow

Access: https://templates.conduct.sh/{template-name}

See templates-server/ for template content.

Quick Start

For Backend Consumers

Install packages:

npm install conduct @superfunctions/db @superfunctions/http-express drizzle-orm postgres

Set up database:

import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';

const client = postgres(process.env.DATABASE_URL);
const db = drizzle(client);

Initialize Conduct:

import { createConductBackend } from 'conduct';
import { drizzleAdapter } from '@superfunctions/db/adapters';

const adapter = drizzleAdapter({ db, dialect: 'postgres' });
const conduct = createConductBackend({
  database: adapter,
  auth: {
    apiKeys: async (key) => validateApiKey(key),
  },
});

Mount in framework:

import { toExpressRouter } from '@superfunctions/http-express';
app.use('/api/conduct', toExpressRouter(conduct.router));

Run migrations:

npx drizzle-kit generate
npx drizzle-kit push

For CLI Users

Install CLI:

npm install -g conduct-cli

Initialize project:

cd your-project
conduct init

Follow prompts to set up profile and project.

Start using:

conduct spec list
conduct spec save --json '{...}'

For AI Agents

Access template: https://templates.conduct.sh/generate-spec
Follow template instructions
Use CLI commands as directed
Track all work with conduct run start/end

🏗️ Architecture

┌─────────────────────────────────────────────┐
│              AI Agent                        │
│  (Uses CLI + Templates)                      │
└────────────────┬────────────────────────────┘
                 │
                 ├─── CLI Commands
                 │
┌────────────────▼────────────────────────────┐
│         Consumer Application                 │
│  ┌────────────────────────────────────────┐ │
│  │  Framework (Express/Hono/Next.js)      │ │
│  └────────────────┬───────────────────────┘ │
│                   │                          │
│  ┌────────────────▼───────────────────────┐ │
│  │     Conduct Backend SDK                 │ │
│  │  (Router + API Handlers)                │ │
│  └────────────────┬───────────────────────┘ │
│                   │                          │
│  ┌────────────────▼───────────────────────┐ │
│  │  Database Adapter                       │ │
│  │  (Drizzle/Prisma/Kysely)                │ │
│  └────────────────┬───────────────────────┘ │
└───────────────────┼──────────────────────────┘
                    │
         ┌──────────▼─────────┐
         │     Database       │
         │  (Postgres/MySQL)  │
         └────────────────────┘

📊 Data Model

Projects - Root entity representing a project

Specs - Specifications with:

mdJson - Markdown AST content
intent - Original user intent
effort - simple|medium|complex|epic
Multiple requirements

Requirements - Individual testable requirements linked to specs

Tasks - Execution tasks with:

Phase grouping
Links to requirements they fulfill
Implementation details

Runs - Agent operation tracking:

Type: spec|plan|execution|check
Agent name
Start/end timestamps
Links to specs/tasks

🔄 Workflow

1. Generate Spec

conduct run start --type spec --agent "Claude"
# ... agent generates spec JSON ...
conduct spec save --json '{...}'
# Returns: spec_abc123
conduct run end <run-id>

2. Generate Plan

conduct run start --type plan --spec-id spec_abc123 --agent "Claude"
# ... agent generates plan JSON ...
conduct plan save spec_abc123 --json '{...}'
conduct run end <run-id>

3. Execute Tasks

conduct run start --type execution --spec-id spec_abc123 --task-id task_1 --agent "Claude"
# ... implement task ...
conduct run end <run-id>
# Repeat for each task

4. Verify

conduct run start --type check --spec-id spec_abc123 --agent "Claude"
# ... verify all requirements met ...
conduct run end <run-id>

📚 Documentation

Backend SDK: backend/README-v2.md
CLI: cli/README-v2.md
API Reference: backend API docs
Agent Templates: templates-server/templates/
Migration Guide: MIGRATION-v0.1-to-v0.2.md

Contributing

Conduct v0.2 is organized as a monorepo:

conduct/
├── backend/          # Backend SDK
├── cli/              # CLI package
├── templates-server/ # Agent template server
└── docs/            # Documentation

Development Setup

# Clone repo
git clone https://github.com/21nOrg/conduct.git
cd conduct

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Test
pnpm test

Package Scripts

Backend:

cd backend
pnpm build          # Compile TypeScript
pnpm lint           # Type check
pnpm test           # Run tests

CLI:

cd cli
pnpm build          # Compile TypeScript
pnpm lint           # Type check
pnpm test           # Run tests

License

MIT

Examples

Backend Integration Examples

See backend/example-server-v2.ts for:

Express integration
Database setup
Adapter configuration
Authentication

CLI Usage Examples

# Initialize
conduct init

# Manage profiles
conduct config add production
conduct config list

# Work with specs
conduct spec save --file spec.json
conduct spec get spec_abc123
conduct spec list

# Create plans
conduct plan save spec_abc123 --file plan.json
conduct plan get spec_abc123

# Track runs
conduct run start --type spec --agent "Claude Sonnet 4"
conduct run end run_xyz789

Agent Workflow Example

See templates for complete workflows:

Support

Documentation: Check docs first
Issues: Report bugs on GitHub
Questions: Open a discussion on GitHub
Security: Email security@conduct.sh

Built with ❤️ for AI agents by 21nCo

conduct-cli