@baldurpan/create-ai-workflow 0.2.0

package/templates/skills/feature-status/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: feature-status
+description: "Read-only report of where the active feature stands — its plan's phase ledger, open findings, and git state — ending with exactly one next action. Explicit invocation only — run this when the user types /feature-status. Do NOT match on 'what's the status', 'where are we', or general progress questions."
+---
+
+# /feature-status
+
+The read-only "where do things stand" view. **It writes nothing, commits nothing, and invokes no other
+agent.**
+
+**It is never a prerequisite.** Every other command resolves its own starting point — nobody has to run
+this first. It exists for when *you* want to know.
+
+Read [`context/workflow.md`](../../../context/workflow.md) for the tier model.
+
+## 1. Read, in this order
+
+1. `context/roadmap.md` — which entry is `active`, and what each entry's **Doc** points at.
+2. That plan document's **status ledger**, and each phase's **Files:** line.
+3. `context/findings.md` — open findings, and which phase each is tied to.
+4. Git state — `git status --short` and the last few commits.
+
+**Nothing is cached and nothing is parsed by a script.** Read the ledger every time. That is the property
+that makes hand-editing a row change this command's answer immediately, with no regeneration step.
+
+## 2. Reconcile before trusting the ledger
+
+Report and **stop** on any of these:
+
+- A phase marked `done` whose **Files:** or commits do not exist.
+- A phase marked `not started` whose work is plainly already in the tree.
+- An entry marked `active` pointing at a document that does not exist.
+- An entry marked `active` for a feature that already has a `context/history.md` row.
+- **A document in `context/plans/` that no roadmap entry points at.**
+
+Do not resolve a discrepancy yourself, and do not pick a next action off a ledger you have just shown to be
+stale. That is the exact failure this workflow exists to prevent.
+
+**Two things that are not discrepancies:**
+
+- Every phase `done` while the entry still reads `active` — that is the normal state before
+  `/feature-close`. Next action 5 handles it.
+- A `done` row with its changes still in the working tree — a phase finished but not committed. Name it in
+  the report; do not stop on it.
+
+## 3. Report
+
+Keep it short. The user is asking a question, not reading a document.
+
+```
+Feature:  <name> — <marker>        (or: none active)
+Plan:     <path>
+Phases:   <n> done · <n> in progress · <n> blocked · <n> not started
+Findings: <n> open (<severities>)  (or: none open)
+
+Next: <exactly one action>
+```
+
+Under the header, list only the phases that are **not** `done`, one line each with their Note. Do not
+re-print the whole ledger.
+
+## 4. Name exactly one next action
+
+In priority order — take the **first** that applies and name only it:
+
+1. An open `P0` or `P1` → fix it. Quote the finding's id and its closing condition.
+2. A phase **`in progress`** → resume it, quoting its Note. Do not restart it.
+3. A phase **`blocked`** with every other phase `done` → report the blocker; the next action is the user's.
+4. A phase `done` with a next **unblocked** phase → `/feature-implement`, naming the phase it will pick.
+5. **Every** phase in the active plan `done` → `/feature-close`.
+6. **No active feature, but at least one entry has a plan** → `/feature-implement`, which ranks the planned
+   entries and asks.
+7. **No plans, at least one `pending` entry** → `/feature-plan`. **Do not pick a candidate yourself** —
+   that command ranks the backlog and asks, and naming one here would either duplicate its ranking or
+   contradict it.
+8. **Nothing at all** → `/roadmap "some idea"`.
+
+"Exactly one" is the point. A list of three things to consider is what this command exists to replace.
+
+## Rules
+
+- **Read-only. No exceptions.** Not the ledger, not the roadmap, not a finding, not a "quick fix while I'm
+  here". If you spot something that needs changing, name it as the next action and let the user decide.
+- **Never invoke another agent.**
+- **Never mark anything.** Reporting that a phase looks finished is not marking it `done`; only
+  `/feature-implement` does that, on gate evidence.

