# Joiner Onboarding Task

**You (the AI) are running this task. The developer does not read this file.**

`zl-q` just ran `trellis init` on a fresh clone, saw "Developer
initialized", and will now start asking you questions in chat. This joiner task
exists under `.trellis/tasks/`; when they want to work on it, they should
start it from a session that provides Trellis session identity.

Your job is to orient them to Trellis. Don't dump all of this at them — open
with a short greeting, ask where they want to start, and fill in the rest as
they engage.

---

## Topics to cover (adapt order to their questions)

### 1. What Trellis is + the workflow

Trellis is a workflow layer over Claude Code / Cursor / etc. that keeps AI
agents consistent with project-specific conventions instead of writing generic
code every session.

- **Three phases**: Plan (brainstorm → `prd.md`) → Execute (code + check) →
  Finish (capture + wrap). Full reference: `.trellis/workflow.md`.
- **Task lifecycle**: planning → in_progress → done → archive, under
  `.trellis/tasks/`.
- **Core slash commands**:
  - `/trellis:continue` — resume the current session's active task
  - `/trellis:finish-work` — wrap up a finished task
  - `/trellis:start` — session boot from scratch (not needed here; the
    SessionStart hook does its job automatically)

### 2. Runtime mechanics (explain when they ask "how does it know what to do")

- **SessionStart hook** runs `get_context.py` and injects identity, git
  status, session active task, active tasks, and workflow phase into the AI
  conversation at every session start.
- **`<workflow-state>` tag** is auto-injected with every user message,
  carrying the current task + phase hint.
- **`/trellis:continue`** loads the Phase Index, reads `prd.md` + recent
  activity, and routes to the right skill (`trellis-brainstorm` for planning,
  `trellis-implement` for coding, `trellis-check` for verification).
- **`trellis-implement` sub-agent** is spawned when code needs to be written.
  The platform hook reads `{TASK_DIR}/implement.jsonl` and auto-injects those
  spec files + `prd.md` into the sub-agent's prompt so it codes per project
  conventions.
- **`trellis-check` sub-agent** follows the same pattern with `check.jsonl`
  — reviews changes against specs, auto-fixes issues, runs lint/typecheck.

File layout (mention when they ask "where does what live"):
- `.trellis/.runtime/sessions/<session>.json` — session active-task state, gitignored
- `.trellis/tasks/<task>/{implement,check}.jsonl` — per-task context manifests
- `.trellis/spec/` — project-wide conventions (source of truth)
- `.trellis/workspace/zl-q/journal-*.md` — their session log,
  rotated at ~2000 lines

### 3. This project's actual conventions

- Summarize `.trellis/spec/` for them — what coding conventions this
  specific team enforces.
- Point at the last 5 entries in `.trellis/tasks/archive/` as a rhythm
  example of how people actually work here. **If archive is empty** (the
  project just started), skip this — don't invent examples.
- Not your job in this onboarding to teach them the business code itself —
  the README and their teammates handle that.

### 4. Their assigned work

- Check if `.trellis/workspace/zl-q/` already exists — if yes, it's
  their journal from another machine and worth mentioning.
- Run `python3 ./.trellis/scripts/task.py list --assignee zl-q` to
  show tasks assigned to them. (Quote the name if it contains spaces.)
- Remind them that the "My Tasks" section appears in the SessionStart context
  on every new session.

---

## Optional: walk through a small task end-to-end

If they want to practice before touching real work, offer to pick a tiny
P3 task or a typo fix and run the full cycle together: `/trellis:continue`
→ you implement via sub-agents → `/trellis:finish-work`.

---

## Completion

When they feel oriented (or after you've covered the four topics with
reasonable back-and-forth), guide them to run:

```bash
python3 ./.trellis/scripts/task.py finish
python3 ./.trellis/scripts/task.py archive 00-join-zl-q
```

---

## Suggested opening line

"Welcome! Your `trellis init` set me up to onboard you to this project. I
can walk you through the workflow, show you the runtime mechanics under the
hood, summarize the team's spec, or jump to what you're already curious about
— which would you prefer?"