OpenSpec Agent Workflow Lifecycle

Overview

A four-phase spec-driven development lifecycle integrating OpenSpec with an agent scratchpad system. Agents create change proposals, implement within isolated sessions, output artifacts for human review, and archive approved changes back into the spec source of truth. Includes validation patterns for pre-archive quality gates using SHALL/MUST normative language and Given/When/Then scenarios.

Four-Phase Lifecycle

1. Proposal Phase

Agents or humans create change proposals in openspec/changes/{change-name}/ containing:

• proposal.md — Problem and solution overview
• spec-deltas/ — Changes to existing specs
• tasks.md — Implementation tasks
• validation.md — Acceptance criteria

2. Implementation Phase

Agents work in isolated sessions at .agent-scratchpad/sessions/{session-id}/ per the agent-scratchpad-workspace pattern. Context is prepared beforehand — agents only see the active change folder plus relevant specs. The boundary-guard-hooks enforce these access restrictions.

3. Review Phase

Completed work outputs to .agent-scratchpad/artifacts/{change-name}/ containing implementation code, tests, a summary, and a diff patch. Artifacts require human approval via HumanLayer before proceeding, implementing human-in-the-loop-approval-gates.

4. Archive Phase

After approval, openspec archive {change-name} merges spec deltas into openspec/specs/ and moves the change to openspec/changes/archive/.

Directory Mapping

Directory	Purpose	Git Status
openspec/specs/	Source of truth	Committed
openspec/changes/	Active proposals	Committed, tracked
.agent-scratchpad/sessions/	Agent working state	Gitignored
.agent-scratchpad/context/	Prepared context	Gitignored
.agent-scratchpad/artifacts/	Pending approval	Committed

Validation Patterns

Spec Format Requirements

Each spec uses delta headers (## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements). Each requirement needs:

1. ### Requirement: header with name
2. Description with SHALL or MUST normative language
3. At least one #### Scenario: block with Given/When/Then structure

Pre-Archive Checklist

• openspec validate {change} passes
• All tasks in tasks.md marked complete
• Spec deltas use proper delta format
• Each requirement contains SHALL or MUST language
• Each requirement has at least one Scenario block
• Human approved via HumanLayer

Integration Points

• Context Boundary — agents only see active change + relevant specs (ai-agent-execution-constraints)
• Approval Gate — artifacts require human approval before archive (human-in-the-loop-approval-gates)
• Loop Budget — iteration limits prevent infinite refactoring (ai-agent-execution-constraints)

See Also

• agent-scratchpad-workspace - Isolated workspace pattern used in implementation phase
• agentic-pipeline-orchestration - Pipeline that executes this lifecycle end-to-end
• ai-agent-execution-constraints - Constraints governing agent behavior during implementation
• boundary-guard-hooks - File access enforcement for context boundaries