Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions src/kiro_crew/builtin_skills/kirocrew-commands/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,20 @@ derivatives) and are no-ops everywhere else; `--path` is refused for
world-writable locations and for shared interpreters such as `/usr/bin/python3`,
which would over-grant.

## Kiro Crew's Own Engine (KAS)

Signs in and runs without kiro-cli: `kas` installs Kiro Crew's own engine bundle and holds its own Kiro identity in the vault.

| Command | Description |
|---------|-------------|
| `kirocrew kas install` | Download this release's pinned KAS engine and Node runtime (`--force` replaces an installed copy; `--from DIR` installs offline; `--version`/`--url` need `--unpinned` to leave the pin) |
| `kirocrew kas status` | Show the pinned engine, what is installed, and the route |
| `kirocrew kas remove` | Delete installed engine versions (`--version V` for one, `--yes` skips the confirmation) |
| `kirocrew kas login` | Sign the vault in with a device code, no browser needed on this host (`--provider builder_id\|idc\|google\|github`, default `builder_id`; `idc` needs `--start-url`, and takes `--region`) |
| `kirocrew kas whoami` | Show which Kiro identity the vault is signed in as (`--format text\|json`) |
| `kirocrew kas logout` | Remove every Kiro identity from the vault |
| `kirocrew kas route` | Print which program owns the Kiro sign-in here: `kas-bundle` or `kiro-cli` |

## Gateway (Server)

| Command | Description |
Expand All @@ -56,6 +70,9 @@ which would over-grant.
| `kirocrew restart` | Restart gateway (service-aware) |
| `kirocrew status` | Show runtime stats (uptime, sessions, crons, lessons) |
| `kirocrew usage` | Recent credit spend per day; `--by model\|agent\|channel\|session`, `--days N` / `--since YYYY-MM-DD`, `--json` |
| `kirocrew trace show KEY` | Print one traced turn as a waterfall of its model calls, tool calls and sub-agents, read from the local span files (written while `telemetry.traces_enabled` is on); `KEY` is a turn id, session key or id, ACP session id or trace id |
| `kirocrew gateway-pid` | Print the PID holding this home's gateway lock (JSON) |
| `kirocrew open SESSION` | Open the desktop app on a session through a `kirocrew://` deep link (`SESSION` is the `?sid=` value in the dashboard URL); `--print` shows the URL and opens nothing |

The token in a `--json-ready` line grants dashboard access for up to 20 hours, so
captured stdout from a test harness is a credential: keep it out of logs and
Expand All @@ -71,6 +88,7 @@ transcripts.
| `kirocrew logs` | Show gateway logs (last 100 lines) |
| `kirocrew logs -f` | Follow (tail) live log output |
| `kirocrew logs -n 50` | Show last N lines |
| `kirocrew tmp` | Remove your idle, unused leftovers from /tmp and /var/tmp |

## Pods (Isolated Worktree Test Instances)

Expand All @@ -93,6 +111,7 @@ Scheduler. `<wt>` is a worktree name
| `kirocrew pod url <wt>` | Print the pod's base URL |
| `kirocrew pod logs <wt> -n N` | Tail the pod's journal |
| `kirocrew pod down <wt>` | Evict the pod and delete its isolated HOME |
| `kirocrew pod restart <wt>` | Restart a pod in place, keeping its home; `--memory` and `--cpu` apply new ceilings (`--json`, `--wait-secs`) |
| `kirocrew pod prune` | Bulk-reclaim orphaned pod HOMEs (`--older-than 3d` by default, `--all`, `--dry-run`, `--json`) |
| `kirocrew pod scenarios` | List the seed scenarios `pod up --seed <scenario>` accepts (`--json`) |
| `kirocrew pod exec <wt> -- <args>` | Run a kirocrew command against a pod, using the pod's own binary and data |
Expand All @@ -117,8 +136,12 @@ Override with `PORT=` in `~/.kiro/crew/pods/<name>.env`.
| `kirocrew token` | Print a dashboard URL with auth token (TTL: 20h) |
| `kirocrew token --ttl 1h` | Token with custom TTL (e.g. 1h, 30m) |
| `kirocrew logout` | Revoke all active dashboard sessions |
| `kirocrew desktop tunnel --host HOST` | Keep the desktop app's SSH forward to a remote crew alive (client-only mode); `--local-port` is the loopback port the app connects to, `--remote-port` the one the crew listens on over there |
| `kirocrew manifest` | Generate Slack app manifest with your alias |
| `kirocrew manifest --url` | Print one-click Slack app creation URL |
| `kirocrew remote-control status` | Show whether personal Remote Control is on (`--json`) |
| `kirocrew remote-control on` | Turn personal Remote Control on; it connects after Kiro Crew restarts |
| `kirocrew remote-control off` | Turn personal Remote Control off; it stays off across restarts |

