Metadata-Version: 2.4
Name: kingdom-cli
Version: 1.0.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
Project-URL: Homepage, https://github.com/jbohnslav/kingdom
Project-URL: Repository, https://github.com/jbohnslav/kingdom
Project-URL: Issues, https://github.com/jbohnslav/kingdom/issues
Project-URL: Changelog, https://github.com/jbohnslav/kingdom/releases
Keywords: cli,ai,development,workflow,agents,multi-model,tickets
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.3.1
Requires-Dist: rich>=14.3.1
Requires-Dist: textual>=7.5.0
Requires-Dist: typer>=0.21.1
Dynamic: license-file

# Kingdom

Kingdom (`kd`) is a ticket-first CLI for software development with multiple AI
agents. Work lives in plain Markdown tickets and epics, each agent session gets
its own execution context, and decisions and verification stay durable in the
ticket worklog.

Start with the small loop. Add the TUI, multi-model council, reviewed peasant
workers, or an epic-level lord only when the work benefits from them.

## Install

```bash
uv tool install kingdom-cli  # add --python 3.11 if Python 3.11+ is not installed yet
```

Then initialize the current Git branch:

```bash
kd start
```

Codex users can install the Kingdom skill and lifecycle hooks as one local
plugin:

```bash
kd plugin install codex
```

Start a new Codex task after installation, then use `/hooks` to review and trust
the Kingdom hooks. Later `kd update` runs refresh an existing plugin along with
the CLI and skill files; they do not install the Codex plugin unless you opted in.

See the dated [supported host integration matrix](docs/support-matrix.md) for
verified versions, evidence levels, and known Claude, Codex, and Cursor limits.

## Core ticket loop

The everyday workflow is create or find, select and start, keep the worklog
current, then close with evidence.

### 1. Create or find the work

Create one small ticket for genuinely new work:

```bash
kd tk create "Fix login redirect loop"
kd tk find <id>                 # print the canonical Markdown file path
```

If the request may already exist, inspect the current and recent work before
creating another ticket:

```bash
kd tk current
kd tk list
kd tk list --recently-closed --limit 10
kd tk show <id>
```

Tickets are living Markdown documents. Edit the file directly for requirements,
acceptance criteria, relationships, and rich worklog entries.

### 2. Pull or start it

Capture unplanned work in the backlog, then select it when it becomes timely:

```bash
kd tk create --backlog "Improve retry diagnostics"
kd tk pull <id>
kd tk start <id>
```

`kd tk start` binds only the calling execution context. Other agent sessions can
start and own different tickets concurrently.

### 3. Log and close

Record durable findings while they are fresh, not only at the end:

```bash
# Plain-text-only notes without shell metacharacters may be inline.
kd tk log <id> "Root cause confirmed; regression test now passes"
kd tk close <id>
```

Send command-rich or multiline notes through stdin with a quoted delimiter so
the shell cannot expand backticks, `$()`, variables, or quotes:

```bash
kd tk log <id> <<'WORKLOG'
Verified `uv run pytest`; literal $HOME and $(pwd) were not expanded.
Record the second line here.
WORKLOG
```

Alternatively, edit the ticket's `## Worklog` as direct Markdown. Before
closing, check off acceptance criteria and record changed files, decisions,
verification commands, results, and remaining concerns.

### 4. Organize related work with epics

An epic is a parent ticket for a concrete outcome. Its children remain normal,
independently executable tickets:

```bash
kd tk create --type epic "Ship account recovery"
kd tk create --parent <epic-id> "Add recovery-token storage"
kd tk create --parent <epic-id> "Implement recovery endpoint"
kd tk list --parent <epic-id>
```

### 5. Check workspace readiness

Status is the end of the loop; there is no separate workspace-finalization step:

```bash
kd status                      # inspect tickets and active contexts
kd status --check              # exit nonzero unless every ticket is terminal and valid
```

`kd status --check` is read-only, so it is safe for local review, CI, and release
gates. Workspace readiness is derived from ticket state rather than stored as a
separate branch lifecycle transition.

