accelint-architecture-doc

What this skill does

# Architecture Doc

Generate or update a living `ARCHITECTURE.md` for the current codebase — a document that gives agents and engineers an instant, complete picture of how the system is structured, what it uses, and how it deploys.

## NEVER Do When Writing Architecture Docs

- **NEVER overwrite ARCHITECTURE.md without reading it first** — existing sections contain human-authored context (deployment specifics, security decisions, roadmap notes) that codebase scanning cannot recover. Always read before touching.
- **NEVER fabricate infrastructure details** — if you cannot determine the cloud provider, deployment model, or data store from the codebase, mark it `<!-- TODO: fill in -->` rather than guessing. Wrong infrastructure docs cause real confusion during incidents.
- **NEVER paste the entire directory tree verbatim** — the Project Structure section should show meaningful architectural layers, not every file. Collapse noisy directories (`node_modules`, `dist`, `.git`, `__pycache__`) and annotate each entry with its architectural role.
- **NEVER skip drift detection in refresh mode** — scan the codebase for changed signals before running any interview. Asking questions about unchanged sections wastes the user's time.
- **NEVER leave all 11 sections as `<!-- TODO -->`** — scan aggressively first. Most sections can be at least partially filled through inference. A document full of TODOs appears complete but misleads every reader.
- **NEVER document internal implementation details in the System Diagram (Section 2)** — that section is a 10,000-foot view of components and data flow. Database schemas, function signatures, and module internals belong elsewhere.
- **NEVER run discovery serially when subagents are available** — Phase 1 spawns parallel subagents for different discovery domains. Serial scanning wastes time on codebases with many config files spread across directories.

## Before Writing, Ask

### Is this root or package level?
- **Are we at the repo root or inside a monorepo package?** Check for `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `workspaces` field in `package.json`. If inside a package, check whether a root-level ARCHITECTURE.md already exists.
- **Root-level docs** cover the whole system — all services, shared infra, top-level architecture. Package-level docs focus on that package and reference the root.

### Is this a create, restructure, or refresh?
- **Does ARCHITECTURE.md already exist?** If yes, read it before scanning — understand what's accurate vs. drifted.
- **Does it follow the template?** If not, proactively offer to restructure it before doing anything else.

### What can I infer vs. what must I ask?
- **Use parallel subagents for discovery.** Spawn them simultaneously across discovery domains — don't scan serially.
- **Reserve questions for genuine gaps** — deployment specifics, roadmap items, and security decisions that aren't in the code.

---

## Phases

### Phase 0 — Scope and File State Detection

Run both steps before any scanning or interview. Announce findings and confirm mode with the user.

---

#### Step 1 — Monorepo Scope Check

Determine whether the current working directory is a monorepo root or a package inside a monorepo.

**Monorepo signals to check:**

| Signal | File |
|--------|------|
| PNPM workspaces | `pnpm-workspace.yaml` |
| npm/Yarn workspaces | `package.json` → `workspaces` field |
| Turborepo | `turbo.json` |
| Nx | `nx.json` |
| Lerna | `lerna.json` |
| Package inside monorepo | Parent dirs contain any of the above |

**If at the monorepo root:**
- Generate a root-level ARCHITECTURE.md covering the full system — all services, shared infra, and how packages relate.
- Within Section 3 (Core Components), create a subsection per significant package rather than treating the repo as a single app.
- In Section 1 (Project Structure), show the workspace layout with each package's role annotated.

**If inside a monorepo package:**
1. Check whether a root-level ARCHITECTURE.md exists above the current directory.
2. If a root doc exists, read it and announce:
   > "I found a root-level ARCHITECTURE.md at [path]. I'll use it as context and generate a package-specific doc here that references it rather than duplicating shared infra."
   The package-level doc should include a header reference:
   ```markdown
   <!-- Part of monorepo: see [relative path to root ARCHITECTURE.md] for system-wide architecture -->
   ```
3. If no root doc exists, offer to generate it first or generate the package-level doc standalone.
4. Package-level docs focus on: this package's purpose, its internal structure, its dependencies on other packages, and any package-specific deployment or config details.

**If not a monorepo:** proceed normally — ARCHITECTURE.md covers the whole project.

---

#### Step 1.5 — Check for Related Documents

Before detecting ARCHITECTURE.md state, check for related onboarding documents:

1. **Check for openspec/config.yml or openspec/config.yaml**
   - If exists: Read it to extract stack facts (runtime, frameworks, libraries, patterns)
   - Use this info to pre-fill tech stack sections and avoid redundant scanning
   - Note its existence for cross-referencing in generated doc
   - Announce: "Found openspec/config.yml — I'll use it as the source of truth for stack facts and coding patterns."

This reduces scanning work and ensures consistency with the project's defined stack.

---

#### Step 2 — File Detection

```
Does ARCHITECTURE.md exist at the target location?
│
├── No → MODE 1: Create
│         Run Phase 1 → Phase 2 → Phase 3 in full.
│
└── Yes → Read the file fully, then assess:
          │
          ├── Empty or near-blank (< ~10 meaningful lines)?
          │     → MODE 1: Create (confirm first)
          │
          ├── Follows the template structure?
          │   (Has ≥3 of: ## 1. Project Structure, ## 2. High-Level
          │    System Diagram, ## 3. Core Components, ## 4. Data Stores,
          │    ## 6. Deployment & Infrastructure)
          │     → MODE 2: Refresh
          │       Drift detection + targeted questions for changed or
          │       missing sections only.
          │
          └── Has real content but does NOT follow the template?
                → MODE 3: Restructure (offer proactively — see below)
```

**MODE 3: Restructure** — When the file has real content in an unrecognised shape, surface this immediately and offer options before doing anything else:

> "ARCHITECTURE.md exists but doesn't follow the standard template structure. I recommend restructuring it — this makes it consistent for agents and engineers onboarding to the codebase. How would you like to proceed?
>
> **(a) Restructure** *(recommended)* — I'll import your existing content into the 11-section template, fill gaps with codebase scanning, and show a full preview before writing anything.
>
> **(b) Append** — I'll add the missing template sections below your existing content without modifying what's already there.
>
> **(c) Dry run** — I'll show exactly what the restructured doc would look like with no filesystem changes. Use this to evaluate fit before committing."

If **(a)** is chosen: carry all existing content forward into the appropriate template sections. Flag any content that doesn't map cleanly — present it to the user and ask where it belongs rather than silently dropping it.

---

### Phase 1 — Parallel Discovery via Subagents

Spawn discovery subagents in parallel — don't scan serially. Each agent focuses on one domain and returns structured findings. Wait for all agents to complete, then merge results before Phase 2.

**Spawn these agents simultaneously:**

**Agent A — Project Identity & Structure**
- Read README.md, package.json / pyproject.toml / go.mod / Cargo.toml for project name and description
- List the top 2–3 levels of the directory tree (exclude `node_modules`, `dist`, `.git`, `__pycache__`, `.next`, `build`)
- Identify monorepo workspace packages and