Skip to content

docs(skills): name the 17 CLI commands the kirocrew-commands skill left out - #30553

Open
JiaDe-Wu wants to merge 3 commits into
kirodotdev:mainfrom
JiaDe-Wu:docs/kirocrew-commands-skill-missing-commands
Open

JiaDe-Wu wants to merge 3 commits into
kirodotdev:mainfrom
JiaDe-Wu:docs/kirocrew-commands-skill-missing-commands

Conversation

@JiaDe-Wu

@JiaDe-Wu JiaDe-Wu commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The kirocrew-commands skill names every user-facing CLI command, and a test keeps it that way.

The skill is the agent's CLI reference; it loads on help, setup and "what can you do", and the agent answers from its tables. Seventeen user-facing commands had no row: the kas family, gateway-pid, open, desktop tunnel, pod restart, memory forget, knowledge stats, app import, secrets authorize and agent pin. An agent asked how to sign in without kiro-cli, or how to restart a pod, had nothing to answer from.

Why it matters

The agent either says the command does not exist or guesses its flags.

Not a goal

  • No change to any command's behaviour or help text.
  • Not a rewrite of the existing rows.

What changed (motivation → approach → change)

The gap was found by walking the parser main() builds and grepping the skill for each command. The fix adds one row per command, worded from its argparse help, and a short "Kiro Crew's Own Engine (KAS)" section for the kas family. A new test captures the same parser and fails on any top-level command in cli_help.COMMAND_GROUPS, or any sub-command registered with a help text, that the skill does not name.

Backwards compatibility

Compatible: documentation rows and one new test; nothing a user runs changes.

Removes nothing: rows are only added.

Tests

  • test_top_level_commands / test_sub_commands: every user-facing command is named in the skill.
  • test_the_walk_finds_known_nested_commands, test_the_walk_leaves_internal_commands_out, test_the_matcher: the walk and the matcher cannot pass vacuously (a KIROCREW_DEBUG=1 prefix is accepted; kas is not satisfied by kas-bundle).

Proof: PROVEN test/test_kirocrew_commands_skill_coverage.py::TestEveryUserFacingCommandIsNamed::test_top_level_commands, test/test_kirocrew_commands_skill_coverage.py::TestEveryUserFacingCommandIsNamed::test_sub_commands (head 54e6da4)

Manual verification

Ran the new test against the skill as it was on main: it lists exactly the 17 commands above.

Related Issues

Closes #29816

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Nov 5, 2026
@JiaDe-Wu
JiaDe-Wu marked this pull request as ready for review November 5, 2026 17:12
@JiaDe-Wu
JiaDe-Wu requested review from a team and KiroCrewCaptain as code owners November 5, 2026 17:12
@dodgeblaster

Copy link
Copy Markdown
Contributor

Thanks for this. I checked it against current main (2d4848e): the merge is clean and the 17 rows match the help texts, but the new coverage test now fails on that merge, because two commands landed on main after this branch was cut:

What the test reports on the merge:

never names these top-level commands: ['acceptance-check', 'remote-control']
never names these sub-commands: ['remote-control off', 'remote-control on', 'remote-control status']

Could you rebase onto main and add rows for those four commands? The test is doing what it is meant to do here. Once the branch moves, a maintainer still has to approve the fork workflow runs before CI runs.

@JiaDe-Wu
JiaDe-Wu force-pushed the docs/kirocrew-commands-skill-missing-commands branch from 54e6da4 to 1171f28 Compare November 14, 2026 10:51
@JiaDe-Wu

Copy link
Copy Markdown
Contributor Author

Thanks, rebased onto main (8a1b4d3) and added the rows you listed: acceptance-check and remote-control (status, on, off).

main has also gained commands since the branch was cut, and the coverage test fails on them too, so the second commit adds a row for each, worded from their argparse help: models, tmp, agent validate, config pending (list, apply, discard), memory dream (list, run) and memory shadow report. Only SKILL.md changes, 13 rows in total.

On this head: test_kirocrew_commands_skill_coverage.py passes (11 tests), and docs-lint, the brand-name gate and the comment-history gate pass. The test will fail again whenever a command lands without a row, which is what it is for. If you would rather have the extra rows in a separate PR, I can split them out.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 17, 2026
@dodgeblaster

Copy link
Copy Markdown
Contributor

