plantod 0.1.0__tar.gz

plantod-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PLANTOD
+
+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.

plantod-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: plantod
+Version: 0.1.0
+Summary: Planning-first, repo-aware AI coding orchestrator CLI
+Author-email: PLANTOD <admin@beinsoft.co.id>
+License: MIT
+Project-URL: Homepage, https://github.com/wandi1209/plantod
+Project-URL: Repository, https://github.com/wandi1209/plantod
+Project-URL: Issues, https://github.com/wandi1209/plantod/issues
+Keywords: ai,cli,coding,orchestrator,planning,agent,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# PLANTOD
+
+**Plan, Task, Orchestrate, Deliver** — a planning-first, repo-aware AI coding orchestrator CLI.
+
+PLANTOD turns a natural-language request ("add login feature") into a structured
+workflow: **plan → tasks → scoped execution → test → handoff → escalation → final review**.
+A strong model plans and reviews; a fast model executes small, scoped tasks. All
+decisions and outputs are written to `.plantod/` in the repo so the work is auditable.
+
+## Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Providers
+
+PLANTOD drives **agentic coding CLIs** as its backends — one per role. Install the
+CLI(s) for the providers you pick; each handles its own auth/model config.
+
+| Provider | Binary | Invocation |
+|----------|--------|-----------|
+| `claude-code` | `claude` | `claude -p "<prompt>"` |
+| `codex` | `codex` | `codex exec "<prompt>"` |
+| `opencode` | `opencode` | `opencode run "<prompt>"` |
+
+### `plantod login`
+
+Set the provider + model for each role (planner / executor / reviewer):
+
+```bash
+plantod login                                             # interactive wizard (all roles)
+plantod login --role executor --provider codex --model o4 # non-interactive, one role
+plantod login --role planner  --provider claude-code      # model optional -> provider default
+plantod login ... --project                               # save to THIS repo instead of global
+```
+
+Config precedence (low → high): **defaults < global (`~/.config/plantod/config.yaml`) < project (`.plantod/config.yaml`)**.
+`login` writes the global scope by default so settings carry across repos (NFR-02);
+`--project` overrides for one repo. `plantod init` inherits the global defaults.
+
+## Prerequisites
+
+- Install the CLI for each provider you configure (see table above); each tool
+  manages its own authentication.
+- `.env` in the repo root is auto-loaded into the environment (see `.env.example`)
+  for any provider that reads env vars.
+- A **git repo** is required for the scope guard — run `plantod init` inside one.
+
+## Usage
+
+```bash
+plantod login                      # pick provider + model per role (see Providers)
+plantod init                       # detect repo, scaffold .plantod/ (inherits global)
+plantod plan "add login feature"   # plan + break into tasks + run the default flow
+plantod plan "..." --yes --review  # approve gated tasks, run final review
+plantod tasks                      # list tasks + status
+plantod next                       # next runnable task
+plantod run T001                   # run a single task
+plantod review R001                # final review for a requirement
+plantod status                     # board summary
+plantod resume                     # where the last session left off
+plantod                            # interactive chat-like session
+```
+
+## Why planning-first saves tokens (cost model)
+
+PLANTOD's economics come from **routing**: a strong, expensive model only *plans*
+and *reviews* (low token volume, high-value reasoning), while a cheap, fast model
+does the *bulk editing* (high token volume, low-level work). Most tokens in a coding
+task are spent reading context and writing edits — so you want those on the cheap model.
+
+**Illustrative example** — one feature = 1 plan + 4 tasks + 1 review. Token splits
+below are *assumptions to show the shape of the saving*, not measurements:
+
+| Stage | Tokens | All-in-one (strong model) | PLANTOD (routed) |
+|-------|-------:|--------------------------:|-----------------:|
+| Plan + review | ~30K | strong | strong |
+| Task execution (×4) | ~200K | strong | **cheap executor** |
+| **Total billed as** | ~230K | 230K × strong-rate | 30K × strong-rate + 200K × cheap-rate |
+
+If the executor model is ~15× cheaper per token than the planner (a typical
+fast-model vs frontier-model gap), the routed run costs roughly:
+
+```
+strong_share = 30K
+cheap_share  = 200K / 15  ≈ 13.3K  strong-equivalent tokens
+routed_total ≈ 43.3K  vs  230K   →  ~5× cheaper for this mix
+```
+
+The exact multiple depends on your models and the plan/execution token ratio —
+plug in current per-token prices for your planner and executor to get real numbers.
+
+> **Honest caveat:** these figures are an illustrative model, not a benchmark.
+> PLANTOD does not yet meter real token usage — **cost tracking is on the v2
+> roadmap** (PRD §27). The structural saving (route bulk edits to a cheap model,
+> keep reasoning on a strong one) holds regardless; the exact ratio is yours to measure.
+
+Beyond cost, the planning-first flow also reduces *wasted* tokens: scoped tasks and
+the scope guard stop the executor from sprawling across the repo and re-generating
+work, which is where "just let the big model code" runs burn tokens on churn.
+
+## How it works
+
+- **Adapters** (`plantod/adapters/`) make backends swappable: `claude`, `opencode`, `mock`.
+- **State machine** (`plantod/schemas.py`) enforces legal task transitions
+  (`pending → ready → in_progress → testing → done → reviewed`, plus `blocked → needs_planner_review`).
+- **Approval gate** (`plantod/orchestrator.py`) auto-runs only low-risk, small-scope,
+  testable tasks; everything else asks for approval.
+- **Artifacts** (`.plantod/`): `requirements/ plans/ tasks/ handoffs/ reviews/ logs/`,
+  markdown + YAML frontmatter; `board.json` / `session.json` for state.
+
+## Configuration (`.plantod/config.yaml`)
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `planner` / `executor` / `reviewer` | `{provider, model}` per role | backend for each role — set via `plantod login` |
+| default providers | claude-code / opencode / claude-code | planner / executor / reviewer |
+| `auto_run_small_tasks` | true | auto-run low-risk tasks |
+| `require_approval_for_architecture` | true | gate high-risk changes |
+| `test_before_done` | true | run tests before marking done |
+| `enforce_scope` | true | revert executor edits outside `files_allowed` |
+| `apply_requires_approval` | false | confirm the in-scope diff before keeping it |
+| `exec_timeout_s` / `test_timeout_s` | 900 / 600 | subprocess timeouts |
+| `max_retries` | 3 | retry transient backend failures / cap replans |
+| `auto_replan_on_escalation` | true | planner advises + retries an escalated task |
+
+## Production notes
+
+- **Scope guard** — after each executor run, any file changed outside the task's
+  `files_allowed` (or matching `files_forbidden`) is reverted via git and the task
+  is escalated. This is enforced, not just prompted.
+- **State safety** — `board.json` / `session.json` and all artifacts are written
+  atomically (temp file + rename). A per-project advisory lock (`.plantod/.lock`)
+  stops concurrent runs from corrupting state.
+- **Escalation loop** — a blocked task goes `needs_planner_review`; the planner
+  produces guidance and the task retries with narrower scope, capped by `max_retries`.
+- **Resilience** — backend calls retry with exponential backoff; subprocesses have
+  timeouts; malformed model JSON is parsed defensively.
+- Requires a **git repo** for the scope guard; run `plantod init` inside one.
+
+## Development
+
+```bash
+pytest        # state machine, artifacts, config, full mock-adapter flow
+```
+
+Layout: `src/` package layout, entry point `plantod.cli:app`.
+
+## License
+
+MIT

