Agentic Development Workflow (OpenSpec + Multi-Agent)

This repository contains our standard multi-agent coding workflow. It uses Atlas as an orchestrator, specialized subagents for implementation, and OpenSpec for token-efficient state management.

By leveraging OpenSpec, we prevent context bloat and ensure our AI assistants stay focused and reliable, even in massive or multi-repository codebases.

Why This Workflow?

Copilot + OpenSpec vs. Copilot Alone Using Copilot by itself is excellent for autocomplete and isolated scripts, but it suffers from "context amnesia" on larger features. Without a plan, the AI easily drifts from your original requirements. OpenSpec gives Copilot a persistent, file-based memory. By anchoring the AI to concrete artifacts (proposal.md, design.md, tasks.md, and delta specs), it stays strictly aligned with your architecture and intent throughout the entire development lifecycle.

The Multi-Agent Advantage A single AI agent trying to act as the planner, software engineer, and code reviewer simultaneously will quickly exhaust its context window and make mistakes. A multi-agent workflow divides labor to keep context windows small and code quality high. OpenSpec acts as the shared state layer for these agents. Atlas orchestrates, Prometheus writes the plan, Sisyphus implements, and Cerberus reviews. They pass state back and forth seamlessly via the openspec/ directory without stepping on each other's toes.

Meet the Agents

Agent	Role	Model	Invoked By
Atlas	Orchestrator	Claude Opus 4.6	User (entry point)
Prometheus	Planner	Claude Opus 4.6	Atlas
Oracle	Researcher	Claude Opus 4.6	Prometheus
Hermes	Scout	GPT-5.2-Codex	Prometheus
Sisyphus	Backend Implementer	GPT-5.2-Codex	Atlas
Vitruvius	GUI Implementer	GPT-5.2-Codex	Atlas
Cerberus	Reviewer	GPT-5.2-Codex	Atlas

Agents marked user-invokable: false (Oracle, Hermes, Sisyphus, Vitruvius, Cerberus) are hidden from the VS Code agent picker and can only be invoked as subagents.

Delegation hierarchy:

• Atlas → Prometheus, Sisyphus, Vitruvius, Cerberus
• Prometheus → Hermes, Oracle

Workflow Architecture

flowchart TD
    classDef user fill:#6366F1,stroke:#4F46E5,stroke-width:2.5px,color:#fff
    classDef orch fill:#1D4ED8,stroke:#1E3A8A,stroke-width:2px,color:#fff
    classDef plan fill:#7C3AED,stroke:#6D28D9,stroke-width:2px,color:#fff
    classDef scout fill:#A78BFA,stroke:#8B5CF6,stroke-width:1.5px,color:#fff
    classDef impl fill:#059669,stroke:#047857,stroke-width:2px,color:#fff
    classDef gate fill:#D97706,stroke:#B45309,stroke-width:2px,color:#fff
    classDef cli fill:#0F172A,stroke:#475569,stroke-width:1.5px,color:#CBD5E1
    classDef store fill:#1E293B,stroke:#475569,stroke-width:1.5px,color:#CBD5E1
    classDef stop fill:#DC2626,stroke:#B91C1C,stroke-width:2px,color:#fff
    classDef done fill:#16A34A,stroke:#15803D,stroke-width:2.5px,color:#fff

    U(["User"]):::user -->|Feature Request| A1

    subgraph P1 ["PHASE 1 — PLANNING"]
        A1["Atlas"]:::orch
        A1 --> S1[/"openspec status --json"/]:::cli
        A1 ==>|Delegate + full context| Prom["Prometheus"]:::plan
        Prom --> S2[/"openspec instructions --json"/]:::cli
        S2 -.->|"template, deps, outputPath"| Prom
        Prom -.->|Parallel| Herm["Hermes"]:::scout
        Prom -.->|Parallel| Orac["Oracle"]:::scout
        Herm -.->|files + usages| Prom
        Orac -.->|deep analysis| Prom
        Prom ==>|Schema-driven writes| Store[("openspec/changes/")]:::store
        Store --> S3[/"openspec validate"/]:::cli
    end

    S3 --> Rev(["STOP — Review Artifacts"]):::stop
    Rev ==> A2

    subgraph P2 ["PHASE 2 — EXECUTION LOOP"]
        A2["Atlas"]:::orch
        A2 -->|Every iteration| S4[/"openspec instructions apply --json"/]:::cli
        S4 -.->|"contextFiles, progress, taskList"| A2
        A2 ==>|"task + contextFiles"| Decide{"Backend or GUI?"}
        Decide -->|core| Sis["Sisyphus"]:::impl
        Decide -->|UI| Vit["Vitruvius"]:::impl
        Sis ==>|summary| Cerb["Cerberus"]:::gate
        Vit ==>|summary| Cerb
        Cerb -.->|NEEDS_REVISION| Decide
        Cerb ==>|"APPROVED"| TM[("tasks.md")]:::store
        TM --> Com(["STOP — User Commits"]):::stop
        Com -->|Loop| A2
    end

    A2 -->|All tasks done| A3

    subgraph P3 ["PHASE 3 — COMPLETION"]
        A3["Atlas"]:::orch --> S5[/"openspec archive"/]:::cli
        S5 --> Specs[("openspec/specs/")]:::store
    end

    Specs ==> Done(["Feature Delivered"]):::done

