Skip to main content

ADR-048: PILOT Execution Workflow System

Status​

Approved - January 1, 2026

Context and Problem Statement​

The Manual Orchestration Problem​

CODITECT's PILOT project execution has been manually orchestrated using:

  1. Individual Commands - /orient, /which, /agent, /cx, /cxq, /session-log, /classify
  2. Manual Track Management - Human selection of Track A-N tasks
  3. Ad-hoc Session Logging - Inconsistent session documentation
  4. Disconnected Components - Skills, agents, scripts, hooks operating independently

Current State (Manual Orchestration):

User → /orient → Manual task selection → /which → /agent → Manual logging → /cx
      └── Disconnected ──┘                      └── Disconnected ──┘

Target State (Unified Workflow):

User → /pilot → Unified 4-Phase Workflow
                  ├── Phase 1: Session Start (orient, context, discovery)
                  ├── Phase 2: Task Selection (Track nomenclature)
                  ├── Phase 3: Task Execution (agent, verify, classify)
                  └── Phase 4: Session Management (log, capture, checkpoint)

Business Impact​

  • Consistency - Uniform workflow execution across sessions
  • Traceability - Complete audit trail with session logs
  • Efficiency - Reduced cognitive overhead for workflow execution
  • Quality - Enforced verification and documentation steps
  • Autonomy - Foundation for semi-autonomous operation

Decision Drivers​

  1. Workflow Fragmentation - Too many independent commands to coordinate
  2. Session Continuity - Need systematic context preservation
  3. Track Nomenclature - ADR-054 requires consistent application
  4. Agent Coordination - Need systematic agent discovery and invocation
  5. Audit Requirements - Complete execution logging for compliance
  6. MoE Methodology - Need to enforce 5-step task execution process

Considered Options​

Option A: Continue Manual Orchestration​

  • Keep individual commands, rely on human coordination
  • Rejected: Inconsistent, error-prone, not scalable

Option B: Script-Based Automation​

  • Create shell script that chains commands
  • Rejected: Inflexible, no interactive decision points

Option C: Unified Workflow System (Selected)​

  • Create workflow document, command, skill, and ADR
  • Selected: Provides structure while maintaining flexibility

Option D: Full Autonomous Orchestrator​

  • Extend ADR-006 autonomous system
  • Rejected: Premature; need human oversight for PILOT phase

Decision​

Implement Option C: Unified Workflow System with four integrated components:

1. Workflow Document​

File: docs/workflows/PILOT-EXECUTION-WORKFLOW.md

Purpose: Define the complete 4-phase workflow with:

  • Phase 1: Session Start (orientation, context, discovery)
  • Phase 2: Task Selection (Track nomenclature, dependencies)
  • Phase 3: Task Execution (agent, verify, classify)
  • Phase 4: Session Management (log, capture, checkpoint)

2. Command​

File: commands/pilot.md

Purpose: Single entry point for workflow execution:

/pilot              # Full workflow
/pilot --status     # Status check
/pilot --track A    # Track-specific
/pilot --task A.1.1 # Task-specific
/pilot --semi-auto  # Semi-autonomous mode

3. Skill​

File: skills/pilot-execution/SKILL.md

Purpose: Reusable skill definition for:

  • 4-phase process documentation
  • Track nomenclature reference
  • Integration point documentation
  • Error handling patterns

4. ADR (This Document)​

Purpose: Architecture decision record documenting:

  • Context and problem statement
  • Decision rationale
  • Component relationships
  • Success metrics

Architecture​

Component Integration​

