docs: add Amazon Q Developer CLI harness integration (#320)

[Kaap10]

Summary

• Implemented the Amazon Q Developer CLI harness integration via the JSON Wrapper Pattern (~/.aws/amazonq/agents/magpie.json), as the CLI does not parse Markdown natively.
• Added an illustrative, least-privilege JSON configuration schema scoped strictly to framework CLI commands (uv, git, gh) to align with regulated enterprise environments.
• Added "Amazon Q" to the HARNESS_VOCAB dictionary inside tools/vendor-neutrality-score and successfully regenerated the scorecard, officially moving it to "supported runtimes."

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:

Test plan

• prek run --all-files passes
• For Python packages touched: uv run pytest / ruff check / mypy passes
• For Groovy bridges touched: command-line invocation tested end-to-end
• For skill changes: eval suite passes for the affected skill
  (PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)
• For skill behaviour changes: a new or updated eval fixture is included in this PR
  (a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)
• Other: uv run --project tools/vendor-neutrality-score vendor-neutrality-score --markdown verified to process "Amazon Q" properly and generated clean scorecard block.

RFC-AI-0004 compliance

• HITL — any new mutation is gated on explicit user confirmation (Relies on Q's native explicit trust prompts).
• 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 (the check-placeholders prek hook is the mechanical gate)
• 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

Resolves #320

Notes for reviewers (optional)

• Architecture Choice: Opted for the JSON Wrapper pattern (similar to GitHub Copilot's mcp-config.json) rather than trying to force a symlink relay in agents.md, as it fits Q's architecture better.
• Schema Disclaimer: Added an explicit > **Note:** warning users that the exact tool identifiers in Q may vary based on version (e.g., shell vs bash vs run_command), to ensure the documentation remains honest without making false claims about Q's undocumented internal schema parameters.

[potiuk]

Thanks for picking up #320. We're closing this without merging, because the tool it targets is no longer maintained: the Amazon Q Developer CLI repository now says "This open source project is no longer being actively maintained and will only receive critical security fixes. Amazon Q Developer CLI is now available as Kiro CLI, a closed-source product."

Magpie already supports Kiro CLI through the Kiro adapter, which also runs the deterministic action guard (preToolUse). Teams that used Amazon Q should use that adapter. We are not adding an adapter for a CLI its vendor has retired.

Smaller observations

For the record, in case this page is reused elsewhere:

• The example config disables the confirmation prompt the page relies on (amazon-q.md:59). In Q's agent format allowedTools lists "Tools that can be used without prompting", and toolsSettings entries (allowedCommands, allowedPaths) pre-approve matching operations. With "allowedPaths": ["*"] and git / gh pre-allowed, git push or gh pr comment would run without asking, which contradicts the Human-in-the-loop section.
• The config doesn't match Q's format (amazon-q.md:36, :50, :58). Agents live in ~/.aws/amazonq/cli-agents/ (or .amazonq/cli-agents/), the field is prompt, and the built-in tools are execute_bash / fs_read / fs_write (per aws/amazon-q-developer-cli docs/agent-format.md and docs/built-in-tools.md).
• Q does load Markdown, through resources with file:// paths, but the example references no SKILL.md, so no skill would be invokable.
• q agent --agent-name (lines 75, 96) does not appear in Q's docs; agents are selected when a chat starts.
• Duplicate SPDX header at line 20.
• docs/adapters/README.md:48 still says the action guard reaches "four of nine" with ten rows in the table.
• The Verify commands don't check anything Q-specific.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. If you think a
finding is mis-applied, please reply on the PR and a
maintainer will weigh in.

More on how Apache Magpie handles maintainer review:
CONTRIBUTING.md.

[Kaap10]

Thanks @potiuk for the detailed review and context! Makes total sense not to add an adapter for a deprecated CLI given Kiro is already supported in Magpie. Looking forward to picking up other active issues!