Specification constitutions for cobbler-based projects and tooling to validate their correctness; the Mage library implements the measure-stitch workflow to exercise and refine them before the core moves to cobbler.

Specifications are authored in YAML rather than spec-kit markdown because Claude reads and generates them autonomously — structured, machine-parseable documents produce more reliable output than prose and are unambiguous in diff.

AI coding assistants handle individual edits well but break down across sessions that require sequenced tasks, dependency management, and clean commit history. Running Claude directly on a working branch conflates exploration with production commits and leaves recovery from failures to the developer.

The primary contribution of this repository is three YAML constitutions — design, planning, and execution — that govern Claude's behavior in each phase of the cobbler workflow. Constitutions enforce specification-first development: Claude may not write code that does not trace to a SRD, must size tasks within defined LOC bounds, and must close the issue with a traceable commit before ending a session. The analyze command validates that produced specifications are internally consistent — no orphaned SRDs, no missing test-suite linkage, no broken use-case references.

The cobbler workflow that the constitutions govern separates task proposal (measure) from task execution (stitch). Measure invokes Claude with the project's specification tree and produces a dependency-ordered task list. Stitch executes each task in an isolated git worktree, merges the result to the generation branch, and records metrics. The generation branch accumulates only finished work; the loop runs unattended until the backlog is empty or the cycle budget is exhausted.

This repository implements the workflow as a Mage library to accumulate operational experience with the constitutions. Once the design is stable, the orchestration logic moves to cobbler and this repository becomes the scaffolding layer that initializes cobbler-based projects with constitutions, configuration, and Mage targets.

graph TD
    subgraph CP["Consuming Project"]
        Magefile["Magefile\n<i>mage targets</i>"]
    end

    subgraph ORCH["orchestrator"]
        Orchestrator["Orchestrator\n<i>main struct</i>"]
        Generator["Generator\n<i>lifecycle</i>"]
        Cobbler["Cobbler\n<i>measure + stitch</i>"]
        Commands["Commands\n<i>git, gh, go wrappers</i>"]
        Stats["Stats\n<i>metrics</i>"]
    end

    subgraph EXT["External Tools"]
        Git
        ClaudeCode["Claude Code"]
        GitHubIssues["GitHub Issues"]
        GoToolchain["Go Toolchain"]
    end

    Magefile --> Orchestrator
    Orchestrator --> Generator
    Orchestrator --> Cobbler
    Orchestrator --> Stats
    Generator --> Commands
    Cobbler --> Commands
    Cobbler --> ClaudeCode
    Commands --> Git
    Commands --> GitHubIssues
    Commands --> GoToolchain

Figure 1 — System context. See docs/ARCHITECTURE-diagrams.md for additional diagrams.

Release 01.0 (Core Orchestrator and Workflows) is complete: 5 of 5 use cases implemented across 5 SRDs. Release 02.0 (VS Code Extension) is not started: 5 use cases specified, 0 implemented.

The specification index at docs/SPECIFICATIONS.yaml lists every SRD, use case, and test suite with cross-references.

A generation is the primary unit of work. It begins from a tagged main state, creates a timestamped branch, runs measure-stitch cycles, and merges the result back to main with lifecycle tags (-start, -finished, -merged).

generator:start  →  cobbler:measure  →  cobbler:stitch  →  (repeat)  →  generator:stop

Measure reads docs/VISION.yaml, docs/ARCHITECTURE.yaml, and the open issue list, then invokes Claude with a prompt template. Claude returns a YAML task list with titles, descriptions, estimated LOC, and dependency indices. The orchestrator creates GitHub Issues for each proposed task, labelled by generation.

Stitch picks the next ready GitHub Issue, creates a git worktree on a task branch (task/{baseBranch}-{issueID}), invokes Claude with the task description and execution constitution, merges the result, records metrics, and closes the issue. The worktree is deleted after merge. Each task runs in isolation; the generation branch receives only merged output.

Constitutions are YAML documents that govern Claude's behavior per phase. The design constitution (docs/constitutions/design.yaml) rules specification authoring. The planning constitution controls task sizing, issue structure, and dependency ordering during measure. The execution constitution enforces traceability, Go coding standards, and session-completion discipline during stitch. All three are scaffolded into consuming projects and referenced from configuration.yaml.

This repository provides the orchestration tooling. To set up orchestration in another Go project, use the scaffold targets from this repo's magefiles.

Install the orchestrator into a target repository:

mage scaffold:push /path/to/target-repo

Push copies orchestrator.go into the target's magefiles/orchestrator.go, writes constitutions to docs/constitutions/, prompts to docs/prompts/, generates configuration.yaml with auto-detected project settings, and wires magefiles/go.mod to depend on the published cobbler-scaffold module. The target repository gains all mage targets (build, test, cobbler, generator, scaffold:pop) without any manual setup.