## Chat

Expand Down Expand Up @@ -239,7 +262,12 @@ leftover prefix without touching it.
| `kirocrew memory restore [--store <name>] [--from FILE \| --cancel-pending]` | Restore a store from a backup (default: its newest) |
| `kirocrew memory carve --store <name>` | Filter or count a crew store's memory by carve facets (`--scope`, `--surface`, `--crew`, `--session-key`) |
| `kirocrew memory retired [--restore ID]` | List episodes a semantic write superseded, and restore one |
| `kirocrew memory forget KEY` | Delete one semantic memory key after you confirm it (owner only; needs a terminal and the running gateway; not on native Windows). `--superseded-by KEY` records the live key that replaces it |
| `kirocrew memory show [preferences\|projects\|history]` | Show the markdown memory layer (default: all three; `--format md\|json`, `--since YYYY-MM-DD` for history) |
| `kirocrew memory dream list` | Print the Dreaming approval list of what a run proposed, read-only (`--store`, `--json`) |
| `kirocrew memory dream run` | Ask the gateway for a Dreaming run now; it still waits for idle |
| `kirocrew memory shadow report` | Per shadow memory stage, show its flag, window, days, sessions and would-change rate, read-only (`--stage`, `--since YYYY-MM-DD` or `<n>d`, `--store`, `--json`) |
| `kirocrew knowledge stats` | Count sources, documents and items in the knowledge library (read-only; `--json` for JSON) |
| `kirocrew knowledge dedup` | Preview cross-source duplicate knowledge documents (dry-run) |
| `kirocrew knowledge dedup --apply` | Actually collapse the duplicates |
| `kirocrew consolidate` | List sessions with unconsolidated messages |
Expand Down Expand Up @@ -276,6 +304,9 @@ LLM-generated UI components (widgets, HTML, markdown, SVG, JSON, text).
| `kirocrew agent update NAME --display-name "Label"` | Change the name the dashboard shows (`""` clears it); the agent name stays |
| `kirocrew agent delete NAME` | Delete an agent |
| `kirocrew agent reset-model [--agent kirocrew]` | Clear a pinned model so the agent tracks the shipped default |
| `kirocrew agent pin [NAME FILE]` | Choose which spec file an agent name runs when several declare it (`agent.spec_pins`); with no arguments, list the pins. `--clear` removes the pin for `NAME` |
| `kirocrew agent validate [PATH]` | Check agent specs offline for unknown fields, wrong value shapes and malformed tools entries; exits 1 on a problem (`--allow-unknown-fields`, `--print-schema`) |
| `kirocrew models [NAME]` | List the model names `--model` accepts, or check one name (`--json`, `--port`) |
| `kirocrew workspace list` | List workspaces |
| `kirocrew workspace create --name NAME --dir DIRNAME` | Create workspace (`--dir` is a **name under the data home**, not an absolute path) |
| `kirocrew workspace create --name NAME --copy-from existing` | Copy from existing |
Expand Down Expand Up @@ -309,6 +340,7 @@ keystone paths are still refused). The CLI is the stricter of the two.
| `kirocrew app info NAME` | Show app details |
| `kirocrew app init NAME` | Scaffold a new app (kebab-case name) |
| `kirocrew app init NAME --backend --ui --cron` | Scaffold with backend, UI, and sample cron |
| `kirocrew app import SOURCE` | Convert a manifest-declared plugin package into an app directory (`--out DIR`, `--name NAME` to override the derived name, `--install` to install it after writing) |
| `kirocrew app dev NAME` | Toggle an app into dev mode (no-store UI serving + live reload on file change) |
| `kirocrew app dev NAME --off` | Leave dev mode |
| `kirocrew app mcp NAME` | Run an app's MCP server on stdio (spawned by kiro-cli, not for humans) |
Expand All @@ -321,6 +353,9 @@ keystone paths are still refused). The CLI is the stricter of the two.
| `kirocrew config get agent.provider` | Get specific value (dot-separated key) |
| `kirocrew config set dashboard.url http://localhost:5476` | Set a config value (port is the KIROCREW_PORT env var, not a config key) |
| `kirocrew config set --file config.json` | Load full config from JSON file |
| `kirocrew config pending list` | Show each settings file changed outside Kiro Crew and held for review, and what changed (the default of `kirocrew config pending`; needs no dashboard) |
| `kirocrew config pending apply FILE SIGNATURE` | Keep the outside change (`FILE` is the file name, e.g. `config.json`; `SIGNATURE` the version `kirocrew config pending` printed) |
| `kirocrew config pending discard FILE SIGNATURE` | Put the saved version back |
| `kirocrew config edit` | Open config in $EDITOR |
| `kirocrew config defaults [KEYS…]` | Review stored values that still hold a superseded default |
| `kirocrew config defaults [KEYS…] --adopt` | Remove those stored keys so the current defaults apply |
Expand Down Expand Up @@ -354,6 +389,8 @@ already-running app record -- restart it.
|---------|-------------|
| `kirocrew secrets import` | Dry-run the migration of plaintext `.env` credentials into the encrypted vault |
| `kirocrew secrets import --apply` | Store the secrets and rewrite `.env` to `secret://` refs |
| `kirocrew secrets authorize NAME https://api.example.com` | Authorize a Custom secret for one exact https origin, so agent write requests may carry it (`--header` sets the header, default `Authorization: Bearer`) |
| `kirocrew secrets authorize NAME --remove` | Remove that authorization. `--reset` discards a policy that does not parse or verify; without it, `authorize` refuses rather than erase entries |
| `kirocrew telemetry status` | Show exactly what the anonymous beacon sends, and whether it will |
| `kirocrew telemetry disable` | Turn the anonymous beacon off permanently |
| `kirocrew telemetry enable` | Turn the anonymous beacon back on |
Expand All @@ -373,6 +410,7 @@ already-running app record -- restart it.
| `kirocrew bench lesson-recall` | Measure lesson ranking recall/MRR/nDCG against a golden set (deterministic) |
| `kirocrew bench session-recall` | Measure session search recall/MRR against a golden set (deterministic) |
| `kirocrew bench compare A B` | Diff two saved JSON reports; refuses to attribute a delta when the runs disagree on corpus |
| `kirocrew acceptance-check --json CHECK REF` | Answer a goal acceptance check that an installed edition provides; prints the report as one JSON object (`CHECK` names the edition's check, `REF` the item it is about) |

## Governance Policy

Expand Down
153 changes: 153 additions & 0 deletions test/test_kirocrew_commands_skill_coverage.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
"""Guard: the ``kirocrew-commands`` skill names every user-facing CLI command.

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, so a command the skill never names is a
command the agent cannot tell a user about. Seventeen commands drifted out this
way (the ``kas`` family, ``gateway-pid``, ``open``, ``desktop tunnel``, ``pod
restart``, ``memory forget``, ``knowledge stats``, ``app import``, ``secrets
authorize`` ...) because nothing connected the parser to the document.

"User-facing" has the same meaning the top-level help gives it: a top-level command
listed in ``cli_help.COMMAND_GROUPS``, or a sub-command registered with a help text.
Internal commands (the ``mcp-*`` servers the agent backend spawns) register with no
help and stay out, exactly as they stay out of ``kirocrew --help``.

The parser is captured from ``kiro_crew.cli.main()`` itself rather than rebuilt, so
the test walks what a user can actually run.
"""

from __future__ import annotations

import argparse
import re
import sys
from pathlib import Path

import pytest

import kiro_crew
from kiro_crew import cli_help

SKILL = (
Path(kiro_crew.__file__).resolve().parent / "builtin_skills" / "kirocrew-commands" / "SKILL.md"
)


def _capture_parser(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> argparse.ArgumentParser:
"""Return the top-level parser ``main()`` builds, without running a command.

``main()`` builds the parser inline and then calls ``parse_args`` on it, so the
call is intercepted and ended before anything dispatches. ``monkeypatch`` undoes
the patch, and the environment writes ``main()`` makes, when the test ends.
"""
captured: list[argparse.ArgumentParser] = []

def _grab(self: argparse.ArgumentParser, *args: object, **kwargs: object) -> None:
captured.append(self)
raise SystemExit(0)

# ``main()`` pops these before it parses; registering them first makes
# monkeypatch restore whatever the host had.
monkeypatch.setenv("KIROCREW_SANDBOX_ACTIVE", "0")
monkeypatch.setenv("KIROCREW_SANDBOX_LEVEL", "0")
# Pinned so ``main()``'s project auto-detection does not walk (and then export)
# the checkout this runs in.
monkeypatch.setenv("KIROCREW_PROJECT_DIR", str(tmp_path))
monkeypatch.setattr(sys, "argv", ["kirocrew"])
monkeypatch.setattr(argparse.ArgumentParser, "parse_args", _grab)

from kiro_crew.cli import main

with pytest.raises(SystemExit):
main()
assert captured, "main() never reached parse_args, so there is no parser to walk"
return captured[0]


def _user_facing_subcommands(
parser: argparse.ArgumentParser, prefix: tuple[str, ...] = ()
) -> set[tuple[str, ...]]:
"""Every sub-command below ``parser`` that was registered with a help text."""
found: set[tuple[str, ...]] = set()
for action in parser._actions:
if not isinstance(action, argparse._SubParsersAction):
continue
helped = {
choice.dest
for choice in action._choices_actions
if choice.help not in (None, argparse.SUPPRESS)
}
for name, sub in action.choices.items():
if name in helped:
found.add((*prefix, name))
found |= _user_facing_subcommands(sub, (*prefix, name))
return found


def _is_named(command: str, skill_text: str) -> bool:
"""Whether the skill shows ``kirocrew <command>`` in a code span.

A leading ``VAR=value`` is allowed because debug-only rows are written
``KIROCREW_DEBUG=1 kirocrew perf sample``. The trailing lookahead stops
``kirocrew kas`` from being satisfied by ``kirocrew kas-bundle`` or ``kirocrew kasten``.
"""
pattern = r"`(?:[A-Z_][A-Z0-9_]*=\S+ )*kirocrew " + re.escape(command) + r"(?![\w-])"
return re.search(pattern, skill_text) is not None


@pytest.fixture(scope="module")
def skill_text() -> str:
return SKILL.read_text(encoding="utf-8")


class TestEveryUserFacingCommandIsNamed:
def test_top_level_commands(self, skill_text: str) -> None:
missing = sorted(name for name in cli_help.SUMMARIES if not _is_named(name, skill_text))
assert not missing, (
f"{SKILL.relative_to(SKILL.parents[3])} never names these top-level commands: "
f"{missing}. Add one row per command, worded from its help text in "
"cli_help.COMMAND_GROUPS."
)

def test_sub_commands(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path, skill_text: str
) -> None:
commands = _user_facing_subcommands(_capture_parser(monkeypatch, tmp_path))
missing = sorted(
" ".join(path) for path in commands if not _is_named(" ".join(path), skill_text)
)
assert not missing, (
f"{SKILL.relative_to(SKILL.parents[3])} never names these sub-commands: {missing}. "
"Add one row per command, worded from its argparse help."
)


class TestTheCoverageCheckCannotPassVacuously:
"""The guard above is only worth having if it can fail."""

def test_the_walk_finds_known_nested_commands(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
commands = _user_facing_subcommands(_capture_parser(monkeypatch, tmp_path))
assert {("pod", "restart"), ("kas", "login"), ("secrets", "authorize")} <= commands

def test_the_walk_leaves_internal_commands_out(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
commands = _user_facing_subcommands(_capture_parser(monkeypatch, tmp_path))
assert not [path for path in commands if path[0].startswith("mcp-")]

@pytest.mark.parametrize(
("text", "command", "expected"),
[
("| `kirocrew kas login` | x |", "kas login", True),
("| `kirocrew kas login --provider idc` | x |", "kas login", True),
("| `KIROCREW_DEBUG=1 kirocrew perf sample` | x |", "perf sample", True),
("| `kirocrew kas-bundle` | x |", "kas", False),
("| `kirocrew kasten` | x |", "kas", False),
("| `kirocrew kas login` | x |", "kas logout", False),
("kirocrew kas login, outside a code span", "kas login", False),
],
)
def test_the_matcher(self, text: str, command: str, expected: bool) -> None:
assert _is_named(command, text) is expected
Loading