kingdom-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{kingdom_cli-0.3.0 → kingdom_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kingdom-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: A markdown file-based CLI for software development with multi-agent council design, markdown tickets, and background worker loops.
 Author: James Robinson-Bohnslav
 License-Expression: Apache-2.0

{kingdom_cli-0.3.0 → kingdom_cli-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kingdom-cli"
-version = "0.3.0"
+version = "0.3.2"
 description = "A markdown file-based CLI for software development with multi-agent council design, markdown tickets, and background worker loops."
 readme = "README.md"
 requires-python = ">=3.10"

{kingdom_cli-0.3.0 → kingdom_cli-0.3.2}/src/kingdom/cli/__init__.py

@@ -124,7 +124,9 @@ def start(
             pass  # Fall back to using base as-is
         typer.echo("Auto-initializing .kd/ directory...")
         ensure_base_layout(base)
-        install_skill()
+
+    # Always refresh bundled skill (skips symlinks for dev setups)
+    install_skill()
 
     # Check for existing current run
     current_path = state_root(base) / "current"
@@ -386,6 +388,63 @@ def status(
                     typer.echo(f"  {assignee}: {t.id} [{t.status}] {t.title}")
 
 
+@app.command(help="Upgrade the CLI and refresh skill files.")
+def update() -> None:
+    """Run ``uv tool upgrade kingdom-cli`` then refresh Claude skill files."""
+    console = Console()
+
+    # Step 1: uv tool upgrade kingdom-cli
+    typer.echo("Upgrading kingdom-cli...")
+    try:
+        result = subprocess.run(
+            ["uv", "tool", "upgrade", "kingdom-cli"],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        upgrade_ok = result.returncode == 0
+        upgrade_output = result.stdout.strip() or result.stderr.strip()
+    except FileNotFoundError:
+        upgrade_ok = False
+        upgrade_output = "uv not found — install it first (https://docs.astral.sh/uv/)"
+    except subprocess.TimeoutExpired:
+        upgrade_ok = False
+        upgrade_output = "uv tool upgrade timed out"
+
+    if upgrade_ok:
+        styled_echo(f"  ✓ {upgrade_output or 'already up to date'}", fg=typer.colors.GREEN)
+    else:
+        styled_echo(f"  ✗ {upgrade_output}", fg=typer.colors.RED)
+
+    # Step 2: refresh skill files
+    typer.echo("Refreshing skill files...")
+    skill_target = Path.home() / ".claude" / "skills" / "kingdom"
+    if skill_target.is_symlink():
+        styled_echo("  ○ Skipped (dev symlink)", fg=typer.colors.YELLOW)
+        skill_status = "skipped (dev symlink)"
+    else:
+        if install_skill():
+            styled_echo("  ✓ Skill files refreshed", fg=typer.colors.GREEN)
+            skill_status = "refreshed"
+        else:
+            styled_echo("  ✗ Skill refresh failed (see warning above)", fg=typer.colors.RED)
+            skill_status = "failed"
+
+    # Summary
+    typer.echo()
+    upgrade_summary = "upgraded" if upgrade_ok else "failed"
+    console.print(
+        Panel(
+            f"CLI: {upgrade_summary}  |  Skills: {skill_status}",
+            title="[bold]kd update[/bold]",
+            border_style="green" if upgrade_ok else "yellow",
+        )
+    )
+
+    if not upgrade_ok or skill_status == "failed":
+        raise typer.Exit(code=1)
+
+
 @app.command(help="Check config and agent CLIs.")
 def doctor(
     output_json: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,

{kingdom_cli-0.3.0 → kingdom_cli-0.3.2}/src/kingdom/cli/design.py

@@ -78,6 +78,7 @@ def design_show() -> None:
 
 
 @design_app.command("approve", help="Mark the design as approved.")
+@design_app.command("accept", hidden=True)
 def design_approve() -> None:
     """Set design_approved=true in state.json."""
     base = require_project_root()

{kingdom_cli-0.3.0 → kingdom_cli-0.3.2}/src/kingdom/cli/helpers.py

@@ -116,12 +116,14 @@ def ensure_feature_branch(feature: str) -> None:
     typer.echo(f"Warning: current branch '{current}' does not match feature '{feature}'.")
 
 
-def install_skill() -> None:
+def install_skill() -> bool:
     """Install the bundled kingdom skill to ~/.claude/skills/kingdom/.
 
     Copies SKILL.md and reference files from the package into the Claude
     skills directory.  Skips if the target is a symlink (dev setup).
     Warns and continues on permission or filesystem errors.
+
+    Returns True on success (including symlink skip), False on error.
     """
     from importlib.resources import as_file, files
 
@@ -130,7 +132,7 @@ def install_skill() -> None:
 
         # Don't overwrite a dev symlink
         if target.is_symlink():
-            return
+            return True
 
         skill_pkg = files("kingdom.skill")
 
@@ -141,8 +143,11 @@ def install_skill() -> None:
         refs_target = target / "references"
         refs_target.mkdir(exist_ok=True)
         refs_pkg = skill_pkg / "references"
-        for name in ("council.md", "peasants.md", "tickets.md"):
-            with as_file(refs_pkg / name) as src:
-                (refs_target / name).write_bytes(src.read_bytes())
+        for item in refs_pkg.iterdir():
+            if item.name.endswith(".md"):
+                with as_file(item) as src:
+                    (refs_target / item.name).write_bytes(src.read_bytes())
     except (OSError, RuntimeError) as exc:
         typer.echo(f"Warning: could not install skill ({exc})")
+        return False
+    return True

{kingdom_cli-0.3.0 → kingdom_cli-0.3.2}/src/kingdom/cli/peasant.py

@@ -481,46 +481,96 @@ def peasant_status(
         console.print(f"[dim]{summary} — use --all to show[/dim]")
 
 
-@peasant_app.command("logs", help="Show peasant logs.")
-def peasant_logs(
+@peasant_app.command("show", help="Show structured peasant history.")
+def peasant_show(
     ticket_id: Annotated[str, typer.Argument(help="Ticket ID.")],
-    follow: Annotated[bool, typer.Option("--follow", "-f", help="Tail logs continuously.")] = False,
 ) -> None:
-    """Show stdout/stderr logs for a peasant."""
-    ctx = resolve_peasant_context(ticket_id)
+    """Show worklog, agent activity, and commits for a peasant."""
+    from kingdom.harness import extract_worklog
+    from kingdom.session import get_agent_state
 
+    ctx = resolve_peasant_context(ticket_id)
     session_name = peasant_session_name(ctx.full_ticket_id)
-    peasant_logs_dir = logs_root(ctx.base, ctx.feature) / session_name
-    stdout_log = peasant_logs_dir / "stdout.log"
-    stderr_log = peasant_logs_dir / "stderr.log"
-
-    if not peasant_logs_dir.exists():
-        print_error(f"No logs found for {ctx.full_ticket_id}. Has the peasant been started?")
-        raise typer.Exit(code=1)
-
-    if follow:
-        # Tail both stdout and stderr
-        with contextlib.suppress(KeyboardInterrupt):
-            files = [str(f) for f in [stdout_log, stderr_log] if f.exists()]
-            if files:
-                subprocess.run(["tail", "-f", *files])
-            else:
-                typer.echo("Log files are empty. The peasant may still be starting up.")
-        return
-
-    # Show both stdout and stderr
     console = Console()
+    state = get_agent_state(ctx.base, ctx.feature, session_name)
+
+    # --- Worklog ---
+    worklog = extract_worklog(ctx.ticket_path)
+    if worklog:
+        console.print(Markdown(f"## Worklog\n\n{worklog}"))
+    else:
+        typer.echo("(no worklog entries)")
 
-    if stdout_log.exists() and stdout_log.stat().st_size > 0:
-        content = stdout_log.read_text(encoding="utf-8")
-        console.print(Markdown(f"## stdout\n\n```\n{content}\n```"))
+    # --- Agent activity from agent-live.log ---
+    agent_live_log = logs_root(ctx.base, ctx.feature) / session_name / "agent-live.log"
+    if agent_live_log.exists() and agent_live_log.stat().st_size > 0:
+        # Resolve backend for NDJSON decoding
+        agent_backend = ""
+        try:
+            from kingdom.config import load_config
+
+            cfg = load_config(ctx.base)
+            agent_name = state.agent_backend or "claude"
+            agent_def = cfg.agents.get(agent_name)
+            if agent_def:
+                agent_backend = agent_def.backend
+        except Exception:
+            pass
+
+        raw_lines = agent_live_log.read_text(encoding="utf-8", errors="replace").splitlines()
+
+        # Reassemble NDJSON stream text (flush=True since we're reading after the fact)
+        stream_lines, _ = reassemble_stream_text(
+            "",
+            raw_lines,
+            agent_backend,
+            max_lines=500,
+            max_chars=300,
+            flush=True,
+        )
+        # Also pick up non-NDJSON readable lines
+        plain_lines = filter_agent_log_lines(raw_lines, max_lines=500, max_chars=300)
+
+        # Plain lines are non-JSON human-readable output; stream lines are
+        # reassembled NDJSON text fragments.  We concatenate them (plain first)
+        # because they come from the same log file but are extracted by
+        # different parsers — ordering within each group is chronological.
+        activity = plain_lines + stream_lines
+        if activity:
+            console.print(Markdown("## Agent Activity"))
+            for line in activity:
+                console.print(f"  {line}", markup=False)
+    else:
+        typer.echo("(no agent activity log)")
 
-    if stderr_log.exists() and stderr_log.stat().st_size > 0:
-        content = stderr_log.read_text(encoding="utf-8")
-        console.print(Markdown(f"## stderr\n\n```\n{content}\n```"))
+    # --- Commits on the peasant's branch ---
+    branch_name = f"ticket/{ctx.full_ticket_id}"
+    if state.hand_mode:
+        start_sha = state.start_sha
+        log_spec = [f"{start_sha}..HEAD"] if start_sha else ["HEAD"]
+    else:
+        # ctx.feature may be normalized (slashes→dashes); resolve the
+        # original git branch name from state.json for a valid ref.
+        from kingdom.state import read_json
 
-    if not (stdout_log.exists() or stderr_log.exists()):
-        typer.echo("Log files are empty. The peasant may still be starting up.")
+        st = read_json(branch_root(ctx.base, ctx.feature) / "state.json")
+        git_ref = st.get("branch", ctx.feature)
+        log_spec = [f"{git_ref}..{branch_name}"]
+    try:
+        result = subprocess.run(
+            ["git", "log", "--oneline", *log_spec],
+            capture_output=True,
+            text=True,
+            cwd=str(ctx.base),
+            timeout=10,
+        )
+        commits = result.stdout.strip()
+        if result.returncode == 0 and commits:
+            console.print(Markdown(f"## Commits\n\n```\n{commits}\n```"))
+        else:
+            typer.echo("(no commits)")
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        typer.echo("(could not read commits)")
 
 
 FLAG_VERBS: dict[str, str] = {
@@ -532,7 +582,7 @@ FLAG_VERBS: dict[str, str] = {
 }
 
 
-def filter_agent_log_lines(lines: list[str], max_lines: int = 3, max_chars: int = 200, backend: str = "") -> list[str]:
+def filter_agent_log_lines(lines: list[str], max_lines: int = 3, max_chars: int = 200) -> list[str]:
     """Filter raw agent log lines to human-readable non-NDJSON content.
 
     Strips ANSI escapes, skips JSON and metadata noise, and returns the last
@@ -823,8 +873,8 @@ def peasant_watch(
                 # Map status to action command and display label
                 status_actions = {
                     "needs_king_review": f"kd peasant review {ctx.full_ticket_id}",
-                    "blocked": f"kd peasant logs {ctx.full_ticket_id}",
-                    "failed": f"kd peasant logs {ctx.full_ticket_id}",
+                    "blocked": f"kd peasant show {ctx.full_ticket_id}",
+                    "failed": f"kd peasant show {ctx.full_ticket_id}",
                     "done": None,
                     "stopped": None,
                 }

{kingdom_cli-0.3.0 → kingdom_cli-0.3.2}/src/kingdom/cli/ticket.py

@@ -342,7 +342,7 @@ def render_ticket_panel(
 def ticket_create(
     title: Annotated[str, typer.Argument(help="Ticket title.")],
     description: Annotated[str | None, typer.Option("-d", "--description", help="Ticket description.")] = None,
-    priority: Annotated[int, typer.Option("-p", "--priority", help="Priority (0-3, 0 is highest).")] = 2,
+    priority: Annotated[str, typer.Option("-p", "--priority", help="Priority (0-3 or p0-p3, 0 is highest).")] = "2",
     ticket_type: Annotated[str, typer.Option("-t", "--type", help="Ticket type (task, bug, feature).")] = "task",
     backlog: Annotated[bool, typer.Option("--backlog", help="Create in backlog instead of current branch.")] = False,
     dep: Annotated[list[str] | None, typer.Option("--dep", help="Ticket ID(s) this depends on.")] = None,
@@ -355,10 +355,14 @@ def ticket_create(
 
     base = require_project_root()
 
-    # Validate priority range (0-3)
-    if priority < 0 or priority > 3:
-        sys.stderr.write(f"Warning: Priority {priority} outside valid range (0-3), clamping.\n")
-        priority = max(0, min(3, priority))
+    # Parse and validate priority (accepts 0-3, p0-p3, P0-P3)
+    from kingdom.ticket import clamp_priority
+
+    try:
+        priority_int = clamp_priority(priority)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1) from None
 
     # Ensure base layout exists
     ensure_base_layout(base)
@@ -402,7 +406,7 @@ def ticket_create(
         links=[],
         created=datetime.now(UTC),
         type=ticket_type,
-        priority=priority,
+        priority=priority_int,
         title=title,
         body=body,
         parent=resolved_parent,

kingdom_cli-0.3.2/src/kingdom/skill/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: kingdom
+description: >
+  Multi-agent design and development workflow using the kd CLI.
+  Manages design, breakdown, tickets, council consultation (multi-model
+  perspectives), and peasant workers. Use when starting a new feature
+  branch, breaking down work into tickets, consulting multiple AI models
+  for design decisions, or managing development workflow with kd commands.
+  Requires the kd CLI to be installed and on PATH.
+compatibility: Requires Python 3.10+, kd CLI (uv tool install kingdom), git
+---
+
+You assist the developer (the "King") using the `kd` CLI. There are two common workflows — pick the one that fits.
+
+All `kd` commands are safe to run. Use them proactively — don't wait to be told.
+
+## Ticket-First Reflex
+
+Every time the King says something, your first thought should be: **does this need a ticket?**
+
+Bug report, feature idea, UX complaint, missing behavior, scope change — if there's work to be done, capture it in a ticket *immediately*. Don't start exploring, don't start coding, don't ask follow-up questions about the implementation. Get the ticket created first, then proceed. The ticket is how work gets tracked, prioritized, and not forgotten.
+
+This applies even mid-conversation. If the King mentions a problem in passing while you're working on something else, create a backlog ticket on the spot (`kd tk create --backlog "..."`). If it's the main thing they're asking about, create it and start working it. Either way: ticket first, always.
+
+The only exception is when you genuinely don't have enough information to write a meaningful title and description — then ask clarifying questions, but only the minimum needed to create the ticket.
+
+## When to Reach for `kd`
+
+Recognize these cues in conversation and translate them into the right `kd` action.
+
+**King reports a bug with clear details.** Extract the actual vs expected behavior and open a ticket:
+
+```
+kd tk create -t bug -d "web app shows raw HTML, expected rendered markdown" "Markdown rendering broken in preview pane"
+```
+
+Only include flags the King actually provided — don't invent a priority or tags if they weren't mentioned.
+
+**King describes a problem vaguely.** "Hey, something's wrong with the backend" is not enough to create a ticket. Ask clarifying questions first:
+
+- What's happening? (actual behavior)
+- What should happen? (expected behavior)
+- Where? (which page, endpoint, flow)
+- Can you reproduce it?
+
+Then structure the answers into a ticket:
+
+```
+kd tk create -t bug -d "Login endpoint returns 500 when email has a plus sign. Expected: normal login. Repro: try user+test@example.com" "Login fails for plus-sign emails"
+```
+
+**King wants to track an idea for later.** Suggest a backlog ticket:
+
+```
+kd tk create --backlog "Add dark mode support"
+```
+
+**King says work is done.** Close the ticket (after verifying acceptance criteria are met and tests pass):
+
+```
+kd tk close ab12
+```
+
+**King is stuck on a design choice.** Suggest consulting the council:
+
+```
+kd council ask "Should we use WebSockets or SSE for real-time updates? We need low latency but also need to work behind corporate proxies."
+```
+
+**King says "ask the council."** Decide whether to continue an existing thread or start a new one. If the conversation is a continuation of an active design discussion, default to the current thread — just run `kd council ask "follow-up question"`. If the topic has shifted materially or the old thread is resolved, start fresh with `kd council ask --new-thread "new topic"`. When ambiguous, check existing threads with `kd council list` or `kd council show <thread>`, or ask the King a brief clarifying question before running the command.
+
+**King wants to note progress.** Log it against the active ticket:
+
+```
+kd tk log ab12 "Finished the API refactor, all endpoint tests passing"
+```
+
+**King wants parallel execution.** Start a peasant worker:
+
+```
+kd peasant start ab12
+```
+
+## Workflow A: New Feature (design-first)
+
+```
+git checkout -b <branch>
+kd start                        # init branch
+kd design show                  # view/iterate on design doc
+# iterate with council, co-author the design with the King
+kd design approve
+# create tickets from the design (via skill or manually with kd tk create)
+# execute tickets (see below)
+kd done                         # archive branch before merging PR
+```
+
+The design phase is collaborative: the King drives direction, you draft content, the council reviews. Use `kd council ask` to get multi-model feedback during design.
+
+## Workflow B: Backlog Sprint (execution-first)
+
+```
+git checkout -b <branch>
+kd start
+kd tk pull <id> <id> ...        # pull existing backlog tickets in
+# execute tickets (see below)
+kd done
+```
+
+No design phase — tickets are already scoped. If a ticket is ambiguous, escalate to the King or ask the council. Don't guess.
+
+## Executing Tickets
+
+After either workflow produces tickets, the King (or the coding agent they're working with, sometimes called the "Hand") chooses how to work through them:
+
+**Option A: Work tickets directly.** The King and their coding agent work tickets one at a time, following the Working Tickets guidelines below.
+
+**Option B: Spin up peasants.** `kd peasant start <id>` spawns a background worker in its own worktree. Each peasant works one ticket at a time — the council reviews automatically, the peasant iterates until approved. Spin up multiple peasants for parallel throughput. The King monitors with `kd peasant status` and `kd peasant watch <id>`. See [peasant reference](references/peasants.md) for details.
+
+Use A when the King wants to be hands-on. Use B for throughput on well-scoped tickets. Both can be mixed — the King might work one tricky ticket directly while peasants handle the straightforward ones.
+
+## Working Tickets
+
+This applies regardless of execution mode.
+
+- **One at a time per worker**: `kd tk start <id>` → do the work → `kd tk close <id>` → commit → next ticket.
+- **Worklog**: append progress notes to the ticket's `## Worklog` section as you go. Log what you're doing, what you found, commands and results, decisions and why. The King reads these to stay informed — don't make them ask.
+- **Acceptance criteria**: only close a ticket when all acceptance criteria are met and the full test suite is green.
+- **Decisions**: ask the King or consult the council (`kd council ask "..."`) for difficult design decisions — don't guess. Never silently resolve ambiguity on architectural, product, or UX tradeoffs.
+- **For bugs: test BEFORE you fix!** Write a test that fails in the current state, fix it, then verify.
+- **Bugs from this branch**: immediately write a failing test that reproduces it, then fix.
+- **Bugs from elsewhere**: if not blocking, create a backlog ticket (`kd tk create --backlog "..."`) and move on.
+- **Commit often**: commit code changes as you go. Commit `.kd/` changes (ticket state, worklogs) alongside code.
+- **One-off tests**: write a script or temp file to test an end-to-end flow with real data. Then consider if it can be an automated integration test.
+
+## Automatic Worklog Updates
+
+Proactively `kd tk log` whenever a durable state change occurs. The King should never have to say "update the worklog." Log against the active ticket without asking which ticket — you know what you're working on.
+
+The threshold is **durable state change**, not every chat turn. If future-you or another agent would need this fact, log it now.
+
+**Decision made** — King says "let's go with raw TypeScript over React":
+
+```
+kd tk log ab12 "Decision: raw TypeScript, not React — King's call
+
+Rationale: we want full control over the build pipeline without
+React's abstraction layer. This means we'll need to handle routing
+and state management ourselves, but the bundle size stays minimal
+and we avoid the React upgrade treadmill.
+
+Affected tickets: may need to revisit ab34 (component library choice)"
+```
+
+**Root cause discovered** — you trace a bug to an unexpected place:
+
+```
+kd tk log ab12 "Root cause: stale cache in render_template()
+
+The DB query was a red herring — render_template() caches the compiled
+template and never invalidates when the schema changes. Found by tracing
+the actual SQL output, which was correct. The fix is to add a cache key
+that includes the schema version.
+
+Affected files: src/kingdom/render.py, src/kingdom/cache.py"
+```
+
+**Scope change** — work expands or shifts mid-ticket:
+
+```
+kd tk log ab12 "Scope change: also need to update the migration script
+
+The original ticket only covered the model changes, but the migration
+script hardcodes the old column names. Without updating it, existing
+installs will break on upgrade. Adding migration updates to this ticket
+rather than splitting — it's the same logical change."
+```
+
+**Blocker cleared** — something that was stuck is now unblocked:
+
+```
+kd tk log ab12 "Unblocked: upstream API now returns correct schema
+
+Tested against staging at 14:30 — the v2 endpoint returns the
+'metadata' field we need. Removing the workaround shim and switching
+to direct parsing. This also unblocks ticket cd56 (metadata display)."
+```
+
+Rich, multi-line log entries are encouraged — a worklog entry is a place to dump everything you know in the moment, not a tweet.
+
+## Workflow Reflexes
+
+Decision patterns to get right:
+
+- **Default to the active ticket.** If you're working a ticket, that's the target for `kd tk log`, `kd tk close`, and status updates. Don't ask "which ticket?" when context is obvious.
+- **Move vs create.** "This work belongs somewhere else" → `kd tk move ab12 --to backlog`. "This is a separate problem I just noticed" → `kd tk create --backlog "..."`. Log is for new information about the current work; create/move is for separate work.
+- **Council follow-through.** After `kd council ask`, summarize the key perspectives and disagreements for the King, log the decision that came out of it (`kd tk log`), and move on. Don't dump the raw council response and wait for the King to synthesize.
+- **Close-out hygiene.** Before `kd tk close`: update the worklog with what changed and how it was verified, confirm tests pass. Closing is the last step after evidence is captured, not a declaration of intent.
+
+## When `kd` Says No
+
+When a command fails, diagnose before retrying. Never silently drop a failed operation.
+
+- **`kd tk close` fails — deps not met.** Inspect with `kd tk deps tree <id>`, figure out what's blocking, work the blocker or tell the King.
+- **No obvious active ticket.** Run `kd tk current` to check. Don't guess.
+- **`kd council ask` times out or errors.** Run `kd council retry` to re-query failed members. Don't re-run the same ask from scratch.
+- **`kd peasant start` fails — ticket is in_review or closed.** The ticket needs to be reopened or the review resolved before a peasant can work it. Check ticket status with `kd tk show <id>` and tell the King.
+- **Peasant seems stuck.** Check `kd peasant status` and `kd peasant show <id>` before escalating to the King.
+- **Council query sent — want to check on it.** Run `kd council show` to read the thread and see which members have responded. Don't re-run `kd council ask` with the same prompt.
+
+## Council
+
+- `kd council ask "prompt"` queries all members for independent perspectives.
+- Use it proactively at decision points, not just when stuck.
+- Present each member's perspective distinctly — don't flatten disagreements. Summarize the key perspectives and disagreements for the King, and preserve the tensions. Link or reference the thread for full detail.
+- See [council reference](references/council.md) for threading, async flags, and session management.
+
+## Command Quick-Ref
+
+```bash
+kd start / status / done                                # branch lifecycle
+kd design show / design approve                         # design doc
+kd tk list / show / list --ready                        # inspect tickets
+kd tk start <id> / close <id>                           # work a ticket
+kd tk current                                           # show active ticket
+kd tk pull <id>...                                      # pull from backlog
+kd tk log <id> "message"                                # append to worklog
+kd tk deps add/remove/tree/cycle                        # manage dependencies
+kd peasant status / watch <id>                          # monitor peasants
+kd peasant review / accept / reject                     # review cycle
+kd peasant msg / read                                   # communicate with peasants
+
+# ticket creation — use only the flags the King provides
+kd tk create "title"                                    # minimal
+kd tk create -t bug -d "details" "title"                # bug with description
+kd tk create -t bug -p 2 -d "details" "title"           # with priority (only if King specified it)
+kd tk create --backlog "title"                           # backlog ticket
+kd tk create --backlog --ac "criterion" "title"          # backlog with acceptance criteria
+
+# council — threading and targeting
+kd council ask "prompt"                                  # all members, current thread
+kd council ask --to claude "prompt"                      # single member
+kd council ask --new-thread "prompt"                     # start fresh thread
+kd council list / show <thread>                          # inspect threads
+kd council retry                                         # re-query failed members
+
+# peasants — launch modes
+kd peasant start <id>                                    # worktree (parallel)
+kd peasant start <id> --hand                             # serial in cwd
+```
+
+Run `kd <command> --help` for flags and options not listed here.
+
+## References
+
+- [Council patterns and usage](references/council.md)
+- [Ticket lifecycle and management](references/tickets.md)
+- [Peasant workers and worktrees](references/peasants.md)

{kingdom_cli-0.3.0 → kingdom_cli-0.3.2}/src/kingdom/skill/references/council.md

@@ -48,9 +48,7 @@ kd council watch <thread-id>      # watch for incoming responses
 
 ## Reading Responses
 
-**Do not synthesize or summarize council responses for the King.** Point them to the thread and let them read directly. The council provides perspectives — the King decides.
-
-If the King asks for a summary, you can highlight key points of agreement and disagreement, but always reference the original responses.
+Summarize council responses for the King when they inform the active decision. Present the main agreements, disagreements, and any recommendation, then point to the thread for full context. Preserve the tensions — don't flatten dissent into false consensus.
 
 ## Async and Streaming
 

{kingdom_cli-0.3.0 → kingdom_cli-0.3.2}/src/kingdom/skill/references/peasants.md

@@ -19,7 +19,8 @@ kd peasant start <ticket-id> --agent codex
 
 ```bash
 kd peasant status            # show all active peasants
-kd peasant logs <id>         # view peasant output
+kd peasant watch <id>        # live-follow a peasant's progress
+kd peasant show <id>         # view structured peasant history
 kd peasant stop <id>         # stop a running peasant
 ```
 
@@ -44,6 +45,12 @@ kd peasant clean <id>        # remove worktree when done
 - **Hand mode** for sequential work that needs the full repo context
 - **Multiple peasants** can run simultaneously on different tickets in worktree mode
 
-## Autonomous Work
+## Reviewing Peasant Work
 
-The worker agent loop is invoked internally by `kd peasant start` via `python -m kingdom.worker`.
+When a peasant finishes its ticket, review and accept or reject:
+
+```bash
+kd peasant review <id>       # review completed work (shows diff + worklog)
+kd peasant accept <id>       # accept work and close the ticket
+kd peasant reject <id>       # reject with feedback — peasant iterates
+```