---
name: forge-onboard
description: "Interactive onboarding conversation that surveys a freshly-bootstrapped project's real repo and builds its initial Project Brain — projectFacts, knowledge entries (overview / workflow / rules), a handful of seed memories, and a proposed pipeline config — through a chat that asks one question at a time and never writes without an explicit human confirm. Use right after a project has bound a runner and run pipeline bootstrap, when its knowledge/memory/pipelineConfig are still empty. Triggers on: /forge-onboard, build project brain, onboard this project, survey the repo for Forge."
user_invocable: true
arguments: ""
---

# Forge Onboard — build the Project Brain

A brand-new Forge project has skills wired and a pipeline preset applied, but its "brain" is
empty: nothing has read the actual repo and turned it into `projectFacts` / knowledge entries /
seed memory / a tuned pipeline config. This skill is that first conversation. It runs once, at
the start of a fresh chat session, and drives a short human-in-the-loop interview to fill that
gap — never by guessing silently and writing, always by proposing and waiting for a yes.

## Hard rules (non-negotiable)

1. **One question per turn.** When you need to ask the human something, ask exactly ONE question,
   then END YOUR TURN immediately — no follow-up questions stacked in the same message, no "while
   I wait, let me also ask...". The reply arrives as the next turn (the session resumes
   automatically); you pick up the conversation from there.
2. **Never write without an explicit confirm.** Before any `forge_knowledge` upsert, `forge_memory`
   write, `forge_config` projectFacts/pipelineConfig patch, or pipeline-config change, present a
   short plain-English summary of exactly what you intend to write and ask "Write this?" (a single
   question, per rule 1). Only write after an unambiguous yes. A "no", a follow-up question, or the
   user closing the tab must never leave a partial write behind — nothing you propose exists until
   it is confirmed.
3. **Acknowledge every write.** Immediately after a confirmed write succeeds, say so in one line
   ("Saved: <what>"). If a write fails, say so plainly and offer to retry — never fail silently and
   move on as if it worked.
4. **No dead ends.** At any point the human can decline a proposal, ask something unrelated, or
   just stop — the conversation keeps working (or ends cleanly) either way; it never gets stuck
   waiting on a write that will never be confirmed.

## Flow

### 1. Survey the repo silently (no questions yet)

Before asking anything, spend this first turn reading what the repo already tells you — the goal
is to minimize what you have to ask a human. Useful sources, whatever exists:

- Root docs: `README.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `docs/` — project purpose, architecture,
  conventions already written down.
- Workspace shape: package manager + monorepo config (`package.json`/`pnpm-workspace.yaml`,
  `Cargo.toml`, `go.mod`, …), the list of packages/services and what each does.
- Build/test/lint: scripts in `package.json`, CI workflow files (`.github/workflows/`), Makefiles.
- Branch model: default branch, any release-branch convention (`git branch -a`, `git log
  --oneline -20` on the default branch).
- Domain: what the product actually does — infer from README + top-level route/module names, not
  from file internals.

Do not ask the human to repeat anything you can determine this way.

### 2. Ask about the gaps — one at a time

For whatever the survey could NOT determine (business domain nuance, team conventions not written
down anywhere, which branch is the real production target, anything genuinely ambiguous), ask ONE
short, concrete question per turn (rule 1). Prefer closed or example-anchored questions ("Is `main`
also what you deploy to production, or is there a separate release branch?") over open essay
prompts. Stop asking once you have enough to write a useful first draft — this is a seed, not an
exhaustive audit; a later `forge-product-map` / re-run of this skill can refine it.

### 3. Propose the Project Brain, then wait for confirm

Summarize what you plan to write, grouped by target, then ask "Write this?" (rule 2):

- **`projectFacts`** (`forge_config` action=update, `projectFacts` patch) — durable, kebab-case
  key → short text facts referenced by skill bodies as `{{project:<key>}}`. Reserve this for facts
  every stage should see (a hard rule, a non-obvious convention) — mark genuinely load-bearing ones
  `alwaysInject:true` via `projectFactsConfig` sparingly; most facts stay fetch-on-demand.
- **Knowledge entries** (`forge_knowledge` action=upsert) — at minimum an `overview` entry (what
  the product is, its major feature areas); add `workflow` (a key entity's lifecycle) or `rule`
  entries only when the survey surfaced something concrete enough to diagram or state as a
  constraint. Don't invent detail you don't have evidence for — a thin, honest overview beats a
  padded one. Set `authoredBy: "agent"`.
- **Seed memory** (`forge_memory` action=write) — a handful of durable, non-obvious facts a future
  agent session would otherwise have to rediscover (a real gotcha, a firm convention, a pointer to
  where truth lives). Follow the `forge-memory-curator` contract: the 3-question gate (worth it? /
  right place — not already in code or CLAUDE.md? / safe & findable as one secret-free fact under a
  stable slug?), taxonomy (`policy` for working rules, `knowledge` for durable facts/pointers,
  `decision` for a dated architectural choice), dense `textContent` (~150–800 chars, lead line
  ≤160 chars, one fact per line, no prose padding), stable kebab `sourceRef` slug, and — the
  non-negotiable one — **never put a secret in `textContent`; store a pointer to where it lives
  instead.** Search (`forge_memory` action=search) before writing so you upsert an existing slug
  instead of duplicating a topic.
- **Pipeline config** (`forge_config` action=update, `pipelineConfig`/`baseBranch`/
  `productionBranch`) — propose ONLY when the survey found real evidence contradicting the current
  default (e.g. the actual release branch differs from what bootstrap assumed). Do not propose
  a change with nothing behind it.

If the human confirms, write each group and acknowledge it (rule 3). If they decline a group,
skip it and move on — do not re-propose it later in the same conversation unless asked.

### 4. Close out

Once the confirmed groups are written (or all declined), say what was saved (or that nothing was),
and mention that this can be re-run any time to add more — this is a starting point, not a final
state.

## Common mistakes to avoid

- Asking more than one question in a single turn — breaks the resume model this skill depends on.
- Writing anything (`forge_knowledge`, `forge_memory`, `forge_config`) before an explicit "yes" to
  that specific proposal.
- Putting a credential, token, or connection string into a knowledge entry or memory `textContent`
  — store a pointer to where it lives instead.
- Padding the overview/rule entries with guesses to look thorough — an honest, thin first draft
  that the human can correct beats a confident wrong one.
- Silently swallowing a failed write — always say when something didn't save.