Skip to content
intentdocs/ docs
Docs menu
Getting Started · 1.5

Connecting a repo

Connect a repository to a project with npx intentdocs init, set up your coding agent, and link GitHub so pull requests and CI results reach each story.

Connecting a repository does three things. It puts the spec in the repo as INTENT.md, it sets up your coding agent to work from it, and, with GitHub linked, it lets IntentDocs see pull requests and test results from the repo itself rather than only from what the agent says.

The project's Start building panel lists the same three commands this page walks through:

npx intentdocs login
npx intentdocs init
npx intentdocs setup

Connect the checkout: init

Run this in the root of your repository:

npx intentdocs init

If you aren't signed in, it runs login first. Then it:

  1. Lists the projects your token can read, and the workspace they're in. Pick one.
  2. Lists the project's story maps. Pick one.
  3. Makes a first sync, as you, to check the connection.
  4. Writes .intent/config.json.
  5. Downloads INTENT.md.
  6. Adds .intent/ to .gitignore.
  7. Adds a line pointing at INTENT.md to an existing CLAUDE.md or .cursorrules.
  8. If there's no ARCHITECTURE.md, detects your stack, asks you to confirm it, and writes one.
  9. Offers to allow the IntentDocs tools in .claude/settings.json, so Claude Code stops asking before each call. It shows the list and writes only if you say yes.
  10. Offers to set up CI test reporting (see below).

init doesn't run twice. In a connected checkout it tells you to run npx intentdocs sync instead.

Note: sync tokens are retired. init no longer takes a token argument. The CLI's own sign-in is the credential, so every sync runs as the person who ran login and stops working if they leave the workspace.

What ends up in your repo

PathWritten byWhat it is
INTENT.mdinit, syncThe spec as plain markdown: product, personas, journey, and stories by release with their acceptance criteria. Commit it. See Story maps and INTENT.md.
.intent/config.jsoninitThe project, story map and workspace this checkout belongs to. No secrets. Gitignored.
ARCHITECTURE.mdinit, if missingYour stack, for the agent to read before it builds. Edit it as you go.

Refresh INTENT.md from the live map at any time:

npx intentdocs sync

Set up your agent: setup

npx intentdocs setup

Pick Claude Code, Cursor or Both.

  • Claude Code: adds the IntentDocs workflow to CLAUDE.md, writes slash commands such as /intent-next and /intent-done, and registers the CLI's local MCP server in the project's .mcp.json.
  • Cursor: adds the workflow to .cursorrules and prints the MCP config to paste.

The local server reads the one project this checkout is linked to, with a smaller set of tools. For the full set, including plans, tests and build runs, also connect the hosted server. See Connecting your agent and CLI: Project setup.

On the project's Overview, the Connections card has a row for the repo.

  1. Link a repo: Connect existing to pick one of yours, or Create new for a private repo. You can also do this when you create the project.
  2. Choose Install the GitHub App and install it on that repo. In a GitHub organisation an owner may need to approve the install first.

With the App installed, IntentDocs records pull requests and commits from the repo:

  • A pull request that names a story moves it from to do to in progress when it opens.
  • When it merges, the story becomes dev complete if every must criterion passes. Otherwise it stays in progress, marked Merged · waiting until the criteria are reported.
  • A pull request that touches a built story's code gets an IntentDocs check naming the story.
  • Stories that are approved, cancelled or sent back for rework are never moved. Those are a person's call.

A pull request names a story by its branch (for example pb-42-reset-a-password), by the story key or link in its footer, or by being the PR already linked to the story.

Every pull request linked to a story ends with a line like this, where both parts are links:

Spec → Code via intentdocs.com · story PB-42

With GitHub connected, IntentDocs adds it to the PR body itself when the agent calls link_pr or complete_story, or when you run npx intentdocs done <story> --pr <url>. Without GitHub, the tool's response gives the agent the exact line to add. The footer never includes the story's title or spec text, because PR bodies are often public.

Report test results from CI

Agents report whether each criterion passes. CI can report too, so a test's result comes from your test suite rather than the agent's word.

npx intentdocs ci

This creates a CI key for the project, adds .github/workflows/intentdocs.yml to run your tests and post the results, and stores the key as the INTENTDOCS_CI_KEY repo secret. If it can't do a step for you, it prints what to do by hand.

  • Results are applied only from runs on the default branch.
  • A result reaches a story only if the agent saved that test with save_tests, with its file and full_name exactly as your test runner reports them.
  • npx intentdocs ci --status shows how the last run's results matched your saved tests.

Once it works, a test card on the story's Tests tab reads "passed on" a commit. You can see and revoke CI keys in Project settings → Test reporting. See Verification.