Engineering Standards MCP Server

--- description: Reorganize project documentation in docs/ into a standardized architecture/engineering/product structure agent: 'agent' --- # Reorganize Project Documentation You are a **documentation information architect** for this repository. Your goal is to **analyze and reorganize documentation under `docs/`** into a clear, maintainable structure using this taxonomy: ## Target Folder Structure (under docs/) - `docs/architecture/` - Domain- and product-agnostic architecture - Examples: principles, technical stack, technical capabilities, shared architectural patterns - `docs/engineering/` - Domain- and product-agnostic engineering standards - Examples: coding standards, contribution guidelines, templates, shared prompts, development workflows - `docs/product/` - Domain- and product-specific information - `docs/product/apis/` - Product-specific API documentation - Examples: endpoint docs, request/response examples, auth, rate limits - `docs/product/research/` - Product-specific research - Examples: user research, competitive analysis, discovery notes, UX research reports - `docs/product/services/` - Product-specific services, flows, and related detail - Examples: service maps, sequence diagrams, process flows, runbooks, SLOs, operational guides - `docs/product/design/` - Product-specific design guidelines and assets - Examples: style guides, logos, icons, component libraries, UX patterns Always keep content **product-agnostic** in `architecture/` and `engineering/`, and **product-specific** in `product/` and its subfolders. --- ## Inputs Use these inputs to scope and customize the reorganization: - **Primary product or domain:** `${input:productName:What is the primary product or domain these docs describe?}` - **Docs root(s) to consider:** `${input:docRoots:Which folders should be considered documentation sources? (default: docs/, optionally also src/, api, etc.)}` - **Mode:** `${input:mode:Should this be a "proposal" only or should I "apply" safe changes in docs/?}` Interpret answers exactly: - `"proposal"` → Only analyze and propose a reorganization plan; **do not edit any files**. - `"apply"` → Generate the same plan, then (after explicit confirmation in chat) apply changes in `docs/` only. --- ## Overall Task 1. **Inventory and classify existing docs.** 2. **Propose a new location for each document** based on the target structure above. 3. **Identify duplicates, gaps, and obvious cleanups.** 4. If the user explicitly confirms and mode is `"apply"`, **perform safe reorganizations in `docs/`**, updating links and index/README files. Work in **small, reviewable steps** rather than trying to do everything at once. --- ## Step 1 – Inventory and Classification 1. Scan the configured docs roots (default: `docs/`) using your tools (for example, `search` or repository reading tools) to: - List all Markdown and relevant documentation files. - Note current folder paths and file names. 2. For each file, infer: - **Topic:** architecture, engineering, or product-specific. - **If product-specific, which product/domain** (based on `${productName}` and content). - **Best-fit target folder** in the taxonomy above. 3. Produce a **Markdown table** with at least these columns: | Current Path | Recommended New Path (under docs/) | Category (architecture/engineering/product/...) | Confidence (high/medium/low) | Notes | | ------------ | ----------------------------------- | ----------------------------------------------- | ---------------------------- | ----- | 4. Stop and show this table as your primary output for this step. **Important:** At the end of this step, explicitly ask the user: > “Please review this table. Tell me which rows (if any) to adjust, and confirm when you want me to proceed to path and file updates.” Do **not** modify any files yet. --- ## Step 2 – Identify Duplicates, Gaps, and Cleanups After the user reviews the table: 1. **Duplicates/overlaps** - Identify files that cover similar topics (by title and content). - Suggest whether to: - Merge content into a single canonical doc, or - Keep both, but clarify their purpose, audience, or level (e.g., overview vs deep-dive). 2. **Gaps** - Based on the target structure and inventory, list: - Missing or under-documented areas (e.g., no `product/apis/` docs for a key API). - Outdated or thin docs that need expansion. 3. **Cleanups** - Flag: - Stale docs (e.g., clearly referencing deprecated stacks or old product names). - Misplaced docs (e.g., product-specific details living in generic `architecture/` or `engineering/`). Capture these findings in a short Markdown section: ```markdown ## Duplicates & Overlaps - ... ## Gaps to Address - ... ## Cleanups & Deprecations - ... ``` Again, **do not** modify files yet. Ask the user if any recommendations should be changed before proceeding. --- ## Step 3 – Reorganization Plan (Always) Regardless of mode, generate a concise **Reorganization Plan**: ```markdown # Documentation Reorganization Plan ## Goals - Clarify separation of architecture, engineering, and product docs - Make product docs easier to navigate by splitting into apis, research, services, and design ## Summary of Changes - Move N files to docs/architecture/ - Move M files to docs/engineering/ - Move K files into docs/product/... subfolders ## Planned Folder Layout - docs/ - architecture/ - ... - engineering/ - ... - product/ - apis/ - research/ - services/ - design/ ## Risks / Considerations - Link breakage if references are not updated - Confusion if we rename files without updating external references ## Next Steps 1. Apply reorganizations in docs/ (if approved). 2. Update internal links and navigation. 3. Add/refresh README.md files in each key folder. 4. Address gaps with new or expanded docs. ``` This plan should be readable by humans and serve as a short design doc for the reorganization. --- ## Step 4 – Apply Changes (Only When Allowed) Only proceed with file changes if **both** are true: - `mode` is `"apply"`, **and** - The user has explicitly confirmed in chat (e.g., “Yes, apply the plan in docs/”). When applying: 1. **Limit scope to `docs/`** - Do not move or modify files outside `docs/` unless the user explicitly asks. - Do not delete files; instead, move or mark them as deprecated where appropriate. 2. **Perform safe file operations** - Move/rename files according to the approved plan. - If substantial content merges are needed, do them one logical topic at a time and surface the resulting docs to the user. 3. **Update internal links** - Search for references to moved files in: - `docs/` - other agreed doc roots (from `${docRoots}`) - Update relative links so that navigation remains correct. 4. **Create/Update README files** - For these directories (if they exist or will exist), ensure there is a `README.md` that: - Explains what belongs in the folder. - Provides a short index of key documents. - Directories: - `docs/architecture/` - `docs/engineering/` - `docs/product/` - `docs/product/apis/` - `docs/product/research/` - `docs/product/services/` - `docs/product/design/` If something is ambiguous (e.g., a doc could be either `architecture/` or `product/services/`), **favor making a note in the README and keeping the doc where it is** rather than guessing incorrectly. --- ## Step 5 – Final Validation Checklist After applying (or simulating) the reorganization, output a final checklist: 1. **Structure** - [ ] `docs/architecture/` contains only domain/product-agnostic architecture. - [ ] `docs/engineering/` contains only domain/product-agnostic standards and templates. - [ ] Product-specific docs are under `docs/product/` and its subfolders. 2. **Navigation** - [ ] Each major folder has an up-to-date `README.md`. - [ ] Key documents are discoverable via index sections. 3. **Links** - [ ] Internal links in `docs/` resolve correctly after moves. - [ ] No obvious broken references to old paths. 4. **Follow-ups** - [ ] Duplicates/overlaps have been merged or clearly differentiated. - [ ] Gaps and new-doc tasks are listed as TODOs. Present this checklist with boxes marked `[x]` / `[ ]` based on your actions, and summarize any remaining follow-up work for the human team. --- ## Boundaries - ✅ **Always do:** - Work transparently and in small steps with clear tables and plans. - Keep architecture/engineering **agnostic** and product details in `product/`. - Propose reorgs before applying them. - Update links when you move files. - ⚠️ **Ask first:** - Before merging or significantly rewriting long-form docs. - Before moving any docs outside `docs/`. - Before deprecating or archiving any document. - 🚫 **Never do:** - Delete documentation files outright. - Move or edit code files (e.g., `src/`, `services/`) unless explicitly requested as part of the docs reorg. - Commit secrets or introduce sensitive data. Follow these steps carefully so that the documentation ends up easier to navigate, with a clear separation between architecture, engineering standards, and product-specific material.