plantod-0.1.0/README.md

@@ -0,0 +1,153 @@
+# PLANTOD
+
+**Plan, Task, Orchestrate, Deliver** — a planning-first, repo-aware AI coding orchestrator CLI.
+
+PLANTOD turns a natural-language request ("add login feature") into a structured
+workflow: **plan → tasks → scoped execution → test → handoff → escalation → final review**.
+A strong model plans and reviews; a fast model executes small, scoped tasks. All
+decisions and outputs are written to `.plantod/` in the repo so the work is auditable.
+
+## Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Providers
+
+PLANTOD drives **agentic coding CLIs** as its backends — one per role. Install the
+CLI(s) for the providers you pick; each handles its own auth/model config.
+
+| Provider | Binary | Invocation |
+|----------|--------|-----------|
+| `claude-code` | `claude` | `claude -p "<prompt>"` |
+| `codex` | `codex` | `codex exec "<prompt>"` |
+| `opencode` | `opencode` | `opencode run "<prompt>"` |
+
+### `plantod login`
+
+Set the provider + model for each role (planner / executor / reviewer):
+
+```bash
+plantod login                                             # interactive wizard (all roles)
+plantod login --role executor --provider codex --model o4 # non-interactive, one role
+plantod login --role planner  --provider claude-code      # model optional -> provider default
+plantod login ... --project                               # save to THIS repo instead of global
+```
+
+Config precedence (low → high): **defaults < global (`~/.config/plantod/config.yaml`) < project (`.plantod/config.yaml`)**.
+`login` writes the global scope by default so settings carry across repos (NFR-02);
+`--project` overrides for one repo. `plantod init` inherits the global defaults.
+
+## Prerequisites
+
+- Install the CLI for each provider you configure (see table above); each tool
+  manages its own authentication.
+- `.env` in the repo root is auto-loaded into the environment (see `.env.example`)
+  for any provider that reads env vars.
+- A **git repo** is required for the scope guard — run `plantod init` inside one.
+
+## Usage
+
+```bash
+plantod login                      # pick provider + model per role (see Providers)
+plantod init                       # detect repo, scaffold .plantod/ (inherits global)
+plantod plan "add login feature"   # plan + break into tasks + run the default flow
+plantod plan "..." --yes --review  # approve gated tasks, run final review
+plantod tasks                      # list tasks + status
+plantod next                       # next runnable task
+plantod run T001                   # run a single task
+plantod review R001                # final review for a requirement
+plantod status                     # board summary
+plantod resume                     # where the last session left off
+plantod                            # interactive chat-like session
+```
+
+## Why planning-first saves tokens (cost model)
+
+PLANTOD's economics come from **routing**: a strong, expensive model only *plans*
+and *reviews* (low token volume, high-value reasoning), while a cheap, fast model
+does the *bulk editing* (high token volume, low-level work). Most tokens in a coding
+task are spent reading context and writing edits — so you want those on the cheap model.
+
+**Illustrative example** — one feature = 1 plan + 4 tasks + 1 review. Token splits
+below are *assumptions to show the shape of the saving*, not measurements:
+
+| Stage | Tokens | All-in-one (strong model) | PLANTOD (routed) |
+|-------|-------:|--------------------------:|-----------------:|
+| Plan + review | ~30K | strong | strong |
+| Task execution (×4) | ~200K | strong | **cheap executor** |
+| **Total billed as** | ~230K | 230K × strong-rate | 30K × strong-rate + 200K × cheap-rate |
+
+If the executor model is ~15× cheaper per token than the planner (a typical
+fast-model vs frontier-model gap), the routed run costs roughly:
+
+```
+strong_share = 30K
+cheap_share  = 200K / 15  ≈ 13.3K  strong-equivalent tokens
+routed_total ≈ 43.3K  vs  230K   →  ~5× cheaper for this mix
+```
+
+The exact multiple depends on your models and the plan/execution token ratio —
+plug in current per-token prices for your planner and executor to get real numbers.
+
+> **Honest caveat:** these figures are an illustrative model, not a benchmark.
+> PLANTOD does not yet meter real token usage — **cost tracking is on the v2
+> roadmap** (PRD §27). The structural saving (route bulk edits to a cheap model,
+> keep reasoning on a strong one) holds regardless; the exact ratio is yours to measure.
+
+Beyond cost, the planning-first flow also reduces *wasted* tokens: scoped tasks and
+the scope guard stop the executor from sprawling across the repo and re-generating
+work, which is where "just let the big model code" runs burn tokens on churn.
+
+## How it works
+
+- **Adapters** (`plantod/adapters/`) make backends swappable: `claude`, `opencode`, `mock`.
+- **State machine** (`plantod/schemas.py`) enforces legal task transitions
+  (`pending → ready → in_progress → testing → done → reviewed`, plus `blocked → needs_planner_review`).
+- **Approval gate** (`plantod/orchestrator.py`) auto-runs only low-risk, small-scope,
+  testable tasks; everything else asks for approval.
+- **Artifacts** (`.plantod/`): `requirements/ plans/ tasks/ handoffs/ reviews/ logs/`,
+  markdown + YAML frontmatter; `board.json` / `session.json` for state.
+
+## Configuration (`.plantod/config.yaml`)
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `planner` / `executor` / `reviewer` | `{provider, model}` per role | backend for each role — set via `plantod login` |
+| default providers | claude-code / opencode / claude-code | planner / executor / reviewer |
+| `auto_run_small_tasks` | true | auto-run low-risk tasks |
+| `require_approval_for_architecture` | true | gate high-risk changes |
+| `test_before_done` | true | run tests before marking done |
+| `enforce_scope` | true | revert executor edits outside `files_allowed` |
+| `apply_requires_approval` | false | confirm the in-scope diff before keeping it |
+| `exec_timeout_s` / `test_timeout_s` | 900 / 600 | subprocess timeouts |
+| `max_retries` | 3 | retry transient backend failures / cap replans |
+| `auto_replan_on_escalation` | true | planner advises + retries an escalated task |
+
+## Production notes
+
+- **Scope guard** — after each executor run, any file changed outside the task's
+  `files_allowed` (or matching `files_forbidden`) is reverted via git and the task
+  is escalated. This is enforced, not just prompted.
+- **State safety** — `board.json` / `session.json` and all artifacts are written
+  atomically (temp file + rename). A per-project advisory lock (`.plantod/.lock`)
+  stops concurrent runs from corrupting state.
+- **Escalation loop** — a blocked task goes `needs_planner_review`; the planner
+  produces guidance and the task retries with narrower scope, capped by `max_retries`.
+- **Resilience** — backend calls retry with exponential backoff; subprocesses have
+  timeouts; malformed model JSON is parsed defensively.
+- Requires a **git repo** for the scope guard; run `plantod init` inside one.
+
+## Development
+
+```bash
+pytest        # state machine, artifacts, config, full mock-adapter flow
+```
+
+Layout: `src/` package layout, entry point `plantod.cli:app`.
+
+## License
+
+MIT

