feat: agent-bootstrap CLI surface + AGENTS-CLI 0.1 reference impl#6
Merged
Conversation
Brainstorm output: a new `agents` subcommand prints a self-contained guide so an AI coding agent in a user's repo can bootstrap into productive use of qualifier without a separately-installed skill or prompt bundle. Pages are hand-written markdown embedded via include_str!(), discovered through a small registry, and surfaced under a new "For AI agents:" group at the top of `qualifier --help`.
Bite-sized TDD breakdown of the spec at docs/superpowers/specs/2026-05-06-qualifier-agents-command-design.md into 10 tasks, each with failing-test-first steps where applicable. Tasks 1–5 build infrastructure (skeleton, registry, dispatch, overview rendering, help-template wiring); Tasks 7–8 fill in real prose for the topical and per-subcommand pages; Task 9 handles version/CHANGELOG/README; Task 10 is final verification.
Adds the `qualifier agents` subcommand as a directory-style module with a bundled markdown overview page. Bare invocation prints the overview; an unrecognized topic name exits with code 2.
Replace placeholder _overview.md with real orientation prose containing
{{TOPICS}}, and add integration + unit tests to verify substitution.
Replaces one-line placeholders in all 9 per-subcommand agent pages with structured content following the Purpose / When to use it / Common invocations / Flags worth knowing / Gotchas template (57–72 lines each). All flags verified against source and --help output; removed features (score, init, graph) are not mentioned.
Two related artifacts: 1. AGENTS-CLI.md (repo root) — a draft protocol document for CLI tools that self-describe to AI coding agents. Tool-agnostic prose with five MUST rules (subcommand existence, bare orientation, topic dispatch, unknown-topic exit-2, --help discoverability) and four SHOULD rules. qualifier 0.5.0+ is the reference implementation. Probe and JSON output are out of scope for 0.1. 2. docs/superpowers/specs/2026-05-06-frontmatter-migration-design.md — qualifier-internal refactor that replaces the hand-coded &[Page] registry with TOML frontmatter on each page, generated at compile time by build.rs. Adds name/summary/sees_also/since fields. No user-visible CLI change.
Replaces the hand-coded &[Page] in src/cli/commands/agents/mod.rs with a build.rs-generated const derived from frontmatter on each pages/*.md. Adds toml + serde as build dependencies; emits $OUT_DIR/agents_pages.rs included by mod.rs. New schema: name (required), summary (required for topic pages), sees_also (optional, parsed but not yet rendered), since (optional). User-visible CLI behavior is unchanged.
…bility Strip the leading '\n' after the closing +++ delimiter so rendered pages no longer start with a blank line. Also narrow Page and its generated constants from pub to private (with #[allow(dead_code)] on the two not-yet-read fields) to avoid the private_interfaces lint under -D warnings.
…amples Three changes to the agent-facing pages: - _overview.md: drop the bullet recommending agents proactively record praise; drop the ## Protocol footer (AGENTS-CLI conformance is for tool authors, not for the agents reading this page). - pitfalls.md: add an explicit pitfall against volunteering positive-polarity annotations without user direction. - record.md: replace the "Approve an artifact" example (which modeled exactly the proactive-positive pattern) with a suggestion example that preserves the --issuer / --issuer-type ai illustration.
…t close Across four pages: - _overview.md "When to use it" drops the resolve bullet; the section now lists only recording-a-finding as an agent-initiated action. - workflows.md drops the "Resolve a finding" recipe and rewrites the drift-triage recipe so the agent surfaces drift to the user instead of auto-resolving DRIFTED/MISSING annotations. - pitfalls.md adds an explicit pitfall against resolving annotations the user has not directed the agent to close. - resolve.md "When to use it" is rewritten to frame resolve as a user-directed action; the --issuer-type ai note is reworded to assume resolve is always done on behalf of the user, never autonomously.
|
🔍 Preview deployed: https://1c8f5b1a.qualifier-dev.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
qualifier agentssubcommand (0.5.0): self-contained guide for AI coding agents, surfaced under a new "For AI agents:" group at the top ofqualifier --help. Barequalifier agentsprints an orientation page;qualifier agents <topic>drills into 12 topics (3 topical: concepts/workflows/pitfalls; 9 per-subcommand: record/reply/resolve/emit/show/ls/praise/review/compact). Pages are hand-written markdown embedded into the binary, version-locked.AGENTS-CLI.md) defining what it means for a CLI tool to self-describe to coding agents — five MUST rules (subcommand existence, bare orientation, topic dispatch, exit-2 unknown-topic,--helpdiscoverability) plus four SHOULD recommendations. qualifier is named the reference implementation. Cross-linked from README; conformance is silent in the orientation page itself (which stays focused on agent-facing usage).build.rsthat walkssrc/cli/commands/agents/pages/*.md, parses TOML frontmatter (name/summary/sees_also/since), and emits thePAGESconst into\$OUT_DIR/agents_pages.rs. Adding a topic = drop in a new.mdfile. Addstomlandserdeas build-only dependencies; runtime binary unaffected.Test plan
CI already covers `cargo test`, `cargo clippy --all-targets --all-features -- -D warnings`, and `cargo fmt --check`. The remaining items are reviewer judgment calls that CI cannot make:
Specs and plans
Need help on this PR? Tag
@codesmithwith what you need.