## Concurrent agent contexts

Each terminal, Codex task, Claude session, or native subagent can have a distinct
execution context. Starting a ticket in one context does not replace another
context's current ticket.

```bash
# Agent session A
kd tk start api1
kd tk current                  # api1

# Agent session B, at the same time
kd tk start ui2
kd tk current                  # ui2

kd status                      # branch-wide tickets and all agent contexts
```

`kd status` shows each context's host, role, ticket, epic, activity, and parent
context when available. The owning session remains responsible for integrating
delegated results into the working tree and durable ticket—even when hooks record
an automatic child handoff.

### Compaction checkpoints

Where a host exposes lifecycle hooks, Kingdom asks the exact bound context to
update its ticket before compaction or handoff with decisions, completed work,
verification, blockers, and next steps. If automatic compaction cannot give the
model another turn first, the request is repeated immediately after compaction
and on compact-resume.

For hosts or modes without a usable pre-compaction hook, run `kd tk current`, edit
that ticket's Markdown directly, and record the same five fields before
compacting or handing off. See [Cursor hook capability](docs/cursor-hooks.md) for
the supported Cursor events and remaining attribution gaps.

## Resource cleanup

Cleanup stays with the command that owns each resource; there is no global
end-of-work cleanup command:

- `kd tk close` and `kd tk defer` clear active bindings for the affected ticket.
- `kd status --prune-stale` removes stale execution-context bindings.
- `kd peasant accept` integrates reviewed work and cleans its worker state;
  `kd peasant clean <id>` removes one retained worktree, and
  `kd peasant prune` removes stale peasant sessions and orphaned state.

## Execution choices

### Direct work

Use direct work for small, sequential, integration-sensitive tickets:

```bash
kd tk start <id>
# implement, test, and update the Markdown worklog
kd tk log <id> "Verified with: pytest tests/test_login.py"
kd tk close <id>
```

### Bounded native subagent

Use the current host's native subagent feature for a bounded research, review, or
independent implementation slice. The owning session keeps ticket ownership,
reviews the child's output, integrates the useful changes, and writes the durable
conclusion into the ticket:

```bash
kd tk start <id>
# delegate one bounded slice with the host's native subagent tool
# owning session reviews and integrates the returned work
kd tk log <id> "Integrated subagent audit; findings and verification recorded"
```

## Power tools

These tools are optional. The core ticket loop works without any of them.

### Reviewed peasant

A peasant runs a well-scoped ticket unattended in an isolated worktree and uses
council review by default. The owning session still performs the final
integration review:

```bash
kd peasant start <id>
kd peasant watch <id>
kd peasant review <id>         # diff, worklog, and council feedback
kd peasant accept <id>         # or: kd peasant reject <id> "feedback"
```

### TUI and council

Use the council for genuine design ambiguity, product tradeoffs, or independent
review blind spots. The chat TUI is a human-friendly way to hold the same
multi-model discussion:

```bash
kd council ask "Which migration strategy best preserves rollback safety?"
kd council chat                 # create a new thread
```

Council output advises the ticket owner; it does not replace the implementation
worker or durable decision record.

### Lords

A lord supervises several ready child tickets under an epic, delegates them to
reviewed peasants, and checks cross-ticket integration:

```bash
kd lord start <epic-id> --watch
kd lord status
```

### Optional design documents

Design documents are optional planning artifacts, not a prerequisite for tickets
or backlog sprints. Use them when cross-cutting ambiguity merits a dedicated
artifact; existing repositories and commands remain supported:

```bash
kd design                       # initialize and print the design path
# edit the design document when the extra planning artifact is useful
kd design show
kd design approve
```

## Consolidated command replacements

Kingdom 1.0.0 consolidates four command routes. Existing repositories keep their
Markdown history; only the commands used for readiness, workspace selection,
ticket movement, and Worklog entries change. See the
[1.0.0 release notes](docs/releases/1.0.0.md) for the complete upgrade boundary.

