feat(rules): agent rules layer with CLI-first directive

[deanq]

Summary

Minimal agent-rules layer: flash init writes AGENTS.md at project root and creates CLAUDE.md as a symlink to it. That's it.

Why

Agentic AI coding tools (Claude Code, Cursor, Copilot, Codex, Aider, etc.) using Flash routinely bypass the flash CLI and generate raw Runpod REST or GraphQL calls to build, deploy, list, or scale endpoints — bypassing auth, config hashing, drift detection, manifest generation, and image selection.

This PR ships a sidecar AGENTS.md whose first section is a "Use the Flash CLI — Do Not Call Runpod REST or GraphQL Directly" directive with an intent → command table. The file is written by flash init for new projects; existing projects run a one-liner documented in the README.

No agentic tool scans site-packages or subdirectories for instruction files — they read named files at project root. Prior art (Prisma, Husky, shadcn, ESLint) never writes into user-owned root files; they prompt or use namespaced directories. This PR follows that pattern: AGENTS.md is Flash-owned (skipped if user already has one), CLAUDE.md is created as a symlink so Claude Code picks up the same content without duplication.

Behavior

• flash init writes ./AGENTS.md if absent; symlinks ./CLAUDE.md → AGENTS.md if absent
• Existing AGENTS.md / CLAUDE.md are never touched
• Broken CLAUDE.md symlink is detected and a warning is logged
• Symlink failure (e.g. Windows without dev mode) is logged and skipped; AGENTS.md still installed
• Missing AGENTS.md in the wheel raises a clear FileNotFoundError with an actionable message
• Opt-out: delete AGENTS.md. Flash will not re-create it
• No flash rules command, no --no-rules flag, no marker injection, no dynamic context, no .flash/context.md

AGENTS.md content

Four endpoint patterns documented:

• A: Queue-based function endpoint
• B: Load-balanced routes
• C: Class-based stateful worker
• D: Pre-built container image (BYOI) — e.g. Endpoint(name="vllm", image="runpod/worker-v1-vllm:v2.18.1", ...) — for workloads that already serve HTTP and don't need a Python handler

Plus a "Rules That Break If Violated" list, a "Common Agent Mistakes" table, and the CLI-first directive at the top.

Existing-project install

python -c "from runpod_flash.rules import install_agent_files; from pathlib import Path; install_agent_files(Path.cwd())"

Diff scope

10 files net change vs main:

• Added: src/runpod_flash/rules/{__init__.py,AGENTS.md}, tests/unit/rules/test_install.py
• Modified: src/runpod_flash/cli/commands/init.py, README.md, pyproject.toml, .gitignore, skeleton .gitignore
• Test mods: tests/unit/cli/commands/test_init.py

Test plan

• make quality-check passes (2702 tests, 85.4%+ coverage)
• Unit tests cover: write-when-absent, no-overwrite, symlink creation, no-replace-existing CLAUDE.md, symlink failure path, broken-symlink warning, missing-asset error, idempotency
• Manual: flash init demo in an empty dir creates AGENTS.md + CLAUDE.md symlink
• Manual: flash init demo in a dir with pre-existing AGENTS.md leaves it untouched
• Manual: Claude Code session in the demo project picks up the rules via CLAUDE.md → AGENTS.md

[promptless]

Promptless prepared a documentation update related to this change.

Triggered by runpod/flash#341

Added documentation for the new AI coding agent integration feature. Created a new flash rules CLI reference page, updated the flash init docs with the --no-rules flag and generated agent files, added the command to the CLI overview, and updated the quickstart with a tip about built-in agent integration.

Review: Flash AI coding agent integration

[Copilot]

Pull request overview

Adds a minimal “agent rules” layer to Flash: flash init now installs a packaged AGENTS.md into the new project root and (best-effort) creates CLAUDE.md as a symlink to AGENTS.md, with unit tests and packaging updates to support distributing the asset in the wheel.

Changes:

• Introduces runpod_flash.rules.install_agent_files() and ships AGENTS.md as package data.
• Wires flash init to call install_agent_files() and documents the behavior in README.md.
• Adds unit tests covering install behavior and edge cases; updates gitignore defaults and packaging config.

Reviewed changes

Copilot reviewed 8 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/runpod_flash/rules/__init__.py	New installer for AGENTS.md + best-effort CLAUDE.md symlink.
src/runpod_flash/rules/AGENTS.md	Packaged rules content intended for AI coding tools.
src/runpod_flash/cli/commands/init.py	Calls install_agent_files() during flash init and updates displayed project tree.
tests/unit/rules/test_install.py	New unit tests for agent file installation behavior.
tests/unit/cli/commands/test_init.py	Ensures flash init invokes install_agent_files().
src/runpod_flash/cli/utils/skeleton_template/.gitignore	Updates ignore defaults in generated projects.
README.md	Documents coding agent integration and installation snippet for existing projects.
pyproject.toml	Ensures rules/**/* is included in wheel package data.
.gitignore	Adds .runpod/ to ignored Flash state paths at repo root.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[runpod-Henrik]

Henrik's AI-Powered Bug Finder — PR #341 Review

Verdict: NEEDS WORK

The mechanism (install AGENTS.md + CLAUDE.md symlink, no-overwrite, broken-symlink warning, idempotent) is correct and well-tested at the unit level. CI green on 3.10/3.11/3.12.

The blocker is in the content of AGENTS.md: it ships as packaged data, gets dropped into every new project via flash init, and becomes the canonical rule source for every AI agent touching a Flash project. Two of the rules contradict the codebase.

---

1. Bug: AGENTS.md claim about workers=N is wrong

User scenario: an agent reads AGENTS.md (line 109 in the bundled file), sees "workers=N for fixed count, workers=(min, max) for auto-scaling range," and writes Endpoint(name="x", workers=3) for a user who wanted exactly 3 warm workers. They get an endpoint that scales (0, 3) — cold-starting on every burst.

