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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kingdom-cli
-Version: 0.2
+Version: 0.3.0
 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,72 @@ 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 council chat --new      # discuss design with the council TUI
+kd design approve          # lock in the design
+# create tickets from the design (via the kingdom skill or manually)
+kd peasant start <id>      # dispatch parallel workers
+kd peasant review <id>     # review completed work
+kd peasant accept <id>     # accept and close, or reject with feedback
+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 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 council 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
 
@@ -114,6 +137,20 @@ All state lives in `.kd/` as plain Markdown and JSON files, tracked in git along
 
 No database. No server. Just files on disk.
 
+## Commands
+
+| Group | Description |
+|-------|-------------|
+| `kd start` / `kd done` / `kd status` | Branch lifecycle — initialize, finish, and inspect sessions |
+| `kd design` | Manage design documents (`show`, `approve`) |
+| `kd council` | Multi-model council — `ask`, `chat`, `review`, `show`, `list`, `watch`, `reset`, `retry` |
+| `kd ticket` (alias `kd tk`) | Ticket management — `create`, `list`, `show`, `start`, `close`, `deps`, and more |
+| `kd peasant` | Worker agents — `start`, `stop`, `review`, `accept`, `reject`, `msg`, `read`, `watch` |
+| `kd config` | View and manage configuration |
+| `kd doctor` | Check config and agent CLIs |
+
+Run `kd <command> --help` for full flags and options.
+
 ## Development
 
 ```bash

kingdom_cli-0.3.0/README.md

@@ -0,0 +1,137 @@
+# Kingdom
+
+Kingdom (`kd`) is a markdown file-based CLI for software development: design with a multi-agent council, track work as markdown tickets, and run background RALPH loops with worker peasants.
+
+The kingdom metaphor is intentional: you are the King, debate your design documents with a council of frontier coding agent CLIs you already use (Claude Code and Codex), break the design into modular markdown tickets, and then peasants execute those tickets in parallel worktrees.
+
+Gastown minus the polecats.
+
+## Why
+
+- **Multi-agent council** — get perspectives from multiple frontier coding models, not just one opinion. Different models catch different things.
+- **Ticket-based execution** — breaking work into scoped tickets fights context rot, lets you use cheaper models for already-designed work, or run tickets in parallel.
+- **Multi-agent reviews** — reviews across models consistently catch bugs that single-agent reviews miss.
+- **Plain markdown files** — tickets, designs, and council threads are all markdown. Your coding agents are already good at finding, reading, and updating markdown.
+- **CLI + TUI** — the TUI is for humans; agent CLIs use `kd` directly to ask the council or other agents for opinions.
+- **Worklog audit trail** — peasant worklogs capture decisions, bugs encountered, and test results in the ticket markdown, committed to git. You can always see *why* something was done, not just the diff.
+
+## Install
+
+```bash
+uv tool install kingdom-cli
+```
+
+## Workflow Scales
+
+`kd` scales down gracefully. You pick the parts of the workflow that fit the size of the work.
+
+### Full workflow (new features)
+
+Design with the council, break into tickets, dispatch peasants, review, and merge.
+
+```bash
+kd start                   # initialize branch session
+kd council chat --new      # discuss design with the council TUI
+kd design approve          # lock in the design
+# create tickets from the design (via the kingdom skill or manually)
+kd peasant start <id>      # dispatch parallel workers
+kd peasant review <id>     # review completed work
+kd peasant accept <id>     # accept and close, or reject with feedback
+kd done                    # archive and clean up
+```
+
+### Medium workflow (refactors, smaller features)
+
+Pull tickets into a branch, work them directly or with peasants. No design phase needed.
+
+```bash
+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
+```
+
+### Lightweight workflow (bug fixes)
+
+Work a single ticket, close it, make a PR. Or batch several bug-fix tickets on one branch.
+
+```bash
+kd start
+kd tk create "fix: login redirect loop"
+kd tk start <id>
+# ... fix the bug ...
+kd tk close <id>
+kd done
+```
+
+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 start                   # start a session on the current branch
+```
+
+Configure council agent CLIs in `.kd/config.json` (check effective config with `kd config show`).
+
+## Chat Modes
+
+The council chat TUI (`kd council chat`) supports four modes, configured via `council.chat.mode`:
+
+| 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
+
+All state lives in `.kd/` as plain Markdown and JSON files, tracked in git alongside your code:
+
+```
+.kd/
+├── branches/                    # Active branch work
+│   └── feature-oauth-refresh/
+│       ├── design.md            # Design document
+│       ├── breakdown.md         # Ticket breakdown
+│       ├── tickets/             # Branch-specific tickets
+│       │   ├── a1b2.md
+│       │   └── c3d4.md
+│       └── threads/             # Council discussion threads
+├── backlog/                     # Unassigned tickets
+│   └── tickets/
+├── archive/                     # Completed branches
+└── worktrees/                   # Git worktrees (gitignored)
+```
+
+No database. No server. Just files on disk.
+
+## Commands
+
+| Group | Description |
+|-------|-------------|
+| `kd start` / `kd done` / `kd status` | Branch lifecycle — initialize, finish, and inspect sessions |
+| `kd design` | Manage design documents (`show`, `approve`) |
+| `kd council` | Multi-model council — `ask`, `chat`, `review`, `show`, `list`, `watch`, `reset`, `retry` |
+| `kd ticket` (alias `kd tk`) | Ticket management — `create`, `list`, `show`, `start`, `close`, `deps`, and more |
+| `kd peasant` | Worker agents — `start`, `stop`, `review`, `accept`, `reject`, `msg`, `read`, `watch` |
+| `kd config` | View and manage configuration |
+| `kd doctor` | Check config and agent CLIs |
+
+Run `kd <command> --help` for full flags and options.
+
+## Development
+
+```bash
+uv sync
+source .venv/bin/activate
+pytest tests/
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE) for details.

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

@@ -1,6 +1,6 @@
 [project]
 name = "kingdom-cli"
-version = "0.2"
+version = "0.3.0"
 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"
@@ -42,6 +42,7 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 "kingdom.skill" = ["*.md", "references/*.md"]
+"kingdom.tui" = ["*.tcss"]
 
 [dependency-groups]
 dev = [

{kingdom_cli-0.2 → kingdom_cli-0.3.0}/src/kingdom/agent.py

@@ -435,13 +435,19 @@ COMMAND_BUILDERS: dict[str, CommandBuilder] = {
 }
 
 
-def clean_agent_env(role: str | None = None, agent_name: str | None = None) -> dict[str, str]:
+def clean_agent_env(
+    role: str | None = None,
+    agent_name: str | None = None,
+    kd_base: str | None = None,
+) -> dict[str, str]:
     """Return an env dict safe for spawning agent CLI subprocesses.
 
     Strips ``CLAUDECODE`` so child ``claude`` processes don't refuse to start
     with a "nested session" error when ``kd`` is invoked from inside Claude Code.
 
-    Optionally injects ``KD_ROLE`` and ``KD_AGENT_NAME`` for ``kd whoami``.
+    Optionally injects ``KD_ROLE``, ``KD_AGENT_NAME``, and ``KD_BASE``.
+    ``KD_BASE`` ensures worktree agents resolve the project root against the
+    main repo, not the worktree's copy of ``.kd/``.
     """
     import os
 
@@ -450,6 +456,8 @@ def clean_agent_env(role: str | None = None, agent_name: str | None = None) -> d
         env["KD_ROLE"] = role
     if agent_name:
         env["KD_AGENT_NAME"] = agent_name
+    if kd_base:
+        env["KD_BASE"] = kd_base
     return env
 
 
@@ -646,3 +654,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)