using-engineering-docs
/using-engineering-docs
The entry point for this plugin. Give it a raw project idea or concept and it takes over: runs a discovery conversation, decides which document skills apply and in what order, then generates that full document set one skill at a time. Use when you have an idea and don't yet know which documents you need.
- Author
- fattain-naime ↗
- Repository
- engineering-docs-agy ↗
- Licence
- MIT
- Last repository change
- 06.11.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 06.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
The entry point for this plugin. Give it a raw project idea or concept and it takes over: runs a discovery conversation, decides which document skills apply and in what order, then generates that full document set one skill at a time. Use when you have an idea and don't yet know which documents you need.
Arguments
/using-engineering-docs [your project idea, in your own words]
Original author description
The entry point for this plugin. Give it a raw project idea or concept and it takes over: runs a discovery conversation, decides which document skills apply and in what order, then generates that full document set one skill at a time. Use when you have an idea and don't yet know which documents you need.
How it works
- Purpose
- Input
- Mode Detection
- Anti-Rationalization
- Gotchas — Common Orchestrator Mistakes
- Key Concepts
- Application
- Output Structure
- Document Metadata Standard
- Security Policy
SKILL.md preview
---
name: using-engineering-docs
argument-hint: "[your project idea, in your own words]"
description: "The entry point for this plugin. Give it a raw project idea or concept and it takes over: runs a discovery conversation, decides which document skills apply and in what order, then generates that full document set one skill at a time. Use when you have an idea and don't yet know which documents you need."
intent: >-
Every other skill in this plugin assumes you already know which document you want. This skill removes that assumption. Most people starting a project do not think in terms of "I need a technical specification and then a system architecture document" — they think in terms of "I want to build X." This skill's entire job is to sit between a raw idea and the 22 specialist skills in this plugin: understand the idea well enough to know which documents a project of this shape actually needs, propose a sequence, and then execute that sequence end to end without ever asking the user to pick a skill by name. The person answers questions about their project; the agent handles every routing decision. The end state is a complete, cross-consistent document set thorough enough that another engineer — or another AI agent starting cold — could read it and build the entire thing to production without having to ask what was meant.
type: orchestrator
theme: engineering-docs
best_for:
- "Turning a raw business or product idea into a complete set of pre-development documents automatically"
- "Starting any new project when you don't know (and shouldn't have to know) which specific documents you need"
- "Handing a project to an AI coding agent and wanting the full context it would need already written down"
- "Working through documentation for a project idea interactively, one document at a time, with the right skill invoked automatically at each step"
scenarios:
- "I have an idea: an e-commerce site where customers build custom gift boxes by picking items, and the site recommends what pairs well or auto-builds a set from a short quiz. Help me turn this into everything needed to build it."
- "I want to build a subscription-based habit tracker app. I don't know what documents I need, just help me figure out and write whatever's necessary."
- "Here's a rough concept for an internal tool our support team needs. Take it from idea to something a developer could start building from."
- "We have an existing app and want to add a payment system. Help me document what's needed."
estimated_time: "1-2 hours for idea intake and planning, then 2-4 hours per document generated — varies by project size"
license: MIT
compatibility: Google Antigravity (AGY)
---
# 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 (e.g., `technical-blueprint`, `architecture-decision-record`, `database-design-document`, `api-design-document`, `test-strategy-document`, or `security-threat-model`).
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](reference.md#anti-rationalization) ("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; downstream docs rely on it.
- **Asking inline questions:** Always use tool calls (e.g., AskUserQuestion) for interview questions.
- **Batching questions:** One question per tool call prevents shallow or partial answers.
- **Generating all conditional documents:** Right-size to project needs; avoid document bloat.
- **Deferring consistency checks:** Validate entities and terminology incrementally after each doc.
- **Ignoring the skill SKILL.md:** Read each specialist skill guide before invoking it.
- **Treating templates as final output:** Fill skeletons with synthesized interview findings.
- **Silently overwriting documents:** Never overwrite on re-run; append versions or archive.
- **Exposing secrets:** Reference credentials by environment variable name only, never literal values.
---
## Key Concepts
### The Skill Directory
| Phase | Skill | Produces | Inclusion |
|:---|:---|:---|:---|
| 0 | `business-concept` | Problem, users, value proposition, monetization, constraints | Always |
| 0.5 | `project-plan` | Scope, milestones, RACI, timeline, work breakdown structure | Always |
| 0.6 | `user-personas-behavior` | User personas, jobs-to-be-done, success metrics, analytics plan | Always |
| 1 | `technical-feasibility-study` | Go/no-go on a specific risky technical approach | Conditional (if technical feasibility is uncertain) |
| 2 | `technical-specification` | Functional & non-functional requirements (SRS/TSD) | Always |
| 2.5 | `ux-flow-specification` | User journeys, screen-by-screen flow, every UI state | Conditional (skip for headless / API-only systems) |
| 3 | `system-architecture-document` | Overall structure — diagrams, tech stack, NFRs | Always |
| 3+ | `architecture-decision-record` | One immutable record per significant decision | Ad hoc (created throughout lifecycle) |
| 4 | `database-design-document` | ERD, schema, indexing, migration plan | Conditional (skip if no structured data to persist) |
| 5 | `api-design-document` | API contract, resources, auth, versioning | Conditional (if exposing or consuming APIs) |
| 5.5 | `admin-access-control-specification` | Roles, permission matrix, audit logging, break-glass | Conditional (if system requires multi-role RBAC) |
| 6 | `security-threat-model` | STRIDE-based threat model and risk register | Conditional (if handling accounts, payments, or PII) |
| 7 | `design-system-specification` | Visual design tokens, components, accessibility | Conditional (skip for API-only or CLI tools) |
| 8 | `technical-blueprint` | Detailed design for one specific feature/component | Ad hoc (per non-trivial feature identified) |
| 8.5 | `implementation-plan` | Dependency-ordered build sequence, phase gates | Always |
| 9 | `test-strategy-document` | Testing pyramid, mocking strategy, CI gates | Always |
| 10 | `deployment-plan` | Release strategy, go/no-go gate, rollback | Always |
| 11 | `technical-runbook` | On-call operations manual | Conditional (for production environments) |
| 11.5 | `disaster-recovery-plan` | RTO/RPO, backup strategy, failover runsheets | Conditional (if downtime carries business risk) |
| 11.6 | `slo-error-budget-document` | Reliability targets, error budget, burn-rate alerts | Conditional (when user-facing uptime targets matter) |
| ongoing | `incident-postmortem` | Blameless review of a real incident | Reactive (post-incident review) |
### 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`, evaluate audience and volatility:
- Solo/small team, MVP stage: Plain narrative + targeted diagrams + ADR log
- Growing team, onboarding needs: Full C4 model (Context → Container → Component)
- Large org, governance requirements: C4 plus 4+1 view breakdown (or ArchiMate)
Always state the recommendation with its reasoning and confirm with the user.
---
## 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 Protocol:** Use tool calls (e.g., `AskUserQuestion`) to present questions one at a time with multiple-choice options, a recommended answer, and "I don't know, you decide" as an escape hatch.
**Standing constraint questions (ask once, early — every downstream document depends on these):** (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
**Business concept questions (one at a time, multiple choice preferred):**
1. **The core idea:** What is being built, and what's the single most important thing it needs to do well?
2. **Who it's for:** Who are the users? What problem are they currently solving without this product?
3. **Value proposition:** Why would someone choose this over alternatives (including doing nothing)?
4. **Monetization:** How does this make money? (subscription, one-time, freemium, ads, internal cost savings)
5. **Must-have vs nice-to-have:** What's the minimum that's useful? What can wait for v2?
6. **Timeline and budget:** When does this need to exist? What's the rough budget?
**Escape hatch:** Every question must accept "I don't know, you decide" as a valid answer. When the user takes that path:
1. Pick the most reasonable option given everything gathered so far
2. Record the choice AND the reasoning in the document, tagged as `[agent-decided]` rather than `[owner-specified]`
3. Continue without blocking
**Output:** `1-business-plan.md` — the foundational document every later skill reads from.
**Quality gate:** Cannot proceed until the business concept is clear enough that a stranger could understand what's being built, for whom, and why.
---
### Phase 1: Idea Intake & Project Characterization
**For Mode A:** The business concept (Phase 0) IS the idea intake. Summarize the key facts and proceed to skill selection.
**For Mode B:** Read existing docs or scan the codebase. Ask the user to confirm or correct your inference about the current state.
**Then:** Using the Skill Directory, determine which conditional skills apply to this specific project, and note the "always core" ones. Do this internally — the output is a plan, not a request for the user to choose skills.
---
### Phase 2: Sequencing Plan Preview
Present the resulting document list and order in a few lines — what will be produced, roughly in what order, and a one-line reason for any conditional skill included or excluded. Invite the user to redirect ("skip the design system doc, we're API-only") but do not turn this into a multi-question gate — proceed once there's no objection.
**Create the progress ledger:** Initialize the master index (`index.md`) using the template. This serves as the durable progress tracker that survives context compaction.
---
### Phase 3: Sequential Document Generation
For each document in the plan, in order:
1. **Read the skill's SKILL.md** to know what that document needs.
2. **Read ALL prior documents** in `.engineering-docs/` to extract already-known information (team size, budget, timeline, tech stack, constraints, etc.).
3. **Diff:** What does this document need that isn't already known from prior documents?
4. **Ask ONLY the truly missing items** — maximum 2-3 questions per skill. If information exists in any prior document, USE IT — do not re-ask.
5. **Generate the document** using the skill's template.
6. **Write it to `.engineering-docs/<N>-<slug>.md`** with the metadata header (see Document Metadata below).
7. **Update `index.md`** with the new document's status.
8. **Confirm with the user** before moving to the next — don't silently chain documents with no checkpoint.
**Context Passing Rules:**
- Read prior documents in `.engineering-docs/` before interviewing.
- Never re-ask questions answered in earlier documents (business plan, project plan, architecture).
- Generate `architecture-decision-record` and `technical-blueprint` documents ad hoc when decisions or features arise.
---
### Phase 4: Consistency & Completeness Pass
After each document (incremental), and again as a final pass before the doc set is declared ready, do a lightweight cross-check:
- Does the architecture doc's chosen approach match what the database and API docs assume?
- Does every endpoint in the API doc have a corresponding entity in the database doc, or a documented external dependency?
- Does the security threat model cover every external-facing API surface listed in the API doc?
- Does the test strategy reference every feature blueprint that exists?
- Do entity names, role names, and terminology match across all documents?
Where a mismatch is found, surface the conflict to the user in plain language with a recommended resolution — same as any other question. Do not silently pick one.
**Definition of done per document type:** each skill defines its own completeness bar. Check against this bar before marking a document `status: final`.
---
### Phase 5: Master Project Index
Produce the master index (using `template.md`) — the single document that lists everything produced, its status, and the recommended reading order for anyone (or any agent) picking up the project cold.
---
### Phase 6: Revision (After User Review)
When the user requests changes to any document:
1. Review user feedback and assess cross-document impacts.
2. Apply changes and update metadata (`last_updated`, `owner_reviewed`).
3. Re-verify cross-document consistency and update `index.md`.
4. Confirm changes with the user before proceeding.
---
## Output Structure
```
<project root>/
.engineering-docs/
index.md
1-business-plan.md
2-project-plan.md
3-user-personas.md
4-feasibility-study.md (if applicable)
5-technical-specification.md
6-ux-flow-specification.md (if applicable)
7-system-architecture.md
8-database-design.md (if applicable)
9-api-design.md (if applicable)
10-admin-access-control.md (if applicable)
11-security-threat-model.md (if applicable)
12-design-system.md (if applicable)
13-blueprint-<feature-name>.md (one per feature, numbered sub-sequence)
14-implementation-plan.md
15-test-strategy.md
16-deployment-plan.md
17-technical-runbook.md (if applicable)
18-disaster-recovery.md (if applicable)
19-slo-error-budget.md (if applicable)
adr/
0001-<decision-slug>.md (ADRs accumulate over the project's life)
```
### Versioning on Re-Run
If the orchestrator is invoked again later (Mode B, or a Mode A project revisited), never overwrite an existing numbered file. New or revised content either:
- Appends a new numbered file continuing the existing sequence (e.g., `18-blueprint-checkout-v2.md`), or
- If truly replacing a stale document, moves the old one to `.engineering-docs/archive/` with its original name and a timestamp suffix, and the new version takes the next available number.
Either way, `index.md` always reflects current reality, and nothing is silently lost.
---
## Document Metadata Standard
Every generated document opens with a frontmatter block so any agent parsing the folder can understand a file's status without reading its full body:
```yaml
---
title: <document title>
skill: <source skill name>
status: draft | final | superseded
owner_reviewed: true | false
last_updated: <date>
depends_on: [<other doc filenames this one assumes as context>]
supersedes: <filename, if this replaces an earlier doc>
---
```
`owner_reviewed: false` specifically flags any document containing one or more `[agent-decided]` answers from the escape hatch — signals to a human reviewer exactly where to focus if they want to sanity-check before build starts.
---
## Security Policy
Never write actual secrets, credentials, API keys, or connection strings into any generated document — even if the user provides them during the interview. Where a document needs to reference such a value (e.g., "the payment provider's API key"), reference it by name/purpose only (e.g., `STRIPE_SECRET_KEY`, to be set via environment variable) and never the literal value.
---
## Session Persistence
Interviews for a full Mode A pipeline can span multiple sessions. The orchestrator must be able to stop and resume without restarting:
- 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 of `using-engineering-docs` in a project that already has a partial `.engineering-docs/` folder, read that state first and resume exactly where it left off — do not re-ask anything already answered.
---
## Context Management & Thresholds
For projects requiring 10+ documents, context window management is critical:
- **Between major phases**, suggest starting a fresh session if context is getting large. A fresh session resumes directly from `index.md`.
- **Each document generation** is self-contained: the skill reads prior docs from files on disk, not conversational memory.
- If the agent begins re-asking already answered questions, check [reference.md](reference.md#context-window-thresholds) and recommend starting a fresh session.
- **`index.md`** serves as the durable progress tracker across session boundaries.
---
## Subagent Delegation
For projects requiring 10+ documents, delegate document generation to subagents to preserve the orchestrator's context for coordination. The full recipes — when to delegate, how to prepare the subagent prompt, and which documents may run in parallel versus which must stay sequential — are in [reference.md](reference.md#subagent-delegation); read that section before delegating.
---
## Standalone Skill Usage
Every skill remains independently callable outside the orchestrator for users who already have partial documentation and want a single artifact (e.g., calling `engineering-docs:security-threat-model` directly on an existing system). Standalone mode skips the orchestrator's phase sequencing and context-loading — it interviews for exactly what that one skill needs.
---
## Handoff
**Reads from:**
- User's raw project idea or existing codebase
- Existing `.engineering-docs/` folder (if brownfield)
- Standing constraints: team size, hosting, budget, timeline, compliance
**Feeds into:**
- Every downstream skill in the pipeline — provides business context, constraints, and prior documents
- The master `index.md` — tracks progress and reading order
- Any AI coding agent starting cold — the complete document set is the handoff artifact
---
## Quality Gate
Before declaring the document set complete, verify:
- [ ] Mode detection was correct (greenfield vs brownfield)
- [ ] Phase 0 (business concept) was completed for Mode A
- [ ] Standing constraint questions were asked once, early
- [ ] Each document was generated using its skill's template
- [ ] Each document has the required metadata frontmatter
- [ ] Incremental consistency checks were run after each document
- [ ] Final consistency pass found no unresolved conflicts
- [ ] Master index (`index.md`) is complete and accurate
- [ ] All `[agent-decided]` items are flagged in the index
- [ ] No secrets, credentials, or API keys appear in any document
- [ ] Reading order in index matches dependency order
- [ ] "If you only read three documents" pointer is accurate
## Error Handling
The playbook for missing templates, failed document generation, skipped documents, and revisiting finished documents is in [reference.md](reference.md#error-handling). The short version: never block the pipeline — save partial work as `status: draft`, record decisions in `index.md`, and surface the situation to the user with options.
## Progress Reporting
After each document completes, report progress to the user:
```
Document 5 of 12 complete: system-architecture-document
Status: draft (awaiting your review)
Next up: database-design-document
```
Include:
- The document number and total count
- The document name and status
- Any `[agent-decided]` items that need human review
- The next document in the sequence
- Estimated time remaining based on remaining documents
## Next Steps
After the full document set is complete:
- Hand the `.engineering-docs/` folder to a coding agent — it has everything needed to build the project
- Use the master `index.md` as the reading guide for any new team member or agent
- Return to any individual skill directly if a single document needs updating (e.g., `engineering-docs:technical-runbook`)
Files in this package (3)
- SKILL.md 25 KB
- reference.md 6 KB
- template.md 7 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · fattain-naime/engineering-docs-agy | 100 | MIT |
| fattain-naime/engineering-docs | 100 | MIT |
Database snapshot: 13.11.2026 · package version bc41d229b9bf (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100arn-spark-discover
This skill should be used when the user says "discover", "product discovery", "arn discover", "help me define this product", "what should I build", "product concept", "define the product", "let's figure out what to build", "vision for this project", "shape this idea", "new… - 100idea-forge
Run any raw idea through a multi-stage R&D pipeline that interprets, expands, scores, and converts it into an actionable engineering plan. Always trigger immediately when the user's message starts with "idea". Also trigger on "ideaforge", "analyze this idea", "expand this… - 100idea-forge
Run any raw idea through a multi-stage R&D pipeline that interprets, expands, scores, and converts it into an actionable engineering plan. Always trigger immediately when the user's message starts with "idea". Also trigger on "ideaforge", "analyze this idea", "expand this… - 90product-discovery
Run product discovery to identify what to build. Use when the user says "product discovery", "how do I know what to build", "validate this idea", "talk to customers", "are we building the right thing", "discovery process", or wants to reduce the risk of building something users… - 100frame
Use this skill whenever someone has a raw idea, feature request, bug complaint, or vague product concept that needs to be investigated before any solution design begins. This is the FIRST step in the Shape Up pipeline. Frame before you shape. If the user says "we need X", "what… - 100workflow-explore-idea
Guided idea exploration workflow that develops a raw concept into a mature, PRD-ready requirement through structured Socratic interviews. Use when user wants to explore, stress-test, or develop an idea — triggers at "explore idea", "I have an idea", "let's explore", or similar.…