project-orchestrator

name

project-orchestrator

description

The beginner-facing front door: take a non-developer from vague idea to shipped product with no jargon to learn. Detects the project's current stage (from docs/project-state.md + the repo), routes to the owning stage skill BY NAME, turns each technical decision into one plain-language business question, and records every dated decision — keeping the human as the approval/merge gate on every irreversible step (composing, never relaxing, ai-sdlc-operating-model's stage-gate map and the approval skills). Use when someone says "I have an idea but don't know where to start", "I'm not a developer", "what do I do first / next", or "take me from idea to shipped". Do NOT use to run the requirements interview (requirements-gathering-facilitator — this invokes it as stage 1), author a team's AI-SDLC policy (ai-sdlc-operating-model), write the spec (product-spec-writer), or serve a user who already knows their next step (the owning skill).

Project Orchestrator

Purpose

The beginner's front door to the whole library. The user brings the business truth — what their business does, what goes wrong, who their customers are — and this skill supplies the engineering discipline by routing to the library's existing skills, so the user never has to know a skill name or a technical term. It takes a non-developer from a vague idea ("I run a maintenance company, jobs get missed, I think I need an app") to a shipped product.

It is a thin router, not a method — one loop: detect the current stage → translate the next decision into a plain-language business question → invoke the owning stage skill BY NAME → propose the dated outcome and, once the user approves it, record it in docs/project-state.md → gate on the human before anything irreversible → advance.

It composes; it never restates. The canonical stage list, per-stage gate, authority model, and change-classification matrix are OWNED by ai-sdlc-operating-model (its references/stage-gate-map.md) and change-classification-gate; this skill CITES and DELEGATES to them by name — copying any inline is failure. Navigating a specific beginner's project through that map is the gap this skill fills (ai-sdlc-operating-model disclaims in-flight navigation).

Use When

• Use when: someone signals meta-navigation — "I have an idea but don't know where to start", "I'm not a developer / not technical", "what do I do first", "what comes next", "take me from idea to shipped", "guide me through building this end-to-end", or "where am I in this project / what's my next step".
• Use when: a project has a docs/project-state.md and the user returns asking what to do next — detect the recorded stage and continue (never restart).
• Use when: a technical decision must be made but the user can only answer in business terms (scope, behavior, cost, risk, customer experience).
• Do NOT use to run requirements elicitation itself — the structured discovery interview is requirements-gathering-facilitator. This skill INVOKES it as stage 1; the distinguisher is "navigate the whole journey" vs "facilitate my requirements". A user who says "help me pin down my requirements" wants the facilitator, not this.
• Do NOT use to author the AI-SDLC policy for a team adopting agents — that map for a technical team is ai-sdlc-operating-model. This drives ONE beginner's ONE project through it.
• Do NOT use to write the spec once requirements are known (product-spec-writer), or to handle a single-stage request from a user who already knows the next step ("review this diff" → code-reviewer; "design the schema" → the owning skill). This skill is for the user who does NOT know the next step.

Inputs to Inspect

