Project Instructions

These rules override defaults. This is a fresh template — fill the _(fill at kickoff)_ blocks in your first session (see KICKOFF.md). Before the first commit, run git remote -v: if origin is the template's repo (the template: line of docs/upstream.md), stop and repoint it, because every session ends with a push (KICKOFF.md → First run).

The Work Model — phases, modes, rituals

Canonical rules + glossary: docs/CONTRIBUTING.md → "The Work Model." Live picture: /system (derived from docs/ every commit — never hand-maintained).

• A phase is a board passing through kinds in order — open, build, close, and inside a run basic layer, survey and deepen — each kind one session at one fixed level from the board's Levels line, or all of them in one chat for small work (docs/CONTRIBUTING.md → The phase pipeline). Its mode — product · system · side · queue-shaping — sets ritual focus, template, orient set, and touch bands. Every phase opens a board in docs/phases/ from its mode's template (mode: product | system | side) and closes it in the same arc; a session (chat) serves one board-kind — a split board's single kind, or a collapsed board's whole arc — and never two boards. Opening a session: match your arrival to a shape — § Session starters in docs/CONTRIBUTING.md (rendered at /system/method); a reading-only session needs no board, and the first edit is the line that opens one. Close = distill + delete: decisions → docs/decisions.md, behavior → feature docs, tracker rows moved, the canon diff ratified by the PO (changes to bedrock/commitments docs — docs/CONTRIBUTING.md → shared rules), board deleted, and the close hands off the opening line for whatever comes next; product phases leave a compact record in docs/archive/phases/. A find about a surface another open board owns lands in that board's ## Raised — any mode may write one, because a note is never an item: the receiving session drains the section at its open, authors its own O or V item where one is owed, and an undrained entry holds that board's close. A closed board has no section; that find goes to a tracker row or the queue. Concurrency: one active board per mode (status: active | waiting | paused; a run holds many waiting boards). paused = stopped mid-kind, nobody on it — set at session end when the kind is unfinished, stage: put back to that kind, holding no slot, and cleared only by a session that picks it up and finishes. Commits are mode-pure and name their board. A phase belongs to one project — the repo its board lives in; a sibling project's work is handed over, never done from here.
• The queue = the ROADMAP's What's Next — upcoming planned work of any mode, one mode-tagged list; every row carries a seed (docs/planning/queued/) where context accumulates. Each phase maintains its own row and reads the rest — its row removed at open (then scan what's left), written as the idea forms, mid-phase or else at close (then feed a dated note into any seed the work bore on), row and seed always together in the same edit; shaping the queue at any other time is a queue-shaping phase (the fourth mode: two-tier orient, one chat, a few-line board). Trackers hold candidates, not queued work — an item that bloats or clusters promotes into a phase.
• Orient, then edit — the touch bands gate pens, not eyes. Every mode's opening ritual reads its core set whole (product: the full strategy shelf) and actively aligns to the emphasized set; reading is never gated. Bands: home ground (edit freely), careful (deliberate, flagged), gated (another mode's ground — suggest, don't edit). Orientation is align or challenge — work pressing on a settled commitment raises a structured challenge; sometimes it should win. (The one-time kickoff bootstrap is the exception — all ground is open, because it's creating the shelf the bands protect; see docs/CONTRIBUTING.md → The Kickoff.)
• Chat levels — your tier→model mapping (fill at kickoff; the canon names tiers, never models): high = [your strongest model / max effort] · standard = [your working model] · cheap = [a fast model, for mechanical stretches]. Boards declare tier words on their Levels line; this mapping is where the words meet a model.
• Product phase: carries a thesis; usually queue-born. On its own it runs open → build → close; inside a run it runs open → basic layer → survey → deepen → close, the basic layer of everything before any polish, V items deferred to the deepen kind. After the build commits, the walkthrough is a main chunk of the phase — a collaborative point-by-point review WITH the user (docs/phases/<name>-walkthrough.md). Before closing: show the user the Closing Checklist.
• System phase: governance docs are its home ground (this file, CONTRIBUTING, ROADMAP structure, /system code), along with production code that is the system's surface — the band is purpose, not file location, and product behavior stays gated. Always done with the user; closes with a light in-chat verification handoff.
• Side phase: tracker-born — a sweep of several punch/question/FC items on a light board. Home ground: the code it changes + its own tracker rows. Grows a thesis → stop, it's product-shaped. Closes with an in-chat verification handoff. Default for "resume a paused board?" is no — ask first.

Workflow Rules

1. Work from the current phase board in docs/phases/. Check it before starting.
2. Read referenced docs before starting a task. Update them if anything changed.
3. Doc frontmatter: every doc has status, tier, last-reviewed, read-when. Bump last-reviewed only when you review a doc, never on a mechanical touch.
4. No feature sprawl. If it's not on the phase board, don't build it without discussion.
5. Phase close = doc review. See docs/product-lifecycle.md → Closing a Phase.
6. Push back, don't just comply. When there's a better approach, make the case — lead with a recommendation, not a menu.
7. Never run npm audit fix --force. In this dependency tree it "fixes" advisories by downgrading Next.js to 9.x — a pre-App-Router version from 2020 that cannot run this app. npm audit fix (without --force) is safe. See "A note on npm audit" below before acting on a vulnerability report.

A note on npm audit

A fresh npm install reports around a dozen high severity advisories. They are all transitive and none is a live exposure for this app:

• Most are the ESLint chain — a denial-of-service in a glob matcher used by a linter that only ever runs on your own machine.
• The rest are inside Next.js's own bundled dependencies (postcss, and sharp, which is only used by next/image — a component this template never imports).

They cannot currently be resolved from here. ESLint 10 breaks eslint-plugin-react, and the vulnerable packages are bundled inside eslint-config-next, so the fix belongs upstream. Dropping eslint-config-next would silence the report at the cost of the React and accessibility rules that catch real mistakes — a bad trade.

What to do: keep Next.js patched (npm install next@latest for patch and minor releases; that is what fixed the last real one). Re-check with npm audit after upstream releases. Do not force it.

Stack

(fill at kickoff — framework, language, styling, backend, dev-server command, test/lint/build commands. Do NOT inherit the template's Next.js stack by default — it hosts the /system dashboard, nothing more. Choose from the project's goals and a FRESH check of current tooling/hosting options and costs; state the reason for the choice in decisions.md. See KICKOFF.md step 3.)

Design & Code Conventions

(fill at kickoff — the stack-neutral reuse-first + flag-new principles live in docs/CONTRIBUTING.md → Design & Code Conventions; add the concrete rules here: styling system, tokens, naming, accessibility baseline, any hard gates)

Key Docs

Strategic Context

(fill at kickoff — the project's guiding thesis and priorities. Full strategy in docs/strategy/.)

Core Principles

(fill at kickoff — foundational rules that shape decisions across the project. Implementation details live in their home docs, not here.)