eryao/.trellis/tasks/archive/2026-05/00-join-zl-q/prd.md

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:

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?"