┌─────────────────────────────────────────────────────────────────────────┐
│                    PILOT EXECUTION WORKFLOW SYSTEM                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌──────────────────────────────────────────────────────────────────┐  │
│   │                         /pilot COMMAND                            │  │
│   │  Entry point for unified workflow execution                       │  │
│   └──────────────────────────┬───────────────────────────────────────┘  │
│                              │                                           │
│                              ▼                                           │
│   ┌──────────────────────────────────────────────────────────────────┐  │
│   │                    pilot-execution SKILL                          │  │
│   │  Reusable skill with 4-phase process definition                   │  │
│   └──────────────────────────┬───────────────────────────────────────┘  │
│                              │                                           │
│                              ▼                                           │
│   ┌──────────────────────────────────────────────────────────────────┐  │
│   │              PILOT-EXECUTION-WORKFLOW DOCUMENT                    │  │
│   │  Complete workflow specification with diagrams                    │  │
│   └──────────────────────────┬───────────────────────────────────────┘  │
│                              │                                           │
│              ┌───────────────┼───────────────┐                          │
│              │               │               │                          │
│              ▼               ▼               ▼                          │
│   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                   │
│   │  COMMANDS    │ │   SKILLS     │ │   SCRIPTS    │                   │
│   │  /orient     │ │  moe-task-   │ │  session-    │                   │
│   │  /which      │ │  execution   │ │  orient.py   │                   │
│   │  /agent      │ │  session-    │ │  context-    │                   │
│   │  /cx, /cxq   │ │  logging     │ │  db.py       │                   │
│   │  /session-log│ │              │ │  classify.py │                   │
│   │  /classify   │ │              │ │              │                   │
│   └──────────────┘ └──────────────┘ └──────────────┘                   │
│                              │                                           │
│                              ▼                                           │
│   ┌──────────────────────────────────────────────────────────────────┐  │
│   │                    Track Nomenclature (ADR-054)                   │  │
│   │  Track A-N nomenclature for task identification                   │  │
│   └──────────────────────────────────────────────────────────────────┘  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Track-to-Agent Mapping​

TrackDomainPrimary AgentFallback Agent
ABackend APIbackend-developmentsenior-architect
BFrontend UIfrontend-react-typescript-expertgeneral-purpose
CDevOpsdevops-engineercloud-architect
DSecuritysecurity-specialistcoditect-adr-specialist
ETestingtesting-specialistcodi-qa-specialist
FDocumentationcodi-documentation-writerqa-reviewer
GDMS Integrationprompt-analyzer-specialistgeneral-purpose
HFrameworksenior-architectorchestrator
IUI Componentsfrontend-react-typescript-expertgeneral-purpose
JMemorysenior-architectmemory-context-agent
KWorkflowdevops-engineergeneral-purpose
LExtended Testingtesting-specialistgeneral-purpose
MExtended Securitysecurity-specialistgeneral-purpose
NGTM/Launchsenior-architectgeneral-purpose

Execution Modes​

ModeDescriptionHuman Intervention
Interactive (default)Human-guided with agent assistanceFull control
Semi-AutonomousAuto-execute with milestone checkpointsApproval at milestones
Dry-RunPreview without executionNone (read-only)

Success Metrics​

MetricTargetMeasurement
Workflow Adoption100%Sessions using /pilot vs manual
Session Log Coverage100%Significant tasks with log entries
Context Preservation100%Sessions with /cx capture
Classification Rate100%New docs classified
Track CompletionPer planPILOT plan progress

Implementation Checklist​

  • Workflow document (PILOT-EXECUTION-WORKFLOW.md)
  • Command (/pilot in commands/pilot.md)
  • Skill (skills/pilot-execution/SKILL.md)
  • ADR (this document)
  • Integration tests
  • Update PILOT plan with workflow section
  • Update TASKLIST with workflow tasks
  • Training documentation

Consequences​

Positive​

  • Unified Execution - Single command orchestrates entire workflow
  • Consistent Nomenclature - Track A-N applied systematically
  • Complete Audit Trail - Session logs, context capture, checkpoints
  • Agent Optimization - Systematic discovery and matching
  • Foundation for Autonomy - Structured workflow enables future automation

Negative​

  • Learning Curve - Users must learn new /pilot command
  • Overhead - Additional structure for simple tasks
  • Rigidity - Enforced phases may feel constraining

Mitigations​

  • Aliases - /px as shortcut for /pilot
  • Quick Modes - --status, --task X for simple operations
  • Skip Options - Allow phase skipping with --skip-phase

Migration Guide​

From Manual Orchestration​

Before (Manual):

/orient
/cxq --recent 200
/which heartbeat
/agent backend-development "implement heartbeat"
# ... execute ...
/session-log "heartbeat done"
/cx

After (Unified):

/pilot
# Workflow handles all phases automatically
# Human makes decisions at selection points

Gradual Adoption​

  1. Week 1: Use /pilot --status alongside manual workflow
  2. Week 2: Use /pilot for new sessions
  3. Week 3: Full adoption, manual commands for edge cases

Decision: APPROVED Date: 2026-01-01 Author: Hal Casteel, Founder/CEO/CTO, AZ1.AI INC Migration: Migrated from cloud-infra per ADR-150 on 2026-02-03