Merge pull request #8716 from QwikDev/v2-ai-iteration-loop

docs: add agent iteration loop and consolidate AI setup pointers

Author: maiieul

.ruler/AGENTS.md

@@ -51,12 +51,32 @@ compatibility override code.
 - pnpm: `>=10.14.0`
 - Package manager: pnpm only
 
-Install dependencies with:
+## Setup And Iteration Loop
+
+This is the canonical loop for nearly all framework work. Default to it; do not substitute broader
+commands:
 
 ```bash
+# 1. Setup — once per checkout, and again after dependency changes
 pnpm install
+
+# 2. Fast dev build — required once before any tests can run, and again after framework
+#    source changes when the verification consumes build output (all e2e suites do)
+pnpm build.core.dev
+
+# 3. Closest focused unit/spec test
+pnpm vitest run packages/qwik/src/core/tests/use-task.spec.tsx
+
+# 4. Focused e2e test
+pnpm playwright test e2e/qwik-e2e/tests/events.e2e.ts --browser=chromium --config e2e/qwik-e2e/playwright.config.ts
 ```
 
+`pnpm build.core.dev` is not optional: the Vitest config itself loads the built optimizer, and e2e
+apps run against build output, so tests are only as fresh as the last build.
+
+For Qwik e2e tests, use `--browser=chromium` with `e2e/qwik-e2e/playwright.config.ts`; do not use
+`--project chromium` with that config.
+
 ## Command Rules
 
 - Prefer focused commands over repo-wide commands.
@@ -66,23 +86,11 @@ pnpm install
 - Use `pnpm build.core.dev` for fast Qwik + Router rebuilds during most framework work.
 - Use `pnpm build.local` for a fresh full local build without rebuilding Rust.
 - Use `pnpm build.full` only when Rust/optimizer changes require it.
+- Run `pnpm tsc.check` for type-level verification when no focused test covers the change.
 - Run `pnpm api.update` after public API changes.
 - Run `pnpm lint` only when the change scope justifies broad linting; otherwise prefer focused
   tests and formatting checks.
 
-Common focused commands:
-
-```bash
-pnpm build.core.dev
-pnpm vitest run packages/qwik/src/core/tests/use-task.spec.tsx
-pnpm playwright test e2e/qwik-e2e/tests/events.e2e.ts --browser=chromium --config e2e/qwik-e2e/playwright.config.ts
-pnpm tsc.check
-pnpm api.update
-```
-
-For Qwik e2e tests, use `--browser=chromium` with `e2e/qwik-e2e/playwright.config.ts`; do not use
-`--project chromium` with that config.
-
 ## Source Rules
 
 Dedicated source rules live under `.ruler/rules/` and are part of the always-on guidance generated

.ruler/README.md

@@ -78,6 +78,14 @@ Ruler concatenates that bundle and writes it to each selected assistant's native
 Use source markers in the generated file to verify inclusion. Do not bypass Ruler by copying these
 Markdown files into a tool-specific directory whose format has not been verified.
 
+If you are an AI assistant building local config for a target tool, research that tool's current
+native guidance, skill, config, and policy formats before adding any tool-specific output. Map
+`.ruler` files by what they mean, not by filename: Markdown guidance belongs in the assistant's
+native AI guidance surface, skills belong in native skills if supported, and command-permission
+policy belongs only in a separately researched policy format. For Codex, Ruler includes all
+`.ruler` Markdown guidance in generated `AGENTS.md`; `.codex/rules/*.rules` is command policy, not
+Markdown guidance.
+
 ### Worked Example: Codex
 
 Current Ruler and OpenAI Codex behavior maps this repo's sources as follows:

CONTRIBUTING.md

@@ -161,6 +161,10 @@ Furthermore, to build the optimizer you optionally need Rust.
 > On Windows, Rust requires [C++ build tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/). You can also select _Desktop development with C++_
 > while installing Visual Studio.
 
+### AI assistants
+
+If you contribute with an AI assistant, read the [AI setup guide](./README.md#ai-assistant-setup) first.
+
 ---
 
 ## Development

README.md

@@ -72,14 +72,6 @@ Use `.ruler/AGENTS.md` for short repo-wide AI instructions, `.ruler/rules/` for
 rules, `.ruler/skills/` for reusable prompts or task-specific skills, and `~/.config/ruler/` for
 personal settings such as local MCP servers or workflow preferences.
 
-If you are an AI assistant building local config for a target tool, research that tool's current
-native guidance, skill, config, and policy formats before adding any tool-specific output. Map
-`.ruler` files by what they mean, not by filename: Markdown guidance belongs in the assistant's
-native AI guidance surface, skills belong in native skills if supported, and command-permission
-policy belongs only in a separately researched policy format. For Codex, Ruler includes all
-`.ruler` Markdown guidance in generated `AGENTS.md`; `.codex/rules/*.rules` is command policy, not
-Markdown guidance.
-
 Do not edit generated files like `AGENTS.md`, `CLAUDE.md`, `.codex/`, `.claude/`, or `.cursor/`
 by hand. Update `.ruler/` and rerun `ruler apply`.