{
  "markdown": "# Fluxzero Agent Plugins\n\nThis repository distributes Fluxzero plugins for Codex, Claude Code, Cursor,\nand GitHub Copilot, plus the equivalent Gemini CLI extension. Every package\ncontains the same application-building skill and configures the production\nFluxzero MCP documentation server and automated local-development server.\nInstall the package for your coding agent once; projects do not need\nhand-maintained Fluxzero manuals or duplicate MCP registrations.\n\n## One-time environment onboarding\n\nTreat first-time Fluxzero onboarding as one complete setup in the current\ncoding-agent task. Before asking for application requirements, prepare and\nverify Git, the agent plugin, the Fluxzero CLI, and Java 25. If\ntools are missing, explain once that this is the first Fluxzero build in the\nenvironment and that the one-time setup enables fast, reliable builds and\ntests. Do not present each prerequisite as an unrelated surprise.\n\nReadiness is a verified state, not an inference from a successful plugin\ncommand. Do not claim that the environment is ready while one of the checks\nbelow is missing. In particular, do not bypass missing Git with a branch ZIP or\nanother mutable source and then treat Git as optional.\n\n### Git on a bare macOS environment\n\nThe plugin commands below use Git. On macOS, inspect Apple Command Line Tools\nwithout first invoking Apple's `/usr/bin/git` shim:\n\n```bash\nxcode-select -p\npkgutil --pkg-info com.apple.pkg.CLTools_Executables\n```\n\nIf neither check finds a usable developer-tools installation, explain that\nmacOS will now open Apple's standard Command Line Tools installer. Run\n`xcode-select --install` exactly once, tell the user to click **Install**, accept\nthe license, wait for completion, and return to this same task. Stop at that\nboundary. Do not install the plugin, CLI, or Java while the dialog is open and do\nnot download an alternative plugin archive to avoid the Git prerequisite.\n\nAfter the user returns, repeat the two non-Git checks and then require a\nsuccessful `git --version`. On other platforms, require `git --version` before\nusing a Git-backed marketplace or extension command.\n\n### Fluxzero CLI prerequisite\n\nThe local-development MCP server runs `fz mcp --ensure-dev`, so\nthe Fluxzero CLI must be installed and available on the coding agent's `PATH`.\nVerify this before starting application work:\n\n```bash\nfz version\n```\n\nInstall the latest native CLI when that command is unavailable:\n\n**macOS or Linux with Homebrew:**\n\n```bash\nbrew install fluxzero-io/tap/fluxzero\n```\n\nOn a bare macOS machine without Homebrew, first complete the Git/Command Line\nTools boundary above and then follow the current installation instructions at\n[brew.sh](https://brew.sh). If Homebrew needs user approval, explain the exact\naction and stop until it is complete. Follow Homebrew's printed shell setup so\na clean login shell can resolve both `brew` and `fz`; do not replace the\nrecommended macOS route with an unversioned CLI download.\n\n**Windows with WinGet:**\n\n```powershell\nwinget install --exact --id Fluxzero.FluxzeroCLI\n```\n\n**Linux or another supported Unix environment:**\n\n```bash\ncurl -sSL https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/install.sh | sh -s -- --install-path\n```\n\nRun `fz version` again after installation. On macOS, also prove that persistent\nlogin configuration—not merely the bootstrap task's inherited environment—can\nresolve it:\n\n```bash\nenv -i HOME=\"$HOME\" USER=\"$USER\" LOGNAME=\"$LOGNAME\" SHELL=/bin/zsh \\\n  /bin/zsh -l -c 'command -v fz && fz version && fz mcp --help && fz init --help'\n```\n\nThe MCP help must list `--ensure-dev`, and the init help must list `--in-place`.\nThese are the command surfaces the plugin uses to\nkeep one dev session alive while a new project is created in its watched root.\n\nmacOS GUI applications do not read `.zprofile`. Publish the verified CLI\ndirectory to processes launched later in the current login session while\npreserving any existing launchd path:\n\n```bash\nfz_path=$(env -i HOME=\"$HOME\" USER=\"$USER\" LOGNAME=\"$LOGNAME\" SHELL=/bin/zsh \\\n  /bin/zsh -l -c 'command -v fz')\nfz_dir=$(dirname \"$fz_path\")\nlaunchd_path=$(/bin/launchctl getenv PATH 2>/dev/null || true)\ncase \":$launchd_path:\" in\n  *\":$fz_dir:\"*) ;;\n  *)\n    if [ -n \"$launchd_path\" ]; then\n      launchd_path=\"$fz_dir:$launchd_path\"\n    else\n      launchd_path=\"$fz_dir:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin\"\n    fi\n    /bin/launchctl setenv PATH \"$launchd_path\"\n    ;;\nesac\n```\n\nThis bridge affects only applications launched afterward; it does not update\nan already-running Codex/ChatGPT process. The login-shell configuration remains\nthe persistent installation state.\n\n### Java 25\n\nThe Fluxzero CLI checks Java when local development starts. If Java 25 is\nmissing and the coding agent's execution environment permits software\ninstallation, the agent installs it without asking the user and retries the\noriginal Fluxzero command. Existing agent execution permission is sufficient;\nthe workflow must not introduce a second confirmation step.\n\nIf the environment requires separate user approval for system installation,\nthe agent asks only: **\"Fluxzero needs Java 25. May I install it?\"** It then\nperforms the installation after approval and retries the original Fluxzero\ncommand. The agent never asks the user to run the command or exposes package,\npath, runtime, JDK, or environment-variable details in that permission question.\n\nThe stable agent-side installation commands are `brew install openjdk@25` on\nmacOS or Linux with Homebrew and\n`winget install --exact --id EclipseAdoptium.Temurin.25.JDK --accept-package-agreements --accept-source-agreements --disable-interactivity`\non Windows. Other Linux environments should use their established package\nmanager. Successful Fluxzero readiness,\nnot separate `java` or `javac` shell probes, verifies the result. Generated\nprojects already include Maven or Gradle wrappers; no system build tool or IDE\nis required.\n\n## Authoritative guidance\n\nThe plugin intentionally stores only stable installation and workflow rules.\nVersion-sensitive knowledge stays with the component that owns it:\n\n| Information | Authoritative source |\n|:------------|:---------------------|\n| CLI installation and agent workflow | This plugin |\n| SDK version used by a project | Its effective Maven or Gradle model |\n| Current SDK concepts and APIs | The `fluxzero-docs` MCP server |\n| SDK guidance for the detected project version | CLI-synchronized `.fluxzero/agents` manuals from the matching SDK release |\n| Current CLI commands | `fz --help` |\n| Current dev actions and options | `fz dev --help` |\n| `.fluxzero/dev.yaml` schema and defaults | `fz dev config` |\n| SDK implementation details when manuals are insufficient | The matching release tag in `https://github.com/fluxzero-io/fluxzero-sdk-java`, never `main` |\n\nAgents compare the SDK version advertised by `fluxzero-docs` with the effective\nproject version before applying version-sensitive guidance. They inspect\nexisting project configuration and command output instead of copying option or\nYAML catalogs into the plugin. When plugin wording and command output differ,\ncommand output wins.\n\nEvery package provides the same workflow:\n\n- use the Fluxzero CLI and a Java or Kotlin starter for a new, empty project\n- preserve the build and layout of an existing project\n- compare its SDK with the version advertised by the MCP documentation\n- retrieve focused framework guidance instead of reading the whole graph\n- let one Fluxzero dev environment watch, compile, run, and test the project\n- follow cursored structured feedback to the relevant terminal state after each\n  coherent edit\n- implement and test a real Fluxzero application rather than a generic service\n\nThe two servers have deliberately separate names and responsibilities:\n\n- `fluxzero-docs` serves stable framework guidance over HTTP.\n- `fluxzero-dev` runs `fz mcp --ensure-dev` in the current\n  workspace. It exposes the control plane before a greenfield project exists,\n  then reuses the same background environment for current problems, bounded\n  logs, test status, and a cursored development event stream.\n\nFor a new workspace, complete a `get_status` call before initialization and\nretain its session ID and cursor. Generate the starter directly into that exact\nwatched root with `fz init --in-place`; do not create and move a named child\nproject. Continue from the pre-initialization cursor with `wait_for_change`\nuntil project discovery, compilation, startup, and tests caused by generation\nreach terminal states, then corroborate them with fresh status, test-status,\nand active-problem calls.\n\nWhen `fluxzero-dev` is active, agents must not run duplicate wrapper tests,\napplications, watchers, or continuous log commands. Project wrappers remain\navailable for CI, releases, and explicit fallback verification.\n\n## Install\n\n### Codex\n\n```bash\ncodex plugin marketplace add fluxzero-io/fluxzero-agent-plugins\ncodex plugin add fluxzero@fluxzero\ncodex plugin list --json\n```\n\nRequire the final output to list `fluxzero@fluxzero` as installed and enabled.\nIf `codex` is not on `PATH`, the Codex desktop application bundles the same\ncommand at `/Applications/ChatGPT.app/Contents/Resources/codex`; use that\nabsolute executable for all three commands. Do not start a new task yet.\n\n### Claude Code\n\n```bash\nclaude plugin marketplace add fluxzero-io/fluxzero-agent-plugins\nclaude plugin install fluxzero@fluxzero\n```\n\nDefer `/reload-plugins` or a new Claude Code session until the final activation\nstep below.\n\n### Cursor\n\nThe repository contains a Cursor marketplace and plugin manifest ready for\nCursor Marketplace publication. Once listed, install it in Cursor with:\n\n```text\n/add-plugin fluxzero\n```\n\nFor local verification before marketplace approval, copy\n`adapters/cursor/fluxzero` to `~/.cursor/plugins/local/fluxzero`, but defer the\nCursor reload until the final activation step below.\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/fluxzero-io/fluxzero-agent-plugins --consent\n```\n\nDefer the Gemini CLI restart until the final activation step below.\n\n### GitHub Copilot CLI\n\n```bash\ncopilot plugin marketplace add fluxzero-io/fluxzero-agent-plugins\ncopilot plugin install fluxzero@fluxzero\n```\n\nDefer the new Copilot CLI session until the final activation step below. The\nsame plugin components are also available to Copilot app clients that use CLI\nplugins.\n\n### Verify readiness, then activate once\n\nAfter installing the package, finish every prerequisite before refreshing or\nrestarting the coding agent. Require all of the following evidence:\n\n- the native plugin or extension listing shows Fluxzero installed and enabled\n- `git --version` succeeds\n- the clean login-shell probe above resolves `fz`, `fz mcp --help` lists\n  `--ensure-dev`, and `fz init --help` lists `--in-place`\n- Fluxzero development readiness succeeds; if Java 25 was initially missing,\n  the agent installed it and retried the original command, obtaining separate\n  approval only when the execution environment required it\n- on macOS, the launchd `PATH` bridge includes the directory containing `fz`\n\nDo not equate a successful marketplace command, archive download, or\ninteractive-shell check with readiness. Do not ask for application requirements\nwhile any item is missing.\n\nOnly after every check passes, cross one activation boundary: completely quit\nand relaunch Codex/ChatGPT on macOS, run `/reload-plugins` or start a new Claude\nCode session, reload Cursor, restart Gemini CLI, or start a new Copilot CLI\nsession. A new task inside an already-running macOS Codex process is not enough\nafter changing its inherited `PATH`.\n\nIn the first activated task, confirm that the `build-fluxzero-app` skill is\navailable, call `docs_start` through `fluxzero-docs`, and complete a\n`get_status` call through `fluxzero-dev` before application work. Merely seeing\nthe development server in configuration or a tool catalogue is not readiness.\nIn an empty workspace, the status call must still succeed and identify that\nworkspace as its project directory. If either completed call is unavailable,\nstop and repair the plugin or process environment; do not bypass it with a\nduplicate wrapper build or a separately started development server.\n\n### Let the coding agent install its Fluxzero package\n\nThis minimal prompt is intentionally agent-neutral:\n\n```text\nI want to build an application using Fluxzero. Follow the onboarding instructions at https://plugins.fluxzero.io to install the Fluxzero plugin and prepare this environment.\nLet me know when everything is ready for my application requirements.\n```\n\nGemini CLI calls this package an extension. Its dedicated instructions and\ncommands below use that native terminology.\n\n## Generated project instructions\n\nThe files in `project-instructions/` are the source for new Fluxzero projects:\n\n- `AGENTS.md` contains the short, agent-neutral invariant used by Codex,\n  Cursor, and GitHub Copilot.\n- `CLAUDE.md` imports `AGENTS.md` and adds only the Claude installation and\n  reload command.\n- `GEMINI.md` imports `AGENTS.md` and adds only the Gemini installation and\n  restart command.\n\nThis avoids maintaining full, divergent manuals per agent while respecting\ntheir different instruction-file discovery rules. SDK-versioned manuals\nsynchronized by the Fluxzero CLI remain valid managed project context; agents\nmust not replace them with hand-maintained copies. An unavailable plugin or\nextension is a bootstrap boundary, not permission to implement from stale\nunmanaged docs.\n\n## Repository layout\n\n`skills/build-fluxzero-app/SKILL.md` is the canonical skill and the Gemini CLI\ncopy. `npm run generate` renders byte-identical skill copies into four thin,\nself-contained plugin packages, plus their manifests, transport-specific\ndocumentation and development MCP configurations, and marketplace catalogs.\nThe internal `adapters/` directories keep agent-specific formats isolated so\none client cannot auto-discover another client's incompatible MCP settings. CI\nrejects generated drift and symlinks.\n\n## Development\n\n```bash\nnpm run generate\nnpm test\n```\n\nThe generators have no third-party runtime dependencies. Validate agent-native\ninstall flows in isolated home directories before publishing a release.\n\n## Releases\n\n`plugins.config.json` is the source of the plugin version rendered into every\nagent package. Keep the matching `package.json` version in sync, run\n`npm run generate`, and merge the version change into `main`. After validation\nsucceeds, CI creates the corresponding `v<version>` tag and GitHub release.\nSubsequent pushes with the same version leave the existing release unchanged.\n\n## License\n\nLicensed under the Apache License 2.0. See [LICENSE](LICENSE).\n",
  "bytes": 14786,
  "sha": "1a9a84d94e8df7a0c34293d6b06c740aacb7b9c624efbdaa30538d4faee765e2",
  "repo_slug": "fluxzero-io/fluxzero-agent-plugins",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_fluxzero_io_fluxzero_agent_plugins_59c78191/readme"
}