Thanks for the rebase and the extra rows. I re-checked head 1171f28 against current main (f4754ac). Two things are needed:

  1. A small rebase conflict. main added a kirocrew usage row (feat(cli): add kirocrew usage, a terminal report of recent spend #38556) at the same place as your gateway-pid and open rows in SKILL.md. Keeping both sides resolves it.
  2. Two more rows. With that conflict resolved, 9 of the 11 coverage tests pass. The other two fail on one command that landed after your rebase, kirocrew trace (feat(tracing): kirocrew trace show prints one turn as a waterfall from the local span files #37537):
    • top-level: trace, from its help "Show one traced turn as a waterfall from the local span files"
    • sub-command: trace show, "Print one turn's spans as a waterfall" (examples: kirocrew trace show <trace id>, kirocrew trace show <session key>)

Keeping the extra rows in this PR is fine. I'm approving the pending CI runs on this head now so the checks can run.

@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 1171f2896fa2f7f3dbe958426d4d79f34502760b touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 1171f2896fa2f7f3dbe958426d4d79f34502760b via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: this adds documentation rows plus a parser-driven test that stops the skill drifting from the CLI again, and it takes nothing away.

Notes

  • The diff adds about 30 rows, not 17. Rows for tmp, remote-control, memory dream/shadow, config pending, agent validate, models and acceptance-check are missing from the description's list, so the count in the description and in the test's module docstring doesn't match the diff.
  • The test gets the parser by patching ArgumentParser.parse_args and calling main(). If main() ever gains side effects before it parses, the test breaks. Exposing a build_parser() seam would remove that dependency.

[DESIGN-REVIEWED] 1171f28

Description read

[DESCRIPTION-READ] 1ba033659072cdbed7f8ddd9c87ec3bd5039707febb97bb6855466f847449fc5

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 1171f2896fa2f7f3dbe958426d4d79f34502760b via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Every added row names a command the base parser registers, and the new test is the only thing linking the parser to the skill (no existing test in test/ does this).

Notes

  • Item 3 — undeclared: the description says "Seventeen user-facing commands had no row", but the diff also adds rows for tmp, models, acceptance-check, remote-control ×3, memory dream ×2, memory shadow report, agent validate and config pending ×3. None of these is on the base skill. They fall within the Goal ("names every user-facing CLI command") and carry no premise risk.

What this change ships

Inventory (4 items) — 3 justified

Intent: let the agent answer questions about every user-facing kirocrew command from its CLI reference skill. This is a FIX (docs drift, #29816).

  1. The skill now has a "Kiro Crew's Own Engine (KAS)" section with the seven kas commands — justified
  2. The skill gains rows for gateway-pid, open, desktop tunnel, pod restart, memory forget, knowledge stats, app import, secrets authorize and agent pin — justified
  3. The skill gains rows for tmp, models, acceptance-check, remote-control, memory dream/shadow, agent validate and config pending — undeclared
  4. A new test fails when a command with help text is missing from the skill — justified

[FIRST-PRINCIPLES-REVIEWED] 1171f28

Description read

[DESCRIPTION-READ] 0682613e5b62df3d02404618dbb769a7c3bf0a2b41e63efc2307cdcfc904503b

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 1171f2896fa2f7f3dbe958426d4d79f34502760b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 1171f28

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 1171f2896fa2f7f3dbe958426d4d79f34502760b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1171f28

…ft out

The kirocrew-commands skill is the agent's CLI reference: it loads on
help, setup and "what can you do", and the agent answers from its
tables. Seventeen user-facing commands had no row in it, so an agent
asked how to sign in without kiro-cli, restart a pod, or forget a
memory key had nothing to answer from.

Adds one row per command, worded from its argparse help: the kas
family (with a short section of its own), gateway-pid, open,
desktop tunnel, pod restart, memory forget, knowledge stats,
app import, secrets authorize and agent pin.

A new test captures the parser main() builds and fails on any
top-level command in cli_help.COMMAND_GROUPS, or any sub-command
registered with a help text, that the skill does not name. It also
checks the walk and the matcher cannot pass vacuously.

Closes kirodotdev#29816
…was cut

The coverage test fails on a merge with main because commands added
after this branch was cut have no row in the kirocrew-commands skill.
Adds one row per command, worded from its argparse help:
acceptance-check, remote-control (status, on, off), models, tmp,
agent validate, config pending (list, apply, discard), memory dream
(list, run) and memory shadow report.
@JiaDe-Wu
JiaDe-Wu force-pushed the docs/kirocrew-commands-skill-missing-commands branch from 1171f28 to 34d00e6 Compare November 19, 2026 05:39
@JiaDe-Wu

Copy link
Copy Markdown
Contributor Author

Rebased onto main (7f8f9d8), kept both sides of the kirocrew usage / gateway-pid / open conflict, and added the trace show row. test_kirocrew_commands_skill_coverage.py: 11 passed locally on the new head 34d00e6.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Nov 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(skills): kirocrew-commands skill leaves out 17 CLI commands

2 participants