Ground truth from the code, endpoint.py:165-176 (_normalize_workers):

- int: shorthand for (DEFAULT_WORKERS_MIN, n)   # = (0, n)
- (min, max): explicit tuple
- None: defaults to (DEFAULT_WORKERS_MIN, DEFAULT_WORKERS_MAX)

And the SDK reference (docs/Flash_SDK_Reference.md:46) confirms: "workers: N = (0, N). (min, max) = explicit range."

So workers=N is not "fixed count" — it's "auto-scale from 0 to N." The actual fixed-count idiom is workers=(N, N).

Fix: replace the bullet in AGENTS.md with something like:

- workers=N is shorthand for (0, N) — auto-scale 0 → N
- workers=(min, max) for explicit range; use (N, N) to pin a fixed count
- workers=(1, N) keeps at least one warm worker (avoids cold starts)

This is the highest-stakes content error — every Flash project initialized after this lands gets this misleading rule, and agents are explicitly told to trust it.

---

2. Question: Pattern D's "Flash deploys the image" vs. is_client semantics

AGENTS.md Pattern D says "Flash deploys the image and gives you HTTP + queue access to it" for Endpoint(name="vllm", image="runpod/worker-v1-vllm:v2.18.1", ...). But the SDK reference (docs/Flash_SDK_Reference.md:200,254) describes image= as a client mode, and is_client returns True when image= is set (endpoint.py:440).

If Endpoint(image=...) actually does provision a fresh endpoint when invoked (as PR #339's description implies for live provisioning), then AGENTS.md is right and the SDK reference is misleading. If image= is purely a client attaching to a pre-deployed endpoint, AGENTS.md is wrong and would have agents writing code that silently no-ops.

Either way, the two source-of-truth documents tell different stories about the same parameter. Worth nailing down which is correct and aligning both before this rule file ships to every new project.

---

3. Issue: a user with a real CLAUDE.md (not symlink) becomes orphaned from rules

User scenario: user has an existing CLAUDE.md (custom Claude Code instructions) and runs flash init (or the existing-project one-liner). The code's not claude.exists() check correctly skips replacement — but the user is now silently in a state where:

• AGENTS.md exists and gets used by Cursor, Codex, Aider, Amp.
• CLAUDE.md is the user's custom file, NOT linked to AGENTS.md.
• Claude Code reads the user's CLAUDE.md and never sees the Flash rules.

The user is unlikely to realise this until they file a "why does Claude break my Flash project but Cursor doesn't" report.

Either:

• Log an info line when CLAUDE.md exists as a real file (not symlink) suggesting the user cat AGENTS.md >> CLAUDE.md or symlink manually.
• Or document this case explicitly in the README's "Coding agent integration" section.

The current README only addresses "AGENTS.md already exists" and "broken symlink" cases.

---

4. Issue: no opt-out at flash init time

PR description explicitly: "No flash rules command, no --no-rules flag, no marker injection." Users in restrictive environments (corporate policy on AI tooling, regulated industries, projects that ban LLM-generated context) have no way to suppress this at init time. Their only recourse is to rm AGENTS.md CLAUDE.md after init.

That's a fine default for the 95% case but worth confirming this is a deliberate product decision rather than a "we'll add it if asked" decision. The earlier commits in this branch (feat(rules): add --no-rules flag to flash init) suggest the flag was considered and removed — would be good to record the reasoning somewhere durable (CHANGELOG, design note in the README) so future contributors don't re-litigate.

---

5. Issue: test gap — flash init integration not verified end-to-end

test_init_calls_install_agent_files patches both install_agent_files and create_project_skeleton, so it only verifies that the function gets called. It doesn't verify the resulting filesystem state. Combined with the manual smoke checks all being unchecked in the PR's own test plan, the actual user-visible behavior of flash init demo → "AGENTS.md and CLAUDE.md appear in demo/" is unverified.

A test that runs flash init end-to-end (without mocks) against a tmp_path and asserts both files exist would close this. The components are individually tested, but the wiring isn't.

---

Nits

• src/runpod_flash/rules/__init__.py:51 — os.symlink("AGENTS.md", claude) creates a relative symlink. Robust for in-place use, but breaks if the user later copies the project somewhere with non-symlink-preserving tools (e.g., scp without -p, some zip extractions). Worth a one-line comment that the relative path is intentional.
• .gitignore diff at repo root adds .runpod/ — .runpod/ is documented in core/credentials.py as ~/.runpod/config.toml (user HOME, not project). Why does the repo need to gitignore .runpod/ at project root? If nothing creates it there, the entry is dead code; if something does, that's worth knowing.
• Pattern A in AGENTS.md uses GpuType.NVIDIA_GEFORCE_RTX_4090. Verified that enum value exists (gpu.py:179). Consistent.
• Pattern B uses cpu="cpu3c-1-2". Verified (cpu.py:34). Consistent.
• The skeleton template's gitignore drops .runpod/ and dist/ — verified .runpod/ isn't a project-local artifact, but dist/ is the standard Python build output. New projects that run python -m build or use flash build will have dist/ show up in git status. Worth keeping it ignored.
• README uses python -c "..." snippet for existing-project install. A bit heavy for a one-shot operation; consider adding a flash rules install subcommand later (acknowledged as out-of-scope here).

---

🤖 Reviewed by Henrik's AI-Powered Bug Finder

[promptless]

Promptless updated the documentation for this change.

Triggered by runpod/flash#341

Corrected the documentation to match the final merged behavior. Removed references to the non-existent flash rules command and --no-rules flag. Updated flash init docs to accurately describe the new agent file generation.

Review: Document Flash AI coding agent integration