This is a submission for Weekend Challenge: Passion Edition
📑 Table of Contents
- What I Built
- Demo
- Code
-
How I Built It
- 1. 🗺️ Where it fits in the pipeline
- 2. 🔤 Two core concepts: Track & Wave
- 3. 🛠️ The three skills
- 4. 🔄 The four flows
- 5. ⚙️ The hooks bundle — mechanical guardrails
- 6. 📸 Evidence — proof, not narration
- 7. 🔒 Security & scope control
- 8. 🚀 Speed — fanout, parallel agents, worktrees
- 9. 🔍 Observability — run artifacts & tracing
- 10. 🧠 Design principles
- 11. 🚀 Getting started
- 📚 Companion Reads
- 📖 Sources & further reading
What I Built
Supspec Orchestration is an autonomous agent workflow layer that closes the gap between "I have a task list" and "I have a reviewed, evidenced draft PR waiting for a human."
🔗 Repo: github.com/truongpx396/supspec-orchestration · MIT licensed · ⚠️ under active development — test thoroughly in your own context before production use.
Most AI coding agent demos stop at "look, it wrote code." The hard parts — Did it actually run the tests, or just claim to? Did it stay in scope? Did it leak a secret? Did it burn 500K tokens looping? Is the PR description fact or fiction? — get hand-waved away.
Supspec Orchestration is an opinionated answer to all of those, built by composing rather than reinventing two proven upstream frameworks:
-
SpecKit upstream — produces the
spec → plan → tasksartifacts (the what). - Superpowers downstream — supplies disciplined skills and dispatched subagents (the how: TDD, review, verification).
On top of that, Supspec Orchestration adds the missing middle: reliability, security, speed, and observability — enforced by mechanical hooks, not by trusting the model to behave.
The one rule it never breaks: No self-merge. Ever. Every pipeline terminates at a draft PR. A human owns the merge.
| Dimension | How Supspec Orchestration delivers it |
|---|---|
| Reliable | Phased TDD (RED → freeze → GREEN), two-step verification, separate code review, evidence gate that checks a tree fingerprint |
| Governed | Reviewer subagent cross-checks against SpecKit constitution + Copilot *.instructions.md (security/OWASP, Go, Python, React…) |
| Secure | Scope guard (deny out-of-scope writes), frozen/immutable paths, destructive-op block, secrets sentinel, token & tool-call ceilings |
| Fast | In-session fanout, parallel worker agents, one git worktree per track, dependency-aware waves |
| Observable | One RUN_ID threads branch ↔ PR ↔ commit ↔ run record; hooks emit runs/<RUN_ID>.json with tool calls, trace, and evidence |
Demo
The best live signal of Supspec Orchestration in action is aisat-studio/pull/8 — a real draft PR generated end-to-end by the single-branch-development scaffold flow against the aisat-studio monorepo.
What the PR shows:
-
Task scope: T001–T010a — bootstrapping a three-runtime monorepo (Go 1.23 API, Python 3.12 FastAPI/LangGraph service, React 19/Vite SPA) from a
tasks.md. -
Run ID
2026-07-11T10-04_setup2threads the branch name, PR title, commit trailer, and run record — grep any surface to reconstruct the whole run. - Parallel fan-out in action: the run trace shows 7 parallel read-only Explore subagents fired concurrently at 10:05–10:07Z before scaffold writing began.
- Auto block (hook-observed facts, not model claims): 50 tool calls · 24 files added, 926 insertions across 5 area groups (Makefile, backend-go/, backend-python/, deploy/, frontend/).
- Evidence: compose config parsed ✅, Python manifest loaded (22 deps) ✅, frontend manifest ✅, tsconfig ✅, Go module ✅, Makefile ✅ — all pasted as verified output, not a model summary.
-
Code review with SpecKit-constitution + OWASP cross-check: the reviewer subagent caught 2
CRITICALhardcoded credentials and 2IMPORTANTunpinned image tags before the PR was opened. All findings resolved in commite12d441. -
Compliance table in the Asserted zone: each SpecKit constitution principle and OWASP control verified or waived with a concrete reference (depguard rule,
${VAR:-fallback}pattern, pinned image SHAs,--cov-fail-under=80). -
Scope discipline: 106 speculative
.gitkeepplaceholders for downstream tasks were automatically trimmed — only the 8 directories declared by T001 remain.
📌 This is a draft PR — it demonstrates the Supspec Orchestration stop-at-draft principle. No self-merge.
Code
🌱 Supspec Orchestration 🤖
⚠️ This repo is under active development. Test it thoroughly in your own context before using in production.
Autonomous agent workflows that turn a SpecKit tasks.md into 1 or N evidenced draft PRs —
gated by mechanical hooks, composed from Superpowers. No self-merge. Ever.
This is an orchestration layer sitting on top of SpecKit artifacts (spec/plan/tasks) and Superpowers skills, automating the gap from "I have a task list" to "I have a reviewed, fingerprint-evidenced draft PR waiting for a human."
-
Feed it a
tasks.md— or a spec, or just a list of stories. - It analyzes whether tasks are independent, produces a wave plan, and asks for your confirmation before touching any branch.
- Autonomous agents run in isolated worktrees — scaffold, story, or refactor modes, or a mix.
- Mechanical hooks enforce scope boundaries, evidence freshness, token ceilings, and a secrets scan. Every run is observable and…
How I Built It
1. 🗺️ Where it fits in the pipeline
SpecKit answers "what should we build?" exceptionally well. Superpowers answers "how should the agent build it?" with real discipline. But neither is designed to be the autonomous conductor that:
- Takes a task list and decides which tasks are independent enough to run in parallel.
- Isolates each unit of work so agents can't step on each other.
- Enforces scope, evidence, and budget mechanically — so compliance doesn't depend on the model "remembering" to comply.
- Produces a traceable, resumable, reviewable artifact at the end.
That conductor role is the gap Supspec Orchestration fills.
💡 The core insight: the skills are only as strong as the worker's compliance — unless the gates are mechanical. Supspec Orchestration makes the gates mechanical.
SpecKit hands off a tasks.md after the upstream specify → clarify → plan → tasks stages. Supspec Orchestration turns it into 1 or N draft PRs. A human reviews and merges. Supspec Orchestration never crosses that final line.
2. 🔤 Two core concepts: Track & Wave
Everything in Supspec Orchestration is organized around two primitives:
- Track — a group of related tasks executed as a unit on one isolated branch/worktree, corresponding to one user story or feature slice. A track has an owner (its worker agent), a defined file-ownership scope, and produces exactly one draft PR.
- Wave — a group of tracks that can run in parallel because they have non-overlapping file ownership and no inter-dependencies. Waves are sequential; tracks within a wave are concurrent.
Wave 1: [Track A] [Track B] [Track C] ← all parallel, disjoint ownership
↓ ↓ ↓
PR-A PR-B PR-C
↓ merge queue ↓
Wave 2: [Track D] [Track E] ← parallel, depend on Wave 1
This is why Step 0 of the parallel conductor analyzes dependencies and groups tasks into waves before fanning out any workers — and requires your explicit confirmation. A bad plan is infinitely cheaper to fix before workers run than after.
3. 🛠️ The three skills
| Skill | Role | What it does |
|---|---|---|
| 🌿 single-branch-development (SBD) | Per-branch worker | One feature, bugfix, refactor, or scaffold — end-to-end on a single branch |
| 🪢 executing-parallel-tracks (EPT) | Conductor | N independent tracks concurrently, each in its own worktree |
| 🔁 pr-review-feedback (PRF) | Rework stage | Turn PR review comments into applied, evidenced changes on the existing PR branch |
🌿 single-branch-development
A thin per-branch bracket — isolation before, evidence gate + draft-PR boundary after — wrapped around an execution core with three modes:
| Mode | When | Core sequence |
|---|---|---|
| scaffold | Non-behavioral bootstrap (config, wiring, structure) | dispatch parallel agents → self-review |
| story | Add or change behavior under phased TDD | dispatch RED batch → freeze test API → subagent-driven GREEN |
| refactor | Behavior-preserving keep-green change | pin-green snapshot → freeze baseline → refactor + systematic-debugging on red |
All modes share using-git-worktrees (isolation), verification-before-completion (evidence gate), requesting-code-review (self-review), and the full hooks bundle.
🪢 executing-parallel-tracks
The conductor. Owns isolation, gates, traceability, and integration sequencing — and delegates each track's implement/review/verify to SBD. It opens with a dependency-aware wave analysis (Step 0) that derives a plan and requires your sign-off before spawning any worker.
🔁 pr-review-feedback
The rework stage. Turns a batch of PR review comments into applied, evidenced changes on the existing PR branch — no fresh RED, no new isolate. It reuses the hooks bundle in resume mode and closes with a PR update.
⚖️ Governance built in.
requesting-code-reviewdispatches a reviewer subagent that automatically inherits any.github/instructions/*.instructions.mdwhoseapplyToglob matches the changed files — socode-review-generic.instructions.md(applyTo: '**') is always in scope, and language-specific instructions (Go, Python, React, state-management, security/OWASP) apply whenever the diff touches matching paths. This is the Copilot-instruction cross-check and the SpecKit-constitution compliance gate, wired with zero extra effort.
4. 🔄 The four flows
Every flow terminates at gh pr create --draft. That's the boundary — a human takes it from there.
Flow 1 — Scaffold (non-behavioral bootstrap)
Step 1: track-preflight.sh --persist 🎫 mint RUN_ID, confirm scope
Step 2: using-git-worktrees 🌿 isolate on a branch
Step 3: dispatching-parallel-agents 🤖 parallel scaffold batches (no TDD)
Step 4: requesting-code-review 🔎 self-review quality + governance
Step 5: verification-before-completion 🚦 evidence gate (fingerprint match)
Step 8: gh pr create --draft 📬 stop — human reviews
Flow 2 — Single feature/bugfix (story mode, TDD)
Step 1: track-preflight.sh --persist 🎫 mint RUN_ID, confirm scope
Step 2: using-git-worktrees 🌿 isolate on a branch
Step 3: dispatching-parallel-agents 🤖 RED batch — write failing tests
Step 4: requesting-code-review 🔎 freeze the test API (maker/checker)
Step 5: subagent-driven-development 🤖 GREEN — make tests pass
Step 6: verification-before-completion 🚦 evidence gate (fingerprint match)
Step 7: requesting-code-review 🔎 full self-review
Step 8: gh pr create --draft 📬 stop — human reviews
The two-step verification is visible here: a requesting-code-review gate that freezes the test contract before implementation (Step 4), and a second full requesting-code-review after GREEN (Step 7) — bracketing an verification-before-completion evidence gate in the middle (Step 6).
Flow 3 — Refactor (behavior-preserving, keep-green)
Step 3: dispatching-parallel-agents 🤖 pin-green (snapshot the passing suite)
Step 5: subagent-driven-development 🤖 refactor; systematic-debugging on red
Step 6: verification-before-completion 🚦 evidence gate
...
Flow 4 — Parallel tracks (N stories at once)
Step 0: Analyze & plan waves 📊 derive dependencies, wave plan, CONFIRM
Step 1: track-precheck.sh 🔎 validate manifest + ownership overlap
Step 2: using-git-worktrees (×N) 🌿 one isolated worktree per track
Step 3: dispatching-parallel-agents 🪢 fan out N worker agents
each agent runs single-branch-development (full pipeline per track)
Step N+1: observe run records 📊 triage by RUN_ID
Step N+2: integration sequencing 🔀 PRs ordered by dependency
↓
human reviews N draft PRs → merge queue
5. ⚙️ The hooks bundle — mechanical guardrails
This is what makes Supspec Orchestration reliable rather than hopeful. Copilot agent hooks run shell commands at lifecycle points (PreToolUse, PostToolUse, SubagentStart/Stop, Stop, …) and can block a tool call before it happens. Each script no-ops until its env is set, so dropping the bundle into any repo is safe before you configure anything.
| Script | Fires at | Category | What it does |
|---|---|---|---|
install-hooks.sh |
manual | Lifecycle | 📦 Idempotent, consent-gated, drift-aware installer |
track-preflight.sh |
Step 1 | Lifecycle | 🎫 Mint/recover a stable RUN_ID; check prereqs; persist a resume breadcrumb |
track-reconcile.sh |
SessionStart | Lifecycle | ♻️ Recover state from history + run record; stash untrusted work |
track-guard.sh |
PreToolUse | Scope & guard | 🛡️ Deny edits outside scope, frozen paths, artifacts, or destructive ops |
track-evidence.sh |
PostToolUse | Evidence | 📸 Capture test output + a code fingerprint — what the tool saw, not a claim |
track-meter.sh |
PostToolUse | Governance | 🔢 Count tool calls + heartbeat; hard-stop at TRACK_MAX_TOOL_CALLS
|
track-trace.sh |
SubagentStart/Stop | Observability | 🔍 Record why each subagent was spawned + its stop reason |
track-note.sh |
manual | Observability | 📝 Self-report ordered skill activations + loop counts (provenance-tagged) |
track-sentinel.sh |
Stop | Scope & guard | 🔒 Scan the staged diff for likely secrets / debug leftovers |
track-evidence-gate.sh |
Stop | Evidence | 🚦 Block stop unless evidence is present, fresh, and passing |
track-tokens.sh |
Stop | Governance | 🪙 Estimate token usage; enforce TRACK_MAX_TOKEN_ESTIMATE
|
track-notify.sh |
Stop | Lifecycle | 📣 Best-effort completion webhook |
track-report.sh |
Step 8 | Observability | 📄 Render the deterministic PR-body Auto block from the run record |
🧪 The bundle is regression-tested: 122 SBD tests + 195 EPT tests cover guard allow/deny decisions, evidence freshness, meter hard-stop, trace schema, sentinel matching, token ceilings, and structural checks on the SKILL/hooks docs. The canonical scripts live under
single-branch-development/scripts/;install-hooks.sh --checkdetects drift between source and the installed.github/hooks/copies.
6. 📸 Evidence — proof, not narration
Evidence is what separates "the agent claimed it worked" from "the agent proved it worked." Every run must pass the evidence gate before it can open a PR.
-
track-evidence.shcaptures the test command output plus a SHA fingerprint of the working tree at capture time. -
track-evidence-gate.shatStopchecks: evidence present? fingerprint matches the current tree? all kinds passing? - If the tree changed after capture (stale fingerprint) or evidence is missing → the gate blocks the agent from stopping.
The installer detects repo signals and seeds sensible stack-aware defaults (fully editable):
| Signal | Evidence kind | Example command |
|---|---|---|
go.mod present (auto) |
go-test |
go test -race ./... |
pyproject.toml / uv.lock (auto) |
py |
uv run pytest |
package.json present (auto) |
ts |
tsc --noEmit && npm test |
migrations/ directory (auto) |
pg-explain |
psql -c 'EXPLAIN (ANALYZE, FORMAT JSON) …' |
| NATS producers/consumers (manual) | nats |
nats consumer info <stream> <consumer> |
| Redis interactions (manual) | redis |
redis-cli TTL <key> |
| REST / gRPC contracts (manual) | contract |
buf lint && buf breaking |
| E2E browser tests (manual) | e2e |
npx playwright test |
7. 🔒 Security & scope control
Supspec Orchestration treats the worker agent as an untrusted actor and constrains it at the tool boundary:
-
Controllable scope —
TRACK_ALLOWED_PREFIXES(required; empty = deny all edits) lists exactly which path prefixes a worker may write.track-guard.shdenies everything else atPreToolUse, fail-closed. -
Frozen & immutable paths —
TRACK_FROZEN_PATHS(no worker may edit) andTRACK_IMMUTABLE_PREFIXES(e.g.migrations/— committed files are append-only, never rewritten). -
Destructive-op block —
TRACK_GUARD_DESTRUCTIVE=1denies irreversible shell/DB ops (rm -rf, data-wipe commands). -
Secrets sentinel —
track-sentinel.shscans the staged diff for likely secrets and debug leftovers before handoff. -
Token guard —
TRACK_MAX_TOKEN_ESTIMATEblocks stop and writesstatus=budget-exceededwhen the ceiling is hit. -
Tool-call ceiling —
TRACK_MAX_TOOL_CALLShard-stops a run that loops without progress (status=no-progress). -
No forced pushes by default —
TRACK_ALLOW_FF_PUSHis empty except in thepr-review-feedbackflow that intentionally updates an existing PR branch.
Config precedence is explicit: exported env > per-worktree track-env.sh > repo-wide track-env.base.sh > script default.
8. 🚀 Speed — fanout, parallel agents, worktrees
Reliability without speed is just a slow, careful bottleneck. Supspec Orchestration pulls three levers:
-
In-session fanout —
dispatching-parallel-agentsspawns multiple subagents within a single session to work disjoint file clusters concurrently (e.g. a scaffold's config vs. wiring vs. structure batches). - Parallel tracks — the conductor runs an entire wave of tracks at once, each an independent SBD pipeline, because Step 0 guaranteed their file ownership doesn't overlap.
-
Git worktrees —
using-git-worktreesgives each track its own physical checkout, so parallel agents never race on the working tree, the index, or branch state. Isolation means a real worktree, not just a branch.
The result: N user stories can be in-flight simultaneously, each producing its own evidenced draft PR, then integrated in dependency order.
9. 🔍 Observability — run artifacts & tracing
Every run is independently traceable through one RUN_ID threaded across four surfaces:
| Surface | Example |
|---|---|
| Branch name | track/us1 |
| Draft PR title | track/us1 [run 2026-06-26T14-03_us1] |
| Commit trailer | Run-Id: 2026-06-26T14-03_us1 |
| Run record file | runs/2026-06-26T14-03_us1.json |
Grep any one surface → reconstruct the whole run. runs/summary.md aggregates all tracks for a wave.
The run record (runs/<RUN_ID>.json, gitignored) is populated by hooks — never re-typed by the model:
{
"run_id": "2026-06-26T14-03_us1",
"track": "us1",
"status": "success",
"evidence": { "go-test": "42 passed", "ts": "0 errors" },
"tool_calls": 137,
"token_estimate": 48000,
"trace": [ { "kind": "subagent", "event": "start", "agent_type": "implementer", "reason": "green T038 impl" } ],
"skills": [ { "skill": "subagent-driven-development", "step": "4-green", "self_reported": true } ]
}
A crucial distinction the design never blurs:
-
trace[]= hook-observed subagent events → mechanical facts. -
skills[]= the model's self-reported activations → provenance-tagged claims (self_reported: true).
Statuses (success, blocked, no-progress, budget-exceeded) are all written by hooks, never by the model. The PR body is a two-zone template: an Auto block rendered deterministically by track-report.sh from the run record, and an Asserted block that's the only place the model writes prose.
10. 🧠 Design principles
- Mechanical over prompt-trusted. If a gate can be enforced by a hook, it is. The model complying is secondary.
- Hooks are no-ops until configured. Drop the bundle into any repo — nothing changes until you set env vars.
- Evidence is fingerprinted, not narrated. The gate checks the tree hash, not the agent's summary.
- No self-merge. Every pipeline terminates at a draft PR. A human decides what merges.
-
Observable by
RUN_ID. One stable ID threads branch, PR, commit, and run record. - Confirm before fan-out. Step 0 requires explicit human sign-off on the wave plan before any worker spawns.
11. 🚀 Getting started
Prerequisites: SpecKit installed with a tasks.md; the Superpowers catalog under .github/skills/; git with worktree support; authenticated gh CLI; jq; Docker if any track runs integration suites; Copilot agent hooks enabled (recommended).
# 1️⃣ Copy the .github/skills/ directories into your repo, then install the hooks:
bash .github/skills/single-branch-development/scripts/install-hooks.sh # dry-run
bash .github/skills/single-branch-development/scripts/install-hooks.sh --check # probe for drift
bash .github/skills/single-branch-development/scripts/install-hooks.sh --apply # sync + gitignore runs/ + seed config
# 2️⃣ Configure repo-wide policy defaults
$EDITOR .github/hooks/track-env.base.sh # set TRACK_ALLOWED_PREFIXES, evidence rules, ceilings…
# 4️⃣ Self-test the bundle
bash .github/skills/single-branch-development/tests/test-skill.sh
bash .github/skills/executing-parallel-tracks/tests/test-skill.sh
3️⃣ Invoke a skill — point Copilot at the task and let the skill drive:
- "implement Phase 1 Setup — shared infrastructure (T001–T010a)" → Flow 1 (scaffold)
- "implement Phase 3 User Story 1: ingest knowledge into a searchable library (T035–T056)" → Flow 2 (story/TDD)
- "refactor Phase 2 Foundational — frontend API client (T031) using single-branch-development" → Flow 3 (refactor)
- "execute Phase 3 US1, Phase 4 US2, Phase 5 US3 in parallel using executing-parallel-tracks" → Flow 4 (parallel)
The worker stops at gh pr create --draft. A human owns the merge.
Supspec Orchestration is an opinionated answer to the trust question in agentic coding, built by composing rather than reinventing:
- SpecKit gives it a clear contract to build against.
- Superpowers gives it disciplined skills and subagents to build with.
- Mechanical hooks give it guarantees the model can't talk its way out of.
- A human always owns the merge.
That combination — reliable, governed, secure, fast, observable, and never self-merging — is what turns "I have a task list" into "I have a reviewed, evidenced draft PR" without a human babysitting every step.
📚 Companion Reads
| Document | Why it pairs with this project |
|---|---|
| 📘 Spec Kit vs. Superpowers ⚡ — A Comprehensive Comparison & Practical Guide to Combining Both 🚀 | The two frameworks Supspec Orchestration composes — read this to understand the upstream/downstream split it builds on. |
| 🏗️ Building Production-Grade Fullstack Products with AI Coding Agents | The end-to-end shipping discipline (migrations, PR gates, deploy, monitoring) that Supspec automates. |
| 🏗️ Building High-Quality AI Agents — A Field Guide | The agent-design principles — tool ergonomics, failure modes, guardrails — behind the hooks bundle. |
| 🤖 SWE-agent — Deep Dive & Build-Your-Own Guide | The agent loop (observe → act → check) that each worker track runs. |
| 🎯 The AI Engineer 🤖 Interview Playbook 📖 | Evaluation, verification, and trade-off reasoning — the same rigor Supspec enforces mechanically. |
📖 Sources & further reading
- Supspec Orchestration — github.com/truongpx396/supspec-orchestration (README, SKILL docs, hooks reference).
- SpecKit — github.com/github/spec-kit — GitHub's toolkit for Spec-Driven Development (spec → plan → tasks).
- Superpowers — github.com/obra/superpowers — Jesse Vincent's agentic skills framework (brainstorm → TDD → review → ship).
- Copilot agent hooks — docs.github.com/copilot/concepts/agents/hooks — lifecycle events that make the gates mechanical.
This project is under active development; verify specific flags, env vars, and behavior against the current repo before relying on them.
If you found this helpful, let me know by leaving a 👍 or a comment!, or if you think this post could help someone, feel free to share it! Thank you very much! 😃
Top comments (0)