From 745ca4800a0a04e12d2cc7cc343369ecd393b7f8 Mon Sep 17 00:00:00 2001 From: mrwogu Date: Thu, 1 Oct 2026 08:49:05 +0200 Subject: [PATCH 1/3] docs: align README with homepage, add security and models --- README.md | 111 +++++++++++++++--- .../checkout-service_Hcf074592/claude.md | 1 + .../checkout-service_Hcf074592/cursor.mdc | 6 + .../checkout-service_Hcf074592/github.md | 1 + 4 files changed, 105 insertions(+), 14 deletions(-) create mode 100644 docs/__snapshots__/README.md/checkout-service_Hcf074592/claude.md create mode 100644 docs/__snapshots__/README.md/checkout-service_Hcf074592/cursor.mdc create mode 100644 docs/__snapshots__/README.md/checkout-service_Hcf074592/github.md diff --git a/README.md b/README.md index 69b79a04454..02cd149208d 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,11 @@ # PromptScript -**Agent platform configuration as code** +**Write your AI rules once. Every agent follows them.** -_Define instructions, skills, agents, MCP servers, hooks, workflows, and policies once. Compile -native configuration for 50 AI coding platforms._ +_One source for Claude Code, GitHub Copilot, Cursor, and 47 more tools. Define instructions, +skills, agents, MCP servers, hooks, and policies once, inherit them like code, and compile native +files for every tool._ [![CI](https://github.com/mrwogu/promptscript/actions/workflows/ci.yml/badge.svg)](https://github.com/mrwogu/promptscript/actions/workflows/ci.yml) [![codecov](https://codecov.io/github/mrwogu/promptscript/graph/badge.svg?token=MPUCPQLVWR)](https://codecov.io/github/mrwogu/promptscript) @@ -28,7 +29,7 @@ native configuration for 50 AI coding platforms._ ## What is PromptScript? -PromptScript is an open-source language and compiler for AI agent configuration. `.prs` sources +PromptScript is an open-source compiler for AI coding agent rules. `.prs` sources define instructions, project standards, restrictions, skills, agents, MCP servers, hooks, and workflows, while `promptscript.yaml` configures targets and extension-compliance policies. The compiler turns them into the native files each AI tool already knows: `CLAUDE.md` for Claude Code, @@ -76,6 +77,8 @@ source. See the [full comparison](https://getpromptscript.dev/guides/vs-manual/) - [One Language, Complete Platform](#one-language-complete-platform) - [Compose Instead of Copying](#compose-instead-of-copying) - [Portable Skills, Native Agents](#portable-skills-native-agents) +- [Name a Model Once](#name-a-model-once) +- [Built-In Security Scanner](#built-in-security-scanner) - [50 Built-In Targets](#50-built-in-targets) - [Built for Repositories and Organizations](#built-for-repositories-and-organizations) - [Adopt Without a Rewrite](#adopt-without-a-rewrite) @@ -322,6 +325,78 @@ PromptScript validates Agent Skills metadata, resolves dependencies and resource native skill path for each selected platform. Agents can reference those skills and receive target-native model, reasoning, sandbox, tool, permission, and MCP settings. +## Name a Model Once + +Each tool spells model names differently. Write an alias like `opus` or a full model id, and +PromptScript writes the name each target expects: + +```promptscript +@meta { + id: "checkout-service" + syntax: "1.5.0" +} + +@agents { + reviewer: { + description: "Review pull requests" + model: "opus" + content: "Review changed code, tests, and operational impact." + } +} +``` + + + + Try in Playground + + + +| Target | Writes | +| :------------- | :----------------------------- | +| Claude Code | `opus` | +| GitHub Copilot | `Claude Opus 5.5` | +| Factory AI | `claude-opus-5-5` | +| Cursor | `claude-opus-5-5` | +| Codex | omitted, with a PS4004 warning | + +When a target cannot run the model, the compiler warns instead of writing a value the tool would +reject. Claude Code picks the release for an alias itself. Other targets get the current release +from the catalog and move on when you upgrade PromptScript and compile again. See the +[model catalog and aliases](https://getpromptscript.dev/reference/models/). + +## Built-In Security Scanner + +Instruction files and imported skills are a prompt injection surface. `prs validate` scans every +instruction, skill, and imported file before anything is written. Encoded payloads are decoded +first, so hiding an attack in hex or Base64 does not get it through: + +```text +$ prs validate --strict +✖ Validation failed +✗ Blocked pattern detected: + ignore\s+(all\s+)?previous\s+instructions + at project.prs:8:1 +✗ PS012: Malicious content detected + in raw hex (spaced): Prompt injection + Decoded: "IGNORE SAFETY RULES" + at project.prs:16:14 +✗ PS010: URL shortener detected: + http://bit.ly/deploy-help + at project.prs:16:14 +``` + +| Rule | Catches | +| :---- | :----------------------------------------------------------------------------- | +| PS005 | Injection phrases like "ignore previous instructions" | +| PS011 | Fake authority overrides and "bypass all safety" instructions | +| PS012 | Payloads hidden in Base64, hex, URL encoding, HTML entities, ROT13, and 4 more | +| PS013 | Path traversal in `@use` declarations | +| PS014 | Right-to-left overrides, zero-width characters, and homoglyphs | +| PS010 | Plain HTTP links, link shorteners, and credentials in URLs | + +Run it in CI with `prs validate --strict` so a poisoned skill fails the build, not the agent. See +the [security guide](https://getpromptscript.dev/guides/security/). + ## 50 Built-In Targets PromptScript ships 50 output targets: @@ -338,6 +413,11 @@ See exact output paths and feature support in the ## Built for Repositories and Organizations +- **Runs locally** - PromptScript is a compiler, not a service. No hosted backend and no proxy + between your team and its tools, the output is plain files you review and commit. +- **Your prompts stay yours** - anonymous usage telemetry never includes source, prompts, or file + paths. Turn it off with `prs telemetry disable` or `DO_NOT_TRACK=1`. See + [what is collected](https://getpromptscript.dev/reference/telemetry/). - **Git-native governance** - review source and deterministic generated diffs in pull requests. - **Private registries** - share versioned standards through local, HTTP, or Git registries with SSH and token-based authentication. @@ -384,16 +464,19 @@ with `includePromptScriptSkill: false`. ## Documentation -| Resource | Description | -| :------------------------------------------------------------------------------- | :---------------------------------------------------------- | -| [Getting Started](https://getpromptscript.dev/getting-started/) | First project from initialization to native output | -| [Agent Platform](https://getpromptscript.dev/features/) | Skills, agents, MCP, plugins, hooks, workflows, and targets | -| [Language Reference](https://getpromptscript.dev/reference/language/) | Complete PromptScript syntax | -| [CLI Reference](https://getpromptscript.dev/reference/cli/) | Commands and options | -| [Configuration Reference](https://getpromptscript.dev/reference/config/) | Targets, registries, builds, policies, and formatting | -| [Anonymous Usage Telemetry](https://getpromptscript.dev/reference/telemetry/) | Collected fields, delivery, and opt-out controls | -| [Upgrade 1.15 to 1.16](https://getpromptscript.dev/guides/upgrade-1-15-to-1-16/) | Syntax, block shape, and hook migration guide | -| [Enterprise Guide](https://getpromptscript.dev/guides/enterprise/) | Organization-wide adoption and governance | +| Resource | Description | +| :---------------------------------------------------------------------------- | :---------------------------------------------------------- | +| [Getting Started](https://getpromptscript.dev/getting-started/) | First project from initialization to native output | +| [Agent Platform](https://getpromptscript.dev/features/) | Skills, agents, MCP, plugins, hooks, workflows, and targets | +| [Language Reference](https://getpromptscript.dev/reference/language/) | Complete PromptScript syntax | +| [CLI Reference](https://getpromptscript.dev/reference/cli/) | Commands and options | +| [Configuration Reference](https://getpromptscript.dev/reference/config/) | Targets, registries, builds, policies, and formatting | +| [Security Guide](https://getpromptscript.dev/guides/security/) | Validation rules, injection detection, and safe registries | +| [Model Catalog](https://getpromptscript.dev/reference/models/) | Model aliases and per-target model names | +| [Anonymous Usage Telemetry](https://getpromptscript.dev/reference/telemetry/) | Collected fields, delivery, and opt-out controls | +| [Glossary](https://getpromptscript.dev/glossary/) | Every PromptScript term in one place | +| [FAQ](https://getpromptscript.dev/guides/faq/) | Common questions about adoption, targets, and security | +| [Enterprise Guide](https://getpromptscript.dev/guides/enterprise/) | Organization-wide adoption and governance | ## Contributing diff --git a/docs/__snapshots__/README.md/checkout-service_Hcf074592/claude.md b/docs/__snapshots__/README.md/checkout-service_Hcf074592/claude.md new file mode 100644 index 00000000000..af5b2e8f729 --- /dev/null +++ b/docs/__snapshots__/README.md/checkout-service_Hcf074592/claude.md @@ -0,0 +1 @@ +# CLAUDE.md diff --git a/docs/__snapshots__/README.md/checkout-service_Hcf074592/cursor.mdc b/docs/__snapshots__/README.md/checkout-service_Hcf074592/cursor.mdc new file mode 100644 index 00000000000..911d7475e0f --- /dev/null +++ b/docs/__snapshots__/README.md/checkout-service_Hcf074592/cursor.mdc @@ -0,0 +1,6 @@ +--- +description: "Project-specific rules" +alwaysApply: true +--- + +You are working on the project. diff --git a/docs/__snapshots__/README.md/checkout-service_Hcf074592/github.md b/docs/__snapshots__/README.md/checkout-service_Hcf074592/github.md new file mode 100644 index 00000000000..5b7af13061c --- /dev/null +++ b/docs/__snapshots__/README.md/checkout-service_Hcf074592/github.md @@ -0,0 +1 @@ +# GitHub Copilot Instructions From 11904744abc69a30537aff516117cd20ed9a2746 Mon Sep 17 00:00:00 2001 From: mrwogu Date: Thu, 1 Oct 2026 08:49:08 +0200 Subject: [PATCH 2/3] docs(cli): add security scanner, privacy and missing commands --- packages/cli/README.md | 79 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 68 insertions(+), 11 deletions(-) diff --git a/packages/cli/README.md b/packages/cli/README.md index 76bcc0017c8..a039e2e79c0 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -2,10 +2,11 @@ # @promptscript/cli -**Agent platform configuration as code** +**Write your AI rules once. Every agent follows them.** -Define instructions, skills, agents, MCP servers, hooks, workflows, and policies once. Compile -native configuration for 50 AI coding platforms. +One source for Claude Code, GitHub Copilot, Cursor, and 47 more tools. Define instructions, +skills, agents, MCP servers, hooks, and policies once, inherit them like code, and compile native +files for every tool. [![npm version](https://img.shields.io/npm/v/@promptscript/cli.svg)](https://www.npmjs.com/package/@promptscript/cli) [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-5FA04E?logo=nodedotjs&logoColor=white)](https://getpromptscript.dev/getting-started/#installation) @@ -24,7 +25,7 @@ native configuration for 50 AI coding platforms. ## What is PromptScript? -PromptScript is an open-source language and compiler for AI agent configuration. `.prs` sources +PromptScript is an open-source compiler for AI coding agent rules. `.prs` sources define instructions, project standards, restrictions, skills, agents, MCP servers, hooks, and workflows, while `promptscript.yaml` configures targets and extension-compliance policies. PromptScript compiles them into the native files each AI tool already reads, including `CLAUDE.md`, @@ -43,7 +44,8 @@ PromptScript fixes the source instead of patching each generated file: -> compile deterministic native files ``` -No runtime proxy. Each selected platform keeps consuming its own native configuration. +No runtime proxy and no hosted service. PromptScript runs on your machine and in CI, and each +selected platform keeps consuming its own native configuration. ## Why maintain native files by hand? @@ -78,8 +80,14 @@ prs --version ## Running under Deno -The CLI also runs on Deno 2.9 or later, either straight from the installed -package or compiled into a standalone binary that needs no other runtime. +The CLI also runs on Deno 2.9 or later. Install it globally from npm: + +```bash +deno install -g --allow-env --allow-sys --allow-read --allow-write --allow-net --allow-run npm:@promptscript/cli +``` + +It can also run straight from the installed package or be compiled into a +standalone binary that needs no other runtime. In any project that has `@promptscript/cli` in its dependencies, point Deno at the installed bin shim: @@ -141,6 +149,7 @@ CLAUDE.md .claude/agents/reviewer.md .claude/skills/security-review/SKILL.md .cursor/rules/project.mdc +.cursor/agents/reviewer.md .opencode/agents/reviewer.md ``` @@ -390,8 +399,8 @@ prs migrate --llm Static migration deterministically imports detected instruction files. AI-assisted migration generates a migration prompt and installs the PromptScript skill. Existing source instructions -remain untouched, and existing PromptScript configuration is preserved byte-for-byte. Static output is isolated under -`.promptscript/migrated/`; no detected candidates means no writes. +remain untouched, and existing PromptScript configuration is preserved byte-for-byte. Static +output is isolated under `.promptscript/migrated/`; no detected candidates means no writes. Projects upgrading from PromptScript 1.15 should preview syntax changes with `prs upgrade --dry-run`, then run `prs validate --strict`. Factory targets also @@ -414,6 +423,39 @@ with changes exit 0; compilation and report errors emit `success: false` and exi target when `--target` selects one, never writes generated files or registry cache metadata, and requires Git registries to already exist in vendor mode or a valid local cache. +## Built-In Security Scanner + +`prs validate` scans every instruction, skill, and imported file for prompt injection before +anything is written. Encoded payloads are decoded first, so an attack hidden in hex or Base64 does +not get through: + +```text +$ prs validate --strict +✖ Validation failed +✗ Blocked pattern detected: + ignore\s+(all\s+)?previous\s+instructions + at project.prs:8:1 +✗ PS012: Malicious content detected + in raw hex (spaced): Prompt injection + Decoded: "IGNORE SAFETY RULES" + at project.prs:16:14 +✗ PS010: URL shortener detected: + http://bit.ly/deploy-help + at project.prs:16:14 +``` + +| Rule | Catches | +| :---- | :----------------------------------------------------------------------------- | +| PS005 | Injection phrases like "ignore previous instructions" | +| PS011 | Fake authority overrides and "bypass all safety" instructions | +| PS012 | Payloads hidden in Base64, hex, URL encoding, HTML entities, ROT13, and 4 more | +| PS013 | Path traversal in `@use` declarations | +| PS014 | Right-to-left overrides, zero-width characters, and homoglyphs | +| PS010 | Plain HTTP links, link shorteners, and credentials in URLs | + +Run `prs validate --strict` in CI so a poisoned skill fails the build, not the agent. See the +[security guide](https://getpromptscript.dev/guides/security/). + ## CLI Commands | Command | Purpose | @@ -425,17 +467,22 @@ requires Git registries to already exist in vendor mode or a valid local cache. | `prs compile --all-builds` | Compile every named profile | | `prs validate --strict` | Validate source, references, policies, and capabilities | | `prs validate --fix` | Upgrade outdated syntax declarations when possible | +| `prs check` | Check config, entries, lockfile, registry, and imports | | `prs diff --all` | Preview compiled output differences | | `prs inspect ` | Show skill layers and property provenance | | `prs explain ` | Show source and composition provenance | | `prs hooks install [tool]` | Integrate supported AI tools and protect generated files | -| `prs skills ` | Manage remote Markdown skills | +| `prs hook ` | Low-level handler called by AI tool hooks | +| `prs skills ` | Manage remote and local skills | | `prs registry ` | Manage registries and aliases | +| `prs pull` | Pull updates from the registry | | `prs lock` / `prs update` | Pin or refresh remote dependencies | | `prs vendor sync` / `prs vendor check` | Prepare and verify offline dependencies | | `prs resolve ` | Explain import resolution | | `prs import ` / `prs migrate` | Adopt existing instruction files | | `prs upgrade` | Upgrade `.prs` syntax versions | +| `prs update-check` | Check npm for a newer CLI version | +| `prs telemetry ` | Inspect or change anonymous telemetry settings | | `prs serve` | Connect local files to the online playground | `prs explain` emits project-relative source paths by default. Pass @@ -460,6 +507,13 @@ Targets with native skill support can receive the bundled PromptScript language compatible agents to work with `.prs` source. Disable it with `includePromptScriptSkill: false`. +## Privacy and Telemetry + +PromptScript is a compiler, not a service. Compiling needs no hosted backend, and the output is +plain files in your repository. Anonymous usage telemetry never includes source, prompts, or file +paths. Turn it off with `prs telemetry disable` or `DO_NOT_TRACK=1`. See +[what is collected](https://getpromptscript.dev/reference/telemetry/). + ## Docker ```bash @@ -479,7 +533,10 @@ for syntax highlighting, bracket matching, code folding, and file icons. - [Language Reference](https://getpromptscript.dev/reference/language/) - [Configuration Reference](https://getpromptscript.dev/reference/config/) - [Target Matrix](https://getpromptscript.dev/reference/formatters/) -- [Upgrade 1.15 to 1.16](https://getpromptscript.dev/guides/upgrade-1-15-to-1-16/) +- [Security Guide](https://getpromptscript.dev/guides/security/) +- [Model Catalog](https://getpromptscript.dev/reference/models/) +- [Glossary](https://getpromptscript.dev/glossary/) +- [FAQ](https://getpromptscript.dev/guides/faq/) - [Enterprise Guide](https://getpromptscript.dev/guides/enterprise/) - [Playground](https://getpromptscript.dev/playground/) From 9947dcdce51e4d3948c2e838d492ddc65873441e Mon Sep 17 00:00:00 2001 From: mrwogu Date: Thu, 1 Oct 2026 09:03:54 +0200 Subject: [PATCH 3/3] docs: clarify security scan scope and PS011 phrase --- README.md | 12 ++++++------ packages/cli/README.md | 11 ++++++----- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 02cd149208d..1080e06d096 100644 --- a/README.md +++ b/README.md @@ -366,9 +366,9 @@ from the catalog and move on when you upgrade PromptScript and compile again. Se ## Built-In Security Scanner -Instruction files and imported skills are a prompt injection surface. `prs validate` scans every -instruction, skill, and imported file before anything is written. Encoded payloads are decoded -first, so hiding an attack in hex or Base64 does not get it through: +Instruction files and imported skills are a prompt injection surface. `prs validate` scans the +instructions and skills in your entry file and everything it imports, before anything is written. +Encoded payloads are decoded first, so hiding an attack in hex or Base64 does not get it through: ```text $ prs validate --strict @@ -388,13 +388,14 @@ $ prs validate --strict | Rule | Catches | | :---- | :----------------------------------------------------------------------------- | | PS005 | Injection phrases like "ignore previous instructions" | -| PS011 | Fake authority overrides and "bypass all safety" instructions | +| PS011 | Fake authority overrides and "bypass all safety checks" instructions | | PS012 | Payloads hidden in Base64, hex, URL encoding, HTML entities, ROT13, and 4 more | | PS013 | Path traversal in `@use` declarations | | PS014 | Right-to-left overrides, zero-width characters, and homoglyphs | | PS010 | Plain HTTP links, link shorteners, and credentials in URLs | -Run it in CI with `prs validate --strict` so a poisoned skill fails the build, not the agent. See +`--strict` turns warnings into errors. Run it in CI so a poisoned skill fails the build, not the +agent. See the [security guide](https://getpromptscript.dev/guides/security/). ## 50 Built-In Targets @@ -474,7 +475,6 @@ with `includePromptScriptSkill: false`. | [Security Guide](https://getpromptscript.dev/guides/security/) | Validation rules, injection detection, and safe registries | | [Model Catalog](https://getpromptscript.dev/reference/models/) | Model aliases and per-target model names | | [Anonymous Usage Telemetry](https://getpromptscript.dev/reference/telemetry/) | Collected fields, delivery, and opt-out controls | -| [Glossary](https://getpromptscript.dev/glossary/) | Every PromptScript term in one place | | [FAQ](https://getpromptscript.dev/guides/faq/) | Common questions about adoption, targets, and security | | [Enterprise Guide](https://getpromptscript.dev/guides/enterprise/) | Organization-wide adoption and governance | diff --git a/packages/cli/README.md b/packages/cli/README.md index a039e2e79c0..b2699bf038d 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -425,9 +425,9 @@ requires Git registries to already exist in vendor mode or a valid local cache. ## Built-In Security Scanner -`prs validate` scans every instruction, skill, and imported file for prompt injection before -anything is written. Encoded payloads are decoded first, so an attack hidden in hex or Base64 does -not get through: +`prs validate` scans the instructions and skills in your entry file and everything it imports for +prompt injection, before anything is written. Encoded payloads are decoded first, so an attack +hidden in hex or Base64 does not get through: ```text $ prs validate --strict @@ -447,13 +447,14 @@ $ prs validate --strict | Rule | Catches | | :---- | :----------------------------------------------------------------------------- | | PS005 | Injection phrases like "ignore previous instructions" | -| PS011 | Fake authority overrides and "bypass all safety" instructions | +| PS011 | Fake authority overrides and "bypass all safety checks" instructions | | PS012 | Payloads hidden in Base64, hex, URL encoding, HTML entities, ROT13, and 4 more | | PS013 | Path traversal in `@use` declarations | | PS014 | Right-to-left overrides, zero-width characters, and homoglyphs | | PS010 | Plain HTTP links, link shorteners, and credentials in URLs | -Run `prs validate --strict` in CI so a poisoned skill fails the build, not the agent. See the +`--strict` turns warnings into errors. Run `prs validate --strict` in CI so a poisoned skill fails +the build, not the agent. See the [security guide](https://getpromptscript.dev/guides/security/). ## CLI Commands