# Onboarding document templates

The six-document onboarding suite, with structure and generation process for each. Load this when you're about to write any of the six docs — the SKILL.md keeps the operational steps; this file keeps the detail.

Where SKILL.md says "follow the template in references/document-templates.md", that means: open this file, find the matching document section, follow its **Structure** and **Generation Process** blocks.

---

## Document 1: Getting Started Guide

**Purpose:** New developer goes from zero to running tests in under 5 minutes.

**File:** `docs/getting-started.md`

**Structure:**

```markdown
# Getting Started

## Prerequisites
{List exact versions of required tools: Node.js 20+, Python 3.11+, Docker, etc.}
{Include installation links for each}

## Quick Start (5 minutes)

### 1. Clone the Repository
{exact clone command}

### 2. Install Dependencies
{exact install command(s)}

### 3. Set Up Environment
{copy .env.example, fill in required values}
{note which values need real credentials vs. can use defaults}

### 4. Start Services
{Docker compose up or equivalent}
{what services start, what ports they use}

### 5. Run Tests
{exact test command}
{what to expect: "You should see X tests passing"}

### 6. Start the Application
{exact start command}
{where to access it: "Open http://localhost:3000"}

## Troubleshooting
{Top 3-5 issues new developers hit and how to fix them}
```

**Generation Process:**

1. **Detect Prerequisites**
   - Read project config files (package.json, pyproject.toml, go.mod)
   - Check Dockerfile for base image (reveals required runtime versions)
   - Check docker-compose.yml for required services
   - Check .env.example for required variables

2. **Extract Commands**
   - Install: `npm install`, `pip install -r requirements.txt`, etc.
   - Start: `npm run dev`, `docker compose up`, etc.
   - Test: `npm test`, `pytest`, `go test ./...`, etc.
   - Read package.json scripts or Makefile targets

3. **Verify by Execution**
   - If possible, run the commands to verify they work
   - Note any commands that require special setup
   - Document actual output so reader knows what to expect

4. **Common Troubleshooting**
   - Check `aiwiki/gotchas/` for setup-related gotchas
   - Check project issues/PRs for setup problems
   - Include: port conflicts, Docker issues, env var issues, version mismatches

---

## Document 2: Architecture Overview

**Purpose:** Developer understands what the project does and how it is organized.

**File:** `docs/architecture-overview.md`

**Structure:**

```markdown
# Architecture Overview

## What This Project Does
{One paragraph: what problem it solves, who uses it}

## System Diagram
{ASCII diagram showing major components and their relationships}

## Directory Structure
{Annotated tree showing what each major directory contains}

## Key Components
### {Component 1}
- **Purpose**: {what it does}
- **Location**: {directory/file}
- **Key files**: {most important files to understand}
- **Depends on**: {other components it uses}

### {Component 2}
...

## Data Flow
{How data moves through the system: request -> handler -> service -> database}
{Sequence diagram for the most common operation}

## Technology Stack
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | {React, Vue, etc.} | {User interface} |
| Backend | {Express, FastAPI, etc.} | {API server} |
| Database | {Postgres, MongoDB, etc.} | {Data persistence} |
| Cache | {Redis, etc.} | {Session/data caching} |
| Queue | {RabbitMQ, etc.} | {Async job processing} |

## Key Patterns
{Design patterns used in this project: repository pattern, service layer, etc.}
{Link to relevant code examples}
```

**Generation Process:**

1. **Map Project Structure**
   - Read directory tree (top 3 levels)
   - Identify entry points (main files, index files, app files)
   - Identify configuration files

2. **Identify Components**
   - Look for common patterns: routes/, controllers/, services/, models/
   - Read import graphs to understand dependencies
   - Identify the "core" vs "infrastructure" code

3. **Generate Diagrams**
   - Use ASCII box-and-arrow diagrams (readable everywhere — terminal, editor, agent context)
   - Component diagram for system overview
   - Sequence diagram for most common user flow

4. **Extract Technology Stack**
   - From package.json dependencies, pyproject.toml, go.mod
   - From Docker configuration
   - From infrastructure files (terraform, serverless, etc.)

---

## Document 3: Local Environment Setup

**Purpose:** Detailed setup instructions for the full development environment.

**File:** `docs/local-setup.md`

**Structure:**

```markdown
# Local Environment Setup

## Required Tools
{Detailed list with version requirements and install instructions}

## Docker Setup
{If applicable: what containers are needed, how to start them}
{Port mappings, volume mounts, network configuration}

## Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| DATABASE_URL | Yes | - | PostgreSQL connection string |
| API_KEY | Yes | - | Third-party API key (get from {source}) |
| DEBUG | No | false | Enable debug logging |

## Database Setup
{How to create the database}
{How to run migrations}
{How to seed with test data}
{How to reset the database}

## IDE Setup (Optional)
{Recommended VS Code extensions or IntelliJ plugins}
{Debugging configuration}
{Recommended settings}

## Common Issues
{Port already in use}
{Docker memory limits}
{Database connection refused}
{Environment variable missing}
```

**Generation Process:**

1. **Environment Variables**
   - Parse .env.example for all variables
   - Classify: required vs optional, secret vs non-secret
   - Note where to obtain secret values (but never include actual secrets)

