Agentic Pipeline Orchestration: GTD-to-Archive Workflow

Overview

A five-stage pipeline orchestrator running the full GTD-to-OpenSpec-to-RepoMirror-to-HumanLayer workflow. Each stage is a discrete shell script, and the orchestrator manages state transitions, failure recovery, and resumption across the complete change lifecycle.

Pipeline Stages

Stage	Script	Purpose
SPEC	spec-start.sh	Create or validate OpenSpec change proposal
PREPARE	agent-start.sh	Set up agent context boundaries and session
EXECUTE	ralph.sh	Run agent with loop budget enforcement
APPROVE	artifact-approve.sh	Human review and approval via HumanLayer
ARCHIVE	artifact-approve.sh	Archive approved spec (automatic on approval)

SPEC Stage

Creates a new OpenSpec change or validates an existing one. If a change-id is provided and exists, the pipeline uses that change. If the change-id is new, it creates the change. Without a change-id, it lists existing changes and prompts for selection.

PREPARE Stage

Sets up agent context boundaries by running context-prepare.sh to generate an ALLOWLIST.txt, creating an agent session in .agent-scratchpad/sessions/, and copying relevant specs and sources to the context directory. This is where the boundary-guard-hooks pattern enforces file access rules.

EXECUTE Stage

Runs the RepoMirror agent with a loop budget. Budget exhaustion is expected behavior (not an error). Work is saved to .agent-scratchpad/artifacts/ per the agent-scratchpad-workspace pattern. The ai-agent-execution-constraints govern iteration limits.

APPROVE Stage

Requests human approval via HumanLayer with a configurable timeout (default 5 minutes). Reviews artifacts, sends approval request to the HumanLayer daemon, and waits for a human decision. On approval, the pipeline proceeds to archive. This implements the human-in-the-loop-approval-gates taxonomy.

ARCHIVE Stage

Completes the change lifecycle by moving the approved change from changes/ to specs/, clearing pipeline state on success. This follows the openspec-agent-workflow-lifecycle archive phase.

Configuration

Key environment variables control pipeline behavior:

• REQUIRE_APPROVAL (default: true) — require HumanLayer approval at gates
• APPROVAL_TIMEOUT (default: 300) — seconds to wait for approval
• HUMANLAYER_DAEMON_URL — HumanLayer daemon endpoint

For development or testing, approval can be disabled: REQUIRE_APPROVAL=false ./pipeline.sh --change-id test-feature

Recovery

The pipeline supports resumption from any failed stage via ./pipeline.sh --resume and provides recovery instructions via ./pipeline.sh --recover. State is persisted between stages to enable graceful recovery.

See Also

• agent-scratchpad-workspace - Workspace isolation pattern used in PREPARE and EXECUTE stages
• human-in-the-loop-approval-gates - Approval gate taxonomy implemented in APPROVE stage
• ai-agent-execution-constraints - Loop budgets and execution discipline for EXECUTE stage
• context-refresh-session-state - Session state management across pipeline stages
• openspec-agent-workflow-lifecycle - Spec-driven lifecycle that the pipeline orchestrates