From 42a9a5868e323e034e054b60abdad45e7fccff17 Mon Sep 17 00:00:00 2001 From: bercianor Date: Wed, 3 Jun 2026 21:45:41 +0200 Subject: [PATCH 1/3] feat: skills install and llms.txt documentation --- docs/cli/cli.md | 109 +++++++++++++++++-------------- docs/resources/agentic-coders.md | 75 +++++++++++++++++++++ 2 files changed, 136 insertions(+), 48 deletions(-) create mode 100644 docs/resources/agentic-coders.md diff --git a/docs/cli/cli.md b/docs/cli/cli.md index 6cedf47e..b68b12e3 100644 --- a/docs/cli/cli.md +++ b/docs/cli/cli.md @@ -66,25 +66,38 @@ flamingock [global-options] [command-options] ### Global options -| Option | Short | Description | -|--------|-------|-------------| -| `--log-level` | `-l` | Application log level: `debug`, `info`, `warn`, `error` | -| `--quiet` | `-q` | Suppress non-essential output | -| `--no-color` | | Disable colored output | -| `--help` | `-h` | Show help information | -| `--version` | | Show version information | +| Option | Short | Description | +|---------------|--------|---------------------------------------------------------| +| `--log-level` | `-l` | Application log level: `debug`, `info`, `warn`, `error` | +| `--quiet` | `-q` | Suppress non-essential output | +| `--no-color` | | Disable colored output | +| `--help` | `-h` | Show help information | +| `--version` | | Show version information | Global options are inherited by all subcommands. +### `install-skills` + +Install skills from the Flamingock registry. By default, installs all skills to `./.agents/skills`. Use `--agent` to install skills for a specific agent. + +| Command | Destination | +|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------| +| `flamingock install-skills` | `./.agents/skills` | +| `flamingock install-skills --agent {claude, github, cursor, opencode, gemini, windsurf, pi}` | `./.{claude, github, cursor, opencode, gemini, windsurf, pi}/skills` | + +:::note +Paths are resolved relative to the directory where you run the command. +::: + ### `execute apply` Apply pending changes by spawning your application JAR. -| Option | Short | Required | Description | -|--------|-------|----------|-------------| -| `--jar` | `-j` | Yes | Path to the application JAR | -| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | -| `--` | | No | Separator — everything after is passed as application arguments | +| Option | Short | Required | Description | +|--------------|-------|----------|-----------------------------------------------------------------| +| `--jar` | `-j` | Yes | Path to the application JAR | +| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | +| `--` | | No | Separator — everything after is passed as application arguments | ```bash # Apply pending changes @@ -104,14 +117,14 @@ flamingock execute apply --jar ./my-app.jar -J -Xmx1g -- --spring.profiles.activ List audit entries from the change history. -| Option | Short | Required | Description | -|--------|-------|----------|-------------| -| `--jar` | `-j` | Yes | Path to the application JAR | -| `--history` | | No | Show full chronological history instead of snapshot | -| `--since` | | No | Filter entries since date (ISO-8601: `yyyy-MM-dd` or `yyyy-MM-ddTHH:mm:ss`) | -| `--extended` | `-e` | No | Show extended information (execution ID, class, method, hostname) | -| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | -| `--` | | No | Separator — everything after is passed as application arguments | +| Option | Short | Required | Description | +|--------------|-------|----------|-----------------------------------------------------------------------------| +| `--jar` | `-j` | Yes | Path to the application JAR | +| `--history` | | No | Show full chronological history instead of snapshot | +| `--since` | | No | Filter entries since date (ISO-8601: `yyyy-MM-dd` or `yyyy-MM-ddTHH:mm:ss`) | +| `--extended` | `-e` | No | Show extended information (execution ID, class, method, hostname) | +| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | +| `--` | | No | Separator — everything after is passed as application arguments | ```bash # Current state (latest per change unit) @@ -131,13 +144,13 @@ flamingock audit list --jar ./my-app.jar --extended Fix audit state for a change with issues. After manually verifying or fixing the state, mark the change as resolved. -| Option | Short | Required | Description | -|--------|-------|----------|-------------| -| `--jar` | `-j` | Yes | Path to the application JAR | -| `--change-id` | `-c` | Yes | Change unit ID to fix | -| `--resolution` | `-r` | Yes | Resolution type: `APPLIED` or `ROLLED_BACK` | -| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | -| `--` | | No | Separator — everything after is passed as application arguments | +| Option | Short | Required | Description | +|----------------|-------|----------|-----------------------------------------------------------------| +| `--jar` | `-j` | Yes | Path to the application JAR | +| `--change-id` | `-c` | Yes | Change unit ID to fix | +| `--resolution` | `-r` | Yes | Resolution type: `APPLIED` or `ROLLED_BACK` | +| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | +| `--` | | No | Separator — everything after is passed as application arguments | ```bash # Mark as successfully applied @@ -153,12 +166,12 @@ For detailed workflows on issue resolution, see [Issue resolution](../safety-and List all change units with inconsistent audit states. -| Option | Short | Required | Description | -|--------|-------|----------|-------------| -| `--jar` | `-j` | Yes | Path to the application JAR | -| `--json` | | No | Output in JSON format | -| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | -| `--` | | No | Separator — everything after is passed as application arguments | +| Option | Short | Required | Description | +|--------------|-------|----------|-----------------------------------------------------------------| +| `--jar` | `-j` | Yes | Path to the application JAR | +| `--json` | | No | Output in JSON format | +| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | +| `--` | | No | Separator — everything after is passed as application arguments | ```bash # List issues in table format @@ -172,14 +185,14 @@ flamingock issue list --jar ./my-app.jar --json Get detailed information about an audit issue. -| Option | Short | Required | Description | -|--------|-------|----------|-------------| -| `--jar` | `-j` | Yes | Path to the application JAR | -| `--change-id` | `-c` | No | Specific change unit ID (shows first issue if omitted) | -| `--guidance` | `-g` | No | Include resolution guidance | -| `--json` | | No | Output in JSON format | -| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | -| `--` | | No | Separator — everything after is passed as application arguments | +| Option | Short | Required | Description | +|---------------|-------|----------|-----------------------------------------------------------------| +| `--jar` | `-j` | Yes | Path to the application JAR | +| `--change-id` | `-c` | No | Specific change unit ID (shows first issue if omitted) | +| `--guidance` | `-g` | No | Include resolution guidance | +| `--json` | | No | Output in JSON format | +| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) | +| `--` | | No | Separator — everything after is passed as application arguments | ```bash # Get next priority issue with resolution guidance @@ -197,13 +210,13 @@ flamingock issue get --jar ./my-app.jar -c user-change-v2 --json ## Exit codes -| Code | Meaning | -|------|---------| -| `0` | Success | -| `1` | Execution error (change failed, process error, etc.) | -| `2` | Usage error (invalid arguments) | -| `126` | JAR not found or not a file | -| `130` | Interrupted (Ctrl+C) | +| Code | Meaning | +|-------|------------------------------------------------------| +| `0` | Success | +| `1` | Execution error (change failed, process error, etc.) | +| `2` | Usage error (invalid arguments) | +| `126` | JAR not found or not a file | +| `130` | Interrupted (Ctrl+C) | ## Example output diff --git a/docs/resources/agentic-coders.md b/docs/resources/agentic-coders.md new file mode 100644 index 00000000..0a442ff6 --- /dev/null +++ b/docs/resources/agentic-coders.md @@ -0,0 +1,75 @@ +--- +title: Using Flamingock with Agentic Coders +sidebar_position: 50 +--- + +# Using Flamingock with agentic coders + +**Flamingock** is designed to be **agent-ready**. Modern agentic coding assistants — such as **Claude Code**, **Gemini CLI**, and **OpenCode** — can be significantly more productive and accurate when working with Flamingock thanks to our adherence to emerging standards for AI-developer collaboration. + +By providing structured context and specialized skills, Flamingock ensures that AI agents generate setup and change code that is not only syntactically correct but also follows all architectural best practices, naming conventions, and safety patterns. + +--- + +## 🛠 Pillar 1: LLM-optimized documentation (`llms.txt`) + +Flamingock documentation is optimized for Large Language Models (LLMs) using the [llms.txt](https://llmstxt.org/) standard. Instead of having an agent crawl dozens of HTML pages, you can provide a single, structured entry point. + +We provide two key files at the root of our documentation: + +1. **`/llms.txt`**: A concise index of the documentation, providing a high-level overview and links to all relevant sections. +2. **`/llms-full.txt`**: A comprehensive, markdown-formatted file containing the **entire documentation** content. This is the most efficient way to give an agent the full context of Flamingock in a single request. + +### How to use it + +When starting a session with an agentic coder, point it to these resources to ensure it has the latest information: + +```bash +# Example with an agent that supports external context URLs +claude "Create a new Flamingock change to add an index to the users collection. Read the documentation at: https://docs.flamingock.io/llms-full.txt" +``` + +--- + +## 🧠 Pillar 2: Agent skills (`agentskills.io`) + +Beyond general documentation, Flamingock provides specialized **Skills** following the [agentskills.io](https://agentskills.io/) standard. A skill is a set of machine-readable instructions that teaches an agent exactly how to perform a specific task within the Flamingock ecosystem — without guessing or hallucinating APIs. + +All official skills are hosted at: [github.com/flamingock/flamingock-skills](https://github.com/flamingock/flamingock-skills). + +### Installing skills + +Skills are installed per project, and you can install all of them using the Flamingock CLI tool: + +| Command | Destination | +|----------------------------------------------|----------------------| +| `flamingock install-skills` | `./.agents/skills` | +| `flamingock install-skills --agent claude` | `./.claude/skills` | +| `flamingock install-skills --agent github` | `./.github/skills` | +| `flamingock install-skills --agent cursor` | `./.cursor/skills` | +| `flamingock install-skills --agent opencode` | `./.opencode/skills` | +| `flamingock install-skills --agent gemini` | `./.gemini/skills` | +| `flamingock install-skills --agent windsurf` | `./.windsurf/skills` | +| `flamingock install-skills --agent pi` | `./.pi/skills` | + +:::note +Paths are resolved relative to the directory where you run the command. +::: + +Then commit it to your repository so every developer and every CI agent gets it automatically: + +```bash +git add .agents/skills/flamingock-*/ +git commit -m "chore: add Flamingock agent skills" +``` + +Refer to the [Flamingock Skills repository](https://github.com/flamingock/flamingock-skills) for the full list of available skills. + +--- + +## 💎 Benefits of the agentic approach + +- **Correctness**: The agent follows the exact Flamingock API — no guessed method names, no invented configuration keys. +- **Consistency**: Every project gets the same setup patterns, regardless of which developer or agent generates them. +- **Safety**: Guards in the skill prevent common mistakes before any code is written. +- **Speed**: From "I need to set up Flamingock" to a working, production-ready configuration in seconds. From 9fd39bd7af3e7af59c0e08158d3b46707b4432a9 Mon Sep 17 00:00:00 2001 From: bercianor Date: Wed, 3 Jun 2026 21:46:06 +0200 Subject: [PATCH 2/3] chore: update to a new llms.txt plugin --- docusaurus.config.js | 28 ++++++++++++++++++++++++++-- package.json | 2 +- yarn.lock | 31 ++++++++++++++++++++++++++----- 3 files changed, 53 insertions(+), 8 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 5c4e18ae..dee67f65 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -195,9 +195,33 @@ const config = { }), plugins: [ [ - "docusaurus-plugin-generate-llms-txt", + 'docusaurus-plugin-llms', // https://github.com/rachfop/docusaurus-plugin-llms { - outputFile: "llms.txt", + generateLLMsTxt: true, + generateLLMsFullTxt: true, + docsDir: 'docs', + includeBlog: true, + excludeImports: true, + removeDuplicateHeadings: true, + generateMarkdownFiles: true, + includeOrder: [ + 'overview.md', + 'get-started/**/*', + 'flamingock-library-config/**/*', + 'changes/**/*', + 'target-systems/**/*', + 'audit-stores/**/*', + 'safety-and-recovery/**/*', + 'templates/**/*', + 'frameworks/**/*', + 'testing/**/*', + 'cli/**/*', + 'resources/**/*', + ], + includeUnmatchedLast: true, + pathTransformation: { + ignorePaths: ['docs'], + }, }, ], [require.resolve('docusaurus-lunr-search'), { diff --git a/package.json b/package.json index 1d8db992..6317ba38 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,7 @@ "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", "docusaurus-lunr-search": "^3.6.0", - "docusaurus-plugin-generate-llms-txt": "^0.0.1", + "docusaurus-plugin-llms": "^0.4.0", "prism-react-renderer": "^2.3.0", "react": "^19.0.0", "react-dom": "^19.0.0" diff --git a/yarn.lock b/yarn.lock index d13704ac..81f4585e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3433,6 +3433,13 @@ brace-expansion@^1.1.7: balanced-match "^1.0.0" concat-map "0.0.1" +brace-expansion@^2.0.2: + version "2.1.1" + resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.1.tgz#c68b1c4111c76aae3a6fba55d496cee10c39dad8" + integrity sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA== + dependencies: + balanced-match "^1.0.0" + braces@^3.0.3, braces@~3.0.2: version "3.0.3" resolved "https://registry.yarnpkg.com/braces/-/braces-3.0.3.tgz#490332f40919452272d55a8480adc0c441358789" @@ -4630,12 +4637,14 @@ docusaurus-lunr-search@^3.6.0: unified "^9.2.2" unist-util-is "^4.1.0" -docusaurus-plugin-generate-llms-txt@^0.0.1: - version "0.0.1" - resolved "https://registry.yarnpkg.com/docusaurus-plugin-generate-llms-txt/-/docusaurus-plugin-generate-llms-txt-0.0.1.tgz#e2104a73bdf59ea9f576f319e73e7d9c664e6ea8" - integrity sha512-XlUeQ23anYc85I1k9pO61fWcMWcUs8Tx7n3zqIus/1wjZ1mjezm0lOX9jymu9Y2MAi3/YQbDxsfo4kZrMf5q6A== +docusaurus-plugin-llms@^0.4.0: + version "0.4.0" + resolved "https://registry.yarnpkg.com/docusaurus-plugin-llms/-/docusaurus-plugin-llms-0.4.0.tgz#020f00d83459c7feb71c7b6e61774d864336d8ae" + integrity sha512-jYlj2HJ5+gu7oJZuJ83Hk8KlB65YlZZ/7UpHXiL7Qr+qpNBkVocmt2Molc6F3HNr5RqcfhWD/98CvgyNztg/ow== dependencies: - js-yaml "^4.1.0" + gray-matter "^4.0.3" + minimatch "^9.0.3" + yaml "^2.8.1" dom-converter@^0.2.0: version "0.2.0" @@ -7321,6 +7330,13 @@ minimatch@^3.1.2: dependencies: brace-expansion "^1.1.7" +minimatch@^9.0.3: + version "9.0.9" + resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-9.0.9.tgz#9b0cb9fcb78087f6fd7eababe2511c4d3d60574e" + integrity sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg== + dependencies: + brace-expansion "^2.0.2" + minimist@^1.2.0: version "1.2.8" resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.8.tgz#c1a464e7693302e082a075cee0c057741ac4772c" @@ -10230,6 +10246,11 @@ yallist@^3.0.2: resolved "https://registry.yarnpkg.com/yallist/-/yallist-3.1.1.tgz#dbb7daf9bfd8bac9ab45ebf602b8cbad0d5d08fd" integrity sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g== +yaml@^2.8.1: + version "2.9.0" + resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.9.0.tgz#78274afd93598a1dfdd6130df6a566defcbf9aa4" + integrity sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA== + yocto-queue@^1.0.0: version "1.2.1" resolved "https://registry.yarnpkg.com/yocto-queue/-/yocto-queue-1.2.1.tgz#36d7c4739f775b3cbc28e6136e21aa057adec418" From 6aa4a8d7605c073f36b2681c62e87361cd4cb083 Mon Sep 17 00:00:00 2001 From: bercianor Date: Thu, 4 Jun 2026 20:37:20 +0200 Subject: [PATCH 3/3] fix: add agentic-coders link and beta warning --- docs/cli/cli.md | 2 ++ docs/resources/agentic-coders.md | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/docs/cli/cli.md b/docs/cli/cli.md index b68b12e3..8917022a 100644 --- a/docs/cli/cli.md +++ b/docs/cli/cli.md @@ -89,6 +89,8 @@ Install skills from the Flamingock registry. By default, installs all skills to Paths are resolved relative to the directory where you run the command. ::: +More info at [Using Flamingock with agentic coders](../resources/agentic-coders.md). + ### `execute apply` Apply pending changes by spawning your application JAR. diff --git a/docs/resources/agentic-coders.md b/docs/resources/agentic-coders.md index 0a442ff6..f2f1ff79 100644 --- a/docs/resources/agentic-coders.md +++ b/docs/resources/agentic-coders.md @@ -33,6 +33,10 @@ claude "Create a new Flamingock change to add an index to the users collection. ## 🧠 Pillar 2: Agent skills (`agentskills.io`) +:::caution Beta feature +Flamingock Skills are still in **beta**. +::: + Beyond general documentation, Flamingock provides specialized **Skills** following the [agentskills.io](https://agentskills.io/) standard. A skill is a set of machine-readable instructions that teaches an agent exactly how to perform a specific task within the Flamingock ecosystem — without guessing or hallucinating APIs. All official skills are hosted at: [github.com/flamingock/flamingock-skills](https://github.com/flamingock/flamingock-skills).