Start Session

Run once at the beginning of a conversation to orient. Gathers cheap signals and routes to wayfinder.

Bundled skills (always available)

The following mattpocock/skills ship with this plugin in skills/ — no external detection or installation needed:

grilling, grill-with-docs, domain-modeling, tdd, prototype, codebase-design, diagnosing-bugs, improve-codebase-architecture

These are referenced at specific integration points by wayfinder, implement, to-spec, and code-review.

Process

Step 1: Determine which path applies

Check whether .agent/state.json exists in the project root.

Path A: Resume (.agent/state.json exists)

1. Read .agent/state.json in full.
2. Check schema version. If version is 1 (v1 state), tell the user: "This project has v1 state from an earlier version of the plugin. Would you like me to migrate it to v2, or start fresh?" Act on their answer.
3. Read the wayfinder map (at map_ref path) and any CONTEXT.md or ADRs.
4. Summarize current status to the user: what the destination is, which tickets are done, which are next.
5. Resume: read the map and pick up the next unresolved ticket.

Path B: Empty directory (no substantive files)

Count files excluding .git*, .agent*, README*, LICENSE*, .gitignore, .gitattributes. If zero:

1. Tell the user: "This directory is empty — treating as a new project."
2. Invoke skills/setup/SKILL.md to configure the tracker.
3. Invoke skills/wayfinder/SKILL.md — the first ticket on the map will be a grilling ticket to establish what the project is.

Path C: Existing codebase (has files)

Gather cheap heuristic signals:

1. Tracked files — git ls-files | wc -l (or directory file count).
2. Approximate LOC — count lines across common source extensions.
3. Existing documentation — check for CONTEXT.md, docs/CONTEXT.md, docs/agents/, docs/adr/, docs/architecture/.
4. Size class — large (300+ files or 30k+ LOC), medium (40+ or 3k+), small (everything else).

Report signals to the user, then:

5. Invoke skills/setup/SKILL.md to configure the tracker.
6. If size class is medium or large, invoke skills/scope-lock/SKILL.md before any broad reading.
7. Invoke skills/wayfinder/SKILL.md — the first ticket on the map will be a grilling ticket to establish what the user wants to do.

What this skill must never do

• Never start implementation before wayfinder has completed its map.
• Never re-run the full orient when .agent/state.json already exists (use Path A instead).
• Never read broadly across a medium/large repo before scope-lock runs.