Loading

Reading the diagram: Rectangles are agents, color-coded by role: blue orchestrator, purple planner, light purple research, green implementers, amber reviewer. Dark parallelograms are OpenSpec CLI calls. Dark cylinders are persistent state on disk. Pills are user touchpoints: indigo to start, red for mandatory stops, green for delivery. The diamond is Atlas's routing decision. Thick arrows (==>) trace the primary flow; dotted arrows (-.->) show parallel paths and data returns.

Model Configuration

The agent files use the model frontmatter field. How this field behaves depends on your environment:

VS Code Copilot Chat

VS Code supports per-agent model selection. Each agent's model field is respected independently, including for subagents. Subagents that don't specify a model inherit from the parent agent.

The agent files use display names from the VS Code model picker as prioritized arrays with fallbacks:

• Planning agents: ['Claude Opus 4.6', 'Claude Opus 4.5']
• Implementation agents: ['GPT-5.2-Codex', 'GPT-4.1']

The display names must exactly match the model picker. Claude models use spaces (Claude Opus 4.6), Codex models use hyphens (GPT-5.2-Codex).

Copilot CLI

The model frontmatter field is not supported in Copilot CLI. It is silently ignored — all agents fall back to the session default (gpt-4.1).

Use the /model command before invoking Atlas:

/model claude-opus-4.6
@.github/agents/atlas.md build the feature from AILAB-1373.

This sets a single model for Atlas and all subagents in the session. Per-agent model routing is not possible in CLI.

Available Models

Claude Opus 4.6          Claude Opus 4.5          Claude Sonnet 4.5
Claude Sonnet 4          GPT-5.2-Codex            GPT-5.1-Codex-Max
GPT-5.1-Codex            GPT-5.1-Codex-Mini       GPT-5 mini
GPT-4.1                  GPT-4o                   Gemini 3 Pro (Preview)
Gemini 3 Flash (Preview)

Verification

After any session, check the Breakdown by AI model in the usage summary. In VS Code you should see multiple models if per-agent routing is working. In CLI you'll see only the single model set via /model.

Setup Instructions

1. Install and Initialize OpenSpec

npm install -g @fission-ai/openspec
openspec init --tools github-copilot

This creates:

• openspec/config.yaml — project context and rules
• openspec/specs/ — baseline specifications
• .github/prompts/opsx-*.prompt.md — Copilot slash commands (/opsx-propose, /opsx-apply, etc.)
• .github/skills/openspec-*/SKILL.md — cross-tool skill files

These files coexist with .github/agents/ — there are no conflicts. The prompts directory provides standalone OpenSpec slash commands, while the agents directory provides the full orchestrated workflow.

2. Configure Project Context (Recommended)

openspec init generates openspec/config.yaml with context and rules commented out. The workflow works without them — Prometheus can still research the codebase via Hermes/Oracle and generate artifacts from schema templates. However, filling them in is recommended because openspec instructions injects context and rules into every artifact generation request, giving agents your constraints upfront rather than relying on codebase inference alone.

schema: spec-driven
context: |
  Tech stack: Python, CustomTkinter
  Testing: strict TDD with pytest
rules:
  specs:
    - Use Given/When/Then format for scenarios

What to put where:

• context — tech stack, non-obvious constraints, critical conventions. Injected into every request, so keep it concise (50KB limit). Skip anything the AI can infer from reading code.
• rules — per-artifact formatting preferences (e.g., "proposals must include rollback plans"). Only injected for the matching artifact type, so these can be more specific.

3. VS Code Extensions (Recommended)

OpenSpec for Copilot by Atman Dev

• Full spec lifecycle management (create, browse, manage)
• CodeLens task execution with AI chat context injection
• Agents explorer sidebar for .github/agents
• Create GitHub issues from spec changes

