Setup

Project setup

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
1. ...
2. ...

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

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: app/ routes; ui/ primitives; features/ per feature; lib/ data and validation; existing token file preserved Commands: Detected install, dev, check, test from manifest; no new tooling added Env: .env.example checked in; server-side validation module; secrets stay server-side Tokens / data / checks: Reuse detected token file; data in lib/data/; detected check 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

• Repair the detected foundation; do not propose a new stack when the task is foundation repair.
• Verify runtime, package manager, and commands from manifests and lockfiles; do not invent tooling.
• Preserve existing conventions and user edits; change only the implicated foundation.
• Place code near its owner; do not create empty folders for hypothetical scale.
• Keep secrets server-side; do not import secret-bearing env objects into browser code.
• Reuse one token source and existing primitives; do not add a second system without need.

Boundaries

• Do not use to choose the framework — use $stack first.
• Do not use to audit UI drift or duplicate components — use $system for that review.