Agentic Engineering Workflow

A lightweight, spec-driven framework for structured AI-assisted software development using GitHub Copilot agents.

No CLI tools. No dependencies. Just agents, skills, and templates that work directly in VS Code.

Philosophy

Traditional AI coding assistants generate code from prompts — but prompts are ephemeral, ambiguous, and don't scale. This framework applies Spec-Driven Development (SDD) principles, extended with an exploration and orchestration layer to handle real-world ambiguity:

• Specifications are the source of truth — code derives from specs, not the other way around
• Exploration before commitment — the Strategist helps navigate ambiguity before locking in a direction
• Enriched prompts over raw requests — the Orchestrator refines your intent before dispatching
• Quality gates, not afterthoughts — QA and Security agents validate against the spec

This workflow is designed to augment engineering teams, not replace them. Humans — tech leads, developers, and Product Owners — remain responsible for direction, decisions, and validation, while agents assist in structuring, refining, and accelerating each phase.

Workflow

  You
   │
   ├──→ Strategist        (explore ideas, write product requirements, own constitution)
   │
   └──→ Orchestrator      (refine intent, enrich context, route)
            │
            ├──→ Strategist    product-requirements.md (epic)
            │
            ├──→ Architect     Spec → Plan → Tasks
            │
            ├──→ Coder         Implement tasks from the plan
            │
            └──→ PR Reviewer   Validate code against the spec
                    │
                    ├──→ QA Agent        (test strategy + quality validation)
                    └──→ Security Agent  (threat model + security review)

Development Phases

Phase	Agent	Output
Ideation	Strategist	Options, trade-offs, open questions
Product Requirements	Strategist	product-requirements.md — epic goal, users, scope, philosophy
Specification	Architect	spec.md — what to build and why (reads product-requirements.md)
Planning	Architect	plan.md — how to build it, phased
Task Breakdown	Architect	tasks.md — executable task list
Implementation	Coder	Code changes, scoped to tasks
Review	PR Reviewer	Spec-traced code review
Quality Gate	QA + Security	Post-implementation validation

Agents

Agent	Role	Invocation
Strategist	Product thinking companion — explores ideas, writes product requirements epics, owns the constitution	Bounce ideas, write epics, refine product direction
Orchestrator	Prompt enricher and router — refines your request and dispatches to the right specialist	Primary entry point for task execution
Architect	Spec and plan generator — produces specifications, implementation plans, and task breakdowns	Design and planning phase
Coder	Implementation agent — executes tasks from the plan with minimal, focused changes	Build phase
PR Reviewer	Code validator — reviews diffs against the spec, plan, and acceptance criteria	Review phase
QA	Quality assurance — validates test strategy, coverage, and acceptance criteria	Post-implementation gate
Security	Security reviewer — threat modeling, OWASP checks, dependency review	Post-implementation gate

Installation

The framework lives in src/. Copy its contents to the right location depending on how you want to use it.

Option A — Repo-level install (per project)

Agents, prompts, and skills apply only to this repository. Recommended for team projects.

# Create target directories and copy
mkdir -p your-repo/.github
cp -r src/agents      your-repo/.github/agents
cp -r src/prompts     your-repo/.github/prompts
cp -r src/skills      your-repo/.github/skills
cp    src/copilot-instructions.md your-repo/.github/copilot-instructions.md
cp -r src/specs/      your-repo/specs

GitHub Copilot picks up agents from .github/agents/, slash commands from .github/prompts/, skills from .github/skills/, and repo instructions from .github/copilot-instructions.md automatically.

Option B — Global install (all your repos)

Agents and skills apply across all repositories on your machine. Useful if you want the framework available everywhere without copying per project.

Agents and skills go to the Copilot user folder:

# Windows (PowerShell)
Copy-Item -Recurse src/agents $env:USERPROFILE\.copilot\agents
Copy-Item -Recurse src/skills $env:USERPROFILE\.copilot\skills
Copy-Item src/copilot-instructions.md $env:USERPROFILE\.copilot\copilot-instructions.md

