en
new
0
Avatar
Truong Phung @truong396
755 31 110
Published Thursday, 1:11 p.m. 13 min read
33

🌱 Supspec Orchestration πŸ€– β€” From Spec to Evidenced Draft PRs, Autonomously

πŸ“‘ Table of Contents

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 β†’ tasks artifacts (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.

It runs on either agent surface β€” GitHub Copilot or Claude Code. The hook scripts are surface-agnostic; only the wiring manifest differs, and one installer handles both.

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 SpecKit constitution + matched *.instructions.md explicitly carried into every subagent brief (makers AND reviewer) β€” subagents have isolated context and won't inherit VS Code's injected instructions unless the brief includes the content
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_setup2 threads 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 CRITICAL hardcoded credentials and 2 IMPORTANT unpinned image tags before the PR was opened. All findings resolved in commit e12d441.
  • 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 .gitkeep placeholders 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

{% github truongpx396/supspec-orchestration %}

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:

  1. Takes a task list and decides which tasks are independent enough to run in parallel.
  2. Isolates each unit of work so agents can't step on each other.
  3. Enforces scope, evidence, and budget mechanically β€” so compliance doesn't depend on the model "remembering" to comply.
  4. 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.

Image description

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 β€” and explicitly passed through. Subagents have isolated context: they do not automatically inherit .github/instructions/*.instructions.md files β€” under Copilot/VS Code those are auto-injected into the main session by applyTo glob but not into subagents, and Claude Code has no applyTo auto-injection at all. Either way, governance is a two-stage obligation:

  1. Discovery (Step 4 / pre-code gate). The orchestrator collects the governance set: relevant SpecKit constitution principles + every .github/instructions/*.instructions.md whose applyTo glob matches the files the task will touch (code-review-generic.instructions.md with applyTo: '**' is always included; language-specific ones β€” Go, Python, React, state-management, security/OWASP, backing-services, devops-cicd β€” apply when the diff touches matching paths).

  2. Explicit passthrough into every subagent brief. When invoking subagent-driven-development (GREEN implementers) or dispatching-parallel-agents (RED authors, scaffold makers), the orchestrator embeds the full text of the collected constitution excerpts + instructions into each subagent's brief β€” not just a filename reference, which would be an empty pointer. A brief that names a file without its content is ignored. Each maker must satisfy the governance constraints while implementing, so the reviewer's role is a backstop, not the first application.

For frontend task clusters, the brief also carries the relevant design artefacts (.stitch/designs/<page>.html mock and/or design-system/ page spec, if they exist), so makers and test-RED authors assert the approved design intent rather than generating UI from inference.

This is the Copilot-instruction cross-check and the SpecKit-constitution compliance gate β€” wired end-to-end, not just at review.

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)

Skill: single-branch-development in scaffold mode

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)

Skill: single-branch-development in story mode

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)

Skill: single-branch-development in refactor mode

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)

Skill: executing-parallel-tracks + NΓ— single-branch-development

Step 0: Analyze & plan waves           πŸ“Š derive dependencies, wave plan, CONFIRM
Step 1: track-wave-preflight.sh        🌊 mint WAVE_ID + per-track RUN_IDs, persist wave dispatch
        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 (wave prefix β†’ all tracks visible)
Step N+2: integration sequencing       πŸ”€ PRs ordered by dependency
Step 7:   track-wave-preflight.sh --complete  🏁 close wave dispatch (final_status)
        ↓
human reviews N draft PRs β†’ merge queue

5. βš™οΈ The hooks bundle β€” mechanical guardrails

This is what makes Supspec Orchestration reliable rather than hopeful. Agent hooks β€” Copilot agent hooks or Claude Code 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.

πŸ”Œ One bundle, two surfaces. The track-*.sh scripts are surface-agnostic: they read both platforms' stdin JSON (tool_name, tool_input.file_path / notebook_path / command, hook_event_name) and emit both permission contracts (hookSpecificOutput.permissionDecision:"deny" on PreToolUse, {decision:"block", reason} on Stop). Only the wiring manifest differs β€” .github/hooks/track-hooks.json for Copilot, .claude/settings.json for Claude Code β€” and the same installer wires either or both: install-hooks.sh --surface {copilot|claude|both} (default both).

Script Fires at Category What it does
install-hooks.sh skill-invoked (setup) Lifecycle πŸ“¦ Idempotent, consent-gated, drift-aware installer
track-preflight.sh skill-invoked (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 (Copilot) Β· SubagentStop (Claude Code) Observability πŸ” Record why each subagent was spawned + its stop reason
track-note.sh skill-invoked (each core step) 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 skill-invoked (Step 8) Observability πŸ“„ Render the deterministic PR-body Auto block from the run record
track-wave-preflight.sh skill-invoked (EPT Step 1 + 7) Lifecycle 🌊 Mint/recover wave dispatch breadcrumb (runs/<wave-id>.wave.dispatch); derive per-track RUN_IDs as <wave-id>_<track-id>; close wave at Step 7

⚠️ Two Claude Code deltas. (1) There is no SubagentStart event β€” only SubagentStop, whose payload carries no agent_type/reason. So under Claude Code, trace[] still counts subagent boundaries and stamps the heartbeat, but the spawn-reason column is Copilot-only. (2) VS Code auto-injects .github/instructions/* by applyTo glob; Claude Code doesn't. That's a no-op for correctness β€” the Step 4 pre-code gate already mandates reading the matched instruction files in-session, so governance is driven by the skill body, not by editor auto-injection. Also: Claude Code blocks a stop only on exit 2, which is why track-tokens.sh exits 2 (still non-zero, so Copilot blocks on it too).

πŸ§ͺ 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 --check detects 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.

  1. track-evidence.sh captures the test command output plus a SHA fingerprint of the working tree at capture time.
  2. track-evidence-gate.sh at Stop checks: evidence present? fingerprint matches the current tree? all kinds passing?
  3. 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.sh denies everything else at PreToolUse, fail-closed.
  • Frozen & immutable paths β€” TRACK_FROZEN_PATHS (no worker may edit) and TRACK_IMMUTABLE_PREFIXES (e.g. migrations/ β€” committed files are append-only, never rewritten).
  • Destructive-op block β€” TRACK_GUARD_DESTRUCTIVE=1 denies irreversible shell/DB ops (rm -rf, data-wipe commands).
  • Secrets sentinel β€” track-sentinel.sh scans the staged diff for likely secrets and debug leftovers before handoff.
  • Token guard β€” TRACK_MAX_TOKEN_ESTIMATE blocks stop and writes status=budget-exceeded when the ceiling is hit.
  • Tool-call ceiling β€” TRACK_MAX_TOOL_CALLS hard-stops a run that loops without progress (status=no-progress).
  • No forced pushes by default β€” TRACK_ALLOW_FF_PUSH is empty except in the pr-review-feedback flow 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-agents spawns 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-worktrees gives 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 SBD standalone (Flows 1–3) EPT wave track (Flow 4)
Branch name track/us1 track/us1
Draft PR title track/us1 [run 2026-07-20T14-03_us1] track/us1 [run 2026-07-20T11-30_wave1_us1]
Commit trailer Run-Id: 2026-07-20T14-03_us1 Run-Id: 2026-07-20T11-30_wave1_us1
Run record file runs/2026-07-20T14-03_us1.json runs/2026-07-20T11-30_wave1_us1.json

When invoked via EPT, track-wave-preflight.sh derives each track's RUN_ID as <WAVE_ID>_<track-id> β€” so the wave membership is visible in every filename and log line. Standalone SBD runs mint their own <UTC-timestamp>_<track-id> with no wave prefix.

Grep any one surface β†’ reconstruct the whole run. runs/summary.md aggregates all tracks for a wave.

Two artifact tiers per wave (EPT). One wave with 3 tracks produces 4 files sharing the same WAVE_ID prefix β€” ls runs/*wave1* shows the complete fleet state at a glance:

runs/2026-07-20T11-30_wave1.wave.dispatch      ← orchestrator breadcrumb (track-wave-preflight.sh)
runs/2026-07-20T11-30_wave1_us1.json           ← per-track run record
runs/2026-07-20T11-30_wave1_us2.json
runs/2026-07-20T11-30_wave1_us3.json

Per-track breadcrumb (runs/<RUN_ID>.dispatch) β€” produced by single-branch-development (track-preflight.sh). Written at Step 1 (--persist), closed at Step 8 (--complete). Exists for every SBD run, whether standalone or EPT-dispatched. Enables resume: if the session is interrupted, track-reconcile.sh finds this file and rebuilds position without re-minting a new ID.

Standalone SBD run (Flows 1–3) β€” plain <timestamp>_<track-id> format, no wave prefix:

{
  "run_id": "2026-07-20T14-03_us1",
  "track": "us1",
  "branch": "track/us1",
  "scope": "internal/ingest/:migrations/0007_",
  "toolchain": "go,uv",
  "evidence_floor": "go-test",
  "completed_utc": null
}

EPT-dispatched track (Flow 4) β€” RUN_ID carries the wave prefix, derived by track-wave-preflight.sh:

{
  "run_id": "2026-07-20T11-30_wave1_us1",
  "track": "us1",
  "branch": "track/us1",
  "scope": "internal/ingest/:migrations/0007_",
  "toolchain": "go,uv",
  "evidence_floor": "go-test",
  "completed_utc": null
}

Wave dispatch (runs/<WAVE_ID>.wave.dispatch) β€” produced by executing-parallel-tracks (track-wave-preflight.sh). Written before fan-out and closed by --complete after all tracks finish. EPT-only: standalone SBD runs do not produce this file. It is the durable orchestrator resume anchor β€” if interrupted, the wave's track_run_ids[] list is the authoritative source for reconstructing per-track state.

{
  "wave_id": "2026-07-20T11-30_wave1",
  "wave_number": 1,
  "base_ref": "origin/main",
  "base_sha": "abc123def456",
  "track_run_ids": ["2026-07-20T11-30_wave1_us1", "2026-07-20T11-30_wave1_us2", "2026-07-20T11-30_wave1_us3"],
  "status": "in-progress",
  "created_utc": "2026-07-20T11:30:00Z",
  "completed_utc": null,
  "final_status": null
}

final_status values: all-success | partial-blocked | budget-exceeded | aborted.

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

  1. Mechanical over prompt-trusted. If a gate can be enforced by a hook, it is. The model complying is secondary.
  2. Hooks are no-ops until configured. Drop the bundle into any repo β€” nothing changes until you set env vars.
  3. Evidence is fingerprinted, not narrated. The gate checks the tree hash, not the agent's summary.
  4. No self-merge. Every pipeline terminates at a draft PR. A human decides what merges.
  5. Observable by RUN_ID. One stable ID threads branch, PR, commit, and run record.
  6. 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 discoverable by your agent; git with worktree support; authenticated gh CLI; jq; Docker if any track runs integration suites; lifecycle hooks enabled β€” Copilot agent hooks or Claude Code hooks (recommended).

Skill placement depends on your surface β€” the hook scripts live in .github/hooks/ for both:

Agent Skill location
GitHub Copilot .github/skills/**/SKILL.md
Claude Code .claude/skills/**/SKILL.md (or as a Superpowers plugin) 
# 1️⃣ Copy the skill 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

# …or wire one surface only (default is --surface both):
bash .github/skills/single-branch-development/scripts/install-hooks.sh --apply --surface claude    # .claude/settings.json
bash .github/skills/single-branch-development/scripts/install-hooks.sh --apply --surface copilot   # .github/hooks/track-hooks.json

# 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 your agent (Copilot or Claude Code) at the task and let the skill drive:

  • "implement Phase 1 Setup β€” shared infrastructure (T001–T010a) using single-branch-development skill" β†’ Flow 1 (scaffold)
  • "implement Phase 3 User Story 1: ingest knowledge into a searchable library (T035–T056) using single-branch-development skill" β†’ Flow 2 (story/TDD)
  • "refactor Phase 2 Foundational β€” frontend API client (T031) using single-branch-development skill" β†’ Flow 3 (refactor)
  • "execute Phase 3 US1, Phase 4 US2, Phase 5 US3 in parallel using executing-parallel-tracks skill" β†’ 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

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! πŸ˜ƒ

Android iOS JavaScript ReactJS Ruby on Rails

All Rights Reserved

Table of contents


Viblo
Let's register a Viblo Account to get more interesting posts.
Register