specd Get started

DOCS · GUIDES

Ground your repository

What the onboarding scan reads, what it writes, and how to review the setup pull request properly — the highest-leverage review in the whole product.

On this page

Grounding is the station that decides how good every later spec can be. Everything downstream cites what lands here, so this is the one pull request worth reading line by line.

What the scan reads

It reads the repository the way a new engineer would, starting with the files that state facts rather than opinions:

  • Manifests — package.json, go.mod, pyproject.toml, workspace files: what this is built with, and what the commands are.
  • CI workflows — the pipeline that actually gates merges, which is the most reliable statement of "how we verify" any repository contains.
  • Compose files and Dockerfiles — the services the thing needs to run.
  • `.env.example` — the configuration surface, named and described by whoever wrote it.
  • Schemas and migrations — the entities, and their real names.
  • Workspace layout — where the modules are and how they depend on each other.

What it writes

A setup branch and a pull request containing two things: AGENTS.md at the root, and a knowledge/ tree. The content splits cleanly into two halves, and the split is the thing to understand before reviewing.

HalfWhat it isHow to review it
The scanned halfTables of commands, pipelines, services, configuration and entities — quoted from the files they name.Spot-check a row against its source file. It should be a quote, not a paraphrase.
The drafted halfThe judgement around the tables: what the architecture means, why it is shaped this way.Read it as a first draft by someone who read your repo this morning. Correct it freely — that is what it is for.
UNVERIFIED markersEverything the scan could not ground.Each is a question. Answer the ones you can; leave the rest as open questions.

Reviewing the setup pull request

  1. Check the commands table first

    If the "verify before PR" command is wrong, the build station will run the wrong thing on every future spec. This single row is worth more than the rest of the review.

  2. Read architecture.md as a stranger would

    The question is not "is this how I would describe it" but "would someone who had never seen this repo be misled". Fix the misleading parts; leave the merely terse ones.

  3. Sweep the UNVERIFIED markers

    Answer what you know, in the same pull request. Move the rest into knowledge/open-questions.md so they are tracked rather than lost.

  4. Read AGENTS.md and agree to it

    It is your team's working agreement with every agent that touches the repo. If a rule does not fit how you work, change it now — it is your file, in your repo.

  5. Merge

    Merging is adoption. specd indexes knowledge/ the moment the webhook lands.

Without a model credential

Grounding still runs, and still produces something useful. The scanned half — commands, CI, services, configuration, entities, test layout — is written without a model at all. The judgement sections are left carrying the question they exist to answer instead of being filled in with plausible prose.

Grounding is a queued job

A grounding run is a queued row, claimed by whatever will execute it — the server, or a paired runner if the project is in subscription mode. A run whose executor dies is failed rather than left spinning, and the run log streams live in the app while it works.

Re-grounding later

You can ground again — after a large refactor, or when adding a second repository to the project. It is a one-per-repo investment: spend properly on the first review, because every spec afterwards cites it. Grounding never overwrites your edits silently; it proposes, and you review the same way you did the first time.