clarc-onboarding

## When to Use

Use this skill when:
- A developer is new to clarc and needs a staged learning path
- Onboarding a team to clarc for the first time
- Starting clarc on a new project type
- Helping someone understand which clarc components matter for their role

## The Three Phases

### Day 1 — Survive (Core 5 Commands)

Get value within the first 30 minutes. Learn exactly these commands in order:

| Command | Why first |
|---------|-----------|
| `/quickstart` | Interactive setup — installs the right rules for your stack |
| `/context` | See which clarc components matter for your project |
| `/plan` | Turn a feature request into a concrete plan |
| `/code-review` | Immediate code quality feedback |
| `/tdd` | Write your first feature the right way |

**Day 1 goal:** Complete one real task (a small feature or bug fix) using `/plan` → `/tdd` → `/code-review` in sequence.

### Week 1 — Grow (Workflow Integration)

Integrate clarc into your daily workflow. Add these:

| Command/Agent | When to use it |
|--------------|---------------|
| `/guide <task>` | Any time you start a new task — get the right workflow |
| `/security-review` | Before every PR that touches auth, APIs, or user data |
| `/e2e` | For any feature with a critical user flow |
| `code-reviewer` agent | After every significant code change (or use the nudge hook) |
| `/doctor` | Weekly — verify clarc installation is healthy |

**Week 1 goal:** Run `/guide <task>` for every task this week. Notice which skills get recommended.

### Month 1 — Master (Advanced Agents)

Unlock the full workflow OS. Add these:

| Component | When it pays off |
|-----------|-----------------|
| `/orchestrate` | Complex tasks needing 3+ independent analyses |
| `architect` agent | Any architectural decision |
| `tdd-guide` agent | For disciplined TDD on complex features |
| `/debt-audit` | Monthly — identify where to invest refactoring time |
| `/instinct-report` | See what clarc has learned about your codebase |
| `/skill-create` | Extract patterns from your git history into skills |

**Month 1 goal:** Have a personal set of project-local instincts in `~/.clarc/instincts/`.

---

## Solo Developer Path

**Priority order:**
1. `/plan` + `/tdd` + `/code-review` — your core loop
2. `/security-review` — catch vulnerabilities before they reach production
3. `/guide <task>` — get the right tool for every job
4. `/instinct-report` — review what clarc has learned after 30 sessions

**What to skip initially:**
- Multi-agent orchestration (overkill for solo work)
- `/team-sync` (no team to sync with)
- CI/CD integration (do this in Month 2)

---

## Team Path

**Week 1 team setup:**
1. One person runs `/quickstart` and commits `.clarc/` config to the repo
2. Everyone installs: `npx github:marvinrichter/clarc` in the project root
3. Run `/onboard` to generate `CONTRIBUTING.md` and setup scripts
4. Add `/setup-ci` to wire clarc into the CI pipeline

**Shared conventions to establish:**
- Which hooks are disabled for this project (`.clarc/hooks-config.json`)
- Whether to commit `.clarc/skills/` for project-local skills
- Who owns the `/doctor` health check (runs weekly)

**Team commands that matter:**

| Command | Team value |
|---------|-----------|
| `/code-review` | Consistent review quality across all PRs |
| `/security-review` | Security standards enforced on every PR |
| `/e2e` | Shared E2E test suite that everyone runs |
| `/onboard` | New hires set up independently in < 5 minutes |
| `/agent-stats` | See which agents the team uses most |

---

## Role-Specific Paths

### Frontend Developer
Start with: `/context` → `/e2e` → `/a11y-audit` → `/web-perf`
Key skills: `frontend-patterns`, `state-management`, `accessibility-patterns`, `e2e-testing`

**Example session — frontend developer, Day 1:**
```
User: /context
clarc: Detected React + TypeScript project. Relevant skills: frontend-patterns, state-management, e2e-testing.

User: /e2e add checkout flow test
clarc: [e2e-runner] Generated Playwright test: checkout-flow.spec.ts — 3 critical paths covered.

User: /a11y-audit
clarc: [design-system-reviewer] Found 2 issues: missing aria-label on cart button, colour contrast ratio 3.2:1 (min 4.5:1).

User: /web-perf
clarc: [performance-analyst] LCP 3.8s (target <2.5s) — ProductImage not lazy-loaded. Fix: add loading="lazy".
```

### Backend Developer
Start with: `/context` → `/tdd` → `/database-review` → `/security-review`
Key skills: `api-design`, `auth-patterns`, `database-migrations`, `observability`

### DevOps / Platform Engineer
Start with: `/context` → `/iac-review` → `/gitops-review` → `/finops-audit`
Key skills: `kubernetes-patterns`, `terraform-patterns`, `gitops-patterns`, `observability`

### Tech Lead / Architect
Start with: `/plan` → `/explore` → `/arc42` → `/debt-audit`
Key agents: `architect`, `planner`, `modernization-planner`

---

## Common Mistakes in Week 1

| Mistake | Fix |
|---------|-----|
| Using `/help` instead of `/guide <task>` | `/guide` gives you a workflow, `/help` gives you a list |
| Running `/code-review` on every line | Use the code-review-nudge hook — it suggests automatically |
| Ignoring the TDD guard nudge | The nudge fires for a reason — write the test first |
| Not reading the suggested skill | Skills contain the patterns Claude will use — read them |
| Using `/orchestrate` for simple tasks | Reserve it for tasks needing 3+ independent analyses |

---

## Quick Reference Card

```
New task?          → /guide <task description>
New project?       → /context
Implementing?      → /plan → /tdd → /code-review
Before PR?         → /security + /code-review
Architecture?      → /explore → /arc42
Build broken?      → say "fix the build" (build-error-resolver auto-triggers)
Performance issue? → /profile
Stuck?             → /clarc-way
```

---

## Example: First Session Transcript

A new developer joining a Python/FastAPI project:

```
# Day 1 — first 30 minutes

User: /quickstart
clarc: Detected Python project (FastAPI). Installing rules/python/ and core skills.
       Nudge hooks enabled. Run `/context` next to see what matters for this codebase.

User: /context
clarc: Found 3 relevant skills for this project:
       - fastapi-patterns (FastAPI routing, dependency injection, Pydantic v2)
       - python-patterns (PEP 8, type hints, dataclasses)
       - postgres-patterns (async SQLAlchemy, migrations)
       Run /plan before implementing, /tdd to write tests first.

User: /plan add user authentication with JWT
clarc: [planner agent] Breaking down: JWT token generation, login endpoint,
       dependency for protected routes, refresh token flow...
       Task list created in TODO.md.

User: /tdd implement the login endpoint
clarc: [tdd-guide agent] Writing test first:
       test_login_returns_jwt_on_valid_credentials
       test_login_returns_401_on_wrong_password
       RED: tests fail. Now implement login_router.py...

User: /code-review
clarc: [python-reviewer agent] Found 2 issues:
       HIGH: Password compared without constant-time comparison (timing attack)
       MEDIUM: JWT secret read directly from os.environ — use pydantic Settings instead.
```

**What happened:** 30 minutes, one real feature shipped, two security issues caught before PR.