2. **Docker Configuration**
   - Parse docker-compose.yml for services, ports, volumes
   - Document any initialization scripts (database init, etc.)
   - Note resource requirements (memory limits, disk space)

3. **Database Setup**
   - Detect database type from config
   - Document creation, migration, and seeding commands
   - Include reset command (for starting fresh)

4. **IDE Configuration**
   - Check for .vscode/ directory (settings, extensions, launch configs)
   - Check for .idea/ directory (IntelliJ settings)
   - Check for .editorconfig

---

## Document 4: Testing Guide

**Purpose:** Developer knows how to run every type of test and what each tests.

**File:** `docs/testing-guide.md`

**Structure:**

```markdown
# Testing Guide

## Test Types
| Type | Command | Directory | Purpose |
|---|---|---|---|
| Unit | `npm test` | `tests/unit/` | Individual function behavior |
| Integration | `npm run test:integration` | `tests/integration/` | Component interaction |
| E2E | `npm run test:e2e` | `tests/e2e/` | Full user flows |
| Smoke | `npm run test:smoke` | `tests/smoke/` | Critical path verification |

## Running Tests

### All Tests
{command to run everything}

### Specific Test File
{command to run a single test file}

### Specific Test Case
{command to run a single test by name}

### With Coverage
{command to generate coverage report}
{where to find coverage report}

## Writing Tests

### Test File Location
{convention: co-located with source, or in tests/ directory}
{naming convention: *.test.ts, *_test.py, etc.}

### Test Structure
{example of a well-written test from this project}
{conventions: describe blocks, test naming, setup/teardown}

### Mocking
{how mocking is done in this project}
{what to mock vs what to use real implementations for}

## CI Integration
{how tests run in CI}
{what happens when tests fail}

## Troubleshooting Test Failures
{common reasons tests fail locally but pass in CI (or vice versa)}
{database state issues}
{timing/async issues}
```

**Generation Process:**

1. **Detect Test Infrastructure**
   - Test runner: Jest, Vitest, pytest, go test, etc.
   - Test directories and file patterns
   - Configuration files (jest.config, pytest.ini, etc.)

2. **Extract Commands**
   - From package.json scripts, Makefile targets, or framework defaults
   - Include: run all, run one, run with coverage, run in watch mode

3. **Find Test Examples**
   - Pick a well-written test from the project as an example
   - Show the project's actual conventions, not generic ones

4. **Document CI Integration**
   - Check .github/workflows/ for test-related workflows
   - Note any CI-specific configuration or differences

---

## Document 5: Common Tasks Guide

**Purpose:** Developer knows how to perform routine development tasks.

**File:** `docs/common-tasks.md`

**Structure:**

```markdown
# Common Tasks

## Adding a New Feature
1. {Create branch: git checkout -b feat/my-feature}
2. {Run /feature command or follow manual process}
3. {Key files to create/modify}
4. {Run tests}
5. {Create PR}

## Fixing a Bug
1. {Create branch: git checkout -b fix/bug-description}
2. {Run /bugfix command or follow manual process}
3. {Write failing test first}
4. {Implement fix}
5. {Verify all tests pass}
6. {Create PR}

## Adding a New API Endpoint
1. {Where to define the route}
2. {Where to add the handler/controller}
3. {Where to add validation}
4. {Where to add tests}
5. {How to update API documentation}

## Adding a Database Migration
1. {Command to generate migration}
2. {How to write up/down}
3. {How to test migration}
4. {How to run migration}

## Deploying
1. {Pre-deploy checklist}
2. {Deploy command}
3. {Post-deploy verification}
4. {Rollback procedure}

## Updating Dependencies
1. {How to check for updates}
2. {How to update safely}
3. {How to verify nothing broke}
```

**Generation Process:**

1. **Analyze Project Workflow**
   - Check git history for common commit patterns
   - Check PR templates for expected process
   - Check CONTRIBUTING.md if it exists

2. **Extract from forge Commands**
   - Map /feature, /bugfix, /refactor to developer-friendly steps
   - Include both the forge command and the manual process

3. **Project-Specific Tasks**
   - Identify common operations from project structure
   - Adding routes, models, components, etc.
   - Framework-specific tasks (Next.js pages, Django views, etc.)

---

## Document 6: Glossary

**Purpose:** Define project-specific terms that a newcomer would not know.

**File:** `docs/glossary.md`

**Structure:**

```markdown
# Glossary

| Term | Definition |
|---|---|
| {Project-specific term} | {Clear, concise definition} |
| {Abbreviation} | {What it stands for and what it means} |
| {Internal name} | {What the team calls X and what it actually is} |
```

**Generation Process:**

1. **Extract Project Terms**
   - Scan README, code comments, and variable names for domain-specific terms
   - Check for terms that appear frequently but would confuse an outsider
   - Include abbreviations and acronyms used in the codebase

2. **forge Terms (if applicable)**
   - Work manifest, quality gates, gotchas, slice graph
   - Skill groups: discover, plan, build, quality, deliver, support
   - Commands: /feature, /greenfield, /bugfix, etc.