Skip to main content
The Engineering Docs orchestrator is the entry point that sits between a raw project idea and the 21 specialist skills in the plugin. When you describe what you want to build — a single sentence, a messy paragraph, a half-formed concept — the orchestrator takes over: it conducts a structured discovery conversation, decides which documents your specific project needs and in which order, invokes each skill in turn, and stitches the results into a single coherent, navigable document set. You never choose a skill by name; the orchestrator handles every routing decision.
Key distinction: The orchestrator is a router, not a writer. It does not draft documents itself. Its job is to understand the project well enough to hand off to the correct specialist skill at the correct time, in the correct sequence.

​
What the Orchestrator Does

The using-engineering-docs skill runs a six-phase lifecycle on every invocation:
1

Mode Detection

Before anything else, the orchestrator determines whether you’re in Mode A (Greenfield) — a net-new product with no existing .engineering-docs/ folder — or Mode B (Brownfield) — an existing project, existing codebase, or a “add a feature” request. The document set and interview questions are different for each mode. See Greenfield vs. Brownfield for full details.
2

Idea Intake and Standing Constraints

For Mode A, Phase 0 runs a structured business concept interview using tool calls (AskUserQuestion) — not inline chat. Six standing constraint questions (team size, hosting, budget, timeline, regulatory needs, existing integrations) are asked once, early, because every downstream document depends on them. Answers are written to 1-business-plan.md immediately.
3

Skill Selection and Sequencing Plan

Using the Skill Directory (below), the orchestrator determines which conditional skills apply to this particular project and proposes the resulting document list. It presents this plan to the user in a few lines and invites redirects — but does not turn plan approval into a multi-question gate.
4

Sequential Document Generation

For each document in the plan, the orchestrator reads the skill’s SKILL.md, reads all prior documents to extract already-known information, identifies only the truly missing items (maximum 2–3 questions), generates the document using the skill’s template, writes it to .engineering-docs/, updates index.md, and asks for user confirmation before moving to the next document.
5

Consistency and Completeness Pass

After each document is produced, the orchestrator runs a lightweight cross-check against all previously written documents — entity names, architectural assumptions, role definitions, endpoint-to-entity alignment. A final pass runs across the complete set before the document set is declared ready.
6

Master Project Index

The final output is index.md — a structured navigation document listing every document produced, its status, and the reading order a new engineer or AI agent should follow to get full context fast.

​
The Skill Directory

Every skill has a phase number, which controls its position in the generated sequence. “Always core” skills run on every project regardless of scope; conditional skills are included only when the project actually needs them.

​
Right-Sizing, Not Maximalism

A weekend side project and a payments platform do not need the same 15 documents. The orchestrator’s job is to determine which conditional skills actually apply — generating every possible document regardless of project scope defeats the purpose.

Always include for projects with…

Real users depending on uptime, any money or personal data, multi-team codebases, or compliance obligations (PCI, GDPR, SOC 2). When in doubt on a conditional skill, lean toward including it.

Consider skipping for…

Internal prototypes, side projects, CLI tools with no user-facing UI, or experimental work with no production deployment planned. The orchestrator states which way it leaned and why.

​
Anti-Rationalization: What to Stop Doing

These thoughts signal the orchestrator (or the agent running it) is rationalizing a shortcut. They come directly from the using-engineering-docs SKILL.md:

​
Standalone Skill Usage

Every skill remains independently callable outside the orchestrator. If you already have partial documentation and need only a single artifact — say, a security threat model on an existing system — you can invoke engineering-docs:security-threat-model directly. Standalone mode skips the orchestrator’s phase sequencing and context-loading, interviewing for exactly what that one skill needs.
standalone-skill.sh

​
Session Persistence and Resume

Full Mode A pipelines span multiple sessions. The orchestrator never loses progress:
  • After every phase completes, index.md records which phases are done, which is in progress, and what the next unanswered question is.
  • On a new invocation where a partial .engineering-docs/ folder already exists, the orchestrator reads index.md first and resumes exactly where it left off.
  • Nothing already answered is re-asked. No completed document is overwritten.
For large projects requiring 10 or more documents, the orchestrator proactively suggests starting a fresh session between major phases. The index.md file is the anchor — a fresh session reads it first, loads the most recent 2–3 documents for context, and continues from the last recorded checkpoint.

​
Output Structure

The complete output lives in .engineering-docs/ at the project root:
project-root/.engineering-docs/
On re-run, the orchestrator never overwrites existing numbered files. New content appends as a new numbered file (e.g., 18-blueprint-checkout-v2.md), or the old file is archived to .engineering-docs/archive/ with a timestamp suffix. The index.md always reflects current reality.