package/templates/skills/onboard/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: onboard
+description: "Fill in this project's own workflow stubs — context/verify.md, context/executors.md and context/stack.md — by asking, and by running each candidate verification command and keeping only the ones that pass. Explicit invocation only — run this when the user types /onboard. Do NOT match on 'set up the project', 'get started', or general setup requests."
+---
+
+# /onboard
+
+Fills the project-owned stubs the installer deliberately left empty. **Re-runnable** — run it again after
+the stack changes, and it re-proposes against what is there now.
+
+**Asking is not guessing.** The installer could have detected a test command and written it in; that is
+exactly how a file ends up naming a command that has never run. This command asks, and where it can, it
+*checks*.
+
+Read [`context/workflow.md`](../../../context/workflow.md) for the tier model.
+
+## What it writes
+
+| File | Gets |
+|---|---|
+| [`context/verify.md`](../../../context/verify.md) | the real Lint / Typecheck / Build / Test commands — **only ones that exited 0** |
+| [`context/executors.md`](../../../context/executors.md) | how this project dispatches a coder and a reviewer |
+| [`context/stack.md`](../../../context/stack.md) | runtime, layout, conventions |
+
+Show every proposed edit before writing it, and **do not commit.** The user reviews and commits.
+
+## Step 1 — Coder dispatch
+
+Ask whether implementation runs **in-host** or is **offloaded** to an external coder CLI.
+
+- **In-host** is the default, and a valid configuration rather than a gap. Leave the Coder section of
+  `context/executors.md` saying so.
+- **Offloaded** — the user names the invocation. Write it into `context/executors.md` verbatim, including
+  any directory or permission scoping it needs on this machine. Its system prompt is
+  [`context/roles/coder.md`](../../../context/roles/coder.md).
+
+If an external coder is named, **test one assumption before writing it down**: that it can read this
+repository unaided. Briefs cite paths rather than pasting file contents, so everything downstream depends
+on that being true, and it is true of some executors and not others.
+
+1. Pick a fact only available by opening a file here — a heading partway down `context/workflow.md` does.
+2. Send a one-line brief that cites the path and asks for that fact. Nothing else.
+3. If the fact comes back, record in `context/executors.md` that repository reads were verified, and when.
+4. If it comes back empty, guessed, or refused, record that **this executor needs content inline** — the
+   one case where a brief carries file contents instead of paths.
+
+Never write down an invocation you have not run. This is the same rule as Step 4, for the same reason.
+
+## Step 2 — Reviewer dispatch
+
+Ask how Gate 2 should get a review:
+
+- **The host reviews the diff itself** against the plan's review checklist and the standards. That is the
+  default. It is weaker than an independent reviewer, and any command that runs the gate must say which one
+  it ran.
+- **An external reviewer** — the user names the invocation. Write it into `context/executors.md` verbatim,
+  including any scoping it needs on this machine.
+
+A host that offers review usually offers more than one shape of it — a review subcommand, a review skill it
+can be asked to run, or both — and they do not review alike. **Find out what this host actually provides
+rather than assuming**, show the user what you found, and let them choose. Nothing shipped here names a
+winner: it differs per host and changes underneath you. What ships is the contract, not the command.
+
+Whatever is chosen, that contract stands: a review happens, every blocking finding carries a `P0`–`P3`
+severity, and a `FAIL` writes a finding before the loopback.
+
+## Step 3 — Standards source
+
+`context/standards/` ships with a bundled default. Ask whether that is right for this project.
+
+- **Keep it** — nothing to do. It stays tool-owned and updates with the tool.
+- **Swap it** — the user gives a git URL, and the swap is
+  `npx @baldurpan/create-ai-workflow standards add <git-url>`. Tell them that command rather than cloning
+  it yourself: it validates that the tree has a usable conditional-loading table, and whatever lands
+  becomes project-owned from that point.
+
+Say plainly what the default is and that a wrong set is not inert — agents load from that README's
+conditional table unprompted, on every task.
+
+## Step 4 — Verification commands
+
+**This is the most valuable step in this command.** Do it properly.
+
+1. **Propose candidates.** Read `package.json` scripts, or the stack's equivalent — `Makefile`,
+   `composer.json`, `pyproject.toml`, `Cargo.toml`, the CI workflow. The CI config is the best source
+   available: it lists commands that demonstrably run in a clean checkout.
+2. **Show the candidates and ask** which belong in Lint, Typecheck, Build and Test, and whether anything is
+   missing. Ask about prerequisites too — a package manager version, an install step, a service that must
+   be up.
+3. **Run each one.** Actually run it, from the repo root.
+4. **Write only the commands that exited 0.** For each one that failed, show the output and ask: fix it,
+   replace it, or leave that section empty. **Never write a command that has not passed.** An empty section
+   is skipped by Gate 1 and says so; a wrong command fails a gate on every task until someone notices.
+5. Put anything that needs Docker, a cloud account or a deploy target under **Not run by Gate 1**, so
+   nobody promotes it into a gate section by mistake.
+
+Explain what you are doing: this turns `verify.md` from someone's guess into something verified at install
+time, which is the one moment it is cheap to catch.
+
+## Step 5 — Stack
+
+A few questions, then write `context/stack.md`:
+
+- What does this project do, in a paragraph — and anything about its history that explains its shape.
+- Runtime, package manager, database, storage, hosting.
+- The directories that matter, one line each.
+- **The conventions that would not be guessed** — what breaks in this runtime, what is deliberately kept
+  separate, where local secrets live, what must never be run against production. This section is the one
+  that earns its keep; the rest is discoverable.
+
+Point out that anything else added under `context/` should be indexed in `stack.md`, not in
+`context/README.md`, which is tool-owned and replaced on update.
+
+## Rules
+
+- **Never write a credential.** Write `$SENTRY_DSN`-style placeholders and name where the real value lives
+  — this command collects shell commands, which is the most likely place a token appears inline. See the
+  standing rule in [`context/workflow.md`](../../../context/workflow.md).
+- **Never write a command you have not run.**
+- **Never touch a tool-owned file.** `README.md`, `workflow.md`, `plan-template*.md` and `roles/` are
+  replaced on the next update; an edit there is an edit lost.
+- **Do not commit.**

