start-session

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

From lynchypin/project-onboard, MIT.

More from lynchypin/project-onboard