kengash-ai 0.1.0__tar.gz

kengash_ai-0.1.0/.antigravity-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "kengash-ai",
+  "version": "0.1.0",
+  "description": "Plan, ticket and run many projects at once with the coding-agent subscriptions you already have, through the harness CLI."
+}

kengash_ai-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "kengash-ai",
+  "description": "kengash_ai: plan, ticket and run many projects with your coding-agent subscriptions.",
+  "owner": {
+    "name": "normatov13"
+  },
+  "plugins": [
+    {
+      "name": "kengash-ai",
+      "source": "./",
+      "description": "Plan, ticket and run many projects at once with the coding-agent subscriptions you already have, through the harness CLI."
+    }
+  ]
+}

kengash_ai-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "kengash-ai",
+  "version": "0.1.0",
+  "description": "Plan, ticket and run many projects at once with the coding-agent subscriptions you already have, through the harness CLI.",
+  "author": { "name": "normatov13" },
+  "homepage": "https://github.com/normatov07/kengash-ai",
+  "repository": "https://github.com/normatov07/kengash-ai",
+  "license": "MIT",
+  "keywords": ["planning", "tickets", "multi-agent", "orchestration"]
+}

kengash_ai-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# local agent folders: Claude Code settings and worktrees, plan workspaces
+.claude/
+.superpowers/
+
+# Python and tooling
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.import_linter_cache/
+.coverage
+build/
+dist/
+*.egg-info/