OpenSpec by Codder13

• CodeLens "Start task" / "Continue task" buttons in tasks.md
• Auto-injects full context (proposal, design, spec deltas) into AI chat
• Task status indicators (not started, in progress, completed)

Both require an OpenSpec-initialized workspace and GitHub Copilot Chat.

4. Greenfield Projects

1. Initialize your git repository.
2. Run openspec init --tools github-copilot in the root directory.
3. If this will be a multi-repo workspace, create your target directories now.
4. Invoke Atlas (see Running the Workflow).

5. Brownfield Projects

1. Open your workspace at the highest common root.
2. Run openspec init --tools github-copilot at this root level.
3. Update openspec/config.yaml with critical project context.
4. When prompting Atlas, explicitly mention the repositories or folders involved.

Running the Workflow

VS Code (Recommended)

1. Open your workspace in VS Code.
2. Open Copilot Chat (Cmd+Shift+I / Ctrl+Shift+I).
3. Select Atlas from the agent picker dropdown (or type @atlas).
4. Prompt:

   build the feature from AILAB-1373. Use your tools to read the ticket,
   then have Prometheus write the OpenSpec files.
   

5. Atlas runs on its configured model and delegates to subagents, each on their own model.
6. After Phase 1, review the artifacts in openspec/changes/ and approve to continue.
7. Monitor subagent progress in the collapsible tool-call panels in the chat.

Copilot CLI

/model claude-opus-4.6
@.github/agents/atlas.md build the feature from AILAB-1373. Use your tools to read the ticket, then have Prometheus write the OpenSpec files.

CLI-specific note: To avoid triggering global OpenSpec skills in .github/skills/, always address Atlas directly. Avoid typing bare words like "apply" or "propose" in your prompt to Atlas, or the semantic router may hijack the session and run the default OpenSpec skill instead. This is not an issue in VS Code, which routes through the agent picker.

State Management & Session Recovery

How State Flows Through the System

OpenSpec replaces "memory in chat history" with "state in files." No agent needs to remember what happened — they query the filesystem.

During Planning (Phase 1):

openspec new change <name>                              → scaffolds change directory
openspec status --change <name> --json                  → artifact dependency graph
openspec instructions <artifact-id> --change <name> --json → template, dependencies, outputPath

Prometheus writes each artifact using schema-driven templates. The CLI tells it what to write, where, and in what order.

During Implementation (Phase 2):

openspec instructions apply --change <name> --json      → contextFiles, progress, taskList, state

Atlas runs this every loop iteration (not just once). It returns:

Field	Purpose
contextFiles	Exact files the implementer must read (schema-driven, not hardcoded)
progress	{ total: 8, complete: 3, remaining: 5 }
taskList	Each task with its current status
state	"blocked", "all_done", or ready to implement
dynamicInstruction	Schema-specific guidance for the current state

Atlas passes contextFiles to subagents so they load only what's needed. Each subagent gets a fresh context window — no baggage from prior tasks.

The checkpoint cycle:

Atlas queries openspec instructions apply
  → reads state, finds next task
  → Sisyphus/Vitruvius implements (fresh context)
  → Cerberus reviews (fresh context)
  → Atlas updates tasks.md: [ ] → [x]
  → git commit (user approves)
  → loop

Each commit is a recovery point.

Context Window Protection

Mechanism	What It Prevents
Subagent isolation	Each implementer/reviewer starts with a fresh context window
contextFiles from CLI	Subagents read only schema-required files, not everything in the change
Delta specs	Only ADDED/MODIFIED/REMOVED requirements — not full baseline specs
Atlas context hygiene	One-sentence subagent summaries prevent context accumulation
Re-query each iteration	openspec instructions apply gives Atlas fresh state every cycle
Mandatory commit stops	Creates git checkpoints and natural session boundaries

Resuming After Interruption

Step 1 — Assess:

openspec status --change <feature>    # Which artifacts are done?
git status                             # Any uncommitted changes?
git log --oneline -5                   # What was the last commit?

Step 2 — Handle uncommitted work:

Situation	Action
Clean working tree	Safe to resume — all state is in tasks.md
Uncommitted changes, tests pass	git add + git commit, then resume
Uncommitted changes, tests fail	Inspect with git diff HEAD. Fix and commit, or git stash to set aside

Step 3 — Resume in a new chat:

Open a new Copilot Chat, select Atlas, and prompt:

Resume work on <feature-name>. The repo_root is <path>.

