Your first spec, end to end

This is the whole product in one sitting. Follow it with the demo running and you will have connected a repository, grounded it, approved a spec and merged a generated pull request.

01 · Connect — point specd at a repository

In the wizard, register the seeded fixture repository. In a real project you have three ways in: a local path (nothing leaves your machine), a GitHub App installation (repository-scoped tokens that expire within the hour), or a GitLab access token. See Connect a repository.

What to look at: specd records which repository, not a copy of it. Your git remains the source of truth for everything that follows.

02 · Ground — let it read the repo

Grounding reads the repository the way a new engineer would: manifests, CI workflows, compose files, .env.example, schemas, the workspace layout. It then opens a setup pull request carrying two things — an AGENTS.md of working agreements, and a knowledge/ base.

Open that pull request and read it properly. This is the most important review in the whole product, because everything downstream cites it.

Tables are quoted, not inferred

Commands, pipelines, services, configuration and entities are quoted from the files they name. If the table says the test command is pnpm test, a file in your repo says so.

Judgement is drafted, and labelled as draft

The prose around the tables — what the architecture means — is a draft for you to correct. It is not presented as established fact.

UNVERIFIED is a question, not a placeholder

Anything the scan could not ground says so. The wizard does not pretend to know your architecture. Answering these is the highest-value editing you will do all week.

03 · Adopt — merge the setup branch

Merging is the adoption signal. specd indexes knowledge/ the moment the webhook lands; in local mode there is an "I merged it" button instead. Nothing about adoption is a separate ceremony — the merge you were going to do anyway is the event.

04 · Spec — turn a ticket into something reviewable

Create a ticket on the board (or import one from Jira) and hit Draft spec. The SpecAgent retrieves from your knowledge base and writes three sections.

1. Requirements

   EARS-shaped acceptance criteria — when ‹trigger›, the system shall ‹response›. Testable by construction, because "shall" statements are what a test asserts.

2. Design

   The approach, with a citation behind every claim. A claim the agent could not ground in your own docs is marked UNVERIFIED instead of asserted.

3. Tasks

   An ordered list, each sized to one pull request. The final task of every spec is always the same: file the as-built record into knowledge/specs/.

Without a model credential, this step fails with a clear error rather than inventing content — see Bring your own model.

05 · The gate — read it, then approve it

This is the step that only a human can take. Reviewing and approving a spec is a checklist for doing it well; the short version:

• Read the requirements first and ask whether shipping exactly these would satisfy the ticket. Everything else is downstream of this.
• Spot-check two or three citations. Click them. A citation is a promise that someone can follow it.
• Read every `UNVERIFIED` claim. Each one is a decision the agent is asking you to make.
• Check the tasks are each genuinely one pull request.

06 · Build — the agent implements what you approved

Start the build from the spec drawer. Three properties are enforced rather than hoped for:

• The gate is re-checked at the point of use. An unapproved spec gets a 409 at the exact moment agent output would first reach code.
• The agent gets editing tools only — never a shell. specd runs your repository's own verify command itself.
• It never touches your working tree. Local builds use a throwaway git worktree; the branch survives, the workspace does not.

You get a pull request: one commit per task, on the spec's own spec/<id>-<slug> branch. Verify results distinguish failed (your tests ran and did not pass) from could not run (toolchain missing) — different problems, different reviewers.

07 · Learn — merge, and watch the loop close

You merge the pull request. The webhook fires, the as-built spec is filed into knowledge/specs/, and the index refreshes. That record is now retrievable context for the next spec.

The loop closes on merge, not on approval — because the thing worth remembering is what actually shipped, not what was planned.

What you just proved

• A ticket became a document a human could check in minutes.
• A named person approved it, and that approval is pinned to a version.
• An agent built only what was approved, and could not have built anything else.
• The knowledge base is one spec richer than it was this morning.

Next