Copilot Local Architecture — metrics-dashboard

Prompt (slash command)

Hook (system-enforced)

Agent (subagent worker)

Native / always-on

Gap / missing

Repository structure

.github/ — complete configuration

all files present

.github/

◆ copilot-instructions.md always-on ambient context loaded every session — equivalent to CLAUDE.md

▸ prompts/ slash commands, user-invoked

◆ plan_to_build.prompt.md /plan_to_build brainstorm → team composition → exhaustive spec → self-verify → report. Reads project.json for context.

◆ build.prompt.md /build reads spec → dispatches builder + validator subagents sequentially with TDD + rollback

◆ bug_to_pr.prompt.md /bug_to_pr 6-phase local async PR pipeline: triage → fix (plan_to_build + build inline) → PR → adversarial review → merge gate

▸ agents/ subagent workers

◆ builder.agent.md builder implements one task, writes tests first (TDD), verifies with commands, reports completion

◆ validator.agent.md validator read-only verification, runs validation commands, returns PASS / FAIL with actual output

◆ bug-creator.agent.md bug pipeline investigates codebase, reproduces bug, writes JIRA-format report to bugs/BUG-NNN/report.md

◆ bug-router.agent.md bug pipeline read-only classifier — reads report + project.json, outputs JSON routing to correct fixer agent

◆ bug-fixer-backend.agent.md bug pipeline reads bug report, investigates backend code, creates fix plan at specs/fix-NNN.md

◆ bug-fixer-frontend.agent.md bug pipeline reads bug report, investigates frontend code, creates fix plan at specs/fix-NNN.md

◆ bug-fixer-go.agent.md bug pipeline Go module specialist — reads project.json for commands, creates fix plan

◆ bug-fixer-java.agent.md bug pipeline Java module specialist — reads project.json for commands, creates fix plan

◆ bug-reviewer.agent.md bug pipeline adversarial read-only reviewer — 5-point checklist, APPROVE/REJECT verdict posted as gh pr review

▸ hooks/ system-enforced, fires on platform events

◆ hooks.json config wires three events: sessionStart → setup.sh · postToolUse → validator · agentStop → validator

◆ setup.sh sessionStart pip install -r requirements.txt + npm install before every session — no manual setup needed

◆ setup.ps1 sessionStart Windows PowerShell equivalent of setup.sh

▸ validators/

◆ post_tool_validator.py postToolUse ruff on .py · tsc on .ts/.tsx · 7 sections + validator frequency on specs/*.md · 8 sections on bugs/*/report.md · CI bypass

◆ validate_spec.py agentStop final gate — blocks agent from stopping if spec is missing any of the 7 required sections

▸ instructions/ always-on scoped rules

