kaji 0.13.0__tar.gz

kaji-0.13.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

kaji-0.13.0/PKG-INFO

@@ -0,0 +1,403 @@
+Metadata-Version: 2.4
+Name: kaji
+Version: 0.13.0
+Summary: AI-driven software development workflow orchestrator
+Author: apokamo
+Maintainer: apokamo
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/apokamo/kaji
+Project-URL: Repository, https://github.com/apokamo/kaji
+Project-URL: Issues, https://github.com/apokamo/kaji/issues
+Project-URL: Changelog, https://github.com/apokamo/kaji/blob/main/CHANGELOG.md
+Keywords: ai,agent,workflow,orchestrator,claude,codex,gemini
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jq>=1.6
+Dynamic: license-file
+
+# kaji
+
+Language: English | [Japanese](README.ja.md)
+
+[![Release](https://img.shields.io/github/v/release/apokamo/kaji?include_prereleases)](https://github.com/apokamo/kaji/releases)
+[![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](pyproject.toml)
+[![License](https://img.shields.io/badge/License-Apache--2.0-blue)](LICENSE)
+
+https://github.com/user-attachments/assets/b1e3fb2e-6b92-4798-8f4c-0227b0727ce1
+
+<p align="center">
+  <a href="docs/assets/demo.mp4">Watch the terminal demo (MP4)</a>
+</p>
+
+Closed-loop agentic development for Claude Code, Codex, and Gemini CLI.
+
+kaji turns an issue into a resumable design -> implement -> review -> fix
+-> verify -> PR loop, with human-in-the-loop gates and artifact-backed
+verdicts. It is built for developers who want AI agents to do real work without
+turning the development process into a black box.
+
+> `kaji` means "rudder" in Japanese: the human keeps direction, agents do the
+> rowing.
+
+## Why kaji
+
+AI coding agents are powerful, but one-shot prompting is hard to govern. The
+missing layer is often the workflow around the agent: when to design, when to
+review, when to fix, when to stop, and when a human should decide.
+
+kaji provides that layer.
+
+- Define the development process as workflow YAML.
+- Route each step to Claude Code, Codex, or Gemini CLI.
+- Use bounded review/fix/verify loops instead of endless chat.
+- Capture decisions as structured verdict artifacts.
+- Resume from a specific step when work is interrupted.
+- Keep human approval at the points that matter.
+
+Beyond vibe coding: kaji gives AI-assisted development a loop, a log, and a
+quality gate.
+
+## How it works
+
+```mermaid
+flowchart TB
+  Issue["Issue"] --> Ready{"Ready gate"}
+  Ready -- "PASS" --> Start["Issue start"]
+  Ready -- "RETRY" --> FixReady["Fix ready"]
+  FixReady --> Ready
+
+  Start --> Design["Design"]
+  Design --> DesignReview{"Design review"}
+  DesignReview -- "PASS" --> Implement["Implement"]
+  DesignReview -- "RETRY" --> FixDesign["Fix design"]
+  FixDesign --> VerifyDesign["Verify design"]
+  VerifyDesign -- "PASS" --> Implement
+  VerifyDesign -- "RETRY" --> FixDesign
+
+  Implement -- "PASS" --> CodeReview{"Code review"}
+  Implement -- "RETRY" --> Implement
+  Implement -- "BACK" --> Design
+  CodeReview -- "PASS" --> FinalCheck["Final check"]
+  CodeReview -- "RETRY" --> FixCode["Fix code"]
+  CodeReview -- "BACK" --> Design
+  CodeReview -- "BACK_IMPLEMENT" --> Implement
+  FixCode --> VerifyCode["Verify code"]
+  VerifyCode -- "PASS" --> FinalCheck
+  VerifyCode -- "RETRY" --> FixCode
+
+  FinalCheck -- "PASS" --> PR["Pull request"]
+  FinalCheck -- "RETRY" --> FinalCheck
+  FinalCheck -- "BACK_DESIGN" --> Design
+  FinalCheck -- "BACK_IMPLEMENT" --> Implement
+
+  PR -- "PASS" --> ReviewPoll{"PR review poll"}
+  PR -- "RETRY" --> PR
+  ReviewPoll -- "PASS" --> Close["Issue close"]
+  ReviewPoll -- "RETRY" --> PRFix["PR fix"]
+  ReviewPoll -- "BACK_FALLBACK" --> Review["Fallback review"]
+  PRFix --> PRVerify["PR verify"]
+  PRVerify -- "PASS" --> Close
+  PRVerify -- "RETRY" --> PRFix
+  Review -- "PASS" --> Close
+  Review -- "RETRY" --> PRFix
+```
+
+Every agent step returns a verdict:
+
+| Verdict | Meaning |
+|---------|---------|
+| `PASS` | Continue to the next step. |
+| `RETRY` | Fix the current problem and verify again. |
+| `BACK` | Return to an earlier phase, such as design or implementation. |
+| `ABORT` | Stop the workflow with an explicit reason. |
+
+The harness reads structured outputs such as `verdict.yaml`, records attempt
+artifacts, and advances the workflow deterministically from each verdict.
+
+## Core features
+
+- **Multi-agent workflow orchestration**: run Claude Code, Codex, and Gemini CLI
+  from one workflow definition.
+- **Closed review loops**: model review feedback as explicit
+  review -> fix -> verify cycles.
+- **Interactive tmux runner**: run normal CLI agents in tmux panes while kaji
+  watches for artifact-backed verdicts.
+- **Headless runner**: keep existing non-interactive automation paths for CI-like
+  execution.
+- **Deterministic exec steps**: run subprocess steps directly when no LLM is
+  needed.
+- **Artifact-primary verdicts**: prefer `verdict.yaml`, then fall back to issue
+  comments or stdout parsing.
+- **Issue and PR lifecycle**: coordinate GitHub issue, branch, PR, review, and
+  close workflows.
+- **TDD and docs-as-code**: keep implementation, review, tests, and docs in the
+  same process.
+
+## Extensibility
+
+kaji currently focuses on Claude Code, Codex, and Gemini CLI. The runner and
+workflow model are designed to support additional coding-agent CLIs when there
+is real demand.
+
+Have another coding agent you want to plug into the loop? Open an issue and
+tell us what workflow you want to run.
+
+## Quick start
+
+### Prerequisites
+
+- Python 3.11 or newer
+- `uv`
+- Claude Code, Codex, or Gemini CLI installed for the agents you want to run
+- `gh` authenticated if you use GitHub-backed issue and PR operations
+- `tmux` 3.1 or newer if you use the interactive terminal runner
+- A target repository with kaji skills under `.claude/skills/`
+
+### Install kaji
+
+Install from PyPI:
+
+```bash
+uv tool install kaji
+kaji --help
+```
+
+For unreleased development builds, install from Git:
+
+```bash
+uv tool install git+https://github.com/apokamo/kaji.git
+```
+
+### Configure your repository
+
+In the repository where you want to run kaji, add `.kaji/config.toml`.
+The default workflow below, `.kaji/wf/dev.yaml`, is GitHub-backed because it
+opens PRs, polls review state, and closes issues.
+
+```toml
+[paths]
+artifacts_dir = ".kaji-artifacts"
+skill_dir = ".claude/skills"
+worktree_prefix = "kaji"
+
+[execution]
+default_timeout = 1800
+agent_runner = "headless"
+interactive_terminal_close_on_verdict = true
+
+[provider]
+type = "github"
+
+[provider.github]
+repo = "<owner>/<name>"
+default_branch = "main"
+git_remote = "origin"
+```
+
+For the full `.kaji/config.toml` reference, including overlays and all
+available keys, see
+[Configuration Reference](docs/reference/configuration.md).
+
+For local issue storage without GitHub, use a local provider config and create a
+gitignored machine overlay:
+
+```toml
+[provider]
+type = "local"
+```
+
+```bash
+kaji local init
+```
+
+`kaji local init` creates `.kaji/config.local.toml` for the current machine; it
+does not replace the tracked base config. Local mode uses local-specific
+workflows such as `.kaji/wf/dev-local.yaml`. See
+[Local Mode CLI Guide](docs/cli-guides/local-mode.md)
+([Japanese](docs/cli-guides/local-mode.ja.md)) for the local provider setup.
+
+Skills live under `.claude/skills/`. Other agent-specific skill directories can
+point to the same canonical skill files with symlinks.
+
+### Run a workflow
+
+Workflow files are run from `.kaji/wf/` in each repository. This repository
+ships `.kaji/wf/dev.yaml`, `.kaji/wf/dev-thorough.yaml`, and `.kaji/wf/docs.yaml`
+as the current GitHub-backed workflow set. To start a new Python project with
+these workflows preconfigured, create it from the
+[kaji-starter-python](https://github.com/apokamo/kaji-starter-python) template
+repository and follow the
+[Python Starter Guide](docs/guides/python-starter.md).
+
+The `dev.yaml` example assumes that a GitHub issue already exists, required
+skills are available, selected agent CLIs are installed, and `/issue-create` has
+already been completed. The workflow runs `issue-start` itself.
+
+Run a workflow:
+
+```bash
+kaji run .kaji/wf/dev.yaml <issue-id>
+```
+
+Resume from a specific step:
+
+```bash
+kaji run .kaji/wf/dev.yaml <issue-id> --from fix-code
+```
+
+Run only one step:
+
+```bash
+kaji run .kaji/wf/dev.yaml <issue-id> --step review-code
+```
+
+### Develop kaji itself
+
+Use this path only when you want to work on kaji, not just run it in another
+repository:
+
+```bash
+git clone https://github.com/apokamo/kaji.git
+cd kaji
+uv sync
+source .venv/bin/activate
+kaji --help
+```
+
+## tmux interactive terminal runner
+
+Use this when you want kaji to launch normal Claude Code or Codex CLI sessions
+inside tmux panes instead of using the headless runner.
+
+```toml
+[execution]
+default_timeout = 2400
+agent_runner = "interactive_terminal"
+interactive_terminal_close_on_verdict = true
+```
+
+Then run from inside a tmux session:
+
+```bash
+tmux new-session
+kaji run .kaji/wf/dev.yaml <issue-id> --agent-runner interactive-terminal
+```
+
+The runner opens managed panes, records terminal transcripts, waits for
+`verdict.yaml`, and advances the workflow. This is useful for live observation,
+subscription CLI usage, and debugging agent behavior.
+
+Read more:
+[Interactive Terminal Runner](docs/cli-guides/interactive-terminal-runner.md)
+([Japanese](docs/cli-guides/interactive-terminal-runner.ja.md))
+
+## Workflow example
+
+```yaml
+name: minimal-code-review
+description: "Bounded implement -> review -> fix -> verify loop"
+execution_policy: auto
+
+cycles:
+  code-review:
+    entry: review-code
+    loop: [fix-code, verify-code]
+    max_iterations: 3
+    on_exhaust: ABORT
+
+steps:
+  - id: implement
+    skill: issue-implement
+    agent: claude
+    on:
+      PASS: review-code
+      ABORT: end
+
+  - id: review-code
+    skill: issue-review-code
+    agent: codex
+    on:
+      PASS: end
+      RETRY: fix-code
+      BACK_IMPLEMENT: implement
+      ABORT: end
+
+  - id: fix-code
+    skill: issue-fix-code
+    agent: claude
+    on:
+      PASS: verify-code
+      ABORT: end
+
+  - id: verify-code
+    skill: issue-verify-code
+    agent: codex
+    resume: review-code
+    on:
+      PASS: end
+      RETRY: fix-code
+      ABORT: end
+```
+
+The review loop is bounded by `cycles.code-review.max_iterations`. The skill
+names above match kaji's standard skill set; your repository must provide those
+skill files. `model` and `effort` are optional in the YAML schema and omitted in
+this compact example; production workflows often pin them.
+
+`resume` tells kaji to continue from a previous session for the same agent when
+the runner supports it.
+
+## Documentation
+
+| Topic | Link |
+|-------|------|
+| Architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
+| Workflow overview | [docs/dev/workflow_overview.md](docs/dev/workflow_overview.md) |
+| Workflow authoring | [docs/dev/workflow-authoring.md](docs/dev/workflow-authoring.md) |
+| Skill authoring | [docs/dev/skill-authoring.md](docs/dev/skill-authoring.md) |
+| Interactive terminal runner | [docs/cli-guides/interactive-terminal-runner.md](docs/cli-guides/interactive-terminal-runner.md) ([Japanese](docs/cli-guides/interactive-terminal-runner.ja.md)) |
+| AI-driven development strategy | [docs/concepts/ai-driven-strategy.md](docs/concepts/ai-driven-strategy.md) ([Japanese](docs/concepts/ai-driven-strategy.ja.md)) |
+| CLI guides | [docs/cli-guides/](docs/cli-guides/) |
+
+## AI-readable docs
+
+For AI assistants and crawlers, [llms.txt](llms.txt) provides a compact index of
+the most important docs, commands, and workflow concepts.
+
+## Project status
+
+Current release: v0.12.0. kaji is under active development, and the supported
+user-facing entry point is the `kaji` CLI.
+
+The `legacy/` directory contains historical code and is not part of the current
+supported runtime.
+
+## Development
+
+```bash
+source .venv/bin/activate
+make check
+```
+
+Individual targets:
+
+```bash
+make lint
+make format
+make typecheck
+make test
+make verify-docs
+make verify-packaging
+```
+
+## License
+
+Apache-2.0