package/templates/skills/orchestrate/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: orchestrate
+description: "Run one ad-hoc, commit-sized change through the same verification and review gates the feature loop uses, without a roadmap entry or a phase ledger. Explicit invocation only — run this when the user types /orchestrate. Do NOT match on 'build X', 'implement X', 'orchestrate the work', or any request that belongs to a planned feature."
+---
+
+# /orchestrate
+
+A gated one-shot pass over a scope you name. No roadmap entry, no ledger, **no tier boundary crossed.**
+
+It exists because the valuable part of the loop is the **gate machinery** — Gate 1 reading `verify.md`,
+Gate 2's reviewer, failures landing in `findings.md` before the loopback — and that is worth having for
+unplanned work too, arguably most of all, since that is where fixes get cowboyed. Without it, the only
+route to a verified, reviewed change is to file a roadmap entry, and people will route around the workflow
+for small things.
+
+Read [`context/workflow.md`](../../../context/workflow.md) for the gate contract and the feature/task rule.
+
+## Usage
+
+```
+/orchestrate "<what to do>"
+```
+
+## 0. Sweep first
+
+Move every **closed** finding tied to `ad-hoc` out of `context/findings.md`. Those belong to no feature, so
+nothing else would ever retire them and the file would grow forever. Say what you swept.
+
+## 1. Refuse, before anything else
+
+Two guards, or this becomes the way to skip planning:
+
+1. **Refuse anything that is not commit-sized.** A commit-sized unit has one checkable outcome. A category
+   of activity ("add tests", "improve error handling", "refactor the API layer") is not one. Say what the
+   scope would need to be split into, and name `/roadmap`.
+2. **Refuse anything an existing roadmap entry already covers.** Read `context/roadmap.md` and check. If
+   one covers it, say which, and name `/feature-plan` and `/feature-implement`.
+
+Apply the standing test from [`context/workflow.md`](../../../context/workflow.md): *if you would want a
+`history.md` row for it, it is a feature.* Ask that question out loud and answer it before proceeding.
+
+A refusal here is the workflow working.
+
+## 2. Do the work
+
+Read `context/stack.md` and load `context/standards/README.md` per its conditional table.
+
+Delegate to a coder per [`context/executors.md`](../../../context/executors.md) if one is configured;
+otherwise implement in-host. The coder's system prompt is
+[`context/roles/coder.md`](../../../context/roles/coder.md). The brief **cites paths, it does not paste
+files.** Describe what needs to happen, never how to code it.
+
+## 3. Gate 1 — verification
+
+Read [`context/verify.md`](../../../context/verify.md) and run its sections in order: Lint → Typecheck →
+Build → Test. **Never carry a copy of these commands here and never invent one.** A missing section is
+skipped and said so, never faked. Exit 0 is the verdict regardless of summary text. If `verify.md` does not
+exist or has no filled-in section, stop and say so. Docs-only changes run Lint plus a read of the diff.
+
+## 4. Gate 2 — review
+
+Dispatch per [`context/executors.md`](../../../context/executors.md). With no independent reviewer
+configured, review the diff yourself against the standards — weaker, and **say which one you ran.**
+
+Require concrete evidence — file paths, command output — for every verdict, and a `P0`–`P3` severity on
+every blocking finding.
+
+- `PASS` or `PASS WITH NOTES` → done.
+- `FAIL` → **write it to [`context/findings.md`](../../../context/findings.md) first, then** loop back.
+
+Findings raised here are recorded with **`Tied to: ad-hoc`**.
+
+## 5. Loopback
+
+Cap: **two loops per gate.** Re-brief with the prior implementation and the validator's feedback
+**verbatim**, plus the instruction to address only the failing items, refactor nothing that passes, and
+expand no scope.
+
+At the cap: write a finding (`P1` for a Gate 1 cap-out), then escalate with the current state and the last
+feedback. **Escalating is not a substitute for recording.**
+
+## 6. Report
+
+What changed, the Gate 1 output, the Gate 2 verdict, any loopbacks, and any findings written, closed or
+swept — by id.
+
+## Rules
+
+- **No ledger row is touched.** This command has no phase and does not belong to a feature.
+- **No roadmap entry is created, activated or retired.** If the work turns out to be a feature, stop and
+  say so; the user runs `/roadmap`.
+- **Never skip Gate 1 to save time.** The gates are the entire reason this command exists.

