Workstate Docs

Engineering ​

Give coding agents the codebase, the docs and the decisions behind them.

Who it's for ​

Developers, tech leads and platform teams who work with coding agents such as Claude Code, Cursor or Codex. Also anyone who has asked "why is it built this way?" and got no answer.

What Workstate does for you ​

Your agent searches every connected repository, design page and ticket in one call. It answers with citations: repository, file path and line range. Before it changes something, it checks the ledger for decisions and past incidents about that code. When it finishes, it records what it decided, so the next person's agent doesn't have to work it out again.

The prompts below are illustrative. Change the names to match your own repositories and projects.

Answer questions about the codebase, with citations ​

text
Where do we verify webhook signatures? Search the code and cite the repository, file and line range for each place you find.

Search ranks results by the meaning of your question, across every repository in the namespace. The agent can narrow a search to one repository, a language or a path prefix.

Record decisions as you make them ​

text
Before we put a cache in front of the pricing service, search the ledger for earlier decisions about caching or pricing. If we go ahead, record a decision in project "pricing" with what we chose and what we rejected.

A decision topic works as a lightweight architecture decision record. It has a fixed summary of the question, a current state that says what stands now, and an append-only history.

Follow an incident through ​

text
Search the ledger for incidents about payment timeouts. For each one, tell me the cause and whether a fix was recorded. Then append today's finding to the incident that's still open.

Onboard to an unfamiliar service ​

text
I'm new to the billing service. Using the code, the Confluence design pages and the ledger, explain how an invoice is generated. List the decisions I most need to know, with citations.

Sources to connect ​

Available now

  • GitHub, through the Workstate GitHub App. It's read-only, and you choose the repositories. Workstate indexes each repository's default branch.
  • Confluence, for design documents and runbooks.
  • Jira, for issues and their comments.
  • Upload files, for exported documents or code that isn't on GitHub.

Coming soon

  • GitLab Coming soon
  • GitHub Enterprise Coming soon
  • Linear Coming soon
  • Slack Coming soon

Instructions to give your agents ​

Start from the shared agent instructions, then add rules for your team:

md
- Before you change a module, search the code for how it works now, and search the ledger for decisions about it. Filter both by the repository's name.
- Cite the repository, path and line range for every claim about the code.
- Record each design decision, root-caused bug or dead end as its own ledger topic. Use the repository's name as the project.
- If a decision replaces an earlier one, create the new topic and supersede the old one. Never rewrite history.

Ledger habits ​

  • Decision for each design choice, with the options you rejected.
  • Incident for an outage, with the current state updated as it moves.
  • Defect for a bug you root-caused, especially a non-obvious one.
  • Investigation for an approach you tried and dropped, so nobody tries it again without knowing.

Name the ledger project after the repository. Topic ids then read like payments-0012, and one repository filter narrows both code and ledger searches.

An illustrative example ​

Illustrative

A developer asks Claude Code to add automatic retries to card charges. Before writing code, the agent searches the ledger. It finds payments-0012, an accepted decision: no automatic retries on charges, because a retried charge could bill a customer twice until the payment provider supports idempotency keys.

The agent stops, cites the decision and asks how to proceed. The developer asks it to make retries safe first. When that change ships, the agent records payments-0019, which supersedes payments-0012. Both stay in the ledger, and the older one is marked superseded.

Limits to know ​

  • GitHub sources index the default branch only. They don't include history, pull requests or issues.
  • Workstate skips files over 1 MB, dotfiles (including .env files), vendor and build folders, lockfiles, and minified or binary files.
  • Workstate doesn't filter secrets committed to a repository. Remove committed secrets before you connect a repository, or leave it out.
  • Search returns the best matches, not every match. To find every call site of a function, use your editor's search.
  • Everyone with access to the namespace sees everything indexed in it.

Next steps ​

Workstate is built by Nerdstorm Pty Ltd, Sydney.