◆ team-orchestration.instructions.md applyTo: specs/** planning-only rules enforced whenever a file in specs/ is in context

◆ project.json config language-agnostic project registry — module paths, test/lint/run commands, fixer agent mappings. All agents read this. Edit once, pipeline adapts.

▸ workflows/ GitHub Actions

◆ ci.yml CI backend lint + test · frontend typecheck + lint + test + build on every PR

◆ copilot-setup-steps.yml cloud agent provisions the GitHub Actions environment before async coding agent starts work

Runtime architecture — local interactive mode

VS Code Copilot — agent mode

synchronous · local · user-driven

flowchart TD DEV([👤 Developer
VS Code]) -->|"/plan_to_build
'add feature X'"| PWT DEV -->|"/bug_to_pr
'describe bug'"| BUG subgraph PREREQ ["🔍 Prerequisites (plan_to_build.prompt.md)"] PWT["Read codebase
read project.json"] --> BRAIN BRAIN["Prerequisite 1:
Explore Before Planning
— one question, multiple choice
— technical approach"] BRAIN --> TEAM_Q TEAM_Q["Prerequisite 2:
Team Composition
— single / two / three builders?
— workstream split?"] end TEAM_Q --> PLAN_WRITE subgraph PLAN_PHASE ["📋 Plan Creation"] PLAN_WRITE["Write spec to
specs/*.md
(exhaustive task descriptions)"] PLAN_WRITE --> VERIFY VERIFY["Step 8: Self-verify
ls -la specs/file.md
grep -c sections = 7"] VERIFY --> HOOK_POST HOOK_POST["postToolUse hook
post_tool_validator.py
— 7 required sections?
— validator frequency?
— ruff / tsc on code files"] end HOOK_POST -->|"PASS → continue
FAIL → block + fix"| REPORT1 REPORT1["Plan report
+ EXECUTION DIRECTIVE
in spec file"] REPORT1 -->|"'execute the plan
in specs/file.md'"| BUILD subgraph BUILD_PHASE ["⚙️ Build Orchestration (build.prompt.md)"] BUILD["Orchestrator
reads spec
builds todo list"] BUILD --> TASK_LOOP subgraph TASK_LOOP ["Task loop — sequential"] BLD["runSubagent
'builder'
TDD preamble
+ task description verbatim"] BLD --> VAL VAL["runSubagent
'validator'
run commands
PASS / FAIL"] VAL -->|"PASS"| NEXT["next task"] VAL -->|"FAIL ≤2"| FIX FIX["runSubagent
'builder'
DEBUG: reproduce→isolate
→root cause→fix"] FIX --> VAL VAL -->|"FAIL >2"| ROLLBACK ROLLBACK["runSubagent
'builder'
git checkout rollback
log + continue"] ROLLBACK --> NEXT NEXT --> BLD end TASK_LOOP -->|"every 3 tasks"| CKPT["Checkpoint
report to user
course-correct?"] CKPT --> TASK_LOOP end BUILD_PHASE --> FINAL_VAL FINAL_VAL["validate-all
runSubagent validator
all commands + criteria
actual output required"] FINAL_VAL --> DONE["Build Complete
task table
actual command output
files changed"] subgraph BUG_PIPE ["🐛 Bug-to-PR Pipeline (bug_to_pr.prompt.md)"] BUG["Phase 0: Setup
BUG-NNN · branch · todo"] --> TRIAGE TRIAGE["Phase 1: Triage
bug-creator → report.md
bug-router → project.json
routes to module fixer"] TRIAGE --> FIX2A FIX2A["Phase 2a: Fix Planning
bug-fixer-{module}
reads report + project.json
writes specs/fix-NNN.md"] FIX2A --> FIX2B FIX2B["Phase 2b: Fix Execution
build protocol inline
builder + validator per task
TDD + rollback same as /build"] FIX2B --> FIX2C FIX2C["Phase 2c: Test Evidence
run module test command
capture to bugs/NNN/test-results.md"] FIX2C --> PR_CREATE PR_CREATE["Phase 3: PR Creation
gh pr create
gh pr comment → bug report
branch: fix/bug-NNN"] PR_CREATE --> REVIEW REVIEW["Phase 4: Adversarial Review
reviewer-alpha (isolated)
reviewer-beta (isolated)
hold verdicts in memory"] REVIEW --> MERGE_GATE MERGE_GATE["Phase 5: Merge Gate
gh pr review --approve/--request-changes
both approve → ask user
reject → fix cycle ≤2 → retry"] end BUG_PIPE --> PR_ARTIFACT["PR Artifact
bug report as comment
alpha verdict as review
beta verdict as review
test evidence committed"] subgraph HOOKS ["🪝 Hooks — system-enforced (hooks.json)"] H1["sessionStart
setup.sh
pip install + npm install"] H2["postToolUse
post_tool_validator.py
ruff / tsc / spec 7 sections
bug report 8 sections
CI bypass flag"] H3["agentStop
validate_spec.py
7 sections check"] end style DEV fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style PREREQ fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style PWT fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style BRAIN fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style TEAM_Q fill:#edf2fb,stroke:#2a5fa5,color:#7a7468 style PLAN_PHASE fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style PLAN_WRITE fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style VERIFY fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style HOOK_POST fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style REPORT1 fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style BUILD_PHASE fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a style BUILD fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a style TASK_LOOP fill:#f0ecfc,stroke:#6450b4,color:#1a1a1a style BLD fill:#f0ecfc,stroke:#6450b4,color:#1a1a1a style VAL fill:#f0ecfc,stroke:#2d7a4f,color:#1a1a1a style NEXT fill:#f0ecfc,stroke:#6450b4,color:#7a7468 style FIX fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style ROLLBACK fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style CKPT fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style FINAL_VAL fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style DONE fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style BUG_PIPE fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style BUG fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style TRIAGE fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style FIX2A fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style FIX2B fill:#f0ecfc,stroke:#6450b4,color:#1a1a1a style FIX2C fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style PR_CREATE fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style REVIEW fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style MERGE_GATE fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style PR_ARTIFACT fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style HOOKS fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style H1 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468 style H2 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468 style H3 fill:#fdf6e3,stroke:#b08a2e,color:#7a7468

Prompt internals — embedded engineering philosophy

📋 plan_to_build.prompt.md

Explore Before Planning
technical approach — one question, multiple choice

Team Composition
single / two / three builders, workstream split

Task Quality Rules
2-5 min tasks, ≥50 word descriptions, design assertions

Intermediate Validators rule
1-5 builders→1 val / 6-10→2 / 11+→1 per 5

Self-Audit Before Saving
count builders, validators, descriptions, assertions

Step 8: Mandatory verify
ls + grep -c = 7 before reporting

EXECUTION DIRECTIVE in spec
FORBIDDEN: direct implementation by main agent

⚙️ build.prompt.md

TDD preamble
RED-GREEN-REFACTOR, test first is mandatory

Systematic debugging
reproduce → isolate → root cause → fix. No random changes.

Verification before completion
never say done without actual command output

Safe rollback
git checkout on 2 failed fix cycles, never leave broken code

Batch checkpoints
pause every 3 tasks, user can course-correct

NEVER rules
no self-implementation, no skipping validation, no silent failures

🪝 hooks.json — three events

sessionStart → setup.sh
pip install -r requirements.txt
npm install (if no node_modules)

postToolUse → post_tool_validator.py
.py → ruff check (lint)
.ts/.tsx → tsc --noEmit (types)
specs/*.md → 7 sections + validator frequency

agentStop → validate_spec.py
final gate: all 7 required sections present
blocks if spec incomplete before agent stops

🐛 bug_to_pr.prompt.md

Setup
BUG-NNN · branch fix/bug-NNN · mkdir bugs/ · todo list

Triage
bug-creator → 8-section report · bug-router reads project.json → routes to fixer

Fix (nested orchestration)
2a fixer creates spec · 2b build protocol inline · 2c test evidence captured

PR + Artifacts
gh pr create · bug report as pr comment

Adversarial Review
alpha + beta isolated · verdicts in memory until both done · gh pr review

Merge Gate
both approve → user confirms → gh pr merge · reject → fix cycle ≤2

Engineering philosophy — skills embedded in prompts

Skills → Prompt embedding traceability matrix

deterministic enforcement

Skill	Embedded In	Enforcement	Key Rule
brainstorming	plan_to_build → Prerequisite 1	prompt	one question at a time, multiple-choice preferred
team-composition	plan_to_build → Prerequisite 2	prompt	single / two / three builders, skip if user specified
writing-plans	plan_to_build → Task Quality Rules	prompt + hook	≥50 word descriptions, 2-5 min task size
plan-reviewer	plan_to_build → Self-Audit	prompt	count builders/validators, check every criterion
test-driven-development	build → builder preamble · bug_to_pr Phase 2b	prompt	RED-GREEN-REFACTOR, test first mandatory
terminal-discipline	build → builder preamble	prompt	note long durations, read full output
systematic-debugging	build → fix cycle dispatch · bug_to_pr Phase 2b	prompt	reproduce → isolate → root cause → fix
verification-before-completion	build → validator dispatch + report	prompt	never say PASS without actual output
safe-rollback	build → exhausted fix cycle handler	prompt	git checkout rollback, verify with git diff
executing-plans	build → batch checkpoint rule	prompt	pause every 3 tasks, report progress
spec section check	post_tool_validator.py	SYSTEM	7 sections required, blocks write if missing
validator frequency	post_tool_validator.py	SYSTEM	>5 builders → (builders//5)+1 validators required
dependency auto-install	setup.sh (sessionStart hook)	SYSTEM	pip install + npm install before every session
bug report 8 sections	post_tool_validator.py	SYSTEM	8 sections required in bugs/*/report.md, blocks write if missing
adversarial review isolation	bug_to_pr → Phase 4 protocol	structural + prompt	verdicts held in memory; files not written until both reviewers complete
language-agnostic commands	project.json → all agents read	config-driven	test/lint/run commands per module in one file — no hardcoding in agents
CI bypass	post_tool_validator.py CI env check	SYSTEM	hooks skip in CI=true env — prevents hook loops in cloud agent

Known gaps vs Claude Code

What Copilot local mode cannot do

honest gaps

Feature	Claude Code	Copilot (this setup)
Shared task board	✓ TaskCreate/Update/List on disk	⚠ todo list in orchestrator context only
Agent resume	✓ resume: agentId preserves context	✗ each dispatch is fresh, stateless
Parallel execution	✓ run_in_background: true	✗ sequential only
Agent Teams / SendMessage	✓ peer-to-peer messaging	✗ not available
Tool restriction in agents	✓ disallowed-tools frontmatter	⚠ tools: field exists but names undocumented — using instructions only
Native OTel traces	✓ metrics + events via OTLP	✗ session logs only, no distributed traces
Spec compensates for	runtime orchestration	airtight exhaustive descriptions

GitHub Copilot Local Architecture