package/templates/skills/roadmap/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: roadmap
+description: "Print the Tier-1 feature backlog in context/roadmap.md, or append one new pending entry to it. Explicit invocation only — run this when the user types /roadmap. Do NOT match on general planning talk, 'what should we build next', or any request to design, plan, or implement a feature."
+---
+
+# /roadmap
+
+Maintains **Tier 1** — the backlog in `context/roadmap.md`. It never promotes anything, never writes a
+plan, never marks anything `active`, and never removes an entry.
+
+It *may* write a **draft** in `context/drafts/` — raw reference material the user supplied, which
+`/feature-plan` later turns into a plan. Keep that line straight: capturing what someone told you is not
+designing.
+
+Read [`context/workflow.md`](../../../context/workflow.md) for the tier model.
+
+## Usage
+
+```
+/roadmap              # print the backlog — read-only
+/roadmap "some idea"  # append one pending entry
+```
+
+## No arguments — print the backlog
+
+1. Read `context/roadmap.md`.
+2. Print every entry: name, marker, size, the one-line why, and what its **Doc** field points at.
+3. Say which entries have a plan (**Doc** into `plans/`) and which do not. Those are different facts from
+   the `pending`/`active` marker, and reporting them as one is the mistake the two fields exist to prevent.
+4. If nothing is `active`, name `/feature-plan` as the way to get there. **Do not pick a candidate** — that
+   command ranks the backlog and asks.
+
+**Do not** read a plan's ledger or report phase status. That is `/feature-status`. This command answers
+"what is on the list", not "what is next".
+
+## With an argument — append an entry
+
+1. Read `context/roadmap.md` for the existing entries and the format already in the file.
+2. **Check for an entry that already covers the idea.** If one exists, say so, show it, and stop — do not
+   add a near-duplicate. Also check `context/history.md`: an idea previously `dropped` has a recorded
+   reason, and re-proposing it needs that reason addressed, not ignored.
+3. Derive a **kebab-case name**. It becomes the entry's identity and is what `/feature-plan`,
+   `/feature-implement` and `/feature-close` are given later, so make it specific and stable.
+4. Append to the end of the **Features** list, matching the file's format. It is always `pending` — the
+   marker in the heading is the entry's status, and this command never sets any other value:
+
+```markdown
+### <kebab-case-name> — `pending`
+
+<One or two lines: the problem, or what becomes possible. Not a design.>
+
+- **Size:** <small | medium | large> — <what drives the size, a few words>
+- **Doc:** none yet
+```
+
+5. **If the user supplied reference material, capture it** — see below. Otherwise leave `**Doc:** none yet`.
+6. Show the appended entry, and the draft if you wrote one, then stop.
+
+### Capturing reference material
+
+**Capture beats summarise.** When the user gives you more than the idea — a screenshot of documentation, a
+pasted setup guide, a URL, an error dump, a long explanation of how they want it to work — that material
+does not go in the entry and must not be thrown away. Write it to `context/drafts/<NAME>.md` and point the
+entry's **Doc** field at it:
+
+```markdown
+- **Doc:** [`drafts/<NAME>.md`](drafts/<NAME>.md) — <what it is, a few words>
+```
+
+`drafts/` is the right directory and `plans/` is not. A draft is notes: no ledger, no template sections,
+nothing executable. `/feature-plan` moves it into `plans/` when it writes the plan, which is also why you
+never write directly into `plans/` from here.
+
+What to write in it:
+
+- **The specifics that are expensive to re-derive** — exact package names, version or compatibility
+  requirements, config keys, the shape of an API call, the wording of an error.
+- **Where it came from, and when.** A screenshot of vendor docs on a date is worth more than the same facts
+  with no provenance, because docs move.
+- **What it means for *this* repo.** Check the relevant config or source and say what already holds and
+  what would have to change. This is the part a screenshot cannot tell you, and the part that rots slowest.
+- **Never transcribe a credential.** See the standing rule in
+  [`context/workflow.md`](../../../context/workflow.md): a DSN, token or key gets described and pointed at
+  the secret store, never copied into a tracked file.
+
+Keep the entry itself one or two lines regardless.
+
+## Rules
+
+- **One or two lines of why. No more.** If you find yourself writing a third paragraph, that is a signal the
+  idea is ready for `/feature-plan`, not that the entry should be longer.
+- **Never guess at a design.** The entry records that a thing is wanted, not how it would work.
+- **Never mark anything `active`.** Only `/feature-plan --activate` and `/feature-implement` do that.
+- **Never remove an entry.** Entries leave only via `/feature-close`, which records why. Deleting one loses
+  the reason it was dropped, which is the whole point of `history.md`.
+- If the idea is really several ideas, say so and offer to add them as separate entries rather than writing
+  one vague entry covering all of them.

