Setup Ssot

---
name: setup-ssot
description: >
  Set up SSOT documentation: docs/architecture.md, ADR structure, and CODEMAPS
  for codebase navigation. Called by init or standalone.
  Trigger phrases: "setup ssot", "create architecture docs", "setup ADR structure",
  "create CODEMAPS", "document architecture".
argument-hint: "[--architecture-only] [--adr] [--codemaps]"
---

# /setup-ssot

Configures SSOT documentation: `docs/architecture.md`, `docs/adr/`, `docs/CODEMAPS/`.

## Mode Detection

Read `.claude/starter-context.json` if it exists:
- **Exists:** use `architecture`, `ssot.adr`, `ssot.codemaps` fields — skip questions
- **Missing (standalone):** ask which outputs to create, then gather architecture details

## Flags

- `--architecture-only` — write `docs/architecture.md` only, skip ADR and CODEMAPS
- `--adr` — include ADR structure
- `--codemaps` — include CODEMAPS structure
- Flags can be combined: `--adr --codemaps`

## Standalone Questions (when no context file)

Ask once, grouped:

**Which outputs to create?**
- [ ] `docs/architecture.md` — architecture overview
- [ ] `docs/adr/` — ADR structure with ADR-0001
- [ ] `docs/CODEMAPS/` — codebase navigation guide

**For each selected output, gather:**
- Project name and type (web app / API / CLI / lib)?
- Primary stack (language + framework)?
- Architecture style (monolith / microservices / modular monolith / event-driven)?
- Key layers and their directories?
- Entry points?
- External dependencies (DB, queue, cache, external APIs)?
- Directories/files that must NOT be edited manually?
- Sensitive areas requiring extra care?

## Output 1: `docs/architecture.md`

Draft from `starter-context.json.architecture` (or standalone answers). Use actual paths, not generic placeholders:

```markdown
# Architecture Overview

*Generated by /shipwithai-starter on [DATE]. Edit directly.*

## System overview

[Project name] is a [type] built with [stack].
Architecture style: [monolith / microservices / modular monolith / event-driven].

## Key layers

| Layer | Directory | Responsibility |
|-------|-----------|----------------|
| [API] | [src/routes/] | [HTTP handlers, validation] |
| [Service] | [src/services/] | [Business logic] |
| [Data] | [src/db/] | [Database access, ORM] |

## Entry points

- `[src/index.ts]` → [main server, port 3000]
- `[src/worker.ts]` → [background job processor]

## External dependencies

| Service | Purpose | Connection |
|---------|---------|------------|
| [PostgreSQL] | [Primary database] | [DATABASE_URL] |
| [Redis] | [Session cache] | [REDIS_URL] |

## Key directories

[paste tree output or scan result]

## What to know before touching code

[Gotchas: generated dirs, build order, sensitive areas]
```

### Existing file behavior

If `docs/architecture.md` already exists, ask: **Overwrite / Merge / Skip?**
- **Overwrite:** replace entirely with new draft
- **Merge:** append new sections that don't exist, keep existing content unchanged
- **Skip:** leave untouched

## Output 2: ADR Structure

```
docs/adr/
  README.md              ← index + how to create new ADRs
  ADR-0001-initial-architecture.md
```

`docs/adr/README.md` template:

```markdown
# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for [Project name].

## What is an ADR?

An ADR documents a significant architectural decision: the context, the options
considered, and the rationale behind the choice.

## How to create a new ADR

1. Copy `adr-template.md` (ask Claude: "create a new ADR for [topic]")
2. Name it `ADR-XXXX-short-title.md` (increment the number)
3. Fill in all sections — do not leave placeholders
4. Update the index table below

## Index

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [ADR-0001](ADR-0001-initial-architecture.md) | Initial Architecture | Accepted | [DATE] |
```

`ADR-0001` is drafted from architecture answers using the format in `adr-template.md`.

## Output 3: `docs/CODEMAPS/`

```
docs/CODEMAPS/
  README.md              ← how to use CODEMAPS
  overview.md            ← high-level codebase map
```

`docs/CODEMAPS/README.md` template:

```markdown
# CODEMAPS

Navigation guides for this codebase. Read the relevant map before touching code
in a new area.

## How to use

Before working in an unfamiliar part of this codebase:
1. Find the relevant map in this directory
2. Read the entry points, data flows, and gotchas
3. Update the map when you make significant structural changes

## Maps

| File | Covers |
|------|--------|
| [overview.md](overview.md) | Full codebase — start here |
```

`docs/CODEMAPS/overview.md` template:

```markdown
# Codebase Overview

*Generated by /shipwithai-starter on [DATE]. Update when structure changes.*

## Entry points

| File | Purpose |
|------|---------|
| [src/index.ts] | [Main server — starts HTTP on port 3000] |

## Key directories

| Directory | Purpose |
|-----------|---------|
| [src/routes/] | [API route handlers] |
| [src/services/] | [Business logic] |
| [src/db/] | [Database access] |

## Data flow

[Request] → [src/routes/] → [src/services/] → [src/db/] → [Response]

## What NOT to edit manually

- [src/generated/] — auto-generated, overwritten on build

## Sensitive areas

- [auth/] — changes require security review
- [payments/] — changes require payment team sign-off
```

## Write Rules

- Use actual directory paths from codebase scan — no generic placeholder text
- Check each output separately: user may select only `architecture.md` and skip ADR
- Never silently overwrite existing files — always ask Overwrite / Merge / Skip
- If a selected output directory already exists with content, treat as existing and ask