Atlas will:

1. Run openspec status --change <feature-name> --json to see artifact states.
2. Run openspec instructions apply --change <feature-name> --json to get fresh context.
3. Pick up from the next unchecked task in tasks.md.

No prior conversation history is needed.

Failure Scenarios

Scenario	What Happens	Recovery
VS Code crashes mid-task	Implementer may have written partial files. tasks.md is NOT yet updated (Atlas does that after review).	Check git diff HEAD. If changes look incomplete, git checkout -- . to discard and re-do. If correct, commit and resume Atlas.
LLM stops responding	The in-flight subagent call is lost. No state was corrupted — the task checkbox wasn't updated yet.	Start a new chat and resume Atlas. It will re-attempt the same task.
Context window exhausted	Atlas may degrade (forget feature name, skip steps).	The re-query on each loop iteration re-grounds Atlas. If you notice degradation, commit current work and start a fresh session.
Phase 1 interrupted	Some artifacts may be missing.	Run openspec status --change <feature>. Re-invoke Atlas — it checks status and re-delegates to Prometheus for remaining artifacts.
Network disconnection	Same effect as a crash.	Check git status + openspec status, commit valid work, resume.
Cerberus rejects a task	Atlas receives NEEDS_REVISION.	Atlas should re-invoke the implementer with revision notes. If it doesn't (session died), resume Atlas — it will see the task is still [ ] and retry.

Manual Intervention

You can always interact with OpenSpec state directly:

openspec status --change <feature>                        # Check progress
openspec instructions apply --change <feature> --json     # See compiled implementation context
openspec validate <feature>                               # Check artifact quality
openspec archive <feature>                                # Skip to completion

Edit tasks.md by hand to reorder, add, remove, or check off tasks. The agents treat it as the source of truth — manual edits are respected on next resume.

Observability & Tracking

VS Code

• Subagent panels: Each subagent invocation appears as a collapsible tool call in the chat. Expand to see its full tool calls, prompts, and results.
• Chat Diagnostics: Run Copilot: Show Chat Diagnostics from the command palette to verify which agents are loaded, their configured models, and any errors.
• Extension sidebar: If the OpenSpec for Copilot extension is installed, the sidebar shows active changes, artifact status, and task progress.

OpenSpec CLI

These commands work in both VS Code's integrated terminal and standalone terminals:

Command	What It Shows
openspec status --change [feature]	Artifact states: complete, ready, or blocked
openspec status --change [feature] --json	Machine-readable JSON for programmatic use
openspec validate [feature]	Syntax and formatting errors in artifacts
openspec list --json	All active and archived changes
openspec view	Interactive terminal dashboard
openspec instructions apply --change [feature]	Compiled prompt that implementers receive

Git

• git diff / git status — see what implementer agents modified before Cerberus approves.
• Atlas pauses for a user-approved commit after each task, giving a clean checkpoint.
• openspec/changes/<feature>/tasks.md is the single source of truth: [x] = done, [ ] = pending.

Post-Session Checklist

1. Check the usage summary for model breakdown.
2. Run openspec status --change <feature> to verify all artifacts reached complete.
3. Review tasks.md — all boxes should be checked.
4. Run openspec archive <feature> (or let Atlas handle it in Phase 3).

File Structure

.github/
  agents/                          # Custom Copilot agents (this workflow)
    atlas.md                       #   Orchestrator
    prometheus.md                  #   Planner
    oracle.md                      #   Researcher (subagent)
    hermes.md                      #   Scout (subagent)
    sisyphus.md                    #   Backend implementer (subagent)
    vitruvius.md                   #   GUI implementer (subagent)
    cerberus.md                    #   Reviewer (subagent)
  prompts/                         # OpenSpec slash commands (generated by openspec init)
    opsx-propose.prompt.md         #   /opsx-propose
    opsx-apply.prompt.md           #   /opsx-apply
    opsx-explore.prompt.md         #   /opsx-explore
    opsx-archive.prompt.md         #   /opsx-archive
  skills/                          # OpenSpec cross-tool skills (generated)
    openspec-propose/SKILL.md
    openspec-apply-change/SKILL.md
    ...
  readme.md                        # This file
openspec/
  config.yaml                      # Project context, rules, schema
  specs/                           # Archived baseline specifications
  changes/                         # Active feature work
    <feature-name>/
      proposal.md                  #   Intent and scope
      design.md                    #   Technical architecture
      tasks.md                     #   Implementation checklist
      specs/<domain>/spec.md       #   Delta specifications