package/templates/standards/.source

@@ -0,0 +1,8 @@
+# Origin of this standards tree, recorded so `update` can report when upstream has moved.
+# Managed by @baldurpan/create-ai-workflow. Replace this whole directory with:
+#   npx @baldurpan/create-ai-workflow standards add <git-url>
+# Vendored verbatim, with one mechanical rename: npm cannot publish a file called `.gitignore`, so it
+# ships as `templates/_dot_gitignore` and is written back with its leading dot at install time.
+origin=https://github.com/baldurpan/ai-engineering-standards
+ref=dd8b7e206ff46d7555aabb2522c792d9272510b9
+vendored=2026-05-19T22:07:27+00:00

package/templates/standards/README.md

@@ -0,0 +1,104 @@
+# AI Engineering Standards
+
+Personal AI-native engineering standards for TypeScript and React projects. Optimized for AI agent consumption while remaining readable for humans.
+
+**Source:** `https://github.com/baldurpan/ai-engineering-standards`
+
+**Primary stack:** TypeScript on Node.js, React on the frontend. All standards in `philosophy/`, `typescript/`, `react/`, `architecture/`, `tooling/`, and `security/` apply to this stack.
+
+**Secondary stack:** PHP, supported in [`php/`](php/), only when the task is explicitly PHP. Do not suggest PHP for a new project, a Node-friendly task, or a TypeScript codebase.
+
+---
+
+## For Humans — How to Use This Repo
+
+In your project, create an `AGENTS.md` that references this repo:
+
+```md
+# AGENTS.md
+
+This project follows [AI Engineering Standards](https://github.com/baldurpan/ai-engineering-standards).
+Load that repo's `README.md` and follow its conditional-loading guidance.
+
+## Project / Stack / Commands
+[your project-specific content]
+```
+
+Copy [`templates/AGENTS.md`](templates/AGENTS.md) as a starting point. Optionally add a `CLAUDE.md` that points at your `AGENTS.md` ([`templates/CLAUDE.md`](templates/CLAUDE.md)).
+
+Everything below this line is for the AI agent.
+
+---
+
+## For AI Agents — Standards Index
+
+You are working inside a project that references this standards repository. Load only the sections relevant to the current task. All paths below are relative to the repository root (`https://github.com/baldurpan/ai-engineering-standards`).
+
+### Conditional Loading
+
+| If the task involves… | Load… |
+|---|---|
+| Any task (always) | [`philosophy/ai-agent-behavior.md`](philosophy/ai-agent-behavior.md), [`philosophy/core-principles.md`](philosophy/core-principles.md) |
+| TypeScript code | [`typescript/rules.md`](typescript/rules.md), [`typescript/anti-patterns.md`](typescript/anti-patterns.md) |
+| Validation / schemas | [`typescript/validation.md`](typescript/validation.md), [`security/validation.md`](security/validation.md) |
+| Naming | [`typescript/naming.md`](typescript/naming.md) |
+| Errors | [`typescript/error-handling.md`](typescript/error-handling.md) |
+| React components or hooks | [`react/component-design.md`](react/component-design.md), [`react/hooks.md`](react/hooks.md), [`react/use-effect.md`](react/use-effect.md) |
+| State management | [`react/state-management.md`](react/state-management.md) |
+| Forms | [`react/forms.md`](react/forms.md) |
+| Accessibility | [`react/accessibility.md`](react/accessibility.md) |
+| Performance / memoization | [`react/memoization.md`](react/memoization.md) |
+| Error boundaries / Suspense / loading states | [`react/error-boundaries.md`](react/error-boundaries.md) |
+| Testing | [`react/testing.md`](react/testing.md) |
+| Refactoring | [`architecture/refactoring.md`](architecture/refactoring.md), [`philosophy/incremental-abstraction.md`](philosophy/incremental-abstraction.md) |
+| Folder structure / new module | [`architecture/feature-driven.md`](architecture/feature-driven.md), [`architecture/folder-structure.md`](architecture/folder-structure.md), [`architecture/dependency-boundaries.md`](architecture/dependency-boundaries.md) |
+| Shared code decisions | [`architecture/shared-code.md`](architecture/shared-code.md) |
+| Monorepo work | [`architecture/monorepos.md`](architecture/monorepos.md) |
+| API client / contract design | [`architecture/api-design.md`](architecture/api-design.md) |
+| Date / time / timezone handling | [`tooling/dates.md`](tooling/dates.md) |
+| Tooling — TanStack (overview) | [`tooling/tanstack.md`](tooling/tanstack.md) |
+| Tooling — TanStack Router (deep) | [`tooling/tanstack-router.md`](tooling/tanstack-router.md) |
+| Tooling — TanStack Query (deep) | [`tooling/tanstack-query.md`](tooling/tanstack-query.md) |
+| Tooling — Vite | [`tooling/vite.md`](tooling/vite.md) |
+| Tooling — Biome | [`tooling/biome.md`](tooling/biome.md) |
+| Tooling — Tailwind | [`tooling/tailwind.md`](tooling/tailwind.md) |
+| Tooling — shadcn/ui | [`tooling/shadcn.md`](tooling/shadcn.md) |
+| Tooling — Prisma | [`tooling/prisma.md`](tooling/prisma.md) |
+| Tooling — Nx | [`tooling/nx.md`](tooling/nx.md) |
+| Adding a dependency | [`tooling/dependencies.md`](tooling/dependencies.md) |
+| CI / PRs / merge strategy | [`tooling/ci.md`](tooling/ci.md) |
+| Logging, metrics, error monitoring | [`tooling/observability.md`](tooling/observability.md) |
+| Security — auth | [`security/auth.md`](security/auth.md) |
+| Security — secrets | [`security/secrets.md`](security/secrets.md) |
+| Security — API design | [`security/api-security.md`](security/api-security.md) |
+| Concrete examples | [`examples/good/`](examples/good/), [`examples/bad/`](examples/bad/) |
+| **Task is explicitly PHP** | [`php/README.md`](php/README.md) (load first — it has its own conditional table) |
+
+### Repository Map
+
+| Directory | Purpose |
+|---|---|
+| [`philosophy/`](philosophy/) | Core principles and AI agent behavior rules |
+| [`typescript/`](typescript/) | TypeScript rules, anti-patterns, validation, naming, error handling |
+| [`typescript/tsconfig/`](typescript/tsconfig/) | Reference tsconfig presets (base, React, Next.js) |
+| [`react/`](react/) | Component design, hooks, state, forms, a11y, testing |
+| [`architecture/`](architecture/) | Feature-driven structure, monorepos, refactoring, dependency rules |
+| [`tooling/`](tooling/) | TanStack, Nx, Vite, Biome, Tailwind, shadcn, Prisma |
+| [`security/`](security/) | Validation, secrets, auth, API security |
+| [`examples/`](examples/) | Concrete good and bad code examples |
+| [`templates/`](templates/) | Drop-in starter files — `CLAUDE.md`, `AGENTS.md`, `tsconfig.json`, `biome.json`, `eslint.config.js`, `.gitignore`, `.editorconfig`, `.nvmrc`, project README, PR template |
+| [`php/`](php/) | **Secondary stack.** PHP standards — only when the task is explicitly PHP |
+
+### Core Philosophy
+
+> Prefer explicit, composable, feature-oriented architecture over generalized abstractions and centralized complexity.
+
+See [`philosophy/core-principles.md`](philosophy/core-principles.md) for the full architectural values.
+
+### Documentation Style
+
+All docs are directive and concise. Expect:
+- `## DO` / `## DO NOT` / `## PRIORITY` sections
+- Side-by-side good and bad code examples
+- Hierarchical headings, no prose essays
+- Cross-references via relative links