Make the next feature easy to locate, run, and verify. Inspect the repository, manifests, lockfile, and local instructions first. Improve existing conventions before introducing new ones.
Work
- Confirm runtime, package manager, framework, deploy target, and actual commands. Distinguish existing tooling from proposed additions.
- Place route composition, feature logic, reusable primitives, validation, and data access near their owners. Do not create empty folders for hypothetical scale.
- Choose one token source and identify how primitives consume it. Reuse an existing UI library; a new repository does not require a custom Button.
- Document environment variable names and safe placeholders. Keep secret validation and access server-side; never import a secret-bearing environment object into browser code.
- Set the smallest useful verification path: types/lint/build and a meaningful check of the first critical flow. Add infrastructure when it addresses a concrete risk.
- On existing projects, preserve user edits and change only the foundation implicated by the task. Explain migration effects on consumers.
Deliver
For planning, give actual/proposed paths, commands, and an ordered setup sequence. For implementation, create the authorized foundation and run its checks rather than stopping at a checklist.
## Foundation plan
Stack assumption: Package manager: Deploy target: Structure: actual/proposed paths Commands: install, dev, check, test Env: names + placeholders + validation Tokens / data / checks: locations and commands
Setup sequence
- ...
- ...
A usable result lets a fresh checkout install reproducibly, run a slice, and locate tokens, data access, and verification commands. Update the package-manager lockfile through the package manager when dependencies change.
Use `$context` to record durable repository facts and `$git` for collaboration policy when those are needed.
## Worked example
```markdown
## Foundation plan
**Stack assumption:** Detected Vue 3 + Vite from manifest; preserved
**Package manager:** Detected npm from lockfile; preserved
**Deploy target:** Detected host from repo config; preserved
**Structure:** Detected `app/`, `ui/`, and `lib/` folders preserved; the first feature gets its own folder once it has files
**Commands:** Detected install, dev, check, test from manifest; no new tooling added
**Env:** `.env.example` added for the three variables the code reads; server-side validation module; secrets stay server-side
**Tokens / data / checks:** Reuse detected token file; data access stays in `lib/`; detected check runs before PRs
### Setup sequence
1. Record detected stack and commands
2. Repair missing env example
3. Reuse token source
4. Build first slice + check
5. Record facts with `$context`
Gotchas
- The lockfile, not the README, names the package manager; installing with another one creates a second lockfile.
- Many frameworks ship variables with a public prefix, and any module a client file imports, to the browser; check how this project keeps secrets server-side.
- Empty folders for future scale (
services/,utils/) become dumping grounds; create a folder with its first file. - A setup that works on one machine often leans on a global tool or a local variable; test from a fresh clone with only the documented steps.
- A foundation repair that moves files breaks every open branch; list the moves for other contributors.
Boundaries
- Do not use to choose the framework or stack; use
$stackinstead. - Do not use to audit UI drift or duplicate components; use
$systeminstead.