Skip to main content
Engineering Docs generates documents in a deliberate sequence, not in parallel or on demand. Each skill in the pipeline reads what came before it — extracting already-known facts about your project so it never repeats a question — and adds a layer of specificity that the next skill depends on. The ordering is not arbitrary: it mirrors the information dependencies that exist in real software engineering. You cannot write a meaningful system architecture without knowing who the users are and what requirements they have; you cannot write a test strategy without knowing what you’re building and how it’s structured. This page describes the full pipeline from Phase 0 through ongoing skills, explains which skills are always-core versus conditional, and documents the context-passing rules that make the no-repeat-questions guarantee possible.

​
The Full Ordered Pipeline

​
Why the Sequence Matters

The pipeline is a directed acyclic graph of information dependencies. Each document extracts specific facts from prior documents and enriches them with new detail. Changing the order breaks this graph.
1

Phase 0: Establish the foundation

business-concept captures the problem, users, value proposition, and constraints. project-plan turns those into scope and milestones. user-personas-behavior defines who exactly will use the product and how success is measured. Every subsequent skill reads from all three of these before its own interview begins.
2

Phases 1–2: Requirements before architecture

technical-specification writes down what the system must do — formally, with EARS-syntax requirements and a traceability matrix. This must precede architecture because an architecture that isn’t grounded in requirements is speculation. technical-feasibility-study (conditional) validates technically uncertain assumptions before committing to a full architecture.
3

Phase 3: Architecture before data and API

system-architecture-document defines the overall structure — components, boundaries, tech stack, NFRs. The database design and API design that follow can only be written correctly once the architectural boundaries are settled. A schema written before the architecture is known may violate component boundaries or duplicate data across services.
4

Phases 4–6: Data, API, and security together

database-design-document and api-design-document both depend on the architecture but not on each other — they can be generated in parallel as subagent delegations for large projects. security-threat-model comes after both because its STRIDE analysis needs the complete API surface and data model to be meaningful.
5

Phases 8–10: Plan, test, deploy

implementation-plan defines the dependency-ordered build sequence — it cannot be written until what is being built is fully specified. test-strategy-document maps to the features and components defined in the implementation plan. deployment-plan assumes both are complete.
6

Phases 11+: Operations — only when real users exist

technical-runbook, disaster-recovery-plan, and slo-error-budget-document are only meaningful once something is actually deployed to production with real users. Writing them for a prototype wastes time and creates false confidence.

​
Always-Core vs. Conditional Skills

These eight skills run on every project regardless of scope, size, or technology:

​
Context Passing: What Each Document Contains and What Subsequent Skills Extract

The no-repeat-questions guarantee is enforced by a strict context-passing rule: before asking any interview question, a skill must read all prior documents and use the information found there. This table shows what each phase provides and what downstream skills draw from it.
If a skill asks a question that’s already answered in a prior document, that’s a signal the prior documents weren’t loaded before the interview began. Every skill’s SKILL.md contains explicit instructions to read prior documents first and diff against what’s already known.

​
The One-Skill-at-a-Time Rule

The pipeline enforces one hard constraint on execution: exactly one skill’s interview runs at a time. The orchestrator never pre-asks questions belonging to a later skill just because they’re on its mind. Each skill’s interview happens only when it’s that skill’s turn, using its own SKILL.md as the guide. This rule exists because batching questions across multiple skills:
  • Overwhelms the user with questions that have no immediate context
  • Produces shallower answers for each skill
  • Creates ambiguity about which answer belongs to which document
  • Makes it impossible to use earlier answers as context for later questions
Interview mechanism: All questions are delivered via tool calls (e.g., AskUserQuestion), not inline in the conversation. One question per tool call. Multiple-choice options are preferred. Every question accepts “I don’t know, you decide” as a valid escape hatch — the orchestrator picks the most reasonable option, records it as [agent-decided], and continues without blocking.

​
Progress Reporting Format

After each document completes, the orchestrator reports to the user in a consistent format:
progress-report.txt
The report always includes: document number and total, document name and status, any [agent-decided] items that need human review, the next document in the sequence, and an estimated time remaining based on remaining documents.

​
Context Window Management for Large Projects

For projects requiring 10 or more documents, context window management becomes critical to output quality:
1

Suggest a fresh session after 5–7 documents

The orchestrator’s context accumulates with each interview and generation cycle. Quality degrades when context is too full — the agent may start re-asking already-answered questions or losing track of entity names established in earlier documents.
2

Watch for the degradation signals

If the agent re-asks a question already answered in a prior document, or loses track of entity names established earlier, context is too full. Start a fresh session immediately rather than continuing.
3

Resume from index.md

A fresh session reads index.md first, loads the most recent 2–3 documents for working context, and resumes from the last recorded checkpoint. Nothing is lost because the documents are on disk.
4

Delegate complex documents to subagents

Documents with 6+ internal phases — system-architecture-document, disaster-recovery-plan — are good candidates for subagent delegation. The subagent starts fresh with only the prior documents it needs, generates the target document, and writes it to .engineering-docs/. The orchestrator reads the result and updates index.md.
5

Parallelize independent documents

Once the architecture is complete, database-design-document and api-design-document depend on the same source (the architecture) but not on each other. They can be generated by parallel subagents, halving the time for that phase. The same applies to admin-access-control-specification and security-threat-model, and to multiple technical-blueprint documents for independent features.