Push also accepts a Go module reference in module@version format. The orchestrator downloads the module, copies it to a temp directory, scaffolds it, and prints the path:

mage scaffold:push github.com/org/repo@v0.20260222.1

Remove the orchestrator from a target repository:

mage scaffold:pop /path/to/target-repo

Pop removes magefiles/orchestrator.go, docs/constitutions/, docs/prompts/, and configuration.yaml. It also drops the orchestrator replace directive from magefiles/go.mod. The target's own code and magefiles/go.mod are preserved.

Both targets accept . for the current directory, but self-targeting is blocked: running scaffold:push . or scaffold:pop . from this repository exits with an error. Push would replace the development magefile with the template; pop would delete source constitutions, prompts, and configuration. Use a separate target repository.

The specification tree is the source of truth for requirements and design decisions. Code comments and commit messages reference these documents by ID (e.g., srd001-orchestrator-core R6).

How to navigate: Start with docs/VISION.yaml for context, then docs/ARCHITECTURE.yaml for component boundaries. When reading code, the file header lists which SRDs it implements. When a requirement is unclear, look up the R-number in the relevant SRD; the use cases for that SRD are listed in docs/SPECIFICATIONS.yaml.

Use cases are stable by numeric ID. The release they belong to is recorded in docs/road-map.yaml, not in the filename — re-prioritizing a use case to a later release does not rename the file.

pkg/orchestrator/      — library implementation; exported types are Orchestrator, Config, New, LoadConfig
orchestrator.go        — Mage target template; scaffold:push copies this to target repos as magefiles/orchestrator.go
magefiles/magefile.go  — build targets for this repository (includes scaffold:push, podman targets)
docs/                  — VISION, ARCHITECTURE, SRDs, use cases, test suites, constitutions
docs/constitutions/    — design/planning/execution/go-style/testing constitutions (scaffolded into consuming projects)
docs/prompts/          — measure and stitch prompt templates (scaffolded into consuming projects)
tests/rel01.0/         — release 01 E2E tests; one package per use case (uc001/ through uc007/)
tests/rel01.0/internal/testutil/ — shared test helpers (snapshot preparation, git/mage/gh wrappers)
configuration.yaml     — orchestrator config (auto-created with defaults if missing)
.claude/               — Claude Code skills and project rules

Go — the library embeds prompt templates and constitutions as embed.FS assets, which requires a compiled language; Go's os/exec wrappers around git, gh, and podman are straightforward and testable.

Mage — consuming projects already use Mage for their own build logic; exposing orchestrator operations as Mage targets avoids introducing a second build system.

GitHub Issues — issue state is stored in GitHub, making the backlog visible and manageable without a local service. The gh CLI handles all issue CRUD operations; recovery after interruption simply re-queries open issues.

Podman — rootless container runtime. Claude runs inside a container to prevent it from modifying host files outside the mounted working directory. The container also provides a reproducible environment for credential injection.

mage build
mage lint
mage install

Mage targets handle build tags and flags automatically.

mage test:unit            # unit tests (pkg/orchestrator)
mage test:usecase         # all use-case tests — packages run in parallel
mage test:uc 001          # single use case by number

E2E tests require the -tags=usecase build tag. Each use case lives in its own package under tests/rel01.0/ucNNN/, so Go runs them as independent processes with separate pass/fail reporting.

# Unit tests (no tag needed)
go test ./pkg/orchestrator/...

# All E2E tests — packages run in parallel
go test -tags=usecase -v -count=1 -timeout 1800s ./tests/rel01.0/...

# Single use case
go test -tags=usecase -v -count=1 ./tests/rel01.0/uc001/

# Single test by name
go test -tags=usecase -v -run TestRel01_UC001_Init ./tests/rel01.0/uc001/

E2E tests download github.com/petar-djukic/sdd-hello-world, scaffold it once per package in TestMain, and copy the snapshot per test. Shared helpers live in tests/rel01.0/internal/testutil/. Test names follow the TestRel01_UC{NNN}_Name convention, and within each package tests run in parallel via t.Parallel() since each gets an isolated temp directory.

The mage vscode:push target compiles, packages, and installs the extension into VS Code. It requires the code CLI on PATH.

On macOS, open VS Code and run Shell Command: Install 'code' command in PATH from the Command Palette (Cmd+Shift+P), or add the following to ~/.zshrc:

export PATH="/Applications/Visual Studio Code.app/Contents/Resources/app/bin:$PATH"

Then build and install:

mage vscode:push    # compile, package, install
mage vscode:pop     # uninstall

MIT