plantod-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "plantod"
+version = "0.1.0"
+description = "Planning-first, repo-aware AI coding orchestrator CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "PLANTOD", email = "admin@beinsoft.co.id" }]
+keywords = ["ai", "cli", "coding", "orchestrator", "planning", "agent", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "pydantic>=2.6",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "build>=1.2", "twine>=5.0"]
+
+[project.urls]
+Homepage = "https://github.com/wandi1209/plantod"
+Repository = "https://github.com/wandi1209/plantod"
+Issues = "https://github.com/wandi1209/plantod/issues"
+
+[project.scripts]
+plantod = "plantod.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["plantod*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

plantod-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

plantod-0.1.0/src/plantod/__init__.py

@@ -0,0 +1,6 @@
+"""PLANTOD — Plan, Task, Orchestrate, Deliver.
+
+Planning-first, repo-aware AI coding orchestrator CLI.
+"""
+
+__version__ = "0.1.0"

plantod-0.1.0/src/plantod/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Model backend adapters (planner / executor / reviewer)."""
+
+from .base import ExecResult, ModelAdapter, PlanResult, ReviewResult
+from .registry import resolve
+
+__all__ = ["ModelAdapter", "PlanResult", "ExecResult", "ReviewResult", "resolve"]

plantod-0.1.0/src/plantod/adapters/base.py

@@ -0,0 +1,59 @@
+"""ModelAdapter interface + result types (PRD 14.1, NFR-03)."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from ..repo import RepoContext
+from ..schemas import Handoff, Task
+
+
+@dataclass
+class PlanResult:
+    title: str
+    summary: str
+    risk_level: str
+    # each task dict is validated into a Task by the planner layer
+    tasks: list[dict] = field(default_factory=list)
+    raw: str = ""
+
+
+@dataclass
+class ExecResult:
+    files_changed: list[str] = field(default_factory=list)
+    summary: str = ""
+    diff: str = ""
+    escalate: bool = False
+    escalate_reason: str = ""
+    raw: str = ""
+
+
+@dataclass
+class ReviewResult:
+    verdict: str = "approve"          # approve | revise
+    summary: str = ""
+    findings: list[str] = field(default_factory=list)
+    raw: str = ""
+
+
+class ModelAdapter(ABC):
+    """Backend-agnostic model interface. Concrete adapters wrap a provider."""
+
+    name: str = "adapter"
+
+    @abstractmethod
+    def plan(self, request: str, repo: RepoContext) -> PlanResult: ...
+
+    @abstractmethod
+    def execute(self, task: Task, repo: RepoContext) -> ExecResult: ...
+
+    @abstractmethod
+    def review(self, request: str, handoffs: list[Handoff], repo: RepoContext) -> ReviewResult: ...
+
+    def advise(self, task: Task, reason: str, repo: RepoContext) -> str:
+        """Planner guidance for a blocked/escalated task. Override in planner adapters."""
+        return (
+            f"Reduce scope and retry {task.id}. Split any architecture decision into a "
+            f"separate task. Blocking reason: {reason}"
+        )