SOP Engine

Execute Standard Operating Procedures with built-in approval gates, state management, and audit logging.

When to Use

• Run multi-step procedures that require human approval between steps

• Execute complex workflows that span multiple agent sessions

• Track and audit compliance procedures

• Create reusable workflow templates

• Implement approval-required workflows (e.g., deployments, changes)

Concepts

SOP (Standard Operating Procedure)

A defined workflow with:

• Steps: Sequential actions to perform

• Approval Gates: Points where human approval is required

• State: Persisted between steps

• Audit Log: Complete execution history

Execution Modes

• auto

• Execute all steps without approval

• supervised

• Request approval before starting, then execute all steps

• step_by_step

• Request approval before each step

• priority_based

• High priority = auto, Normal/Low = supervised

Triggers

• manual

• Triggered by name

• cron

• Scheduled execution (expression)

• webhook

• HTTP trigger

Installation

No additional installation required. Uses built-in tools: jq , curl , git .

Quick Start

1. Create an SOP

Create sops/my-sop.md :

name: deploy-frontend description: Deploy frontend to staging version: "1.0.0" priority: high execution_mode: supervised triggers:

• type: manual
• type: cron expression: "0 9 * * *"

Deploy Frontend to Staging

Step 1: Build the Project

cd /job && npm run build

Step 2: Run Tests

cd /job && npm test

Step 3: Deploy (requires approval)

echo "Deploying to staging..."

Step 4: Verify

curl -s https://staging.example.com/health

### 2. List Available SOPs
```bash
sop-list

3. Execute an SOP

sop-execute deploy-frontend

4. Approve a Step

sop-approve <run-id>

5. Check Status

sop-status <run-id>

Commands

sop-list

List all available SOPs.

sop-list

sop-execute

Start an SOP execution.

sop-execute <sop-name>
sop-execute <sop-name> --payload '{"key": "value"}'

sop-approve

Approve the next step in a running SOP.

sop-approve <run-id>

sop-reject

Reject and cancel a running SOP.

sop-reject <run-id> --reason "Not ready for deployment"

sop-status

Check the status of an SOP run.

sop-status <run-id>

sop-runs

List all SOP runs (active and completed).

sop-runs
sop-runs --sop <sop-name>

SOP Definition Format

SOPs are defined in markdown files with YAML frontmatter:

---
name: <unique-name>
description: <what this does>
version: "1.0.0"
priority: normal  # low, normal, high, critical
execution_mode: supervised  # auto, supervised, step_by_step, priority_based
triggers:
  - type: manual
  - type: cron
    expression: "0 9 * * *"
  - type: webhook
    path: /webhook/deploy
---

# Title

## Step 1: Description
```bash
command to run

Step 2: Description (requires approval)

another command

## Execution Flow

┌─────────────────┐
│  sop-execute    │
│  (start run)    │
└────────┬────────┘
│
▼
┌────────────┐
│ Auto Mode? │───Yes──► Execute All Steps
└─────┬──────┘              and Complete
│ No
▼
┌────────────┐
│ Supervised │───Wait for──►┌─────────────┐
│   Mode     │    Approval   │sop-approve  │
└─────┬──────┘               └──────┬──────┘
│                              │
▼                              ▼
┌────────────┐               Execute Remaining
│StepByStep │───Wait for──►  Steps One-by-One
│   Mode    │   Approval    with Approval Each
└───────────┘

## State Management

State is persisted in `~/.thepopebot/sop-state/<run-id>.json`:

```json
{
  "run_id": "run-abc123",
  "sop_name": "deploy-frontend",
  "status": "running",
  "current_step": 2,
  "started_at": "2024-01-15T09:00:00Z",
  "payload": {"key": "value"},
  "history": [
    {"step": 1, "status": "completed", "output": "...", "timestamp": "..."},
    {"step": 2, "status": "pending_approval", "output": "...", "timestamp": "..."}
  ]
}

Audit Logging

All SOP executions are logged to ~/.thepopebot/sop-audit/
:

- <run-id>.json
 - Full execution record

- <run-id>.log
 - Step-by-step output

Workflow Examples

Deploy with Approval

---
name: deploy-production
description: Deploy to production with approval
priority: critical
execution_mode: step_by_step
triggers:
  - type: manual
---

# Production Deployment

## Step 1: Run Tests
```bash
npm test

Step 2: Build

npm run build

Step 3: Deploy (APPROVAL REQUIRED)

./deploy.sh production

Step 4: Verify

curl -s https://production.example.com/health

### Data Processing Pipeline
```markdown
---
name: process-daily-data
description: Daily data processing pipeline
priority: high
execution_mode: auto
triggers:
  - type: cron
    expression: "0 2 * * *"
---

# Daily Data Processing

## Step 1: Fetch Data
```bash
curl -o data/raw.json https://api.example.com/data

Step 2: Transform

node transform.js data/raw.json > data/processed.json

Step 3: Validate

node validate.js data/processed.json

Step 4: Archive

mv data/processed.json archive/$(date +%Y%m%d).json

## Best Practices

1. **Use descriptive step titles** - Makes approval prompts clearer
2. **Keep steps atomic** - Each step should do one thing
3. **Include rollback commands** - For critical operations
4. **Add verification steps** - Always confirm success
5. **Use appropriate modes** - Production = step_by_step, dev = auto
6. **Document prerequisites** - List what needs to be true before execution

## Limitations

- Current implementation uses shell/bash - not all SOPs can be expressed this way
- State is local to the agent - not shared across different agent instances
- Approval requires human intervention via CLI