Skip to content

docs(setup): correct Codex plugin installation instructions - #1556

Merged
potiuk merged 1 commit into
apache:mainfrom
MakerFlyFly:docs/fix-codex-plugin-install
Oct 8, 2026
Merged

potiuk merged 1 commit into
apache:mainfrom
MakerFlyFly:docs/fix-codex-plugin-install

Conversation

@MakerFlyFly

Copy link
Copy Markdown
Contributor

Summary

  • Replace unsupported Codex plugin install examples with plugin add and explicit marketplace selectors so the commands reach installation.
  • Limit the Codex baseline to the available setup and utilities plugins, and clarify that agent-guard is absent from its marketplace.
  • Correct the Superpowers command in the companion registry and regenerate its documentation so regeneration preserves the fix.

Type of change

  • Skill change (.claude/skills/<name>/) — eval fixtures updated below
  • Tool / bridge contract (tools/<system>/*.md)
  • Python package (tools/*/ with pyproject.toml)
  • Groovy reference impl
  • Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
  • Documentation (docs/, README.md, CONTRIBUTING.md)
  • Project template (projects/_template/)
  • CI / dev loop (prek, workflows, validators)
  • Other: companion installation-command data in tools/dev/companion-skills.json.

Test plan

  • prek run --all-files passes in the Linux validation copy, including workspace pytest, ruff and mypy; prek run lychee --all-files also passes (both exit 0).
  • For Python packages touched: uv run pytest / ruff check / mypy passes — not applicable; no Python implementation changes.
  • For Groovy bridges touched: command-line invocation tested end-to-end — not applicable.
  • For skill changes: eval suite passes for the affected skill — no skill source changed; see the scoped smoke evaluation below.
  • For skill behaviour changes: a new or updated eval fixture is included in this PR — not applicable; no skill workflow or fixture changes.
  • git diff --check and the companion generator's consistency check pass; regenerating the page again produces no additional diff after preserving LF line endings on Windows.
  • Isolated Windows Codex installation: marketplace add, setup add, utilities add and marketplace-filtered plugin list return 0; both plugins are installed and enabled, with 10 and 5 installed skill files respectively.
  • Negative checks: plugin install --help returns 2; unqualified plugin add magpie-setup returns 1; qualified agent-guard add returns 1 because no such catalogue entry exists.
  • Superpowers selector checked against its marketplace manifest and with plugin add ... --help; no third-party plugin installation was performed.
  • Setup evaluation prompts assemble for all 95 existing cases. The author evaluated the 10 existing M3/M4 installation cases: initial comparison 9/10, then 10/10 after correcting the author response's scope for the marketplace-only case. This is a self-evaluation smoke check, not a full-suite or independent-model pass.

RFC-AI-0004 compliance

The change corrects installation examples and command data.
It introduces no new mutation policy, adapter, sandbox access, or skill workflow; the principle-specific rows below are not applicable.

  • HITL — any new mutation is gated on explicit user confirmation
  • Sandbox — no new unrestricted host access; network reach declared in the adapter
  • Vendor neutrality — placeholders (<PROJECT>, <tracker>, <upstream>, <security-list>) used in all skill / tool prose
  • Conversational + correctable — agentic-override path documented if behaviour is adopter-tunable
  • Write-access discipline — no autonomous outbound messages; drafts only, sent on confirmation
  • Privacy LLM — private content does not reach a non-approved LLM; redactor invoked where needed

Linked issues

Closes #1555.

Notes for reviewers (optional)

Validation uses upstream commit f3cab5ce60319da987549a8523ac1226885f1ae7 and the same staged Git tree in a Linux container to preserve repository symlinks.
The first whole-tree run exposed missing container prerequisites (jq, gh, tokenizer cache) and a process-reaping requirement.
After preparing those prerequisites and running under tini, the complete hook run and the separate link check both passed.

Only the three contribution files belong in this PR.
Local reproduction logs, review materials and validation scripts are kept outside the repository checkout.

Suggested labels: family:setup, family:docs, capability:platform.

Generative AI disclosure: Codex assisted with the documentation correction, verification, and preparation of this PR description.
The contributor will review the complete diff and submission text before publication.

Use the supported add subcommand with explicit marketplace selectors.
The bare plugin names still fail after changing the verb, and the Codex
catalogue does not offer the agent-guard plugin shown in the baseline.

Update the companion registry and generated page together so regeneration
keeps the corrected Superpowers installation command.

Generated-by: Codex (codex-cli 0.159.0-alpha.12.1)
@github-actions github-actions Bot added family:setup setup-* skills family:tools tools/* family:docs Docs, MISSION.md, READMEs family:ci .github workflows, prek, validators substrate:framework-dev Tool substrate: build / validate / eval the framework itself labels Oct 8, 2026

@potiuk potiuk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — the Codex install commands now match the real CLI, and CI is green.

Checked:

  • codex plugin add exists and codex plugin install does not, so the old commands were wrong.
  • magpie-agent-guard is not in .agents/plugins/marketplace.json, so dropping it from the Codex block is correct.
  • No other doc or config still uses codex plugin install.

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
Contributing guide.

@potiuk
potiuk merged commit a74adb8 into apache:main Oct 8, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

family:ci .github workflows, prek, validators family:docs Docs, MISSION.md, READMEs family:setup setup-* skills family:tools tools/* substrate:framework-dev Tool substrate: build / validate / eval the framework itself

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Codex installation instructions use an unsupported subcommand and unavailable baseline plugin

2 participants