Maestro

A ready-to-install pack of AI skills and a workflow orchestrator that runs a feature through the KeyValue software-development lifecycle: high-level design → detailed design → implementation → review → QA → release — with a human approval at each gate.

Why

Building a feature well means the same steps every time: design it, review the design, implement to a contract, test it, review the code, QA it, ship it. This pack encodes those steps once so every developer runs them the same way.

• Run it your way. Let Conductor orchestrate the whole pipeline end-to-end, or run each step yourself as a slash command (/plan, /api-contract, /backend-impl, …) in Claude Code, Cursor, or Copilot.
• One place to change behavior. Every step's behavior lives in its skill; which skill (and any helper skill) backs each step is one line in skills.config.yaml. Change it there and it changes everywhere.
• Proof, not promises. Every step writes an artifact to disk, and the pipeline checks the file exists before moving on.

Prerequisites — set up the workspace first

This pack runs against an umbrella workspace: one parent git repo per project that becomes the agent's working surface for a whole feature. Stand it up once per project, then install the pack into it. The flow assumes these are in place — do them in order.

• One parent repo, N child clones. Keep every service repo independent (own branches, PRs, CI) — don't merge them into a monorepo. Instead clone them, gitignored, into the umbrella under codebase/ so a single agent sees the frontend, backend, and every microservice at once, instead of one repo in isolation. A workspace.yaml manifest lists the repos.
• One command for the whole stack. Wire the full stack up and down behind a single command (e.g. stack up / stack down over Docker Compose, Tilt, or Nix — team's choice). Host prerequisites and secrets stay human-owned in a SETUP.md; the workflow never touches them.
• Docs + tests centralised in the umbrella. Keep the per-feature docs tree (docs/technical, docs/functional, docs/business) and the cross-repo integration + UI-automation suites (test/integration, test/ui-automation) here, so one suite spans all repos.
• Source-of-truth MCPs connected. The design flow assumes a PRD + designs already exist — connect Jira / Confluence / Figma over MCP so the agent reads tickets, specs, and designs directly.

The umbrella is a per-project setup, not something this pack ships (yet). Set it up manually for now; the pack installs into it and every feature — requirement input and generated artifacts — lives under .maestro/<slug>/ inside it.

Install

Requires: Node.js (for npx), plus curl + tar (standard on macOS/Linux).

One command from the root of your repo:

curl -fsSL https://raw.githubusercontent.com/KeyValueSoftwareSystems/kv-skills/main/install.sh | bash -s -- claude-code

Or for several IDEs at once:

curl -fsSL https://raw.githubusercontent.com/KeyValueSoftwareSystems/kv-skills/main/install.sh | bash -s -- claude-code cursor

The installer:

1. installs our skills (npx skills add KeyValueSoftwareSystems/kv-skills);
2. installs the external helper skills the flow uses (Superpowers — brainstorming, planning, TDD, code review, debugging, worktrees);
3. copies the Conductor workflows + skills.config.yaml into your repo (fetched from the repo tarball when run piped);
4. installs Conductor (installing uv first if it's missing; skip the whole step with --no-conductor).

Conductor runs the full pipeline; you don't need it if you only use the slash commands.

How to run

As an orchestrator (Conductor)

Conductor runs the skills for you, end to end, with automatic approval gates. Same skills, same artifacts — it just drives the sequence.

The easy way — by feature slug. Scaffold the requirement folder, drop your requirement files in it, and run one command from your repo root:

maestro init user-authentication                          # create .maestro/user-authentication/requirement/
$EDITOR .maestro/user-authentication/requirement/requirement.md   # write the requirement (add more files if you like)
maestro user-authentication                               # run full pipeline
maestro user-authentication --path=workflows/design.yaml  # run design phase only

maestro (installed by the installer) reads the requirement from the folder .maestro/<slug>/requirement/ (every file in it) and runs the default pipeline at http://127.0.0.1:8080 (set web.port in maestro.config.yaml). Use --path=<file> to run a specific workflow. Extra flags go after --, e.g. maestro user-authentication -- --dry-run.

Run individual workflows for specific phases:

Workflow	Command	Purpose
design.yaml	maestro <slug> --path=workflows/design.yaml	HLD → LLDs → API contract → functional test cases
backend_impl.yaml	maestro <slug> --path=workflows/backend_impl.yaml	Backend implementation & tests
frontend_impl.yaml	maestro <slug> --path=workflows/frontend_impl.yaml	Frontend implementation & tests
qa.yaml	maestro <slug> --path=workflows/qa.yaml	QA automation

Resuming a partially-run workflow

Sub-workflows record completed steps in .maestro/<slug>/state.json. Re-run the same command to resume from the first incomplete step. To force a rebuild:

python3 workflows/state.py reset --slug <slug> --step <step-id>   # rebuild one step
python3 workflows/state.py reset --slug <slug> --all              # rebuild everything

Human approval gates always re-ask, even on resume.

As skills (you orchestrate manually)

Run the slash commands yourself, in order, in any IDE (Claude Code, Cursor, Copilot) — you review each artifact before moving to the next:

/plan feature="Add user authentication" feature_slug="user-authentication"   # high-level design, then approve
/backend-design  ∥  /frontend-design   # author the per-stack LLDs
/api-contract          # reconcile the LLDs → the cross-repo contract
/functional-testcases  # derive the functional test-case catalog QA will automate
/architecture-review → /backend-impl → /backend-review
/frontend-impl → /frontend-review → /qa → /verify → /fix → /review-pack

Skill	Command	Edits code?	Purpose
plan	/plan	no	High-level design (HLD): options, choice, risks
backend-design / frontend-design	/backend-design · /frontend-design	no	Author the per-stack low-level design (LLD) — how the feature fits each stack
api-contract	/api-contract	no	Reconcile the LLDs into the OpenAPI contract + acceptance criteria
functional-testcases	/functional-testcases	no	Derive the functional test-case catalog (black-box, traceable) — the source /qa automates
backend-tasks	/backend-tasks	no	Author the task DAG (tasks.json) — ordered tasks grouped into independent slices (fallback when the design phase didn't emit it)
backend-implement	/backend-impl	yes	Implement to the contract, test-first, to backend standards
frontend-implement	/frontend-impl	yes	Implement UI states + tests to frontend standards
qa-automation	/qa	tests	Critical-journey E2E from acceptance criteria
architecture-review	/architecture-review	no	Review the design: gaps, security, scaling
backend-review / frontend-review	/backend-review · /frontend-review	no	Review the implementation
verify	/verify	no	Run deterministic checks → proof report
fix-loop	/fix	bounded	Fix failing checks (≤3 attempts), then escalate
human-review-pack	/review-pack	no	Assemble the PR/release pack

Each editing skill carries the standards a change must meet (security, backward compatibility, migrations, accessibility, performance, …) and a Safety section: it will not write secrets or production config, and it stops to ask a human before anything destructive.

Customisable flow

This is the basic workflow — a starting point you can customize to fit your process. Each step captures decision points, produces artifacts, and gates on their existence before advancing. Completed steps are recorded in .maestro/<slug>/state.json so partial runs resume correctly. Everything for a feature — the requirement input and all generated artifacts — lives under one folder, .maestro/<slug>/.

                     feature + requirement
                                │
                                ▼
                     ┌──────────────────────┐
                     │       HLD  /plan      │  ⟲ open-questions loop
                     └──────────┬───────────┘     (refine until resolved)
                                ▼
                          — ✋ approve —
                                │
                 ┌──────────────┴──────────────┐
                 ▼                              ▼
       ┌──────────────────┐          ┌───────────────────┐
       │  backend-design  │          │  frontend-design  │
       └─────────┬────────┘          └─────────┬─────────┘
                 └──────────────┬──────────────┘
                                ▼
                          /api-contract
                                │
                                ▼
                       functional-testcases      (test-case catalog → QA)
                                │
                                ▼
                          — ✋ approve —
                                │
                                ▼
                      architecture-review
                                │
                                ▼
                          — ✋ approve —
                                │
                 ┌──────────────┴──────────────┐
                 ▼                              ▼
   ┌──────────────────────────┐   ┌──────────────────────────┐
   │  backend-impl            │   │  frontend-impl           │
   │  DAG→slices→merge→tests  │   │  DAG→slices→merge→tests  │
   │  →verify→review          │   │  →a11y→review            │
   └─────────────┬────────────┘   └─────────────┬────────────┘
                 └──────────────┬───────────────┘
                                ▼
                            integrate
                                │
                                ▼
                                QA
                                │
                                ▼
                            review-pack
                                │
                                ▼
                          — ✋ approve —
                                │
                                ▼
                             release
                                │
                                ▼
                        archive (stub → docs/)

Configure

skills.config.yaml — Workflow configuration

This file defines which skill backs each SDLC step. Edit once, change everywhere:

Setting	Purpose
skill:	Which skill runs this step
external:	Optional helper skill (none to use built-in)
reviewer:	Who reviews the output (backend/frontend stack)
artifacts:	Where artifacts are saved (<slug> is feature slug)

Review third-party skills before use. The default flow requires Superpowers (installed by the script); all other slots default to none (built-in).

workflows/maestro.config.yaml — Orchestration settings

Set Conductor-specific knobs (fix-loop cap, coverage gate, environment lifecycle):

Setting	Default	Purpose
models.default	claude-haiku-4-5	Fallback model for any agent
models.agents.<name>	claude-haiku-4-5	Per-agent model override
web.port	8080	Dashboard port
fix_loop.max_attempts	3	Fix-loop cap before escalating
gates.coverage_threshold	80	Minimum test coverage

Model selection

Per-agent, one place. Each agent's model is set under models.agents in maestro.config.yaml, keyed by agent name:

models:
  default: claude-haiku-4-5   # fallback for any agent not listed
  agents:
    author_hld:  claude-sonnet-5   # bump just the HLD author
    arch_review: claude-sonnet-5   # and the architecture review
    # everything else -> claude-haiku-4-5

Any agent you don't list runs on claude-haiku-4-5.