Skip to main content
Engineering Docs works through a structured, six-phase pipeline driven by the using-engineering-docs orchestrator skill. Understanding how the pipeline operates — particularly the interview mechanism, greenfield versus brownfield detection, and context loading — helps you get the most out of every session and explains why the agent never asks the same question twice. This page covers every phase in detail, including the full skill-sequence flow and output folder structure.

​
The Six-Phase Pipeline

​
The Interview Mechanism

The tool-call interview is the core of Engineering Docs’ quality. Every skill asks its questions via tool calls, not inline conversation text. This is a deliberate architectural choice.
Each question is presented through a tool call (e.g., AskUserQuestion) with:
  • A clear, specific question
  • Multiple-choice answer options
  • A pre-selected recommended answer
  • “I don’t know, you decide” as an explicit escape hatch on every question
The agent waits for the user’s selection before proceeding to the next question. One question per tool call — batching multiple questions in one message produces partial or shallow answers.

​
Context Loading — No Repeated Questions

Each skill, before asking any interview questions, reads all prior documents in .engineering-docs/ to extract already-known information. This is what prevents the agent from asking “what’s your tech stack?” for the seventh time. The context passing rules are strict: Every subsequent skill must read these before asking questions and must never ask a question that is already answered in a prior document.

​
The Skill Sequence

The full skill directory, showing which documents are always generated versus conditional:
Right-sizing, not maximalism. A weekend side project and a payments platform do not need the same 15 documents. The orchestrator determines which conditional skills apply based on the idea intake interview — generating every possible document regardless of project size defeats the purpose.

​
Session Persistence & Resumption

Full Mode A pipelines can span multiple sessions. The orchestrator is designed to stop and resume without restarting any phase:
  • After every phase, index.md records which phases are done, which is in progress, and what the next unanswered question is
  • On a new invocation of using-engineering-docs in a project that already has a partial .engineering-docs/ folder, the orchestrator reads index.md first and resumes exactly where it left off
  • Nothing already answered is re-asked
For large projects (10+ documents), the orchestrator suggests starting a fresh session after 5–7 documents, when context accumulation begins to affect output quality. The index.md anchor makes resumption seamless — a fresh session reads index.md, loads the most recent 2–3 documents for context, and continues from the next pending skill.

​
Output Folder Structure

.engineering-docs/ layout

​
Versioning on re-run

When the orchestrator is invoked again on an existing project (Mode B, or a Mode A project revisited), it never overwrites an existing numbered file. New or revised content either:
  • Appends a new numbered file continuing the existing sequence (e.g., 20-blueprint-checkout-v2.md), or
  • If truly replacing a stale document, moves the old one to .engineering-docs/archive/ with a timestamp suffix, and the new version takes the next available number
index.md always reflects current reality. Nothing is silently lost.

​
Frequently Asked Questions

Yes. Every skill is independently callable. Invoke a skill by name and describe what you need — it runs its own interview (scoped to what it needs) and generates that one document. Standalone mode reads any existing documents in .engineering-docs/ for context but skips the orchestrator’s sequencing and consistency logic.
Tell the orchestrator you want to skip it. The orchestrator confirms the skip, explains any downstream documents that may be affected, marks the document as status: skipped in index.md with your stated reason, and continues. Any downstream document that depended on the skipped one notes that assumptions were made without it.
Yes. Request a revision and the orchestrator creates a new version (never overwriting) per the versioning rules, re-runs the consistency check against all downstream documents, and flags any downstream documents that may need updates due to the change.
For projects requiring 10+ documents, the orchestrator can delegate document generation to subagents to preserve its context for coordination. Documents that don’t depend on each other — such as database-design-document and api-design-document (both depend on the architecture but not on each other) — can be generated in parallel. The index.md anchor makes this coordination reliable across sessions.
Never. The security policy is absolute: no API keys, credentials, or connection strings appear in any generated document, even if the user provides them during an interview. References to such values use name/purpose only (e.g., STRIPE_SECRET_KEY, to be set via environment variable).
Yes. All 22 skills are pure Markdown plus plain instructions — no logic tied to a specific agent harness’s proprietary tool names. Any harness-specific action (write a file, ask a question) is described in terms every supported platform can execute. The same skill files work on Claude Code, Gemini CLI, Cursor, Cline, and all other supported platforms.

​
Next Steps

Quickstart

Install the plugin and run your first skill in under two minutes.

Introduction

See the full skills library, custom agents, and platform compatibility table.