From e78b20e3077d7dde92654cc2a3457efceea90d87 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Mon, 25 May 2026 03:25:55 +0000 Subject: [PATCH 1/2] Add Flash AI coding agent integration documentation Document the new flash rules command and AI coding agent integration feature that helps AI assistants work with Flash correctly by generating context files (CLAUDE.md, AGENTS.md, etc.). - Add flash/cli/rules.mdx documenting the new command - Update init.mdx with --no-rules flag and generated agent files - Update overview.mdx to include rules in command table - Update quickstart.mdx to note built-in agent integration - Add rules page to docs.json navigation --- docs.json | 3 +- flash/cli/init.mdx | 30 ++++++++++++++ flash/cli/overview.mdx | 1 + flash/cli/rules.mdx | 93 ++++++++++++++++++++++++++++++++++++++++++ flash/quickstart.mdx | 10 ++--- 5 files changed, 129 insertions(+), 8 deletions(-) create mode 100644 flash/cli/rules.mdx diff --git a/docs.json b/docs.json index 53b7e698..604d5c98 100644 --- a/docs.json +++ b/docs.json @@ -403,7 +403,8 @@ "flash/cli/env", "flash/cli/app", "flash/cli/undeploy", - "flash/cli/update" + "flash/cli/update", + "flash/cli/rules" ] }, { diff --git a/flash/cli/init.mdx b/flash/cli/init.mdx index f5085402..5eeadd5b 100644 --- a/flash/cli/init.mdx +++ b/flash/cli/init.mdx @@ -38,6 +38,10 @@ Name of the project directory to create. Use `.` to initialize in the current di Overwrite existing files if they already exist in the target directory. + +Skip AI coding agent file generation. Use this if you prefer to manage agent context files yourself. + + ## What it creates The command creates the following project structure: @@ -52,6 +56,15 @@ The command creates the following project structure: + + + + + + + + + @@ -62,6 +75,22 @@ The command creates the following project structure: - **cpu_worker.py**: CPU queue-based endpoint. Contains an `@Endpoint` function that runs on CPU-only instances. Provides `/run` or `/runsync` routes for job submission. Creates one Serverless endpoint when deployed. - **.env**: Template for environment variables including `RUNPOD_API_KEY`. +### AI coding agent files + +Flash generates context files that help AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, and others) work with Flash correctly. These files instruct agents to use Flash CLI commands instead of generating raw Runpod API calls. + +| File | Purpose | +|------|---------| +| `CLAUDE.md` | Instructions for Claude Code | +| `AGENTS.md` | Instructions for Codex, Aider, Cursor, Amp, Jules, and other tools | +| `.cursorrules` | Instructions for Cursor (legacy convention) | +| `.github/copilot-instructions.md` | Instructions for GitHub Copilot | +| `.flash/context.md` | Live project state, regenerated on `flash run` and `flash build` | + +Generated content lives between `` and `` markers. You can add project-specific instructions outside these markers. To regenerate after upgrading Flash, run [`flash rules`](/flash/cli/rules). + +Skip agent file generation with `--no-rules`, or disable a specific file by adding `` anywhere in it. + ## Next steps After initialization: @@ -83,3 +112,4 @@ This command only creates local files. It doesn't interact with Runpod or create - [`flash dev`](/flash/cli/dev) - Start the development server - [`flash deploy`](/flash/cli/deploy) - Build and deploy to Runpod +- [`flash rules`](/flash/cli/rules) - Regenerate AI coding agent files diff --git a/flash/cli/overview.mdx b/flash/cli/overview.mdx index f9afb0d7..26ffe229 100644 --- a/flash/cli/overview.mdx +++ b/flash/cli/overview.mdx @@ -22,6 +22,7 @@ Before using the CLI, make sure you've [installed Flash](/flash/overview#install | [`flash app`](/flash/cli/app) | Manage Flash applications | | [`flash undeploy`](/flash/cli/undeploy) | Remove deployed endpoints | | [`flash update`](/flash/cli/update) | Update Flash to the latest or a specific version | +| [`flash rules`](/flash/cli/rules) | Regenerate AI coding agent context files | ## Getting help diff --git a/flash/cli/rules.mdx b/flash/cli/rules.mdx new file mode 100644 index 00000000..24264da2 --- /dev/null +++ b/flash/cli/rules.mdx @@ -0,0 +1,93 @@ +--- +title: "rules" +sidebarTitle: "rules" +--- + +Regenerate AI coding agent context files for your Flash project. Run this command after upgrading Flash to ensure your agent files include the latest CLI directives and patterns. + +```bash +flash rules +``` + +## What it does + +The `flash rules` command regenerates the AI coding agent context files created by `flash init`. These files help AI assistants like Claude Code, Cursor, GitHub Copilot, and Codex work with Flash correctly. + +The command: + +1. Updates content between `` and `` markers in each agent file. +2. Preserves any content you've added outside those markers. +3. Regenerates `.flash/context.md` with live project state from your manifest. + +## Generated files + +| File | Purpose | +|------|---------| +| `CLAUDE.md` | Instructions for Claude Code | +| `AGENTS.md` | Instructions for Codex, Aider, Cursor, Amp, Jules, and other tools | +| `.cursorrules` | Instructions for Cursor (legacy convention) | +| `.github/copilot-instructions.md` | Instructions for GitHub Copilot | +| `.flash/context.md` | Live project state (endpoints, resources, dependencies) | + +## When to run + +Run `flash rules` after: + +- Upgrading Flash to a new version. +- Deleting or modifying agent files and wanting to restore the Flash content. + +You don't need to run this command regularly. The static rules content rarely changes, and `.flash/context.md` updates automatically when you run `flash run` or `flash build`. + +## Customizing agent files + +Generated content lives between `` and `` markers. Add your own project-specific instructions outside these markers, and they're preserved when you regenerate. + +For example, your `CLAUDE.md` might look like: + +```markdown +# My project instructions + +These are my custom rules for this project. + + + + +[Flash CLI directives and patterns...] + + + +# Additional notes + +More project-specific guidance here. +``` + +## Disabling agent files + +To prevent Flash from managing a specific file, add `` anywhere in that file: + +```markdown + +# My custom CLAUDE.md + +I prefer to manage this file myself. +``` + +Flash skips this file during `flash init` and `flash rules`. + +To disable all agent file generation for a project, use `flash init --no-rules` when creating the project. + +## Example output + +```text +$ flash rules +Generated 5 agent file(s): + CLAUDE.md + .cursorrules + AGENTS.md + .github/copilot-instructions.md + .flash/context.md +``` + +## Related commands + +- [`flash init`](/flash/cli/init) - Create a new Flash project (includes initial agent file generation) diff --git a/flash/quickstart.mdx b/flash/quickstart.mdx index f6541737..2f558fbf 100644 --- a/flash/quickstart.mdx +++ b/flash/quickstart.mdx @@ -27,15 +27,11 @@ source .venv/bin/activate uv pip install runpod-flash ``` -### Optional: Install coding agent integration + -If you're using an AI coding agent like Claude Code, Cline, or Cursor, you can install the Flash skill package to give your agent detailed context about the Flash SDK: +Flash includes built-in AI coding agent integration. When you create a project with `flash init`, it generates context files (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`) that help AI assistants like Claude Code, Cursor, and GitHub Copilot work with Flash correctly. See [`flash init`](/flash/cli/init) for details. -```bash -npx skills add runpod/skills -``` - -This enables your coding agent to provide more accurate Flash code suggestions and troubleshooting help. + ## Step 2: Authenticate with Runpod From 44c455395b39fc2d01ede80a9164a313711b37df Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Wed, 27 May 2026 20:01:51 +0000 Subject: [PATCH 2/2] Fix Flash AI agent integration docs to match merged PR #341 The original suggestion documented features that were removed before merge. This commit corrects the docs to reflect the actual behavior: - Remove `flash rules` CLI page (command does not exist) - Remove `--no-rules` flag from `flash init` docs (flag does not exist) - Update `flash init` to show only the files actually created: - `AGENTS.md` (if absent) - `CLAUDE.md` symlink (if absent) - Remove references to `.cursorrules`, `.github/copilot-instructions.md`, `.flash/context.md`, and the marker system (not created by flash init) - Add instructions for existing projects and opt-out - Update quickstart tip to reflect actual behavior --- docs.json | 3 +- flash/cli/init.mdx | 48 ++++++++++++---------- flash/cli/overview.mdx | 1 - flash/cli/rules.mdx | 93 ------------------------------------------ flash/quickstart.mdx | 2 +- 5 files changed, 29 insertions(+), 118 deletions(-) delete mode 100644 flash/cli/rules.mdx diff --git a/docs.json b/docs.json index 604d5c98..53b7e698 100644 --- a/docs.json +++ b/docs.json @@ -403,8 +403,7 @@ "flash/cli/env", "flash/cli/app", "flash/cli/undeploy", - "flash/cli/update", - "flash/cli/rules" + "flash/cli/update" ] }, { diff --git a/flash/cli/init.mdx b/flash/cli/init.mdx index 5eeadd5b..fee00858 100644 --- a/flash/cli/init.mdx +++ b/flash/cli/init.mdx @@ -38,10 +38,6 @@ Name of the project directory to create. Use `.` to initialize in the current di Overwrite existing files if they already exist in the target directory. - -Skip AI coding agent file generation. Use this if you prefer to manage agent context files yourself. - - ## What it creates The command creates the following project structure: @@ -56,15 +52,8 @@ The command creates the following project structure: - - - - - - - - + @@ -77,19 +66,37 @@ The command creates the following project structure: ### AI coding agent files -Flash generates context files that help AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, and others) work with Flash correctly. These files instruct agents to use Flash CLI commands instead of generating raw Runpod API calls. +Flash generates context files that help AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, Aider, and others) use Flash correctly. These files tell agents to use Flash CLI commands instead of raw Runpod API calls. | File | Purpose | |------|---------| -| `CLAUDE.md` | Instructions for Claude Code | -| `AGENTS.md` | Instructions for Codex, Aider, Cursor, Amp, Jules, and other tools | -| `.cursorrules` | Instructions for Cursor (legacy convention) | -| `.github/copilot-instructions.md` | Instructions for GitHub Copilot | -| `.flash/context.md` | Live project state, regenerated on `flash run` and `flash build` | +| `AGENTS.md` | CLI-first rules for AI coding tools (Cursor, Codex, Aider, Amp, Jules, and others) | +| `CLAUDE.md` | Symlink to `AGENTS.md` so Claude Code picks up the same rules | + +Flash writes these files only when they don't already exist. If you have your own `AGENTS.md` or `CLAUDE.md`, Flash leaves them alone. + + + +**Tools using other conventions:** GitHub Copilot reads `.github/copilot-instructions.md` and Cursor (legacy) reads `.cursorrules`. If you use those, symlink or copy `AGENTS.md`: + +```bash +ln -s ../AGENTS.md .github/copilot-instructions.md +ln -s AGENTS.md .cursorrules +``` + + + +### Add agent files to existing projects + +If you've already run `flash init`, add the agent files with: + +```bash +python -c "from runpod_flash.rules import install_agent_files; from pathlib import Path; install_agent_files(Path.cwd())" +``` -Generated content lives between `` and `` markers. You can add project-specific instructions outside these markers. To regenerate after upgrading Flash, run [`flash rules`](/flash/cli/rules). +### Opt out -Skip agent file generation with `--no-rules`, or disable a specific file by adding `` anywhere in it. +Delete `AGENTS.md`. Flash won't re-create it. ## Next steps @@ -112,4 +119,3 @@ This command only creates local files. It doesn't interact with Runpod or create - [`flash dev`](/flash/cli/dev) - Start the development server - [`flash deploy`](/flash/cli/deploy) - Build and deploy to Runpod -- [`flash rules`](/flash/cli/rules) - Regenerate AI coding agent files diff --git a/flash/cli/overview.mdx b/flash/cli/overview.mdx index 26ffe229..f9afb0d7 100644 --- a/flash/cli/overview.mdx +++ b/flash/cli/overview.mdx @@ -22,7 +22,6 @@ Before using the CLI, make sure you've [installed Flash](/flash/overview#install | [`flash app`](/flash/cli/app) | Manage Flash applications | | [`flash undeploy`](/flash/cli/undeploy) | Remove deployed endpoints | | [`flash update`](/flash/cli/update) | Update Flash to the latest or a specific version | -| [`flash rules`](/flash/cli/rules) | Regenerate AI coding agent context files | ## Getting help diff --git a/flash/cli/rules.mdx b/flash/cli/rules.mdx deleted file mode 100644 index 24264da2..00000000 --- a/flash/cli/rules.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "rules" -sidebarTitle: "rules" ---- - -Regenerate AI coding agent context files for your Flash project. Run this command after upgrading Flash to ensure your agent files include the latest CLI directives and patterns. - -```bash -flash rules -``` - -## What it does - -The `flash rules` command regenerates the AI coding agent context files created by `flash init`. These files help AI assistants like Claude Code, Cursor, GitHub Copilot, and Codex work with Flash correctly. - -The command: - -1. Updates content between `` and `` markers in each agent file. -2. Preserves any content you've added outside those markers. -3. Regenerates `.flash/context.md` with live project state from your manifest. - -## Generated files - -| File | Purpose | -|------|---------| -| `CLAUDE.md` | Instructions for Claude Code | -| `AGENTS.md` | Instructions for Codex, Aider, Cursor, Amp, Jules, and other tools | -| `.cursorrules` | Instructions for Cursor (legacy convention) | -| `.github/copilot-instructions.md` | Instructions for GitHub Copilot | -| `.flash/context.md` | Live project state (endpoints, resources, dependencies) | - -## When to run - -Run `flash rules` after: - -- Upgrading Flash to a new version. -- Deleting or modifying agent files and wanting to restore the Flash content. - -You don't need to run this command regularly. The static rules content rarely changes, and `.flash/context.md` updates automatically when you run `flash run` or `flash build`. - -## Customizing agent files - -Generated content lives between `` and `` markers. Add your own project-specific instructions outside these markers, and they're preserved when you regenerate. - -For example, your `CLAUDE.md` might look like: - -```markdown -# My project instructions - -These are my custom rules for this project. - - - - -[Flash CLI directives and patterns...] - - - -# Additional notes - -More project-specific guidance here. -``` - -## Disabling agent files - -To prevent Flash from managing a specific file, add `` anywhere in that file: - -```markdown - -# My custom CLAUDE.md - -I prefer to manage this file myself. -``` - -Flash skips this file during `flash init` and `flash rules`. - -To disable all agent file generation for a project, use `flash init --no-rules` when creating the project. - -## Example output - -```text -$ flash rules -Generated 5 agent file(s): - CLAUDE.md - .cursorrules - AGENTS.md - .github/copilot-instructions.md - .flash/context.md -``` - -## Related commands - -- [`flash init`](/flash/cli/init) - Create a new Flash project (includes initial agent file generation) diff --git a/flash/quickstart.mdx b/flash/quickstart.mdx index 2f558fbf..2624de4c 100644 --- a/flash/quickstart.mdx +++ b/flash/quickstart.mdx @@ -29,7 +29,7 @@ uv pip install runpod-flash -Flash includes built-in AI coding agent integration. When you create a project with `flash init`, it generates context files (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`) that help AI assistants like Claude Code, Cursor, and GitHub Copilot work with Flash correctly. See [`flash init`](/flash/cli/init) for details. +When you create a project with `flash init`, Flash generates `AGENTS.md` (and `CLAUDE.md` as a symlink) with CLI-first rules for AI coding assistants. These files tell AI tools like Claude Code, Cursor, and Codex to use Flash commands instead of raw Runpod API calls. See [`flash init`](/flash/cli/init) for details.