Skip to content
Set up from the terminal

One terminal session connects your code to its spec. Your agent knows what to build, and CI reports back to each story.

Run one command in your repo. You approve it in the browser, pick your project, and the CLI writes the rest. Below is a real session, replayed with the personal details swapped out.

The session, replayed

  1. Step 01

    Log in

    Your browser opens and you approve this machine once. The terminal gets its own token, so you never paste a password or a key into it.

    • The token is tied to the workspace you pick in the browser.
    • Your own Anthropic key is optional, on any plan.
    zsh · ~/code/courtside
    you@laptop ~ % cd ~/code/courtside && npx intentdocs loginLogging in to intentdocs... Opening browser to authorize...If it doesn't open, visit: https://www.intentdocs.com/cli/auth?code=•••••••• Waiting for browser approval.... ✅ Logged in as user_•••••••• — token personal You can now run: npx intentdocs initOptional: add your Anthropic API key to unlock AI features on any plan — npx intentdocs keys set
  2. Step 02

    Pick your project

    init lists the projects you've specced on intentdocs.com. You type a number; nothing to copy, no ids to look up.

    • It says which workspace you're reading from.
    • Pick the project whose spec this code builds.
    zsh · ~/code/courtside
    you@laptop courtside % npx intentdocs init Fetching your projects... Personal workspace — only you can see what's here. Your projects:   1. Pantry Pal  2. Courtside  3. Invoice Nudge  4. Dog Walk Rota Select project [1-4]: 2
  3. Step 03

    Connect the map

    This folder is now tied to the story map. INTENT.md is the spec your agent reads: every story and what “done” means for it, as a plain file in your repo.

    • INTENT.md works without an account. It’s yours.
    • .intent/ holds the local connection and is gitignored, so it never gets committed.
    zsh · ~/code/courtside
    Fetching story maps... Story maps in "Courtside":   1. Courtside — Story Map Select story map [1-1]: 1 Connecting to "Courtside — Story Map"...✓ Connected to "Courtside — Story Map"  22 stories — 3 done, 19 todo ✓ Downloaded INTENT.md✓ Added .intent/ to .gitignore
  4. Step 04

    Confirm your stack

    It reads your repo and guesses the stack. Press Enter if it's right, or type yours. ARCHITECTURE.md records it, so your agent builds on what you have instead of picking a new framework.

    • Edit ARCHITECTURE.md as you build.
    • Then init prints what you can run next.
    zsh · ~/code/courtside
      Detected stack: Node.js (TypeScript)  Is this correct? (press Enter to confirm, or type your stack):  ✓ Created ARCHITECTURE.md with your stack (edit it as you build)   ✅ Ready! Next steps:     npx intentdocs status         — see your story map    npx intentdocs next           — pick up the first story    npx intentdocs setup          — configure Claude Code / Cursor slash commands    npx intentdocs ci             — report your tests' results from CI to each story    npx intentdocs propose        — plan a new feature from the terminal
  5. Step 05

    Wire up CI

    Say yes and it creates a CI key, writes a GitHub Actions workflow that runs your tests, and stores the key as a repo secret with gh. From then on, each test result lands on the story it proves.

    • With gh signed in, the secret is stored for you.
    • Not now? Run npx intentdocs ci later.
    zsh · ~/code/courtside
      Set up CI test reporting now? It creates a key and adds the workflow. (y/N): y ✓ Created a project CI key (shown once below — store it now). ✓ Wrote .github/workflows/intentdocs.yml — it runs your tests and reports each result to its story. ✓ Stored the key as the INTENTDOCS_CI_KEY repo secret with gh.
What you end up with

Three files, one line, one secret.

Everything but the secret is a plain file in your repo, so you can read it, edit it and commit it.

courtside / files written
  • INTENT.mdfileThe spec your agent reads: every story and its acceptance criteria.
  • ARCHITECTURE.mdfileYour stack, so the agent builds on it. Edit it as you go.
  • .github/workflows/intentdocs.ymlfileRuns your tests in CI and reports each result to its story.
  • .gitignore+ .intent/Keeps the local connection out of your commits.
  • INTENTDOCS_CI_KEYrepo secretLets CI report to your project. Stored with gh, never in a file.
Then: build

Your agent starts from the spec, one story at a time.

  1. $ npx intentdocs next

    Pick up the first story, with its acceptance criteria.

  2. $ npx intentdocs setup

    Add slash commands to Claude Code or Cursor, like /intent-next, so your agent can do the same.

  3. $ npx intentdocs ci --status

    After a CI run, see which test results reached which story.

Your agent connects over MCP instead, without the CLI? Connect your AI tool. Then each story goes through the day-to-day loop, from spec to approved.

Get started

Spec it once. Your agent builds against it from the first story.

Your vision and story map are free. Then run one command in your repo.

Get started