fattain-naime/engineering-docs/using-engineering-docs

Engineering-Docs Orchestrator

Purpose

Take a project idea in whatever form it arrives — a sentence, a messy paragraph, a half-formed concept — and turn it into a complete, right-sized set of pre-development documents, using the other skills in this plugin as building blocks. The user never needs to know a skill's name or pick one; they answer questions about their project, and this skill handles which document gets written, in what order, and by which underlying skill.

This is a router, not a writer. It does not draft documents itself — it understands the project well enough to hand off to the correct specialist skill at the correct time, in the correct sequence, and then stitches the results into one coherent, navigable set.

Input

Works best with: A description of the project idea, in the user's own words, at any level of polish — a one-line pitch is enough to start. Also valuable: Anything the user already knows: target users, rough scale, budget/timeline pressure, whether this is a side project or something with real users depending on it, any part of the idea they're already unsure about.

Do not require a polished brief before starting. Extracting the details is this skill's first job, not a precondition for using it.

Mode Detection

Before anything else, determine which of two modes you're operating in. The required documents and the questions are different.

Mode A — Greenfield (new product from an idea)

No existing .engineering-docs/ folder, and no indication of an existing codebase. Full pipeline runs, starting from business concept.

Mode B — Brownfield (new feature / change on an existing system)

Triggered when:

• A .engineering-docs/ folder with an index.md already exists in the repo, OR
• The user's request references "add a feature," "extend," "modify," or similar language, OR
• An existing codebase is present in the project root with no engineering-docs history

In Mode B, do NOT re-run the full business-plan / system-architecture interview. Instead:

1. Read the existing index.md (if present) and the docs it links to for context.
2. If no docs exist, scan the existing codebase/README first to infer current architecture, stack, and conventions — and ask the user to confirm or correct that inference rather than starting from zero.
3. Run only the subset of skills relevant to the change (typically: technical-blueprint for the feature itself, architecture-decision-record if it affects architecture, database-design-document if it touches the data model, api-design-document if it adds/changes endpoints, test-strategy-document scoped to the feature, security-threat-model if it touches auth/payments/PII, project-plan if scope/timeline changes, implementation-plan if build order changes).
4. Produce new numbered docs that append to the existing set, never overwriting prior history.

Anti-Rationalization

Every shortcut in the trap table in reference.md ("the project is simple enough to skip intake," "I'll batch the questions," "I'll check consistency at the end," and the rest) is a rationalization, not a plan. Read that table whenever you feel the urge to skip a step. The short version: do the intake, ask one question per tool call, right-size the document set, and verify quality gates before marking anything final.

Gotchas — Common Orchestrator Mistakes

• Skipping Phase 0. The business concept interview is mandatory. Without it, every downstream document is built on assumptions.
• Asking inline questions. Use tool calls (e.g., AskUserQuestion) for ALL interview questions. Inline questions pollute conversation context and force users to type responses.
• Batching clarifying questions. One question per tool call. Multiple questions in one message produce partial or shallow answers.
• Generating all conditional documents. Not every project needs a disaster recovery plan or an SLO document. Right-size based on the project's actual stakes.
• Deferring consistency checks to the end. Check after each document. Naming mismatches compound if caught late.
• Not reading the skill's SKILL.md before invoking it. Each skill has its own interview process. Read it, then follow it.
• Treating the template as the output. The template is a skeleton. The interview produces the content that fills it.
• Silently overwriting documents on re-run. Never overwrite. Append new versions or archive old ones.
• Writing secrets into documents. Never write actual API keys, credentials, or connection strings. Reference by name/purpose only.

Key Concepts

The Skill Directory

Right-Sizing, Not Maximalism

A weekend side project and a payments platform do not need the same 15 documents. The point of the idea-intake conversation is to determine which conditional skills actually apply — producing every possible document regardless of project size defeats the purpose. When in doubt on a conditional skill, lean toward including it for anything with real users, money, or personal data involved, and toward skipping it for a prototype or internal experiment — and say which way you leaned and why.

One Skill at a Time, Never Batched

Invoke exactly one underlying skill's own mandatory clarifying interview at a time. Do not pre-ask questions belonging to a later skill just because they're on your mind — each skill's interview happens only when it's that skill's turn, using its own SKILL.md.

Interview Mechanism: All skill interviews use tool calls (e.g., AskUserQuestion) to present questions — NOT inline conversation. One question per tool call, multiple-choice options preferred, with "I don't know, you decide" as an escape hatch.

Cross-Document Consistency

After each new document is produced, check it against documents already written for this project: do entity names in the database design match the technical specification? Does the architecture document reflect roles defined in the access-control spec? Reconcile mismatches before moving on rather than letting them accumulate.

The Master Index Is the Deliverable That Ties It Together

The final output of this skill is not just a folder of documents — it's the master index (see template.md) that lists every document produced, its status, and the order a new reader (human or AI agent) should read them in to get full context fast.

Conflict Resolution

When your analysis conflicts with the user's stated preference:

1. Present both positions — show your analysis and their preference side by side
2. Explain the trade-off — what are the consequences of each choice?
3. Recommend with reasoning — state your recommendation and why
4. Respect the user's decision — they own the final call
5. Document the decision — record it as an [owner-specified] override with reasoning

Diagramming Model Selection

For system-architecture-document, do not default to one notation. Ask a short set of plain-language questions and recommend accordingly:

• How many people need to read and act on this document? (just you / a small team / a large org with multiple teams)
• Will this document need to stay accurate for years, or does the system change weekly right now?
• Do you need to show this to non-technical stakeholders, or only engineers?

Recommendation logic:

• Solo/small team, fast-moving, MVP stage → plain narrative + a couple of targeted diagrams + an ADR log
• Growing team, needs onboarding docs, moderate stability → full C4 (Context → Container → Component)
• Large org, multiple teams, formal governance needs → C4 plus a 4+1 view breakdown, or ArchiMate if they already use it elsewhere

Always state the recommendation with its reasoning and let the user override.

Application

Phase 0: Business Concept Completion (Mode A Only)

Before any technical skill runs, interview the user until the business idea itself is complete.

Interview Mechanism: Use tool calls (e.g., AskUserQuestion) to present questions — do NOT ask inline in the conversation. The user selects from options rather than typing responses. This prevents conversation pollution and ensures clean input capture.

Rules:

• One question per tool call
• Present multiple-choice options with a recommended answer
• Include "I don't know, you decide" as an escape hatch option
• Wait for the user's selection before proceeding to the next question

Standing constraint questions (ask once, early — every downstream document depends on these):

1. Team size and skill level (affects stack/framework recommendations)
2. Hosting/infra preference or constraint (self-hosted, cloud, existing vendor lock-in)
3. Budget sensitivity (affects managed-service vs self-hosted tradeoffs)
4. Timeline urgency (MVP-speed vs enterprise rigor)
5. Regulatory/compliance needs if known (data residency, PCI, GDPR, etc.)
6. Existing systems this must integrate with or avoid conflicting with