RonanCodes/graduate-project

Graduate Project

Why this exists

Projects gestate in the LLM Wiki (ideation, research, design docs, decisions hashed out in chat), then get their own code repo, and future sessions run in that repo. The knowledge from the gestation phase lives in an llm-wiki-<slug> vault, but nothing automatically carries it across the repo boundary. So a fresh session in the new repo starts cold and the operator has to remember to say "read the design docs."

This skill is the bridge. Run it once, when a project gets its repo. It turns the vault's gestation knowledge into the repo's durable orientation layer (HANDOFF.md + a coordination GH issue + a thin CLAUDE.md), and it back-links the two so neither side forgets the other. After it runs, a fresh session opened in the repo self-orients from CLAUDE.md → HANDOFF.md → the coordination issue, which is "pick up where the previous wiki session stopped."

It is the forward half of the seam. The vault-side re-entry is [[pickup]]; the repo-side equivalent is the generated CLAUDE.md "Start here" block (a dedicated /ro:pickup-repo is the natural follow-up).

  llm-wiki-<slug> vault                       <new repo>
  (gestation: design,        ──graduate──▶    docs/agents/HANDOFF.md   (cold-start doc)
   ROADMAP, decisions,                        GH issue #N              (coordination hub)
   open questions)                            ready-for-agent issues   (sliced scope)
        ▲                                      CLAUDE.md                (thin, "Start here")
        └────── forward-pointer in vault ◀──── cross-vault back-pointer ┘
                (ROADMAP "graduated → repo")

Preconditions

• The code repo already exists locally with a gh remote (this skill does not scaffold the app — use /ro:new-tanstack-app etc. for that). If it has no gh remote, fall back to writing HANDOFF.md + CLAUDE.md only and skip issues.
• An llm-wiki-<slug> vault exists for the project. If you are unsure which vault, ask, or detect by matching the repo name against vaults/llm-wiki-*.
• Respect /ro:repo-mode: in a work repo, skip the GitHub side (no issues) and keep everything local, per the personal-vs-work rule.

Steps

1. Resolve vault + repo

• <vault-name> is the first arg (with or without the llm-wiki- prefix). Resolve to vaults/llm-wiki-<slug>/.
• --repo <owner/name> names the target repo; otherwise use the current repo (gh repo view --json nameWithOwner). Confirm the pairing with the user before writing anything (AskUserQuestion), since this is a hard-to-undo wiring step.

2. Read the gestation context

Read, in the vault:

• index.md (the map), ROADMAP.md (In progress / Next up / Blocked / recently done), the tail of log.md (recent decisions), and the design docs under wiki/ (concepts, comparisons, sources tagged to the project).
• Prefer /query "<project> design + decisions + open questions" --vault llm-wiki-<slug> over raw grep, so the progressive index + cross-links surface the load-bearing pages.

Pull out: what it is, the architecture north-star, decisions made AND rejected (the rejected ones are the most easily lost), open questions, known blockers, and the scope still to build.

3. Synthesise docs/agents/HANDOFF.md

Write a cold-start doc a fresh agent reads to get warm. Follow /ro:understanding-first. Sections:

• What it is (one plain-English paragraph) + live URL / stack if known.
• Architecture north-star (the agreed shape, not an exhaustive spec).
• Decisions made + rejected (with the why; rejected options prevent re-litigation).
• Open questions (explicit, never buried).
• Blockers (especially anything gated on a paid resource or an external party).
• Backlog (pointer to the coordination issue + the ready-for-agent issues).
• Conventions / gotchas carried from the vault.
• Gestation vault — a cross-vault link back to llm-wiki-<slug> so the repo always knows where it came from.

4. Open the coordination-hub issue (skip if --no-issues or work-mode)

One GH issue that is the shared-memory anchor for the repo (the #39-style hub): points at HANDOFF.md, states the multi-agent shared-memory model (GH issues = coordination, HANDOFF.md + vault = durable, one-file-per-agent = scratch), and lists how work is split. Label ready-for-agent.

5. Slice scope into ready-for-agent child issues

• If the vault holds a PRD, hand off to /ro:slice-into-issues.
• Otherwise create one child issue per item in the vault ROADMAP's "Next up", each referencing the hub via ## Parent\n\n#<hub> per the Pocock convention.
• Never silently truncate: if you cap the number of issues, log() what was left.

6. Write the thin repo CLAUDE.md

Thin and link-heavy (detail lives in HANDOFF.md):

• project one-liner + stack + live URL,
• a "Start here" block: read docs/agents/HANDOFF.md, then gh issue view <hub>,
• load-bearing gotchas (the ones that waste hours if relearned),
• ship flow,
• "Next up",
• a cross-vault back-pointer (obsidian://open?...) to the gestation vault.

If a repo CLAUDE.md already exists, merge a "Start here" + back-pointer block into it rather than overwriting.

7. Write the forward-pointer in the vault

In the vault's ROADMAP.md, move the project to "Recently completed" with a graduated → <owner/name> on <date> note, and append a log.md entry. Add a cross-vault link from the vault to the repo (or to the repo's HANDOFF). Now each side knows the other.

8. Commit both sides

• Repo: feature branch → commit (emoji conventional, no Co-Authored-By, weekday-hours rule) → PR → squash-merge per the CI policy. Never push to main.
• Vault: commit in the vault's own repo.
• Run /ro:vercel-verify (or the repo's deploy verify) only if the change is build-affecting; usually it is docs-only.

Flags

• --repo <owner/name> — target repo if not the current directory.
• --no-issues — write HANDOFF.md + CLAUDE.md only; skip the GH side.
• --dry-run — print what would be written/opened without writing.

Idempotent

Re-running updates HANDOFF.md and the hub issue in place (match by title) and refreshes the CLAUDE.md "Start here" block, rather than duplicating. Safe to run again after more gestation happens in the vault.

Related

• [[pickup]] — vault-side session re-entry; this is the repo-side bridge.
• [[handoff]] / [[close-session]] — single-session durability; this is the cross-repo, cross-phase version.
• [[slice-into-issues]] / [[write-a-prd]] — the Pocock GH-issue pipeline this hands scope off to.
• [[agent-native-repo-pocock]] — the pattern that makes the repo side capturable.
• The multi-agent shared-memory model: skill-lab multi-agent-shared-memory-architecture.