onboard

What this skill does

You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.

YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlying principles, why each skill exists, what problem it solves at a fundamental level.

## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS

This onboarding has THREE equally important parts:

**PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, SKILL DEEP DIVE)
- Explain WHY this workflow exists
- Explain WHAT each skill does and WHY

**PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES)
- Walk through ALL 5 examples in detail
- For EACH step in EACH example, explain:
  - PRINCIPLE: Why this step exists
  - WHAT HAPPENS: What the skill actually does
  - IF SKIPPED: What goes wrong without it

**PART 3: Customize Your Development Guidelines** (Section: CUSTOMIZE YOUR DEVELOPMENT GUIDELINES)
- Check if project guidelines are still empty templates
- If empty, guide the developer to fill them with project-specific content
- Explain the customization workflow

DO NOT skip any part. All three parts are essential:
- Part 1 teaches the concepts
- Part 2 shows how concepts work in practice
- Part 3 ensures the project has proper guidelines for AI to follow

After completing ALL THREE parts, ask the developer about their first task.

---

## CORE PHILOSOPHY: Why This Workflow Exists

AI-assisted development has three fundamental challenges:

### Challenge 1: AI Has No Memory

Every AI session starts with a blank slate. Unlike human engineers who accumulate project knowledge over weeks/months, AI forgets everything when a session ends.

**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work.

**The Solution**: The `.trellis/workspace/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `$start` skill reads this history at session start, giving AI "artificial memory."

### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge

AI models are trained on millions of codebases - they know general patterns for React, TypeScript, databases, etc. But they don't know YOUR project's conventions.

**The Problem**: AI writes code that "works" but doesn't match your project's style. It uses patterns that conflict with existing code. It makes decisions that violate unwritten team rules.

**The Solution**: The `.trellis/spec/` directory contains project-specific guidelines. The `$before-*-dev` skills inject this specialized knowledge into AI context before coding starts.

### Challenge 3: AI Context Window Is Limited

Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential.

**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns.

**The Solution**: The `$check-*` skills re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `$finish-work` skill does a final holistic review.

---

## SYSTEM STRUCTURE

```
.trellis/
|-- .developer              # Your identity (gitignored)
|-- workflow.md             # Complete workflow documentation
|-- workspace/              # "AI Memory" - session history
|   |-- index.md            # All developers' progress
|   +-- {developer}/        # Per-developer directory
|       |-- index.md        # Personal progress index
|       +-- journal-N.md    # Session records (max 2000 lines)
|-- tasks/                  # Task tracking (unified)
|   +-- {MM}-{DD}-{slug}/   # Task directory
|       |-- task.json       # Task metadata
|       +-- prd.md          # Requirements doc
|-- spec/                   # "AI Training Data" - project knowledge
|   |-- frontend/           # Frontend conventions
|   |-- backend/            # Backend conventions
|   +-- guides/             # Thinking patterns
+-- scripts/                # Automation tools
```

### Understanding spec/ subdirectories

**frontend/** - Single-layer frontend knowledge:
- Component patterns (how to write components in THIS project)
- State management rules (Redux? Zustand? Context?)
- Styling conventions (CSS modules? Tailwind? Styled-components?)
- Hook patterns (custom hooks, data fetching)

**backend/** - Single-layer backend knowledge:
- API design patterns (REST? GraphQL? tRPC?)
- Database conventions (query patterns, migrations)
- Error handling standards
- Logging and monitoring rules

**guides/** - Cross-layer thinking guides:
- Code reuse thinking guide
- Cross-layer thinking guide
- Pre-implementation checklists

---

## SKILL DEEP DIVE

### $start - Restore AI Memory

**WHY IT EXISTS**:
When a human engineer joins a project, they spend days/weeks learning: What is this project? What's been built? What's in progress? What's the current state?

AI needs the same onboarding - but compressed into seconds at session start.

**WHAT IT ACTUALLY DOES**:
1. Reads developer identity (who am I in this project?)
2. Checks git status (what branch? uncommitted changes?)
3. Reads recent session history from `workspace/` (what happened before?)
4. Identifies active features (what's in progress?)
5. Understands current project state before making any changes

**WHY THIS MATTERS**:
- Without $start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
- With $start: AI knows project context, can continue where previous session left off, avoids conflicts.

---

### $before-dev - Inject Specialized Knowledge

**WHY IT EXISTS**:
AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns.

**WHAT IT ACTUALLY DOES**:
1. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines
2. Loads project-specific patterns into AI's working context:
   - Component naming conventions
   - State management patterns
   - Database query patterns
   - Error handling standards

**WHY THIS MATTERS**:
- Without before-dev: AI writes generic code that doesn't match project style.
- With before-dev: AI writes code that looks like the rest of the codebase.

---

### $check - Combat Context Drift

**WHY IT EXISTS**:
AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift."

**WHAT IT ACTUALLY DOES**:
1. Re-reads the guidelines that were injected earlier
2. Compares written code against those guidelines
3. Runs type checker and linter
4. Identifies violations and suggests fixes

**WHY THIS MATTERS**:
- Without check-*: Context drift goes unnoticed, code quality degrades.
- With check-*: Drift is caught and corrected before commit.

---

### $check-cross-layer - Multi-Dimension Verification

**WHY IT EXISTS**:
Most bugs don't come from lack of technical skill - they come from "didn't think of it":
- Changed a constant in one place, missed 5 other places
- Modified database schema, forgot to update the API layer
- Created a utility function, but similar one already exists

**WHAT IT ACTUALLY DOES**:
1. Identifies which dimensions your change involves
2. For each dimension, runs targeted checks:
   - Cross-layer data flow
   - Code reuse analysis
   - Import path validation
   - Consistency checks

---

### $finish-work - Holistic Pre-Commit Review

**WHY IT EXISTS**:
The `$check-*` skills focus on code quality within a single layer. But real changes often have cross-cutting concerns.

**WHAT IT ACTUALLY DOES**:
1. Reviews all changes holistically
2. Checks cross-layer consistency
3. Identifies broader impacts
4. Checks if new patterns should be documented

---

### $record-session - Persist Memory for Future

**WHY IT EXISTS