An agent opening a repository it has never seen spends its first forty tool calls on the same questions. Where do the tests live. What may a step call. How is a scenario launched. Which environment variables must be set. What does the product actually expose.

At roughly a minute per turn that is half an hour, in every session, for answers that are identical every time and derivable without a model.

where-are-we derives them by walking the tree, and writes them where the agent will read them.

pip install git+https://github.com/ngavrish/where-are-we

where-are-we --repo ~/work/my-suite --product ~/work/my-app/src --out /tmp/map

framework map: 66 step modules, 1446 steps, 182 features, 1889 scenarios -> /tmp/map/framework_map.md

What you get

Or straight into the file your harness already reads:

where-are-we --repo . --agent-file AGENTS.md      # also CLAUDE.md, .cursorrules, …

The map is written between markers. Whatever else lives in that file survives.

What it finds

Whatever the repository is. A service, a library, a monorepo, a test suite — it is read the same way: what it is made of, where it starts, what it serves, what it exposes, and how its parts depend on each other.

Frameworks

behave · pytest · jest · playwright · cypress · robot · JUnit · TestNG · Cucumber-JVM (Java · Kotlin · Scala) · cucumber-js (TypeScript · JavaScript) · cucumber-ruby · rspec · go test · xUnit · NUnit · SpecFlow · PHPUnit · Behat · Rust · XCTest · karate · gauge · k6 · gatling

Detection is by shape, not by directory name: a page object is a class that owns selectors — wherever it lives, whatever the team calls it. Run it on a repository before you know what is in it.

When the repository knows better

Autodetection gets the shape right and the vocabulary wrong. A repository states its own, and what it states wins:

where-are-we --repo . --init      # writes a starter manifest from what was detected

{
  "name": "billing-e2e",
  "purpose": "End-to-end tests for the billing portal.",
  "layers": {
    "steps": "steps/*.py — steps own no selectors, they call page objects"
  },
  "product_src": ["../billing-web/src"],
  "conventions": ["After a fix, re-run only what failed."]
}

.framework-map.json at the root, or the same block fenced as ```framework-map inside README.md.

Directories can explain themselves too:

wawe-readmes --repo .    # a README in every content directory that lacks one,
                         # derived from what is in it, with one TODO line for a human

The map reads them back.

Keeping it current

A map is worth rebuilding when the thing it describes has moved. The commit and the newest file in the tree are recorded with it, so running the command on every checkout costs a stat walk and nothing else. --force rebuilds regardless.

where-are-we --repo . --install-hook git     # post-checkout, post-merge, post-commit
where-are-we --repo . --install-hook agent   # SessionStart, before the first turn

Options

--repo PATH          the test repository to index
--product PATH,…     source roots of the application under test
--out DIR            where the three files land
--agent-file FILE    also write the brief into AGENTS.md / CLAUDE.md / .cursorrules
--rules PATH         a corpus of rules to list by name
--runs-api URL       a runs database, to carry what earlier runs concluded
--init               write a starter .framework-map.json
--install-hook git|agent
--force              rebuild even when nothing moved
--only "routes,data model"   keep only these sections in the brief
--skip "coverage,history"    drop these
--max-lines N        cap the brief; the full map is untouched
--diff               what changed since the map already in --out
--quiet              no summary line

Why it exists

It was built for an agentic QA pipeline where seven branches ran at once and each one opened the same way: forty greps to find where the steps live, which page object owns the portal, how the driver is built, what environment.py does. Identical in every branch, identical every run, and derivable without a model — three runs died at their deadline with the branches still reading.

Nothing about it turned out to be specific to that pipeline, or to that agent, or to Python. So it lives here.

License

MIT