kengash_ai-0.1.0/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+Kengash AI lets one developer run many projects at once with the coding-agent subscriptions they already have (Claude Code, Codex, Antigravity `agy`, which also serves Google's plans), driven through the official CLIs, never API keys. Skills installed into the user's agent conduct the work, the deterministic `harness` CLI does every mechanical step, and a local UI monitors it all.
+
+Status: all 7 sub-projects done (Foundation; Store + `harness` CLI; Engine; Skills; Web UI; Custom agents; Production readiness): `harness init|doctor|link|adopt|settings|memory|context|plan|ticket|status|next|run|wait|approve|park|stop|pause|resume|merge|skills|agent|ui` work, with detached workers, plan review, memory compaction, role skills, six installed skills (`skills/`, proven by `evals/`), the local web UI (`harness ui open`, seven screens matching the canvas), user-defined agents (`harness agent new` or the UI's New agent), and release tooling (`make dist`, `make audit`, `docs/releasing.md`). `docs/architecture.md` tracks what is built.
+
+## Commands
+
+- `make setup`: install the uv environment and git hooks
+- `make check`: everything CI runs (format, lint, types, tests, docs checks)
+- `make fmt`: format and auto-fix
+- `make live`: live smoke on the real provider CLIs (spends subscription quota; never in `make check`)
+- `make evals`: every skill scenario on every installed agent (spends quota; never in `make check`)
+- `make dist`: build the release artifacts and check them; `make audit`: known vulnerabilities in the locked dependencies
+- One test: `uv run pytest tests/test_cli.py::test_version_names_the_package`
+- `make docs DOCS_BASE=origin/main`: docs checks against another base
+
+## Hard rules
+
+1. The spec `docs/superpowers/specs/2026-10-22-super-harness-design.md` is the contract. Where it differs from `full prompt of app.md` (the original request), the spec wins. Change the spec before changing a contract.
+2. A change to `src/kengash_ai/<module>` updates `docs/modules/<module>/README.md` in the same commit; `make docs` and the pre-commit hook enforce it.
+3. Each project links to the store through one directory symlink. Never use hard links: they cannot link directories and break on status-folder moves and atomic saves.
+4. Only `harness` writes store files; agents never hand-edit plan or ticket state.
+5. Tickets reference their plan by id; never copy the full prompt into tickets.
+6. Providers run only through their official binaries under the user's login: never read or reuse OAuth tokens, never use `claude --bare` (it skips subscription login), and strip provider API-key variables from worker environments.
+7. No always-on daemon: workers are short-lived detached processes, one per job.
+8. Instruction files stay within caps: this file ≤ 100 lines, files under `docs/` ≤ 150 lines (specs and plans exempt).
+9. Each sub-project goes spec → plan → build → critical review of every change against the requirements before the next one starts.
+
+## Read when
+
+- `docs/architecture.md`: adding or moving a module, or changing module dependencies
+- `docs/conventions/instruction-files.md`: writing AGENTS.md, CLAUDE.md, GEMINI.md or any doc
+- `docs/conventions/skills.md`: writing a skill or role skill
+- `docs/conventions/memory-files.md`: touching MEMORY.md, DECISIONS.md, PROCESS.md, SETTINGS.md, plan or ticket formats
+- `docs/modules/<module>/README.md`: changing that module
+- `docs/superpowers/plans/`: implementing a sub-project step by step
+
+## UI design source
+
+The UI implements the Claude Design canvas https://claude.ai/artifact/JiMGMkbaw8qhafeaNbqU7d. In Claude Code, read it with the Artifact tool (`list_files`, then `read_file` on `project/canvas.json` and `project/*.dc.html`), not WebFetch.

kengash_ai-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project are written here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-26
+
+The first release.
+
+### Added
+
+- `harness` CLI: projects and the store (`init`, `doctor`, `link`, `adopt`), plans and tickets, settings and memory, the engine controls (`next`, `run`, `wait`, `approve`, `park`, `stop`, `pause`, `resume`, `merge`), skills (`install`, `lint`, `eval`) and the UI (`ui open`, `ui stop`).
+- An engine that runs each ticket through an importance-based workflow on `claude`, `codex` and `agy` under the user's login, one detached worker per job, one git worktree per ticket, with loop caps, token caps, stall detection, plan review and memory compaction.
+- Installed skills: `to-plan`, `to-plan-with-grill`, `to-ticket`, `to-loop`, `harness-memory`, `open-ui`; seven role skills.
+- A local web UI: overview, task board, ticket sheet with changes and timeline, workflow editor, agents and providers, settings and memory, live over server-sent events.
+- Custom agents: `steps.<name>: {role, kind, does}` in SETTINGS.md, `harness agent new|remove`, and the UI's New agent dialog.
+- Log retention (`logs.keep_days`, default 30).
+
+### Changed
+
+- The app is named **Kengash AI** and installs as `kengash-ai` (PyPI refused `super-harness` as too similar to `superharness`). The `harness` and `hrn` commands, `~/.harness` and every file format stay; an `kengash_ai` command is added.
+- Antigravity replaces Gemini CLI: Google moved Gemini CLI's subscription plans to Antigravity CLI, so `gemini` is no longer a provider; a setting naming it says to use `antigravity`.
+
+### Security
+
+- The UI checks Host, Origin, a per-run token and an `X-Harness` header on changes, and sends a strict Content Security Policy with framing, sniffing and referrer protections.
+
+[0.1.0]: https://github.com/normatov07/kengash-ai/releases/tag/v0.1.0

kengash_ai-0.1.0/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+@AGENTS.md

kengash_ai-0.1.0/GEMINI.md

@@ -0,0 +1 @@
+@AGENTS.md

kengash_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 normatov13
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kengash_ai-0.1.0/Makefile

@@ -0,0 +1,50 @@
+DOCS_BASE ?= main
+MAKEFLAGS += --silent
+
+.PHONY: setup fmt lint type test live evals docs check dist audit
+
+setup:
+	uv sync
+	uv run pre-commit install
+
+fmt:
+	uv run ruff format .
+	uv run ruff check --fix .
+
+lint:
+	uv run ruff format --check --quiet .
+	uv run ruff check --quiet .
+	out=$$(uv run lint-imports 2>&1) || { echo "$$out"; exit 1; }
+	uv run harness skills lint
+
+type:
+	uv run mypy --no-error-summary
+
+test:
+	uv run pytest
+
+# real provider CLIs on a scratch repo (SP3 spec §11); spends subscription quota
+live:
+	uv run pytest -m live -v
+
+# every skill scenario on every installed agent (SP4 spec §2.17); spends subscription quota
+evals:
+	uv run harness skills eval --all
+
+docs:
+	uv run python scripts/check_md_caps.py
+	uv run python scripts/check_docs_sync.py --base $(DOCS_BASE)
+
+check: lint type test docs
+
+# release artifacts, checked: the product and nothing local (SP7 spec decision 8)
+dist:
+	rm -rf dist
+	uv build --quiet
+	uv run python scripts/check_dist.py dist
+
+# known vulnerabilities in the locked dependencies
+audit:
+	uv lock --check
+	uv export --format requirements-txt --all-extras --no-emit-project --quiet > .audit-requirements.txt
+	uvx pip-audit@2.10.1 -r .audit-requirements.txt --disable-pip --require-hashes; status=$$?; rm -f .audit-requirements.txt; exit $$status

kengash_ai-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: kengash-ai
+Version: 0.1.0
+Summary: Run many projects at once with subscription coding-agent CLIs (Claude Code, Codex, Antigravity).
+Project-URL: Homepage, https://github.com/normatov07/kengash-ai
+Project-URL: Repository, https://github.com/normatov07/kengash-ai
+Project-URL: Issues, https://github.com/normatov07/kengash-ai/issues
+Project-URL: Changelog, https://github.com/normatov07/kengash-ai/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/normatov07/kengash-ai#readme
+Author: normatov13
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,antigravity,claude-code,cli,codex,harness,kanban
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: filelock>=3.16
+Requires-Dist: pydantic>=2.9
+Requires-Dist: ruamel-yaml-clib>=0.2.12; platform_python_implementation == 'CPython'
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer>=0.12
+Provides-Extra: ui
+Requires-Dist: fastapi>=0.115; extra == 'ui'
+Requires-Dist: uvicorn>=0.32; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# Kengash AI
+
+[![ci](https://github.com/normatov07/kengash-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/normatov07/kengash-ai/actions/workflows/ci.yml)
+
+A council of coding agents (*kengash* is Uzbek for council) that works many projects at once with the subscriptions you already pay for (Claude Code, Codex, Antigravity), through their official CLIs, never API keys.
+
+You talk to your usual agent. Skills installed into it turn a prompt into a reviewed plan and small tickets, then run each ticket through an agent loop sized to its importance (plan, review, implement, review, security), in parallel across projects, each ticket in its own git worktree. A deterministic `harness` CLI does every mechanical step, a shared memory store keeps decisions across sessions, and a local web UI shows and steers it all.
+
+## Features
+
+- **Subscriptions, not API keys.** Drives `claude`, `codex` and `agy` headless under your own login, reuses one CLI session per ticket and role, and strips provider API-key variables from every worker.
+- **Importance-based loops.** Simple, standard and critical workflows with loop caps, token caps, stall detection and send-back edges; you approve extra loops.
+- **Parallel and safe.** Tickets that touch the same paths run one at a time; the rest run side by side, each in its own worktree, merged when you say so.
+- **Your own agents.** Add a role and its step (`read`, `edit` or `review`) from the CLI or the UI, with a starter skill you can edit.
+- **Memory that lasts.** One store at `~/.harness`, linked into every project by a folder link: MEMORY.md and DECISIONS.md for all projects, PROCESS.md and SETTINGS.md per project, compacted when they grow.
+- **A local control room.** Overview, task board, ticket sheets with every change, a workflow editor, agents and providers, settings and memory, live over server-sent events.
+
+## Requirements
+
+- Linux or macOS (on Windows, use WSL), Python 3.12 or newer, git.
+- [uv](https://docs.astral.sh/uv/) to install.
+- At least one signed-in agent CLI: Claude Code (`claude`), Codex (`codex`) or Antigravity (`agy`).
+
+## Install
+
+    uv tool install 'kengash-ai[ui] @ git+https://github.com/normatov07/kengash-ai'
+    harness skills install --agent claude,codex,antigravity --global
+    harness doctor
+
+Once a release is on PyPI: `uv tool install 'kengash-ai[ui]'` or `pipx install 'kengash-ai[ui]'`. Leave out `[ui]` for the CLI alone.
+
+The skills can also come from Claude Code's plugin marketplace (`/plugin install kengash-ai --marketplace normatov07/kengash-ai`) or `npx skills add normatov07/kengash-ai`.
+
+## Quick start
+
+    cd ~/code/my-app
+    harness init            # registers the project and links .harness to the store
+
+Then, in your agent:
+
+1. `/to-plan` (or `/to-plan-with-grill` to be interviewed first): a plan, reviewed by an agent on another provider.
+2. `/to-ticket`: the plan becomes tickets with importance, dependencies and touched paths.
+3. `/to-loop`: tickets run in their loops; the agent waits, reports gates and asks before granting loops or merging.
+4. `/open-ui` (or `harness ui open`): the web UI on 127.0.0.1 behind a private link.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `harness init`, `link`, `adopt`, `doctor [--fix]` | register projects, repair links, check everything |
+| `harness plan …`, `ticket …` | plans and tickets (agents use these; they never edit store files) |
+| `harness next`, `run`, `wait`, `status` | what can start, start it, wait for gates, a summary |
+| `harness approve`, `park`, `stop`, `pause`, `resume`, `merge` | steer running work |
+| `harness settings show\|get\|check`, `memory …`, `context` | settings, memory and the conductor's digest |
+| `harness agent new\|remove` | your own roles and steps |
+| `harness skills install\|lint\|eval`, `ui open\|stop` | skills and the web UI |
+
+Every command takes `--help`, and most take `--json`. Exit codes: 0 done, 1 a problem, 3 timed out, 4 setup needed, 5 your decision needed.
+
+## Configuration
+
+Settings live in SETTINGS.md files: the package defaults, then `~/.harness/defaults/SETTINGS.md`, then each project's own copy (written by `harness init` and never overwritten). Edit them in the UI's Settings, Workflow and Agents screens, which change only the lines you touch, or by hand and check them with `harness settings check`. Common keys:
+
+    loop_max.critical: 6
+    agents:
+      implementer: {on: true, cli: codex, skill: implement, fallback: [claude/sonnet]}
+    sessions.per_provider: {claude: 3, codex: 3, antigravity: 2}
+    logs.keep_days: 30      # worker logs untouched this long are removed; 0 keeps all
+
+Add your own agent to a workflow, for example a performance reviewer that sends failing work back:
+
+    harness agent new perf-reviewer --kind review --does "Flag N+1 queries and hot loops." \
+        --cli claude/sonnet --workflow critical --after review_code
+
+## Security model
+
+- Providers run only through their official binaries under your login; harness never reads or reuses OAuth tokens and removes provider API-key variables from worker environments.
+- The UI binds to 127.0.0.1, checks Host and Origin, needs a fresh per-run token (kept in an `HttpOnly`, `SameSite=Strict` cookie), requires an `X-Harness` header on every change, and sends a strict Content Security Policy.
+- The store is a private git repository; text written to memory, tickets and the journal is redacted for common secret shapes.
+- Workers are short-lived processes, one per job; nothing runs in the background between jobs.
+
+Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
+
+## Troubleshooting
+
+- `harness doctor` names each problem and its fix; `harness doctor --fix` repairs links, exclude entries and dead workers, and prunes old logs.
+- A provider shows "signed out": run the sign-in command the Agents screen or `doctor` prints, then "Check sign-in again".
+- A ticket is stalled or at a loop cap: open it on the board; the sheet shows the findings and the approve or park actions.
+- Worker logs are in `~/.harness/runtime/logs/`.
+
+## Uninstall
+
+    harness ui stop
+    uv tool uninstall kengash-ai
+
+Your store stays in `~/.harness`; remove it and each project's `.harness` link by hand if you want them gone.
+
+## Develop
+
+Requires uv and GNU make. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+    make setup   # environment and git hooks
+    make check   # format, lint, types, tests, docs and skill checks
+    make dist    # build and check the release artifacts
+    make audit   # known vulnerabilities in the locked dependencies
+    make live    # live smoke on the real CLIs (spends quota)
+    make evals   # skill evals on the real CLIs (spends quota)
+
+Design: [docs/superpowers/specs/](docs/superpowers/specs/). Agent instructions: [AGENTS.md](AGENTS.md). Changes: [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT

kengash_ai-0.1.0/README.md

@@ -0,0 +1,113 @@
+# Kengash AI
+
+[![ci](https://github.com/normatov07/kengash-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/normatov07/kengash-ai/actions/workflows/ci.yml)
+
+A council of coding agents (*kengash* is Uzbek for council) that works many projects at once with the subscriptions you already pay for (Claude Code, Codex, Antigravity), through their official CLIs, never API keys.
+
+You talk to your usual agent. Skills installed into it turn a prompt into a reviewed plan and small tickets, then run each ticket through an agent loop sized to its importance (plan, review, implement, review, security), in parallel across projects, each ticket in its own git worktree. A deterministic `harness` CLI does every mechanical step, a shared memory store keeps decisions across sessions, and a local web UI shows and steers it all.
+
+## Features
+
+- **Subscriptions, not API keys.** Drives `claude`, `codex` and `agy` headless under your own login, reuses one CLI session per ticket and role, and strips provider API-key variables from every worker.
+- **Importance-based loops.** Simple, standard and critical workflows with loop caps, token caps, stall detection and send-back edges; you approve extra loops.
+- **Parallel and safe.** Tickets that touch the same paths run one at a time; the rest run side by side, each in its own worktree, merged when you say so.
+- **Your own agents.** Add a role and its step (`read`, `edit` or `review`) from the CLI or the UI, with a starter skill you can edit.
+- **Memory that lasts.** One store at `~/.harness`, linked into every project by a folder link: MEMORY.md and DECISIONS.md for all projects, PROCESS.md and SETTINGS.md per project, compacted when they grow.
+- **A local control room.** Overview, task board, ticket sheets with every change, a workflow editor, agents and providers, settings and memory, live over server-sent events.
+
+## Requirements
+
+- Linux or macOS (on Windows, use WSL), Python 3.12 or newer, git.
+- [uv](https://docs.astral.sh/uv/) to install.
+- At least one signed-in agent CLI: Claude Code (`claude`), Codex (`codex`) or Antigravity (`agy`).
+
+## Install
+
+    uv tool install 'kengash-ai[ui] @ git+https://github.com/normatov07/kengash-ai'
+    harness skills install --agent claude,codex,antigravity --global
+    harness doctor
+
+Once a release is on PyPI: `uv tool install 'kengash-ai[ui]'` or `pipx install 'kengash-ai[ui]'`. Leave out `[ui]` for the CLI alone.
+
+The skills can also come from Claude Code's plugin marketplace (`/plugin install kengash-ai --marketplace normatov07/kengash-ai`) or `npx skills add normatov07/kengash-ai`.
+
+## Quick start
+
+    cd ~/code/my-app
+    harness init            # registers the project and links .harness to the store
+
+Then, in your agent:
+
+1. `/to-plan` (or `/to-plan-with-grill` to be interviewed first): a plan, reviewed by an agent on another provider.
+2. `/to-ticket`: the plan becomes tickets with importance, dependencies and touched paths.
+3. `/to-loop`: tickets run in their loops; the agent waits, reports gates and asks before granting loops or merging.
+4. `/open-ui` (or `harness ui open`): the web UI on 127.0.0.1 behind a private link.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `harness init`, `link`, `adopt`, `doctor [--fix]` | register projects, repair links, check everything |
+| `harness plan …`, `ticket …` | plans and tickets (agents use these; they never edit store files) |
+| `harness next`, `run`, `wait`, `status` | what can start, start it, wait for gates, a summary |
+| `harness approve`, `park`, `stop`, `pause`, `resume`, `merge` | steer running work |
+| `harness settings show\|get\|check`, `memory …`, `context` | settings, memory and the conductor's digest |
+| `harness agent new\|remove` | your own roles and steps |
+| `harness skills install\|lint\|eval`, `ui open\|stop` | skills and the web UI |
+
+Every command takes `--help`, and most take `--json`. Exit codes: 0 done, 1 a problem, 3 timed out, 4 setup needed, 5 your decision needed.
+
+## Configuration
+
+Settings live in SETTINGS.md files: the package defaults, then `~/.harness/defaults/SETTINGS.md`, then each project's own copy (written by `harness init` and never overwritten). Edit them in the UI's Settings, Workflow and Agents screens, which change only the lines you touch, or by hand and check them with `harness settings check`. Common keys:
+
+    loop_max.critical: 6
+    agents:
+      implementer: {on: true, cli: codex, skill: implement, fallback: [claude/sonnet]}
+    sessions.per_provider: {claude: 3, codex: 3, antigravity: 2}
+    logs.keep_days: 30      # worker logs untouched this long are removed; 0 keeps all
+
+Add your own agent to a workflow, for example a performance reviewer that sends failing work back:
+
+    harness agent new perf-reviewer --kind review --does "Flag N+1 queries and hot loops." \
+        --cli claude/sonnet --workflow critical --after review_code
+
+## Security model
+
+- Providers run only through their official binaries under your login; harness never reads or reuses OAuth tokens and removes provider API-key variables from worker environments.
+- The UI binds to 127.0.0.1, checks Host and Origin, needs a fresh per-run token (kept in an `HttpOnly`, `SameSite=Strict` cookie), requires an `X-Harness` header on every change, and sends a strict Content Security Policy.
+- The store is a private git repository; text written to memory, tickets and the journal is redacted for common secret shapes.
+- Workers are short-lived processes, one per job; nothing runs in the background between jobs.
+
+Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
+
+## Troubleshooting
+
+- `harness doctor` names each problem and its fix; `harness doctor --fix` repairs links, exclude entries and dead workers, and prunes old logs.
+- A provider shows "signed out": run the sign-in command the Agents screen or `doctor` prints, then "Check sign-in again".
+- A ticket is stalled or at a loop cap: open it on the board; the sheet shows the findings and the approve or park actions.
+- Worker logs are in `~/.harness/runtime/logs/`.
+
+## Uninstall
+
+    harness ui stop
+    uv tool uninstall kengash-ai
+
+Your store stays in `~/.harness`; remove it and each project's `.harness` link by hand if you want them gone.
+
+## Develop
+
+Requires uv and GNU make. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+    make setup   # environment and git hooks
+    make check   # format, lint, types, tests, docs and skill checks
+    make dist    # build and check the release artifacts
+    make audit   # known vulnerabilities in the locked dependencies
+    make live    # live smoke on the real CLIs (spends quota)
+    make evals   # skill evals on the real CLIs (spends quota)
+
+Design: [docs/superpowers/specs/](docs/superpowers/specs/). Agent instructions: [AGENTS.md](AGENTS.md). Changes: [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT

kengash_ai-0.1.0/docs/README.md

@@ -0,0 +1,14 @@
+# Docs index
+
+One line per doc: what it holds and when to read it.
+
+| Doc | Read when |
+|---|---|
+| `architecture.md` | adding or moving a module, or changing module dependencies |
+| `releasing.md` | publishing a version to PyPI and GitHub, or setting that up |
+| `conventions/instruction-files.md` | writing AGENTS.md, CLAUDE.md, GEMINI.md or anything under `docs/` |
+| `conventions/skills.md` | writing a skill or role skill |
+| `conventions/memory-files.md` | touching MEMORY.md, DECISIONS.md, PROCESS.md, SETTINGS.md, plan or ticket formats |
+| `modules/<module>/README.md` | changing that module (one per module under `src/kengash_ai/`) |
+| `superpowers/specs/` | the design contract of each sub-project |
+| `superpowers/plans/` | step-by-step implementation plans |

kengash_ai-0.1.0/docs/architecture.md

@@ -0,0 +1,85 @@
+# Architecture
+
+System map of Kengash AI. The contract is the spec, `docs/superpowers/specs/2026-10-22-super-harness-design.md`; this page records what exists now. Update the Status columns whenever a module or sub-project lands.
+
+## Flow
+
+```
+You ──prompt──▶ CONDUCTOR: your claude | codex | agy session, running installed skills
+                      │ shell calls, compact output
+                      ▼
+                 harness CLI (deterministic) ──starts──▶ detached workers, one per job
+                      │                                        │ one CLI session per ticket×role, resumed
+                      ▼                                        ▼
+                 store ~/.harness                        claude -p · codex exec · agy -p
+                 (Markdown + JSONL, a git repo)          (official binaries, the user's login)
+                      ▲
+UI: harness ui → FastAPI + SSE on 127.0.0.1, through the same `ops` layer as the CLI
+```
+
+## Modules
+
+| Module | Responsibility | May import | Status |
+|---|---|---|---|
+| `cli` | Typer command surface, output formatting | `ops`, `model` | `--version`, `init`, `doctor`, `link`, `adopt`, `settings`, `memory` (incl. `compact`), `context`, `plan` (incl. `review`), `ticket` (incl. `changes`, `attach`), `status`, `next`, `run`, `wait`, `approve`, `park`, `stop`, `pause`, `resume`, `merge`, `skills lint|install|eval` |
+| `model` | Pydantic schemas: Plan, Ticket, Settings, Event, StepRequest, StepResult, Verdict | — | Plan, Ticket, TicketInput, Registry, Settings, Event, errors (SP2 M1–M3); runtime files, provider options (SP3 M1); step contract, provider status, trust file (SP3 M2); worker, ticket-state, cursor files (SP3 M3); job kinds, `WaitTimeout` (SP3 M4); custom steps, `role_of`/`kind_of` (SP6) |
+| `store` | Paths, frontmatter, atomic writes, locks, status moves, registry, links, store commits | `model` | built (SP2 M1); runtime slots, claims, pause flags (SP3 M1); repo trust digests (SP3 M2); UI record, `yamledit` (SP5) |
+| `settings` | Seed, load, validate, resolve; comment-preserving edits | `model`, `store` | built (SP2 M2); comment-preserving writes, overrides (SP5 M2) |
+| `memory` | MEMORY/DECISIONS/PROCESS writes and caps | `model`, `store`, `journal`, `settings` | built (SP2 M2): MEMORY and DECISIONS writes; compaction checks and writes, DECISIONS archive (SP3 M4) |
+| `journal` | Append-only JSONL events, follow, usage aggregates | `model`, `store` | built (SP2 M2): append, read; positions (SP3 M3); day files (SP5 M2) |
+| `ops` | Use cases shared by CLI, UI and workers | all units above; starts workers as processes | `projects`, `workspace`, `records`, `plans`, `tickets`, `status` (SP2 M1–M3); `queue` (SP3 M1); `providers` (SP3 M2); `slots`, `agents`, `prompts`, `lifecycle`, `steps`, `controls`, `merging`, `waiting`, `changes` (SP3 M3); `calls`, `jobs`, `reviews`, `compaction` (SP3 M4); `skills` (SP4 M1); `evals` (SP4 M2); `views`, `ui_server` (SP5 M1); `configure`, the screen views (SP5 M2); `agent_config` (SP6) |
+| `scheduler` | Runnable set: dependencies, `touches` overlap, provider slots, fairness | `model` | built (SP3 M1) |
+| `workflow` | Step graph per importance, routing, loop and budget caps, stalls | `model` | built (SP3 M1) |
+| `adapters` | One driver per provider CLI behind the `Provider` protocol | `model` | built (SP3 M2): claude, codex, antigravity, shell |
+| `gitops` | Worktrees, commits with trailers, diffs, rebase, merge | `model` | built (SP3 M2) |
+| `worker` | Runs one job through `ops`; heartbeats; handles signals | `ops`, `model` | built (SP3 M3–M4): `ticket`, `plan-review` and `compact` jobs |
+| `roles` | Packaged role skill files (data only) | — | built (SP4 M1): seven role skills, seeded into `defaults/roles/` |
+| `ui` | FastAPI app, SSE, static assets | `ops`, `model` | built (SP5 M1–M2, canvas parity): token auth, Host, Origin and `X-Harness` checks, journal SSE, the seven screens matching the canvas, settings saves; New agent (SP6) |
+
+`adapters` and `gitops` never touch the store. Import-linter (`make lint`) enforces the layers `cli | worker | ui > ops > memory > journal | settings > store > model` (`journal` and `settings` independent of each other) and keeps `cli`, `worker` and `ui` from importing `store`, `settings`, `memory` or `journal` directly; `workflow`, `scheduler`, `adapters` and `gitops` import only `model`; each new module adds its contract.
+
+## Store (built in SP2 M1)
+
+```
+~/.harness/                      canonical store, a git repo (mode 0700)
+├── registry.yaml                slug → repo path, base branch
+├── memory/                      MEMORY.md, DECISIONS.md (global), archive/
+├── defaults/                    SETTINGS.md, PROCESS.md, roles/ (seeds)
+├── projects/<slug>/             SETTINGS.md, PROCESS.md, memory -> ../../memory,
+│                                plans/, tasks/{in_queue,in_process,done}/
+├── journal/YYYY-MM-DD.jsonl     events
+├── worktrees/<slug>/hrn-<id8>/  ticket worktrees (git-ignored)
+└── runtime/                     locks, pids, heartbeats, logs (git-ignored)
+```
+
+Each registered repo gets one directory symlink, `<repo>/.harness -> ~/.harness/projects/<slug>`, listed in its `.git/info/exclude`.
+
+## Repository layout
+
+- `src/kengash_ai/`: the package; each module has `docs/modules/<module>/README.md`
+- `scripts/`: repository checks (`check_md_caps.py`, `check_docs_sync.py`), run by `make docs`, pre-commit and CI
+- `evals/`: skill eval scenarios (`make evals`, never in `make check`)
+- `tests/`: the pytest suite (`make test`); `tests/live/` runs the real CLIs (`make live`, never in `make check`)
+- `docs/`: index in `docs/README.md`
+- `skills/`: installed skills (data; force-included in the wheel); `.claude-plugin/` and `.antigravity-plugin/`: plugin manifests
+
+## Sub-projects
+
+| # | Sub-project | Status |
+|---|---|---|
+| 1 | Foundation | done: `docs/superpowers/plans/2026-10-22-foundation.md`; CI runs after the first push |
+| 2 | Store + `harness` CLI | done: M1 store core, M2 settings, memory, journal, M3 plans and tickets; plans in `docs/superpowers/plans/` |
+| 3 | Engine | done: spec `docs/superpowers/specs/2026-10-22-sp3-engine-design.md`; M1 engine rules, M2 providers and git, M3 workers and controls, M4 plan review, compaction and live smoke (green for claude and agy on 2026-10-23; codex once installed) |
+| 4 | Skills | done: spec `docs/superpowers/specs/2026-10-23-sp4-skills-design.md`; M1 skill toolkit and role skills, M2 eval runner, M3 the five installed skills (evals green on claude and agy on 2026-10-23; codex once installed) |
+| 5 | Web UI | done: spec `docs/superpowers/specs/2026-10-23-sp5-ui-design.md`; M1 server and monitor screens, M2 inspect and configure screens, canvas parity, M3 the `open-ui` skill (eval green on claude and agy on 2026-10-24) and the parity checklist |
+| 6 | Custom agents | done: spec `docs/superpowers/specs/2026-10-26-sp6-custom-agents-design.md`; custom steps of kind read, edit or review, `harness agent new\|remove`, the New agent dialog, CI fixed for GitHub runners and macOS, canvas follow-ups; Antigravity serves Google's subscription plans (SP7 replaced the gemini provider) |
+| 7 | Production readiness | done: spec `docs/superpowers/specs/2026-10-26-sp7-production-design.md`; content-keyed parse caches (views 24 s → under 1 s on 1,500 tickets), UI security headers, ruff security rules, log retention, Windows guard, clean artifacts with `scripts/check_dist.py`, CI on 3.12–3.14 with package and audit jobs, a tag-driven PyPI release with attestations, Dependabot, accessibility (axe clean), community docs; Antigravity replaces the gemini provider |
+
+## Agent context files
+
+| Agent | Reads | Verified |
+|---|---|---|
+| Claude Code | `CLAUDE.md`, which imports `AGENTS.md` with `@AGENTS.md` | documented import syntax |
+| Codex | `AGENTS.md` natively | documentation only; Codex CLI is not installed on the dev machine |
+| Gemini CLI | `GEMINI.md`, which imports `AGENTS.md` with `@AGENTS.md` | documentation only; Gemini CLI is not installed |
+| Antigravity `agy` | `AGENTS.md` (legacy `GEMINI.md` also supported) | 2026-10-22, agy 1.4.5: a headless run quoted hard rule 3 from `AGENTS.md` with `GEMINI.md` present |

kengash_ai-0.1.0/docs/conventions/instruction-files.md

@@ -0,0 +1,62 @@
+# Writing instruction files
+
+How to write the files agents read: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` and everything under `docs/`. Read this before adding or editing any of them.
+
+## Layers
+
+1. **Entry file** `AGENTS.md`: what the project is, the commands, at most 15 hard rules, and "Read when" links. Every agent loads it in every session, so each line costs tokens every time.
+2. **Topic docs** under `docs/`: one subject each, loaded only when a "Read when" trigger fires.
+3. **Code layer**: types, docstrings and config comments. Agents see these while reading code; never repeat them in docs.
+
+## Caps
+
+`scripts/check_md_caps.py` enforces these through `make docs` and the pre-commit hook:
+
+| File | Cap |
+|---|---|
+| `AGENTS.md` | 100 lines |
+| `docs/**/*.md` | 150 lines; aim for 50–150 for topic docs |
+| `docs/superpowers/**` | exempt (specs and plans) |
+
+When a doc reaches its cap, split it by subject and link the parts; never raise the cap.
+
+## Pointer files
+
+- `CLAUDE.md`: the `/init` prefix plus `@AGENTS.md`, which Claude Code imports.
+- `GEMINI.md`: `@AGENTS.md`, which Gemini CLI imports.
+- Codex and Antigravity `agy` read `AGENTS.md` directly (see `docs/architecture.md`, Agent context files).
+
+Pointer files hold no content of their own; put it in `AGENTS.md` or a topic doc.
+
+## Writing rules
+
+1. Every link says what it holds and when to read it, trigger word first: "`docs/conventions/skills.md`: writing a skill".
+2. Every rule that is not obvious says why and when it applies. Delete it when the why expires.
+3. Phrase instructions positively: say what to do.
+4. Give the shape of an output as a template. Keep "never" for discipline rules an agent might skip under pressure, and put the reason next to it.
+5. Put the most important rules at the top or the bottom; the middle of a long file gets the least attention.
+6. Keep one source of truth: link to it instead of copying, and never restate what code or config already says.
+7. Commands you reference are quiet on success and print only failures, so agents see signal, not noise.
+8. Prune on every edit: delete stale lines and lines that change nothing.
+
+## Module docs
+
+Every module under `src/kengash_ai/` has `docs/modules/<module>/README.md` with four sections:
+
+- **Purpose**: one or two sentences.
+- **Interface**: what users and other modules call.
+- **Invariants**: what must stay true.
+- **Changes**: newest first, at most 20 lines; older history lives in git.
+
+The doc changes in the same commit as the module. `scripts/check_docs_sync.py` enforces this: `make docs` checks the range `DOCS_BASE...HEAD`, the pre-commit hook checks staged files. A top-level `.py` file counts as a module; package dunder files such as `__init__.py` do not.
+
+## Who reads and writes what
+
+| File | Read by | Written by |
+|---|---|---|
+| `AGENTS.md` | every agent, every session | humans and agents, reviewed in pull requests |
+| `docs/modules/*` | agents changing that module | whoever changes the module |
+| `docs/conventions/*` | anyone writing that kind of file | humans |
+| `docs/superpowers/specs/`, `plans/` | anyone working on that sub-project | the brainstorming and writing-plans workflows |
+
+Sources: walkinglabs learn-harness-engineering, lecture 4; HumanLayer, "Skill issue: harness engineering for coding agents"; Matt Pocock, `writing-for-agents`.