# macOS / Linux
cp -r src/agents ~/.copilot/agents
cp -r src/skills ~/.copilot/skills
cp    src/copilot-instructions.md ~/.copilot/copilot-instructions.md

Slash commands (.prompt.md files) are a VS Code Copilot Chat feature and go to the VS Code user prompts folder:

# Windows (PowerShell)
Copy-Item -Recurse src/prompts/* $env:APPDATA\Code\User\prompts\

# macOS
cp -r src/prompts/* "$HOME/Library/Application Support/Code/User/prompts/"

# Linux
cp -r src/prompts/* ~/.config/Code/User/prompts/

Note: Slash commands are only available in VS Code Copilot Chat. They are not supported in Copilot CLI. Global install does not include specs/ — spec artifacts are always repo-local. Restart VS Code after copying for slash commands to appear in the chat input.

---

After installing, open VS Code Copilot Chat and run /init-sdd to bootstrap your repo.

Using with Codex

Codex works a little differently from Copilot:

• There is no direct equivalent of Copilot .prompt.md slash commands, so /init-sdd should be treated as Copilot-only
• Use the reusable skill at src/skills/init-sdd/SKILL.md for the same bootstrap workflow in Codex
• When working with the specialist flows, explicitly invoke the agent you want, such as @Strategist or @Orchestrator

For setup steps and UX differences, see docs/codex.md.

Getting Started

Pick the path that fits your role:

---

I'm a developer or tech lead

When you're unsure what to build or how to approach it: Open @Strategist and describe your idea. It will help you think it through, challenge assumptions, and eventually write a product-requirements.md epic. You don't need to know the answer — that's the point.

When you're ready to execute: Open @Orchestrator and describe the task. It will check your specs, enrich the context, and route to the right agent — Architect for planning, Coder for implementation, PR Reviewer for review. You don't need to know which agent to call.

Typical flow:

@Strategist  → think → product-requirements.md
@Orchestrator → "build feature X from epic Y" → Architect → spec/plan/tasks
@Orchestrator → "implement task 3" → Coder
@Orchestrator → "review this PR" → PR Reviewer → QA + Security

---

I'm a Product Owner

To think through an epic: Open @Strategist and describe what you want to build and why. It will ask questions, challenge your assumptions, and write a structured product-requirements.md that lives in specs/{epic-name}/. You can use that document as the source of truth for your team.

To draft user stories: With an epic already written, open @Strategist and say something like: "Help me write user stories for specs/my-epic/product-requirements.md." It will work through the epic with you, ask clarifying questions to nail the acceptance criteria, and produce Jira-ready story drafts — title, description, and Given/When/Then AC — that you can copy directly into Jira and refine with Jira AI.

Project Structure

This repo contains the framework source. After installation, your target repo will have a different layout — see below.

Framework source (src/)

src/
├── .github/
│   ├── agents/                          # 7 agent definitions
│   │   ├── orchestrator.agent.md        # Copilot agent definition
│   │   ├── orchestrator.agent.toml      # TOML variant for non-Copilot runtimes
│   │   ├── strategist.agent.md          # Product thinking companion, owns constitution
│   │   ├── strategist.agent.toml        # TOML variant for non-Copilot runtimes
│   │   ├── architect.agent.md           # Specs, plans, and task breakdowns
│   │   ├── architect.agent.toml         # TOML variant for non-Copilot runtimes
│   │   ├── coder.agent.md               # Focused implementation
│   │   ├── coder.agent.toml             # TOML variant for non-Copilot runtimes
│   │   ├── pr-reviewer.agent.md         # Spec-traced code review
│   │   ├── pr-reviewer.agent.toml       # TOML variant for non-Copilot runtimes
│   │   ├── qa.agent.md                  # Quality assurance validation
│   │   ├── qa.agent.toml                # TOML variant for non-Copilot runtimes
│   │   ├── security.agent.md            # Security review and threat modeling
│   │   └── security.agent.toml          # TOML variant for non-Copilot runtimes
│   ├── prompts/                         # Slash commands
│   │   └── init-sdd.prompt.md           # /init-sdd — bootstraps constitution + first epic
│   ├── skills/                          # Reusable knowledge modules
│   │   ├── init-sdd/                    # Tool-agnostic SDD bootstrap skill
│   │   ├── architecture-principles/     # Layering, boundaries, design
│   │   ├── coding-principles/           # Code quality standards
│   │   ├── spec-generation/             # How to write good specs
│   │   ├── task-breakdown/              # How to decompose plans into tasks
│   │   ├── pr-review-checklist/         # Code review checklist
│   │   ├── qa-review-checklist/         # QA validation checklist
│   │   └── security-review-checklist/   # Security review checklist
│   └── instructions/
│       └── copilot-instructions.md      # Global repo-level instructions
└── specs/
    ├── constitution.md                  # Constitution template
    └── templates/                       # Spec templates
        ├── product-requirements.md      # Epic product requirements template
        ├── spec.md                      # Feature specification template
        ├── plan.md                      # Implementation plan template
        └── tasks.md                     # Task breakdown template

Your repo after install

your-repo/
├── .github/                             # Copied from src/.github/
│   ├── agents/
│   ├── prompts/
│   ├── skills/
│   └── instructions/
└── specs/                               # Grows as you build
    ├── constitution.md                  # Filled by /init-sdd (owned by Strategist)
    ├── templates/                       # Copied from src/specs/templates/
    ├── {epic-name}/                     # One folder per epic (Strategist only)
    │   └── product-requirements.md
    └── {feature-name}/                  # One folder per feature (Architect only)
        ├── spec.md
        ├── plan.md
        └── tasks.md

Feature specs in practice

Epics and features live in separate folders under specs/. The Strategist owns epic folders; the Architect owns feature folders. Multiple features can belong to the same epic — each in its own folder, each on its own branch:

# Strategist writes the epic first (branch: epic/user-onboarding):
specs/
├── constitution.md                    ← shared, owned by Strategist
├── templates/                         ← shared, rarely changes
└── epic-user-onboarding/              ← epic folder, Strategist only
    └── product-requirements.md

# Dev A works on a feature (branch: feature/signup-flow):
specs/
└── feat-signup-flow/                  ← feature folder, Architect only
    ├── spec.md                        ← reads epic product-requirements.md for context
    ├── plan.md
    └── tasks.md

# Dev B works on another feature in the same epic (branch: feature/email-verification):
specs/
└── feat-email-verification/           ← separate feature folder, no conflict with Dev A
    ├── spec.md
    ├── plan.md
    └── tasks.md

Epic folders and feature folders are fully independent. Multiple developers can build features from the same epic simultaneously with zero conflicts. The only shared files (constitution.md, templates/) change infrequently — treat them like project config.

Key Concepts

Constitution

A project-level document (specs/constitution.md) that defines the project's principles, intent, tech stack, and coding standards. All agents reference it. Owned by the Strategist — only updated when explicitly asked. Generated automatically by /init-sdd on first use.

Product Requirements

An epic-level artifact (specs/{epic-name}/product-requirements.md) written by the Strategist after exploring an idea with the team. It captures the problem, users, scope, and philosophy of an epic — in human language, not technical specs. POs use it to write Jira stories. The Architect reads it when generating a technical spec.

Spec-Driven Development

The pipeline: idea → product-requirements.md → spec.md → plan.md → tasks.md → code. Each artifact feeds the next. When requirements change, you update product-requirements.md and regenerate downstream — not the other way around.

Enriched Prompts

The Orchestrator doesn't just route — it refines your request with context, constraints, and scope before handing off. This produces better results from every downstream agent.

Quality Gates

QA and Security agents act as quality gates, typically post-implementation, validating the solution against the spec and identifying gaps before the work ships.

Acknowledgements

Inspired by:

• Spec Kit — Spec-Driven Development methodology and templates
• SDLC Guardian Agents — Quality gate enforcement across the SDLC

License

MIT