`kd tk defer <id>... --reason "..."` is the supported way to return selected
branch work to backlog. It records the source, previous status and assignee,
reason, time, and calling context in ticket lifecycle history, then resets the
ticket to open/unassigned and clears active bindings. Pull it again when the work
is timely.

`kd done` was removed in v1.0.0. Use the read-only `kd status --check` readiness
gate after closing tickets and epics. There is no replacement finalization
transition and no `--force` bypass; readiness is derived from ticket state.

`kd switch <branch>` was removed in v1.0.0. Use `kd start <branch>` to initialize,
resume, or select a workspace through one idempotent entry point. For
branch-to-branch ticket movement, defer the ticket, check out the target Git
branch, run `kd start <branch>`, then pull the ticket there.

`kd tk move` was removed in v1.0.0. Use `kd tk pull` for backlog→work movement,
`kd tk defer --reason` for work→backlog movement, and the branch-to-branch flow
above. The internal file-move primitive remains an implementation detail used by
pull, defer, archive/restore, and peasant workflows.

`kd tk add-note` was removed in v1.0.0. Use `kd tk log`; it preserves multiline
input while adding the canonical Worklog timestamp and author attribution. The
direct 0.6.x→1.0.0 upgrade crossed the alias's previously announced v0.8.0
removal boundary.

## Ticket closure outcomes

`kd tk close <id>` records `resolution: completed` by default. The other terminal
resolutions are `wont-do`, `duplicate`, `superseded`, and `invalid`; each requires
a non-empty `--reason`. `--duplicate-of <id>` and `--superseded-by <id>` record
their target ticket. Closing appends lifecycle history; reopening clears active
closure fields without erasing that history.

Use `kd tk list --resolution <value>` to filter terminal outcomes.
`kd status --check` validates terminal evidence and reports the same resolution
breakdown without changing workspace state. Resolution-less legacy closures
remain readable and map to their compatible inferred outcome.

## Upgrading existing repositories

`kd update` refreshes the CLI and configured host integrations. Existing `.kd`
repositories use a lazy, idempotent context migration that preserves ticket IDs
and Markdown. Back up `.kd`, verify with the read-only `kd doctor`, and use the
retained legacy context state if you need to roll back. See the complete
[upgrade and rollback guide](docs/upgrading.md).

## How it works

All state lives in `.kd/` as plain Markdown and JSON tracked with the code:

```text
.kd/
├── branches/
│   └── feature-oauth-refresh/
│       ├── tickets/             # active tickets and epics
│       ├── design.md            # optional planning artifact
│       ├── breakdown.md         # optional legacy planning artifact
│       └── threads/             # council discussions and reviews
├── backlog/tickets/             # work not selected yet
├── archive/                     # completed branches and tickets
└── worktrees/                   # peasant worktrees (gitignored)
```

No database. No server. Just files on disk.

## Commands

| Group | Description |
|-------|-------------|
| `kd ticket` / `kd tk` | Create, find, pull, start, log, relate, and close tickets and epics |
| `kd start [branch]` | Initialize, resume, or select a workspace |
| `kd status [--check]` | Show ticket/context state and optionally enforce workspace readiness |
| `kd council` | Power tool for multi-model questions, reviews, and the chat TUI |
| `kd peasant` | Power tool for reviewed unattended ticket workers |
| `kd lord` | Power tool for epic-level peasant orchestration |
| `kd design` | Optional design-document planning (hidden from root help) |
| `kd config` / `kd doctor` | Inspect configuration, repository state, and host integrations |
| `kd plugin` / `kd update` | Install and refresh host integrations |

Run `kd <command> --help` for exact flags.

## Development

Inside a Kingdom checkout, always use `uv run kd` for dogfooding. Bare `kd` may
resolve to a separately installed release instead of the working tree.

```bash
uv sync
uv run pytest tests/
uv run ruff check .
uv run ruff format --check .
uv run pre-commit run ruff --all-files
uv run pre-commit run ruff-format --all-files
uv run kd status
```

## License

Apache-2.0 — see [LICENSE](LICENSE) for details.
