feat(agent-integration): CLI docs, agent skill, and bin build wiring#3851
Conversation
Consolidates the Agent integration & docs epic into main as one atomic PR (the individual features landed on the epic branch, not main): - .claude/skills/protomaker-cli.md — agent skill teaching the protomaker CLI - docs/how-to/drive-the-board.md — CLI how-to guide - docs/reference/cli-commands.md — complete CLI command reference - docs/reference/index.md + docs/README.md — TOC links - package.json: add ./packages/cli to build:packages so the CLI builds with the standard package build (makes the bin available) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
👀 Quinn is reviewing — verdict (PASS / WARN / FAIL) + findings to follow. |
📝 WalkthroughWalkthroughThis PR adds comprehensive documentation for the ChangesCLI Documentation Suite
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![protoquinn[bot]](https://avatars.githubusercontent.com/in/3282126?s=60&v=4){kind=small}
There was a problem hiding this comment.
QA Audit — PR #3851 | feat(agent-integration): CLI docs, agent skill, and bin build wiring
VERDICT: FAIL
CI Status
- No CI checks found for PR#3851 (head b46e7d8) — BLOCKING
Diff Review
- Adds
.claude/skills/protomaker-cli.md— comprehensive 200-line agent skill documenting CLI commands - Adds
docs/how-to/drive-the-board.md+docs/reference/cli-commands.mdwith TOC links - Adds
./packages/clitobuild:packagesin rootpackage.json - All changes are additive (documentation/config) with no destructive edits visible
Observations
- CRITICAL: No CI checks detected for this PR. Cannot verify the
package.jsonbuild change produces a valid output. All PRs require at least one passing CI check before merge. - LOW: CLAWPATCH structural review unavailable (HTTP 502 during repo checkout cache init). Diff-level review shows no code logic changes — only docs + config.
- INFO: Content quality appears solid — skill file is well-structured, docs cover the full CLI surface, JSON mode for parsing is documented.
- INFO: PR body notes it supersedes #3844 and #3846, closing the Agent integration epic atomically.
Checks: 0 | Passed: 0 | Failed: 0 | Gaps: 1
[CRITICAL]: No CI checks found — at minimum, a build check is required before merge. Please trigger CI (e.g., push to branch, or check if branch protection rules need adjustment).
— Quinn, QA Engineer
|
Submitted REQUEST_CHANGES review on |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (2)
.claude/skills/protomaker-cli.md (1)
144-144: ⚡ Quick winAvoid brittle ID extraction from
feature list
jq -r '.[0].id'assumes ordering and non-empty results. Prefer a deterministic selector (for example filtering by the created title) or show extraction from the create command’s JSON output if available.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/protomaker-cli.md at line 144, The current FEATURE_ID extraction uses a brittle index selector (jq -r '.[0].id') which can break if ordering or emptiness changes; instead capture the feature ID deterministically by either parsing the JSON output from the create command or filtering the list by a known title—e.g., run the create command and parse its JSON response to set FEATURE_ID, or replace the jq selector with a filter like select(.title == "<expected-title>") to reliably pick the intended feature ID when using `protomaker feature list`.docs/how-to/drive-the-board.md (1)
27-33: 🏗️ Heavy liftReorder sections so commands appear before explanatory prose.
Across multiple sections, prose precedes snippets. For consistency with the docs standard, place the command block first, then the explanation.
As per coding guidelines, "Code before prose — show the snippet first, explain it second."
Also applies to: 41-42, 76-77, 108-109, 125-126, 139-140, 159-160, 167-168
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/how-to/drive-the-board.md` around lines 27 - 33, Several sections in docs/how-to/drive-the-board.md currently place explanatory prose before command snippets; move each command code block to appear immediately before its explanatory paragraph so "code before prose" is respected. For the blocks at the reported ranges (around the "protomaker board" example and the other instances at 41-42, 76-77, 108-109, 125-126, 139-140, 159-160, 167-168), cut each fenced code block (the bash/command snippet) and paste it above its following explanatory sentence or paragraph so the snippet is shown first, then the explanation; ensure surrounding blank lines and markdown headings remain intact and update any adjacent punctuation to keep sentences grammatically correct.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/protomaker-cli.md:
- Line 197: Update the "Use `--json` for parsing" guidance to explicitly warn
that the `--quiet` flag suppresses all output (including JSON), so combining
`--quiet` with `--json` will produce no machine-readable payload and will break
downstream jq or script pipelines; reference the `--json` and `--quiet` flags in
the sentence and add a short cautionary note about avoiding `--quiet` when you
need JSON output.
In `@docs/how-to/drive-the-board.md`:
- Line 20: Remove the emoji from the example line "Server: ✅ healthy" so the
documentation example uses plain text; update that string to "Server: healthy"
(i.e., remove the "✅" character) and ensure similar examples in the same file do
not contain emojis unless they are table/checklist status indicators.
- Around line 19-23: The fenced block in the documentation snippet is missing a
language tag which triggers MD040; update the triple-backtick fence around the
server status block in docs/how-to/drive-the-board.md to include a language
identifier (e.g., change ``` to ```text) so the fence becomes ```text and keep
the block content unchanged; verify the surrounding section still follows the
repository doc template (title, orientation, prerequisites, code first then
explanation).
In `@docs/reference/cli-commands.md`:
- Around line 1-3: The doc claims "Complete reference" but omits the registered
command groups "project" and "dev"; update docs/reference/cli-commands.md to add
full sections for the protomaker project commands (at minimum "project init" and
"project config" with usage and short descriptions) and for protomaker dev
(e.g., "dev info" with usage and description), and also add corresponding rows
in the "Command Summary" table for `project init`, `project config`, and `dev
info` so the reference is accurate and complete.
- Around line 23-35: Reorder the CLI command sections so the usage snippet
appears before the descriptive prose: for the "protomaker board" section
(heading `protomaker board`) move the usage code block (```bash protomaker board
[global-flags]```) above the sentence "Print a per-status summary of the feature
board." and similarly for the `protomaker query` section (and any other sections
called out in the comment, e.g., the block covering lines 37-55) place their
usage code blocks before their explanatory paragraphs and the "Output:" lines,
ensuring each section now follows the "code before prose" guideline.
---
Nitpick comments:
In @.claude/skills/protomaker-cli.md:
- Line 144: The current FEATURE_ID extraction uses a brittle index selector (jq
-r '.[0].id') which can break if ordering or emptiness changes; instead capture
the feature ID deterministically by either parsing the JSON output from the
create command or filtering the list by a known title—e.g., run the create
command and parse its JSON response to set FEATURE_ID, or replace the jq
selector with a filter like select(.title == "<expected-title>") to reliably
pick the intended feature ID when using `protomaker feature list`.
In `@docs/how-to/drive-the-board.md`:
- Around line 27-33: Several sections in docs/how-to/drive-the-board.md
currently place explanatory prose before command snippets; move each command
code block to appear immediately before its explanatory paragraph so "code
before prose" is respected. For the blocks at the reported ranges (around the
"protomaker board" example and the other instances at 41-42, 76-77, 108-109,
125-126, 139-140, 159-160, 167-168), cut each fenced code block (the
bash/command snippet) and paste it above its following explanatory sentence or
paragraph so the snippet is shown first, then the explanation; ensure
surrounding blank lines and markdown headings remain intact and update any
adjacent punctuation to keep sentences grammatically correct.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: d4fa6464-8c7a-465e-bf65-51d42ffe88cf
📒 Files selected for processing (6)
.claude/skills/protomaker-cli.mddocs/README.mddocs/how-to/drive-the-board.mddocs/reference/cli-commands.mddocs/reference/index.mdpackage.json
| ## Best Practices for Agents | ||
|
|
||
| 1. **Discover via `--help`** — run `protomaker --help` before using unfamiliar commands | ||
| 2. **Use `--json` for parsing** — always use JSON mode when extracting IDs or values for scripting |
There was a problem hiding this comment.
Clarify that --quiet suppresses JSON output too
This line can mislead scripting users: --quiet takes precedence over --json, so combining them returns no machine-readable payload. Add an explicit caution here to prevent broken jq pipelines.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/protomaker-cli.md at line 197, Update the "Use `--json` for
parsing" guidance to explicitly warn that the `--quiet` flag suppresses all
output (including JSON), so combining `--quiet` with `--json` will produce no
machine-readable payload and will break downstream jq or script pipelines;
reference the `--json` and `--quiet` flags in the sentence and add a short
cautionary note about avoiding `--quiet` when you need JSON output.
| ``` | ||
| Server: ✅ healthy | ||
| Version: 0.1.0 | ||
| Checked: 2026-05-26T10:30:00.000Z | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the expected-output fence.
This code fence is missing a language identifier and will keep triggering MD040.
Suggested fix
-```
+```text
Server: ✅ healthy
Version: 0.1.0
Checked: 2026-05-26T10:30:00.000Z</details>
As per coding guidelines, "Documentation pages follow a standard template: outcome-focused title, orientation paragraph, prerequisites (if non-trivial), verb-phrase section headings, code first then explanation, next steps."
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 19-19: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/how-to/drive-the-board.md` around lines 19 - 23, The fenced block in the
documentation snippet is missing a language tag which triggers MD040; update the
triple-backtick fence around the server status block in
docs/how-to/drive-the-board.md to include a language identifier (e.g., change
``` to ```text) so the fence becomes ```text and keep the block content
unchanged; verify the surrounding section still follows the repository doc
template (title, orientation, prerequisites, code first then explanation).
| Expected output: | ||
|
|
||
| ``` | ||
| Server: ✅ healthy |
There was a problem hiding this comment.
Remove emoji from the documentation output example.
✅ is used in a regular code example, not a checklist/table status context.
As per coding guidelines, "No emojis in docs or code — exceptions only for ✅ and ❌ as status indicators in documentation tables or checklists."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/how-to/drive-the-board.md` at line 20, Remove the emoji from the example
line "Server: ✅ healthy" so the documentation example uses plain text; update
that string to "Server: healthy" (i.e., remove the "✅" character) and ensure
similar examples in the same file do not contain emojis unless they are
table/checklist status indicators.
| # CLI Command Reference | ||
|
|
||
| Complete reference for the `protomaker` CLI. Every command supports the global flags `--json`, `--quiet`, and `--project <path>`. |
There was a problem hiding this comment.
Reference is marked complete but omits registered command groups (project, dev).
Line 3 says this is a complete reference, but the page and summary don’t document protomaker project and protomaker dev, which are wired in packages/cli/src/cli.ts.
Suggested doc patch
## `protomaker context`
@@
**Filename rules:** Must end in `.md` or `.txt`.
---
+## `protomaker project`
+
+Manage protomaker projects.
+
+### `project init`
+
+Initialize a new protomaker project.
+
+**Usage:**
+
+```bash
+protomaker project init [options] [global-flags]
+```
+
+### `project config`
+
+View or edit project configuration.
+
+**Usage:**
+
+```bash
+protomaker project config [options] [global-flags]
+```
+
+---
+
+## `protomaker dev`
+
+Development and debugging utilities.
+
+### `dev info`
+
+Show environment and project info.
+
+**Usage:**
+
+```bash
+protomaker dev info [global-flags]
+```
+
+---
+
## Command Summary
@@
| `context create <filename> [--content]` | Create a context file |
| `context delete <filename> [--yes]` | Delete a context file |
+| `project init` | Initialize a project |
+| `project config` | View/edit project config |
+| `dev info` | Show env and project info |As per coding guidelines, reference docs must be “Reference (complete, accurate)”.
Also applies to: 479-509
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/cli-commands.md` around lines 1 - 3, The doc claims "Complete
reference" but omits the registered command groups "project" and "dev"; update
docs/reference/cli-commands.md to add full sections for the protomaker project
commands (at minimum "project init" and "project config" with usage and short
descriptions) and for protomaker dev (e.g., "dev info" with usage and
description), and also add corresponding rows in the "Command Summary" table for
`project init`, `project config`, and `dev info` so the reference is accurate
and complete.
| ## `protomaker board` | ||
|
|
||
| Print a per-status summary of the feature board. | ||
|
|
||
| **Usage:** | ||
|
|
||
| ```bash | ||
| protomaker board [global-flags] | ||
| ``` | ||
|
|
||
| **Output:** Text summary table (counts per status, WIP limits). Use `--json` for raw JSON. | ||
|
|
||
| --- |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major | 🏗️ Heavy lift
Put usage snippets before prose to match docs standard.
Several sections start with explanation first, then usage. Reorder to show the code block first, then the description (for example in board and query).
Example reorder for one section
## `protomaker board`
-Print a per-status summary of the feature board.
-
**Usage:**
```bash
protomaker board [global-flags]+Print a per-status summary of the feature board.
+
Output: Text summary table (counts per status, WIP limits). Use --json for raw JSON.
</details>
As per coding guidelines, “Code before prose — show the snippet first, explain it second.”
Also applies to: 37-55
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @docs/reference/cli-commands.md around lines 23 - 35, Reorder the CLI command
sections so the usage snippet appears before the descriptive prose: for the
"protomaker board" section (heading protomaker board) move the usage code
block (bash protomaker board [global-flags]) above the sentence "Print a
per-status summary of the feature board." and similarly for the protomaker query section (and any other sections called out in the comment, e.g., the
block covering lines 37-55) place their usage code blocks before their
explanatory paragraphs and the "Output:" lines, ensuring each section now
follows the "code before prose" guideline.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
mabry1985
dismissed
protoquinn[bot]’s stale review
Stale — Quinn's only concern was 'No CI checks found' (it reviewed before CI ran, during the namespace-runner outage). CI is now green: build pass, test pass, checks pass. That was its explicit re-review condition.
1 participant
Consolidates the Agent integration & docs epic into main atomically (the features landed on the epic branch, not main — same fragmentation as Core, #3825). Fresh branch off main → clean CI.
Contents
.claude/skills/protomaker-cli.md— agent skill teaching the CLIdocs/how-to/drive-the-board.md+docs/reference/cli-commands.md+ TOC linkspackage.json:./packages/cliadded tobuild:packagesSupersedes #3844 (docs) and the closed #3846 (make-bin). Closes the epic.
🤖 Generated with Claude Code
Summary by CodeRabbit