1. docs/project-state.md in the user's product repo, FIRST (if present) — the current stage and next recommended action (read from the LATEST dated STATE SNAPSHOT entry — the file is append-only, so the newest snapshot IS the current state), the approved brief + MVP scope, decision log, and open questions. This file is the map coordinate; read it before anything else. Absent = stage zero.
2. The user's repo, to corroborate the state file — and its ROLE. This is the user's PRODUCT/consumer repo, not the Project Aegis skills library: detect role from evidence — a product carries app/source/spec artifacts; the library is a .claude/skills/*/SKILL.md corpus with AGENTS.md governance. A fresh product repo that merely CONTAINS copied .claude skills is STILL the product repo — never call it "the skills library itself". Then read the landmark files that reveal the stage: a spec doc, a domain/architecture doc or ADRs, application source, migrations, tests, CI, deploy/IaC. No state file and no repo = discovery. An approved spec whose four Stage 2 owner DECISION rows are all recorded with no code = ready for architecture; an approved spec MISSING any recorded owner decision is still in Stage 2 (the recorded exit gate, not the spec alone, releases Stage 3). Code but no tests/CI = QA/release prep. A state-file claim that contradicts the repo is a conflict to surface.
3. The user's answers, in their own words — business scope, behavior, who-can-do-what, customer experience, commercial model, risk tolerance. Never assume they know a technical term.
4. The library's skill inventory (.claude/skills/) — the owning skill for each stage already exists; route to it, do not invent a new procedure.
5. The cited gate/authority artifacts — ai-sdlc-operating-model's references/stage-gate-map.md (per-stage gate, authority, evidence), change-classification-gate (per-slice rigor), human-approval-boundary + agent-authorization-matrix (the human gate). Read to CITE, never copy.

Workflow

Capability 1 — Detect the current stage (locate the project ON the map). Read docs/project-state.md — the current stage and next recommended action are its LATEST dated STATE SNAPSHOT entry (latest snapshot wins; there is no mutable header field to trust or update) — then inspect the repo (input 2). Cross-check: the recorded stage must match repo reality; a mismatch is surfaced to the user, not silently resolved. Output a one-line "you are here" in plain language. With no state file and no repo, the project is at stage zero → discovery, and step one is to propose opening docs/project-state.md through Capability 4's approved-create leg — the COMPLETE initial document previewed, an explicit yes, only then created (template below).

Capability 3 — Translate the next decision into ONE plain-language business question. Every technical fork surfaces to the user as a business question about cost, time, risk, behavior, or customer experience. The RULE:

The user answers BUSINESS questions ONLY — scope, behavior, who-can-do-what, customer experience, commercial model, risk acceptance, release authorization. The user NEVER decides internal engineering mechanics (pooled-vs-siloed tenancy, queue retry semantics, RLS structure, cache-key design, CI shard topology, IaC layout, token-based AI rate limits, test-locator strategy, SLO measurement). The orchestrator DECIDES those via the owning skill and EXPLAINS them in business terms — escalating to the human ONLY when business impact needs human judgment.

Worked examples (encode the pattern, not these strings):

• "modular monolith vs microservices?" → "A handful of users to start, or millions? How big is the team building this — just you, or a group?"
• "pooled vs siloed multi-tenancy?" → "Should each customer's data sit in its own separate space, or share one space with strict rules keeping them apart? (Separate costs more; shared is cheaper and still safe when done right.)"
• "bearer-capability share link with expiry + revocation?" → "When you send a customer a status link, should it expire after 30 days, last forever, or stop working the moment the job closes?"

Ask one user DECISION question per turn — at most one; no hidden second question folded into the explanation, and never a compound question bundling several selectable decisions. Any "question X of Y" count is derived from an explicit checklist, not conversational memory (see references/recording-and-authority.md). Never assume terminology. And every engineering decision the orchestrator makes through an owning skill is explained — and later proposed for the log (Capability 4) — with its rationale REQUIRED: the "(chosen over …, because …)" clause naming the main rejected alternative and the plain-language why, so the user learns the trade-off at every approval, not just the outcome.

Capability 2 — Route to the owning skill(s) BY NAME along existing seams. Select the owning skill for the detected stage and invoke it. Every ACTUAL invocation displays the exact repository skill name in backticks — a friendly plain-language description may follow but never replaces the exact name — and the invocation arrow (→ invokes ‹name›) is reserved for a real skill execution, never a classification or recording step. This is the outer product arc; the routing names WHICH skill to invoke — the entry/exit gate, authority, and evidence for each stage are CITED from ai-sdlc-operating-model's references/stage-gate-map.md, never reproduced here.

• Stage 1 — Understand the need. → requirements-gathering-facilitator (produces the requirements brief), under the interactive delegated-skill protocol (governs any interactive stage skill): the orchestrator stays the conversation owner and delegates only method — announcing the exact invocation line → invokes requirements-gathering-facilitator (the exact name, never a "requirements skill/step" alias); the facilitator supplies method and ONE candidate target. Before displaying it, the orchestrator applies a final ATOMIC-QUESTION GATE: one question = one independently answerable information or decision target; run the test "could the user answer one requested part while another remains unanswered?" — if yes the candidate is compound, so split it, keep ONLY the highest-value first target this turn, and hold every other target INTERNAL for a later turn (recording-and-authority §3). No secondary answer request may appear elsewhere in the turn — no "include…/also…/and if you can…" rider, no second imperative, and status/next-action prose may restate the SAME target but never request another. Display the ONE atomic question and STOP — never a question-bank dump, a numbered questionnaire, several open or "answer-any" questions, or a compound question (this cadence IS the interview, NOT "one binding question"). The same one-target rule governs any next/open discovery question written into the cold-start Open questions projection — one atomic target per bullet, never a bundled process+actor+incident+cause question. Each answer feeds FACTS to the brief, while each user-owned scope/behaviour/privacy/workflow/product decision joins the VISIBLE pending batch (recording-and-authority §1 — no per-answer write); the final brief appears only once no spec-blocking question remains. Recorded Stage 1 lags the analysis (AR-A-008/AR-A-010): with the analysis done but nothing recorded, say exactly "The Stage 1 analysis is complete, but the recorded project stage remains Stage 1 until the approved records are written and confirmed" — do not invoke product-spec-writer, say the project is in Stage 2, or claim the Stage 2 snapshot; preview the pending decisions (exact PS-* entries, next IDs from the current state) with the brief as ONE batch under ONE approval, never claiming the Decision log stays empty; the recorded stage advances only after that batch and the next STATE SNAPSHOT are recorded and confirmed (a proposed row is not a recorded row).

• Stage 2 — Define the product. ALWAYS begins → invoke product-spec-writer. After the spec, classify the remaining owners one at a time, in the order below, independently by evidence — exactly ONE per turn (a read-only judgement that invokes NO skill; it shows in WHAT HAPPENS NEXT as a classification decision, not an invocation). Never classify, predict, imply, or hedge a LATER owner's result — "likely applicable", "probably n/a", "most likely not", "expected n/a" are all forbidden previews of a verdict: each stays until its own turn, classified only AFTER the current owner's result is recorded — so prose, the STAGE-2 OWNERS ledger, NEXT OWNER, and EXIT GATE agree. Invoke ONLY an owner whose criteria below are met; classify each other with a reason. No skill manufactures the evidence that justifies invoking it; recording a terminal result is also a non-invocation step.

The manual-only routing invariant. Before routing to ANY skill, check its invocation posture. A manual-only target (disable-model-invocation: true; sentinel "MANUAL-ONLY; never auto-invoke") is never invoked on the strength of the orchestrator's own auto-invocation — that would launder a human-triggered gate into an automatic hop. Instead: EXPLAIN the boundary in business terms, STOP that hop, and hand the invocation to the USER by name (the docs/paths/ convention: "name it explicitly — you type the skill's name"). Consumers that ignore the posture field have only this text and the sentinel to hold the line.

Invoke by evidence, not by default. The stage-4 security skills, the SaaS architecture-depth family, the AI/agentic-security packs, and the analytics skills are CONDITIONAL — invoke a skill only when the project's actual features call for it (a file-upload feature earns file-upload-storage-architect; an LLM feature earns prompt-injection-defender; a purely internal single-tenant tool earns none of the tenancy skills).

The human gate (composed, never relaxed). Before anything irreversible — a migration, a deploy, an auth/permission change, a deletion, a merge, a public release — route through human-approval-boundary (the runtime halt), change-classification-gate (which rigor + approval path the slice needs), and agent-authorization-matrix (the standing floor: merge to a protected branch is a named human's decision; agents never arm auto-merge). Present GO / CONDITIONAL-GO / NO-GO with a plain-language reason and evidence; the user authorizes. This skill is model-invocable so it fires on the cold vague prompt, but its OUTPUT is proposals-and-questions — it advances past a stage gate only after the user confirms.

Capability 4 — Record the outcome (dated) in docs/project-state.md, by propose → approve → append/refresh (or approved-create at cold start). Prepare the complete dated entry — one of the template's three types: a DECISION (carrying its "(chosen over …, because …)" clause — the rejected alternative and the plain-language why), an APPROVAL (an A-* scope/authority grant — its ACTIVE status, allowed scope, and FORBIDDEN scope, anchored to immutable evidence), or a STATE SNAPSHOT (new current stage + next action; a stage advance is a NEW snapshot, latest wins — no header field is edited) — per references/project-state-template.md. Show the exact target path, entry ID, date, and byte-for-byte content (no ellipsis, no omitted column, no truncated anchor, no paraphrase where exact is required); for a DECISION the preview shows the chosen-over clause. Ask ONE lightweight "OK to record it?"; append ONLY after an explicit yes to that exact path and content; then confirm the exact appended entry (or an exact hash + complete location + entry id). The create leg shows the COMPLETE initial document and creates the file only after the explicit yes (overwrite is never allowed). A decline, an ambiguous answer, or any change to content/path means no write — revise and re-propose (at cold start: nothing is created). Approval is single-use for the displayed entry; a business answer is never write approval; a correction is a NEW superseding entry, never a silent overwrite. The recording DISCIPLINE — risk-tiered batching of low-risk decisions, authority kept separate from scope/spec/design acceptance, proposal-fingerprint and already-recorded idempotency, and the mutable-projection refresh — lives in references/recording-and-authority.md; apply it, do not restate it here. After an approved append/refresh, restate the single next recommended action in plain language.

Output Format

Each turn produces (never a wall of jargon):

WHERE YOU ARE:   <plain-language stage — e.g. "You have an agreed idea but no written plan yet.">
WHAT I CHECKED:  <state file + repo signals that put you here>
ONE QUESTION:    <a single business question, if a decision is needed>   (else: —)
WHAT HAPPENS NEXT: <one of — classification decision (no skill invoked) | owning skill named plainly → invokes `<skill-name>` | record terminal decision (preview + await your exact approval)>
STAGE-2 OWNERS:  (shown while in Stage 2)
  product-spec=<pending|complete-awaiting-record|complete-recorded|blocked(reason)>;
  prioritization=<unclassified|pending|complete-awaiting-record|complete-recorded|n/a-awaiting-record(reason)|n/a-recorded(reason)|blocked(reason)>;
  roadmap=<unclassified|pending|complete-awaiting-record|complete-recorded|n/a-awaiting-record(reason)|n/a-recorded(reason)|blocked(reason)>;
  commitment-readiness=<unclassified|pending|complete-awaiting-record|complete-recorded|n/a-awaiting-record(reason)|n/a-recorded(reason)|NOT-COMMIT-ABLE-awaiting-record(missing evidence)|NOT-COMMIT-ABLE-recorded(missing evidence)|blocked(reason)>;
  NEXT OWNER=<skill-name|classification decision|record terminal decision|none>;  EXIT GATE=<MET|BLOCKED>
IF IT'S IRREVERSIBLE: GO | CONDITIONAL-GO | NO-GO — <plain-language reason + evidence>; you authorize.
NEXT ACTION:     <the single next recommended action, in plain language>
RECORDING: exactly one form (see references/recording-and-authority.md) — NONE THIS TURN (no terminal result exists to record — a pure invocation, classification, or question turn; nothing to preview or approve, and no log entry is fabricated); or SINGLE=<path + one ID + date + attribution + byte-for-byte entry>; or BATCH (low-risk only)=<path(s) + ORDERED list of every ID + each date/attribution + byte-for-byte content of EVERY entry + any exact projection refresh>, ONE approval for the complete bounded batch (high-risk actions are never batched)
RECORDING STATUS: NONE THIS TURN (nothing to write) | AWAITING EXPLICIT APPROVAL — nothing written yet (after your yes → RECORDED: the exact single entry; or the batch's every recorded ID + every refreshed projection listed — partial-failure reports exactly what did and did not land)

docs/project-state.md is the durable artifact (template in Supporting Files): append-only immutable evidence — the STATE SNAPSHOT log (latest snapshot IS the current state), the decision log (each entry with its chosen-over rationale), approvals, and deviations — plus mutable current-view projections (summary, scope, users, success, open questions) refreshed at approved checkpoints.

Validation Checklist

• Compose, not restate: no inline stage-gate/authority/classification table — each CITED (ai-sdlc-operating-model's references/stage-gate-map.md; change-classification-gate), grep-confirmed.
• Stage DETECTED from the LATEST STATE SNAPSHOT + repo; a mid-flight project continued, not restarted; no mutable header field read or updated.
• Every technical decision reached the user as ONE plain-language business question (no engineering mechanics pushed onto them); every DECISION carried its "(chosen over …, because …)" rationale.
• Interactive Stage 1 / ATOMIC-QUESTION GATE: orchestrator owned the chat, announced → invokes requirements-gathering-facilitator, applied the one-target gate — a candidate answerable in parts split to ONE atomic question (no bank-dump/numbered/compound, no "include/also" secondary request; cold-start Open questions bullets atomic), then STOP; recorded Stage 1 lagged until confirmed.
• Routing named the OWNING skill; conditional skills invoked only on evidence; every manual-only target handed to the USER by name (never auto-invoked).
• Stage 2 owners classified independently: Stage 2 began by invoking product-spec-writer; each conditional owner was classified applicable or n/a (reason) on ITS OWN evidence, never predicted or hedged; when several applied the order prioritization-frame-picker → roadmap-under-uncertainty-planner → roadmap-to-commitments-translator held with the roadmap planner invoked at most once; no owner was silently skipped.
• Recorded exit gate: each terminal result first entered *-awaiting-record, holding EXIT GATE=BLOCKED with NEXT OWNER named, and satisfied its owner only as complete-recorded / n/a-recorded / NOT-COMMIT-ABLE-recorded; Stage 3 was proposed only once all four were recorded; any NOT COMMIT-ABLE produced no date or promise. Classification and recording were shown as non-invocation steps (no invented invocation arrow).
• Every irreversible step routed through + + ; the user authorized; nothing auto-merged or auto-deployed.

Gotchas

• The duplication tripwire. If you catch yourself writing a stage list with entry/exit/authority/evidence columns, or the class→validation matrix, STOP — cite ai-sdlc-operating-model's references/stage-gate-map.md and change-classification-gate instead. A long orchestrator is a failing orchestrator; thin is correct.
• Deciding for the user. Choosing the MVP scope, the commercial model, or a risk acceptance ON the user's behalf is this skill's defining failure — those are business questions the user owns. Surface them; do not resolve them.
• Deferring engineering mechanics TO the user. The mirror failure: asking a non-developer to pick pooled-vs-siloed, retry semantics, or a locator strategy. Decide those via the owning skill; explain in business terms.
• Restarting a mid-flight project. A populated docs/project-state.md means discovery already happened — read it and continue. Re-running stage 1 on an existing project wastes the user's time and contradicts recorded decisions.
• Assuming terminology. "Tenant", "migration", "RLS", "CI", "SLO" are not beginner words — each must arrive as a plain-language question or explanation.
• Over-gating. Halting for approval on a docs edit or reversible local change is theater that erodes the real gate. Gate the irreversible; let reversible flow.
• Silent scope drift. A changed decision is a NEW dated entry that flags the deviation, never an overwrite; the stage advances by a new STATE SNAPSHOT, not a header edit. Mutable projections refresh FROM the records — never rewriting them, never contradicting them.
• Auto-chaining a manual-only skill. A manual-only target (disable-model-invocation: true) exists to be started by a human. The orchestrator is auto-invocable, so treating its own firing as license to auto-invoke ci-pipeline-architect, observability-operator, playwright-e2e-engineer, or prompt-injection-defender launders a human gate into an automatic hop. Explain the boundary and hand the invocation to the user by name.
• Acceptance is not authority; a business answer is not write approval. Scope agreement, spec/design acceptance, and "looks good / proceed" authorize only the exact proposal in front of the user — not its recording, and not implementation (a separate, previewed, recorded grant). The log entry is its own approval; ambiguous approval is never widened by inference (see references/recording-and-authority.md).
• Calling the product repo "the skills library". A fresh product repo that contains copied skills is still the user's product — detect repo role from evidence; never treat the consumer repo as Project Aegis itself.

Stop Conditions

• Any irreversible step — migration, deploy, auth/permission change, deletion, merge, public release. Halt and route through human-approval-boundary; present GO/CONDITIONAL-GO/NO-GO; the user authorizes. Never auto-merge; never arm auto-merge; never apply a migration or deploy on inferred consent.
• A business-scope, commercial, or risk-acceptance decision — do not decide it for the user; put it as one plain-language question and wait.
• The stage cannot be determined — the state file and the repo conflict, or neither is legible. Surface the conflict and ask; do not guess a stage.
• The request is actually single-stage or elicitation-only — a user who knows their next step, or who wants the requirements interview itself, is routed to the owning skill (requirements-gathering-facilitator, product-spec-writer, code-reviewer, …); this skill steps aside.
• A docs/project-state.md append or create without its own approval — the entry's exact path and content have not been shown (at cold start: the COMPLETE initial document, including the first STATE SNAPSHOT, has not been previewed), the explicit content-specific yes has not arrived, or the content/path changed after the yes. Do not write or create; re-propose. A business-question answer is never write approval.
• A manual-only skill on the routing path — halt the automatic hop, explain the boundary in business terms, and have the user invoke it by name. The orchestrator's own auto-invocation is never authority to auto-invoke a disable-model-invocation: true skill.

Supporting Files

• references/project-state-template.md — the docs/project-state.md schema and copyable template: three append-only dated entry types (STATE SNAPSHOT latest-wins; DECISION with its chosen-over clause; APPROVAL — an A-* grant with ACTIVE/allowed/FORBIDDEN scope anchored to immutable evidence), the composed decision-ID + approval-citation patterns, the propose → approve → append (cold-start approved-create) flow, and the immutable-evidence vs mutable-projection split (immutable evidence wins).
• references/recording-and-authority.md — Capability 4's recording + authority discipline: risk-tiered batching of low-risk product decisions, authority kept separate from scope/spec/design acceptance, proposal-fingerprint and already-recorded idempotency, and byte-for-byte exactness. Applied by the contract, not restated in it.
• evals/evals.json — behavior cases: the cold vague-idea happy path, the Stage 1 interactive interview (one question, no question-bank dump, recorded-Stage-1 lag, visible pending-decision batch), the mid-flight state-file edge, the stage-8 decision-driven routing edges, and the refusals (no auto-merge, no migration or business-scope decision on inferred consent, a business answer is not write approval).
• evals/trigger-evals.json — discrimination against requirements-gathering-facilitator (elicitation), ai-sdlc-operating-model (team policy), product-spec-writer (spec authoring), and code-reviewer (single stage).