@jamie-tam/forge 6.0.0

package/skills/deliver-onboarding/references/document-templates.md

@@ -0,0 +1,393 @@
+# 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.

package/skills/deliver-onboarding/templates/getting-started.md

@@ -0,0 +1,122 @@
+# Getting Started
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+| Tool | Version | Installation |
+|------|---------|-------------|
+| {runtime, e.g., Node.js} | {version, e.g., >= 20.x} | {link or command} |
+| {package manager, e.g., npm} | {version} | {comes with Node.js} |
+| {database, e.g., PostgreSQL} | {version, e.g., >= 15} | {link or command} |
+| {container runtime, e.g., Docker} | {version, e.g., >= 24} | {link} |
+| Git | >= 2.x | {link} |
+
+## Clone and Setup
+
+```bash
+# Clone the repository
+git clone {repository_url}
+cd {project_name}
+
+# Install dependencies
+{install command, e.g., npm install}
+```
+
+## Environment Variables
+
+Copy the example environment file and fill in the values:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Description | Where to Get It | Example |
+|----------|-------------|----------------|---------|
+| DATABASE_URL | Database connection string | Local setup below | postgresql://user:pass@localhost:5432/dbname |
+| {VAR_NAME} | {description} | {source} | {example value} |
+| {VAR_NAME} | {description} | {source} | {example value} |
+
+## Database Setup
+
+```bash
+# Start the database (if using Docker)
+docker compose up -d db
+
+# Run migrations
+{migration command, e.g., npx prisma migrate dev}
+
+# Seed the database (optional, for development data)
+{seed command, e.g., npx prisma db seed}
+```
+
+## Running Locally
+
+```bash
+# Start the development server
+{dev command, e.g., npm run dev}
+
+# The application is now running at:
+# http://localhost:{port}
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+{test command, e.g., npm test}
+
+# Run tests in watch mode
+{watch command, e.g., npm run test:watch}
+
+# Run tests with coverage
+{coverage command, e.g., npm run test:coverage}
+
+# Run E2E tests
+{e2e command, e.g., npx playwright test}
+```
+
+## Verify Everything Works
+
+After setup, verify with this quick checklist:
+
+- [ ] `{build command}` completes without errors
+- [ ] `{test command}` passes all tests
+- [ ] `{dev command}` starts the server
+- [ ] Visiting `http://localhost:{port}` shows the application
+- [ ] {Any other verification step specific to the project}
+
+## Common Tasks
+
+| Task | Command |
+|------|---------|
+| Start dev server | `{command}` |
+| Run tests | `{command}` |
+| Run linter | `{command}` |
+| Build for production | `{command}` |
+| Run database migrations | `{command}` |
+| Generate API types | `{command}` |
+
+## Troubleshooting
+
+### {Common problem 1}
+**Symptom**: {what you see}
+**Cause**: {why it happens}
+**Fix**: {how to fix it}
+
+### {Common problem 2}
+**Symptom**: {what you see}
+**Cause**: {why it happens}
+**Fix**: {how to fix it}
+
+### Port already in use
+**Symptom**: Error: listen EADDRINUSE :::3000
+**Cause**: Another process is using the port
+**Fix**: `lsof -i :{port}` to find the process, then `kill {pid}`
+
+## Glossary
+
+| Term | Definition |
+|------|-----------|
+| {project-specific term} | {what it means in this project} |
+| {project-specific term} | {what it means in this project} |