RonanCodes/skills/pickup-repo

Pickup Repo

Why this exists

/ro:graduate-project is the forward half of the LLM-Wiki to repo seam: when a project leaves ideation it writes docs/agents/HANDOFF.md, opens a coordination-hub GitHub issue plus sliced ready-for-agent child issues, and writes a thin repo CLAUDE.md whose "Start here" block points at both with a cross-vault back-pointer to the gestation vault.

This is the back half: the deliberate repo-side re-entry. It is the project-side equivalent of the vault [[pickup]]. A fresh session in a graduated repo can self-orient from the generated CLAUDE.md "Start here" block (that covers most of it), but this skill makes the re-entry a single command that also does the vault round-trip: it reads the gestation vault's recent state so the briefing reflects what happened on the wiki side since graduation, not just the snapshot frozen into HANDOFF.md.

  <repo>                                    llm-wiki-<slug> vault
  CLAUDE.md "Start here"   ──pickup-repo──▶  ROADMAP / log / decisions
  docs/agents/HANDOFF.md                     (read recent state)
  GH hub issue + ready-for-agent issues
        │
        └──── one-screen briefing ◀──── reconcile all three sources

When to fire

• A fresh session opens in a graduated repo and the user says "pick up this repo", "where did this repo leave off", "catch me up", "what's next here", "re-enter this project", or invokes /ro:pickup-repo.
• After /ro:graduate-project has run on a repo and a later session needs to start from cold.

Do NOT fire for:

• A repo that was never graduated (no HANDOFF.md, no hub issue). Fall back to reading CLAUDE.md + README.md + gh issue list and say the repo was not graduated, there is no vault round-trip to do.
• Mid-session "what's next" (the context is already hot, just keep working).
• The vault side. That is [[pickup]]. This is the repo side.

Steps

1. Resolve the repo

• Default to the current repo (gh repo view --json nameWithOwner if a gh remote exists). --repo <owner/name> overrides.
• Confirm you are in a graduated repo by checking for docs/agents/HANDOFF.md. If it is missing, degrade gracefully (see "Not graduated" below).

2. Read the repo orientation layer

In order, exactly as the generated "Start here" block intends:

1. CLAUDE.md: the thin repo guide (one-liner, stack, live URL, load-bearing gotchas, ship flow, "Next up", and the cross-vault back-pointer). Pull the back-pointer (the obsidian://open?... link or the named vault). It is what step 4 needs.
2. docs/agents/HANDOFF.md: the cold-start doc (what it is, architecture north-star, decisions made AND rejected, open questions, blockers, backlog pointers, conventions). This is the frozen snapshot from graduation, treat it as the baseline the live sources update.

3. Refresh live state from GitHub

The handoff is a snapshot; the issues are the truth.

gh issue list --label ready-for-agent --state open --json number,title,labels

• Read the coordination-hub issue (named in HANDOFF.md / CLAUDE.md, the #N-style shared-memory anchor). It states the work split and the shared-memory model.
• Surface in-flight and ready-for-agent issues first; note anything labelled blocked or blocked-on-human and why.

4. Follow the cross-vault back-pointer (skip with --no-vault)

This is the round-trip that makes this skill more than the "Start here" block.

• Resolve the LLM-wiki location (bash "${CLAUDE_PLUGIN_ROOT:-$HOME/Dev/ronan-skills}/scripts/resolve-repo.sh" LLM_WIKI) and the project's gestation vault from the back-pointer in CLAUDE.md (or ./.ronan-skills-llm-wiki.local.json).
• Read the vault's recent state: ROADMAP.md (In progress / Next up / Blocked / recently done), the tail of log.md (decisions since graduation), and any decisions / open-questions pages that changed after the graduation date.
• Prefer /query "<project> recent decisions + open questions + roadmap" --vault llm-wiki-<slug> over raw grep so the progressive index surfaces the load-bearing pages.
• Flag any drift: a vault decision that the repo HANDOFF.md predates, or a ROADMAP item that has no matching ready-for-agent issue yet.

5. Print the one-screen briefing

Reconcile all three sources into a single screen a fresh agent reads cold:

PICKUP: <repo> (graduated from llm-wiki-<slug>)

  What it is:   <one line from HANDOFF / CLAUDE>
  Where it is:  <live URL / stack / current branch>
  Stopped at:   <last thing done, from HANDOFF + recent vault log>
  In flight:    <open issues / branches mid-work>
  Next up:      <top ready-for-agent issues: #.. #..>
  Blocked:      <blocked-on-human / paid-resource / external party + why>
  To claim:     <the issue(s) a worker should pull first>
  Drift:        <vault decisions newer than HANDOFF, if any>

Keep it to one screen. Detail lives in the linked HANDOFF, hub issue, and vault , the briefing is the map, not the territory.

6. Offer the next move

Use AskUserQuestion to ask which issue(s) to start, then hand off to the right flow (/ro:ralph, /ro:planner-worker, or just claim a single issue). The heavy reading happened in this pickup; the main context stays a thin router.

Not graduated

If there is no HANDOFF.md / hub issue, this repo was not graduated. Don't bail: read CLAUDE.md + README.md + gh issue list --state open, print the shortened briefing (no vault round-trip), and tell the user the repo was never graduated , suggest /ro:graduate-project if it gestated in a vault.

Flags

• --repo <owner/name>: target repo if not the current directory.
• --no-vault: skip the cross-vault round-trip (repo + GitHub only).
• --brief-only: print the briefing and stop; do not offer the next move.

Related

• [[graduate-project]]: the forward half this completes. That writes the orientation layer; this re-enters through it with the vault round-trip.
• [[pickup]]: the vault-side session-start briefing. This is the repo-side equivalent.
• [[handoff]] (handoff resume): the per-session repo re-entry from a .handoff/ file. pickup-repo is the cross-phase, graduated-project version that always does the vault round-trip.
• [[close-session]]: the durability checklist that names this skill as the on-the-roadmap repo-side pickup.