kingdom-cli 0.1.4__tar.gz → 0.2.1__tar.gz

{kingdom_cli-0.1.4/src/kingdom_cli.egg-info → kingdom_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kingdom-cli
-Version: 0.1.4
+Version: 0.2.1
 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
@@ -48,49 +48,71 @@ Gastown minus the polecats.
 uv tool install kingdom-cli
 ```
 
-## Getting Started
+## Workflow Scales
+
+`kd` scales down gracefully. You pick the parts of the workflow that fit the size of the work.
+
+### Full workflow (new features)
 
-1. Initialize the project on your current branch:
+Design with the council, break into tickets, dispatch peasants, review, and merge.
 
 ```bash
-kd start
+kd start                   # initialize branch session
+kd chat --new              # discuss design with the council TUI
+kd design approve          # lock in the design
+kd breakdown               # generate tickets from the design
+kd peasant start <id>      # dispatch parallel workers
+kd done                    # archive and clean up
 ```
 
-2. Configure council agent CLIs in `.kd/config.json` (check effective config with `kd config show`).
+### Medium workflow (refactors, smaller features)
 
-3. Design with the council in the TUI:
+Pull tickets into a branch, work them directly or with peasants. No design phase needed.
 
 ```bash
-kd chat --new
+kd start
+kd tk pull <id> <id>       # pull backlog tickets onto this branch
+kd tk start <id>           # work tickets one at a time
+kd tk close <id>
+kd done
 ```
 
-4. Break your design into markdown tickets:
+### Lightweight workflow (bug fixes)
+
+Work a single ticket, close it, make a PR. Or batch several bug-fix tickets on one branch.
 
 ```bash
-kd breakdown
+kd start
+kd tk create "fix: login redirect loop"
+kd tk start <id>
+# ... fix the bug ...
+kd tk close <id>
+kd done
 ```
 
-5. Review and refine tickets:
+Design docs, council sessions, and peasant workers are all optional. A branch with one ticket and no design doc is a perfectly valid `kd` workflow.
+
+## Getting Started
 
 ```bash
-kd ticket list
-kd ticket show <id>
+kd init                    # one-time: create .kd/ directory
+kd start                   # start a session on the current branch
 ```
 
-6. Execute tickets:
-- Serial: tell Claude Code or Codex to work tickets directly, or run `kd work <id>`.
-- Parallel: dispatch peasants in worktrees.
+Configure council agent CLIs in `.kd/config.json` (check effective config with `kd config show`).
 
-```bash
-kd peasant start <id>
-kd peasant status
-```
+## Chat Modes
 
-7. Close out the session:
+The council chat TUI (`kd chat`) supports four modes, configured via `council.chat.mode`:
 
-```bash
-kd done
-```
+| Mode | First turn | Auto-turns | Default |
+|------|-----------|------------|---------|
+| `natural` | parallel broadcast | shuffled round-robin | yes |
+| `round_robin` | sequential fixed-order | sequential fixed-order | |
+| `manual` | only @mentioned | only @mentioned | |
+| `broadcast` | parallel to all | parallel to all | |
+
+LLM-to-LLM @mentions in responses automatically bump the mentioned member to the front of the auto-turn queue.
 
 ## How It Works
 

{kingdom_cli-0.1.4 → kingdom_cli-0.2.1}/README.md

@@ -21,49 +21,71 @@ Gastown minus the polecats.
 uv tool install kingdom-cli
 ```
 
-## Getting Started
+## Workflow Scales
+
+`kd` scales down gracefully. You pick the parts of the workflow that fit the size of the work.
+
+### Full workflow (new features)
 
-1. Initialize the project on your current branch:
+Design with the council, break into tickets, dispatch peasants, review, and merge.
 
 ```bash
-kd start
+kd start                   # initialize branch session
+kd chat --new              # discuss design with the council TUI
+kd design approve          # lock in the design
+kd breakdown               # generate tickets from the design
+kd peasant start <id>      # dispatch parallel workers
+kd done                    # archive and clean up
 ```
 
-2. Configure council agent CLIs in `.kd/config.json` (check effective config with `kd config show`).
+### Medium workflow (refactors, smaller features)
 
-3. Design with the council in the TUI:
+Pull tickets into a branch, work them directly or with peasants. No design phase needed.
 
 ```bash
-kd chat --new
+kd start
+kd tk pull <id> <id>       # pull backlog tickets onto this branch
+kd tk start <id>           # work tickets one at a time
+kd tk close <id>
+kd done
 ```
 
-4. Break your design into markdown tickets:
+### Lightweight workflow (bug fixes)
+
+Work a single ticket, close it, make a PR. Or batch several bug-fix tickets on one branch.
 
 ```bash
-kd breakdown
+kd start
+kd tk create "fix: login redirect loop"
+kd tk start <id>
+# ... fix the bug ...
+kd tk close <id>
+kd done
 ```
 
-5. Review and refine tickets:
+Design docs, council sessions, and peasant workers are all optional. A branch with one ticket and no design doc is a perfectly valid `kd` workflow.
+
+## Getting Started
 
 ```bash
-kd ticket list
-kd ticket show <id>
+kd init                    # one-time: create .kd/ directory
+kd start                   # start a session on the current branch
 ```
 
-6. Execute tickets:
-- Serial: tell Claude Code or Codex to work tickets directly, or run `kd work <id>`.
-- Parallel: dispatch peasants in worktrees.
+Configure council agent CLIs in `.kd/config.json` (check effective config with `kd config show`).
 
-```bash
-kd peasant start <id>
-kd peasant status
-```
+## Chat Modes
 
-7. Close out the session:
+The council chat TUI (`kd chat`) supports four modes, configured via `council.chat.mode`:
 
-```bash
-kd done
-```
+| Mode | First turn | Auto-turns | Default |
+|------|-----------|------------|---------|
+| `natural` | parallel broadcast | shuffled round-robin | yes |
+| `round_robin` | sequential fixed-order | sequential fixed-order | |
+| `manual` | only @mentioned | only @mentioned | |
+| `broadcast` | parallel to all | parallel to all | |
+
+LLM-to-LLM @mentions in responses automatically bump the mentioned member to the front of the auto-turn queue.
 
 ## How It Works
 

{kingdom_cli-0.1.4 → kingdom_cli-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kingdom-cli"
-version = "0.1.4"
+version = "0.2.1"
 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"
@@ -40,6 +40,10 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+"kingdom.skill" = ["*.md", "references/*.md"]
+"kingdom.tui" = ["*.tcss"]
+
 [dependency-groups]
 dev = [
     "pre-commit>=4.0.0",

{kingdom_cli-0.1.4 → kingdom_cli-0.2.1}/src/kingdom/agent.py

@@ -11,8 +11,8 @@ from __future__ import annotations
 import json
 import logging
 import shlex
+from collections.abc import Callable
 from dataclasses import dataclass, field
-from typing import Any
 
 from kingdom.config import AgentDef
 
@@ -301,7 +301,9 @@ def parse_cursor_response(stdout: str, stderr: str, code: int) -> tuple[str, str
     return "", session_id, raw
 
 
-RESPONSE_PARSERS: dict[str, Any] = {
+ResponseParser = Callable[[str, str, int], tuple[str, str | None, str]]
+
+RESPONSE_PARSERS: dict[str, ResponseParser] = {
     "claude_code": parse_claude_response,
     "codex": parse_codex_response,
     "cursor": parse_cursor_response,
@@ -424,7 +426,9 @@ def build_cursor_command(
     return cmd
 
 
-COMMAND_BUILDERS: dict[str, Any] = {
+CommandBuilder = Callable[[AgentConfig, str, str | None, bool, bool], list[str]]
+
+COMMAND_BUILDERS: dict[str, CommandBuilder] = {
     "claude_code": build_claude_command,
     "codex": build_codex_command,
     "cursor": build_cursor_command,
@@ -561,7 +565,9 @@ def extract_cursor_stream_text(line: str) -> str | None:
     return None
 
 
-STREAM_TEXT_EXTRACTORS: dict[str, Any] = {
+StreamExtractor = Callable[[str], str | None]
+
+STREAM_TEXT_EXTRACTORS: dict[str, StreamExtractor] = {
     "claude_code": extract_claude_stream_text,
     "codex": extract_codex_stream_text,
     "cursor": extract_cursor_stream_text,
@@ -624,7 +630,7 @@ def extract_codex_stream_thinking(line: str) -> str | None:
     return None
 
 
-STREAM_THINKING_EXTRACTORS: dict[str, Any] = {
+STREAM_THINKING_EXTRACTORS: dict[str, StreamExtractor] = {
     "codex": extract_codex_stream_thinking,
     "cursor": extract_cursor_stream_thinking,
 }
@@ -640,3 +646,84 @@ def extract_stream_thinking(line: str, backend: str) -> str | None:
     if extractor is None:
         return None
     return extractor(line)
+
+
+# ---------------------------------------------------------------------------
+# Stream tool-use extractors — extract tool invocation names from NDJSON
+# ---------------------------------------------------------------------------
+
+
+def extract_claude_stream_tool_use(line: str) -> str | None:
+    """Extract tool name from a Claude Code stream-json NDJSON line.
+
+    Claude Code emits ``content_block_start`` with a ``tool_use`` block
+    containing the tool name (e.g. "Read", "Bash", "Write").
+    """
+    try:
+        event = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(event, dict):
+        return None
+    if event.get("type") == "stream_event":
+        event = event.get("event", {})
+    if event.get("type") == "content_block_start":
+        block = event.get("content_block", {})
+        if block.get("type") == "tool_use":
+            return block.get("name")
+    return None
+
+
+def extract_cursor_stream_tool_use(line: str) -> str | None:
+    """Extract tool name from a Cursor stream-json NDJSON line.
+
+    Cursor emits ``{"type": "tool_call", "subtype": "started", ...}``
+    when a tool invocation begins.  The ``name`` field may or may not
+    be present depending on the Cursor version.
+    """
+    try:
+        event = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(event, dict):
+        return None
+    if event.get("type") == "tool_call" and event.get("subtype") == "started":
+        return event.get("name") or "tool"
+    return None
+
+
+def extract_codex_stream_tool_use(line: str) -> str | None:
+    """Extract tool name from a Codex NDJSON line.
+
+    Codex emits ``item.completed`` events for tool calls with
+    ``item.type == "function_call"``.
+    """
+    try:
+        event = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(event, dict):
+        return None
+    if event.get("type") == "item.completed":
+        item = event.get("item", {})
+        if item.get("type") == "function_call":
+            return item.get("name", "tool")
+    return None
+
+
+STREAM_TOOL_USE_EXTRACTORS: dict[str, StreamExtractor] = {
+    "claude_code": extract_claude_stream_tool_use,
+    "codex": extract_codex_stream_tool_use,
+    "cursor": extract_cursor_stream_tool_use,
+}
+
+
+def extract_stream_tool_use(line: str, backend: str) -> str | None:
+    """Extract tool name from a single NDJSON line for the given backend.
+
+    Returns the tool name string, or None for non-tool-use events.
+    """
+    extractor = STREAM_TOOL_USE_EXTRACTORS.get(backend)
+    if extractor is None:
+        return None
+    return extractor(line)

{kingdom_cli-0.1.4 → kingdom_cli-0.2.1}/src/kingdom/breakdown.py

@@ -7,7 +7,6 @@ from pathlib import Path
 
 
 def build_breakdown_template(feature: str) -> str:
-    """Return a minimal `breakdown.md` template for a feature."""
     return (
         f"# Breakdown: {feature}\n\n"
         "## Design Summary\n"
@@ -27,7 +26,6 @@ def build_breakdown_template(feature: str) -> str:
 
 
 def read_breakdown(breakdown_path: Path) -> str:
-    """Read the breakdown file text (empty string if missing)."""
     if not breakdown_path.exists():
         return ""
     return breakdown_path.read_text(encoding="utf-8")