Set up Archie
The conventions ship inside this bundle, so the only per-repo work is recording the facts an agent cannot guess: the gate commands, how to start the real app, and where the good test prior art lives.
Explore, present, confirm, then write. Nothing reaches disk before the user has seen the draft.
1. Explore
Fill in every fact below from the repo. A fact is settled only when you have
read the command or the path in a file. Everything else is
— a real answer, and the one that stops a later skill from trying
on a repo that has no such script.
| Fact | Where it is written |
|---|
| Package manager | the lockfile, in , the CI workflow |
| Lint, typecheck, test, build | scripts, , , targets, , , . The CI workflow is the best source of all four: it shows which ones actually run, and how they are scoped in a monorepo |
| Run the app, and its port | the dev script, , , the README quickstart; the port in the dev server config, the e2e , or |
| E2E harness | , , and the directory its specs sit in |
| Unit and integration test prior art | the existing specs. Pick one file per layer that a new test should be modelled on: recently touched, and asserting real behaviour rather than smoke-checking. Name the file, not its directory |
| Seed data and test credentials | seed and fixture scripts, , env, the e2e global-setup file, the README |
| Branch convention | , the merged branches on the remote, and the default branch's name |
| Commit convention | , a or config, |
is a value, not a gap. A skill that reads one asks the user rather than guessing, and there is no greenfield mode: a fresh repo takes the same path and simply records more
s. On a greenfield repo the stack is not chosen yet, and choosing it is cross-cutting and hard to reverse — that belongs to the root Epic's scoping session and lands as an ADR, not as a setup output.
Done when every row holds either a value read out of the repo or
.
2. Present and confirm
One message, then wait:
- The drafted facts block, verbatim as it will appear in .
- Every , named, with a direct question. The user knows the port and the test login even when nothing in the repo says so, and this is the cheapest moment to get them.
- The ignore file amendment from step 4, if one is needed.
Let the user correct the draft before anything is written.
3. Write the facts section
The facts live in a delimited section of
at the repo root, which is already in every agent's context, so no skill needs a file to go and read:
md
<!-- archie:facts:start -->
## Project facts
- **Package manager:** pnpm
- **Lint:** `pnpm lint`
- **Typecheck:** `pnpm typecheck`
- **Test:** `pnpm test`
- **Build:** `pnpm build`
- **Run the app:** `pnpm dev`, served on http://localhost:4200
- **E2E harness:** Playwright, specs in `apps/web-e2e/src/`
- **Unit test prior art:** `libs/scheduling/src/lib/shift.service.spec.ts`
- **Integration test prior art:** `apps/api-e2e/src/api/shift.spec.ts`
- **Seed data and test credentials:** unknown
- **Branch convention:** `feat/<slug>` off `main`
- **Commit convention:** conventional commits, e.g. `feat(ui): users can change their avatar`
<!-- archie:facts:end -->
One line per fact, each command written exactly as it is run, and prior art naming real files whose style new tests should match.
Replace the whole block between the markers, so hand-written content in
survives untouched. No markers means the section does not exist yet: append it at the end, creating the file if the repo has none.
The section is living. Any skill that later finds a fact wrong, or creates a gate the repo lacked, writes the correction back in the same run — so re-running this skill is for a genuine change of stack rather than for filling a gap.
If
exists and does not reach
, add an
import line to it, so the facts are in context where the user's agent actually reads.
4. Keep committed
sh
git check-ignore -v .archie/probe
Silence means the planning tree is already committed. Output names the ignore file, line and pattern that would swallow it: append
and
to that file and re-run until it prints nothing. Planning lives in
and has to survive switching laptops.
When the pattern comes from a global excludes file, report it to the user instead — that file is theirs to change.
5. Report
One message: the facts recorded, and each remaining
with the skill that will ask for it.