context-garden 0.3.1__tar.gz

context_garden-0.3.1/.gitignore

@@ -0,0 +1,9 @@
+.garden/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+garden.local.yaml

context_garden-0.3.1/LICENSE

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

context_garden-0.3.1/PKG-INFO

@@ -0,0 +1,338 @@
+Metadata-Version: 2.5
+Name: context-garden
+Version: 0.3.1
+Summary: Drive agent development from a repository of context files: principles, products, phases, tasks.
+Project-URL: Homepage, https://github.com/joshmarcus/context-garden
+Project-URL: Documentation, https://github.com/joshmarcus/context-garden/tree/main/docs
+Project-URL: Issues, https://github.com/joshmarcus/context-garden/issues
+Project-URL: Source, https://github.com/joshmarcus/context-garden
+Author: Josh Marcus
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+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
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: markdown>=3.5
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.60
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: aws
+Requires-Dist: boto3>=1.34; extra == 'aws'
+Provides-Extra: dev
+Requires-Dist: pytest-timeout==2.4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: plates
+Requires-Dist: pillow>=10; extra == 'plates'
+Provides-Extra: walkthrough
+Requires-Dist: playwright>=1.40; extra == 'walkthrough'
+Description-Content-Type: text/markdown
+
+# context-garden
+
+**Drive autonomous agent development by tending a context garden.** You maintain principles, product overviews, phase goals, and specs as Markdown; context-garden turns that context into plans, working code, and reviewed pull requests. As your project grows, you refine the documents that guide the agents, and the agents carry the work through implementation, checks, review, and revision. Your job is to shape the goals, make decisions, and choose what ships.
+
+You can change the direction of the project in the same place you define it. Each worker gets a focused brief built from the shared context, and each phase leaves evidence you can use to improve the next one: what shipped, where agents got stuck, how reviewers responded, and what the work cost.
+
+[![Context Garden's development loop: tasks return through revision on the left while growing file nodes and code dependencies fill the graph on the right.](docs/screenshots/history-film.png)](https://drive.google.com/file/d/146FxqsfkbsCL8AwFBRdbsInpjA0v0MQI/view?usp=sharing)
+
+[Watch Context Garden build itself — one-minute video](https://drive.google.com/file/d/146FxqsfkbsCL8AwFBRdbsInpjA0v0MQI/view?usp=sharing) · [Reproduce the film](scripts/history-film/README.md)
+
+[Features](#what-you-can-do) · [See it in action](#feature-tour) · [Ontology](ONTOLOGY.md) · [Getting started](docs/getting-started.md) · [Operating guide](docs/operations.md) · [Contributing](docs/contributing.md) · [All documentation](docs/README.md)
+
+![The development loop: maintain principles, product context, goals, and specs; plan and approve; build and check; review and merge. Feedback drives revisions, and retrospectives inform the next phase.](docs/development-loop.svg)
+
+## What you can do
+
+- **Keep context useful as the project changes.** Maintain principles, product overviews, goals, and specs in Git. Each worker's brief includes the shared context and its task's reading list, so the direction you set reaches the work being done.
+- **Turn goals into coordinated work.** Plan a phase as tasks with acceptance criteria and dependencies. Run agents in parallel worktrees; stack related PRs and advance dependent tasks as changes merge.
+- **Close the review loop.** Configured tests and lint gate PR creation. Automated reviewers check the task's criteria, and failed checks or review feedback drive bounded revisions. Add persona reviews for another perspective.
+- **Handle decisions without losing the thread.** Answer a worker's question, approve scope, send a PR back, or recover a stopped task. The task keeps its brief, run output, review evidence, and history together.
+- **Watch autonomous work as it happens.** Now shows runs in flight, progress excerpts, what is queued next, and where the phase stands. The Board gives you columns, a task list, and a backlog you can reorder across phases.
+- **Compare models by the work they get accepted.** Inspect cost per accepted task, first-pass approval, revision rounds, and lead time by model and difficulty. Compare per-run costs, run model trials, set budgets, and account for delegated operator spend.
+- **Use each phase to improve the next.** Retrospectives bring together outcomes, friction, costs, and persona reviews. They can propose follow-up work or identify blockers before a phase closes; you refine the context for what comes next.
+- **Bring your existing project and tools.** Onboarding drafts context and a first phase from your repository. Use Claude Code, Codex, or a custom CLI harness with your project's setup, test, and lint commands; choose local, SSH, remote lease-based, or manual workers.
+
+The scheduler itself uses **no model tokens**: it polls, orders tasks, collects results, and advances state in Python. Models do the planning, implementation, reviews, agent-assisted revisions, and retrospectives. A delegated operator session also uses tokens. Waiting for CI does not require an agent to sit in a chat polling it.
+
+## Feature tour
+
+### Watch the work move
+
+**Now** is the live view of the loop: workers and reviewers in flight, progress from their output, the next tasks, and phase progress. Open a run to inspect its evidence. Below is the garden developing context-garden itself.
+
+![Now showing parallel agent runs, progress excerpts, review work, and the last 24 hours of activity in the real development garden](docs/screenshots/now-light.png)
+
+### Handle the decisions that need you
+
+The **Inbox** brings worker questions, draft approvals, and PR triage together. Answer a question to resume the work, approve the next tasks, or send a draft PR back with feedback.
+
+![Example Inbox with a worker question, an answer field, and draft tasks to approve](docs/screenshots/inbox-light.png)
+
+*This small example garden shows a worker asking about export behavior and two tasks awaiting approval.*
+
+### Shape the plan across phases
+
+The **Board** backlog puts upcoming work in phase order, with controls to change priority and move tasks between phases. Switch to columns for state or to the list for a compact view of tasks and PRs.
+
+![Live Board backlog showing tasks grouped by phase with priorities, state, and reorder controls](docs/screenshots/board-backlog-light.png)
+
+<details>
+<summary>See the Board's columns and list views</summary>
+
+**Columns:** scan the work by state, from draft and blocked through running and review. The board scrolls horizontally to show the remaining states.
+
+![Live Board columns showing draft, blocked, ready, running, and review work](docs/screenshots/board-columns-light.png)
+
+**List:** read task titles, state, priority, difficulty, and PR links together.
+
+![Live Board list showing tasks by state in a single phase](docs/screenshots/board-list-light.png)
+
+</details>
+
+### See which models work well for your tasks
+
+The comparison charts lower down **Now** connect model choices to outcomes. Cost per accepted task, first-pass approval, revision rounds, and lead time are broken out by difficulty. Cells include sample counts; sparse results are marked so a small sample does not look like a reliable winner.
+
+![Now comparison charts showing cost per accepted task, first-pass approval, work-run cost, revision rounds, and median lead time by model and difficulty](docs/screenshots/now-outcomes-light.png)
+
+The per-run comparison separates work, revision, review, and other activities by harness and model. Use it alongside the outcome charts when tuning model assignments and the amount of review a task needs. The **Costs** page provides spending history and additional filters.
+
+![Now heatmap comparing mean cost per run across activities, harnesses, and models, with totals and sample counts](docs/screenshots/now-run-costs-light.png)
+
+*These are snapshots of this project's development history over the selected 24-hour window, not controlled model benchmarks or estimates for your project.*
+
+### Keep the context and decisions within reach
+
+The **Trellis** makes dependencies visible. Task pages keep the brief, acceptance criteria, worker questions, and recorded usage together. Phase pages connect the work to goals and specs; closed phases remain available in the **Herbarium**.
+
+<details>
+<summary>Explore the Trellis, task page, and phase page</summary>
+
+These three captures use the same fictional Fieldnotes project as the Inbox above to make the individual features easy to read.
+
+![Trellis showing dependencies across an example project's tasks](docs/screenshots/trellis-light.png)
+
+![Dark task page with a worker question, acceptance criteria, and recorded usage](docs/screenshots/task-dark.png)
+
+![Example phase page with progress, task status, and its specification](docs/screenshots/phase-light.png)
+
+</details>
+
+## What you maintain
+
+Your **garden** is a git repository of Markdown files. It holds the context and task history; each product points to its code repository. The garden driving this tool lives at [joshmarcus/garden](https://github.com/joshmarcus/garden).
+
+```text
+my-garden/
+  garden.yaml                    # products, harnesses, capacity, checks
+  principles/00-index.md          # shared rules included in every brief
+  widget/
+    product.md                   # product context and development conventions
+    phase-01/
+      goals.md                   # outcomes, scope, definition of done
+      specs/                     # designs and requirements
+      tasks/                     # task briefs and scheduler-managed state
+  .garden/                       # local run records and working state (gitignored)
+```
+
+Edit and version the context in your usual editor. Use garden commands or the UI for task status changes.
+
+## Install
+
+You need **Python 3.11+**, **git**, a logged-in **Claude Code or Codex CLI**, and GitHub access through authenticated `gh` or `GITHUB_TOKEN`. Linux and macOS are supported; **on Windows, run garden inside WSL**. Your product repository needs a committed base branch, a GitHub remote you can push to, and a configured git author identity.
+
+Install the released command and library from PyPI:
+
+```bash
+python -m pip install context-garden
+garden --help
+```
+
+The supported library surface currently consists of the documented modules under `garden`.
+For example, task-document tools can parse and render the YAML frontmatter used by a garden:
+
+```python
+from garden import __version__
+from garden.model import join_frontmatter, split_frontmatter
+
+document = join_frontmatter({"id": "CG-1", "status": "ready"}, "## Goal\n\nShip it.")
+metadata, body = split_frontmatter(document)
+print(__version__, metadata["id"], body.strip())
+```
+
+Other modules are implementation details unless they are documented here or in the linked
+guides. Source contributors can instead use an editable checkout:
+
+```bash
+git clone https://github.com/joshmarcus/context-garden
+cd context-garden
+uv venv
+uv pip install -e .
+source .venv/bin/activate
+garden --help
+```
+
+Without uv, create the environment with `python3 -m venv .venv`, activate it, and run `python -m pip install -e .`. Keep that environment active when you move into your garden directory.
+
+## Your first project
+
+The steps below are a compact preview. The [getting-started guide](docs/getting-started.md)
+adds platform notes, expected outcomes, command explanations, and setup recovery.
+
+### 1. Create a garden and choose a harness
+
+From the tool checkout, with its environment active:
+
+```bash
+garden init ../my-garden --name my-garden
+```
+
+The default harness is Claude. To use Codex, set `harness: codex` in `../my-garden/garden.yaml` before onboarding. See [Codex setup](docs/codex.md) for authentication and model configuration.
+
+Workers use a private HOME and a scrubbed environment. Saved harness credentials are copied into private directories for each dispatch. If your credentials live elsewhere, configure `worker_env.config_dirs`; individual approved tool files use `worker_env.config_files`. Keep secrets out of tracked YAML. See [worker environment and configuration](docs/architecture.md#configuration-and-environments).
+
+### 2. Draft context from your repository
+
+Replace the path below with your project's local checkout:
+
+```bash
+garden onboard /absolute/path/to/widget --into ../my-garden
+cd ../my-garden
+git init
+```
+
+Onboarding attempts GitHub discovery and calls the configured planner, so **this step uses a model**. It infers a product name and creates `phase-01` with draft tasks. The examples below assume that name is `widget`.
+
+Read `widget/docs/onboarding.md` to see what was found, inferred, or left unresolved. Review `widget/product.md`, the principles, phase goals, and tasks. Correct the scope and the product's `setup.command`, `setup.test`, and `setup.lint` in `garden.yaml`. Onboarding does not install project dependencies or prove those commands work; validate them in a disposable checkout before approving work.
+
+<details>
+<summary>Prefer to write the context yourself?</summary>
+
+After `garden init`, enter your garden and scaffold the product and phase:
+
+```bash
+cd ../my-garden
+garden new-product widget --repo /absolute/path/to/widget --base-branch main
+garden new-phase widget phase-01
+```
+
+Fill in `principles/00-index.md`, `widget/product.md`, `widget/phase-01/goals.md`, and the specs under `widget/phase-01/specs/`. Configure the product's setup, test, and lint commands, then run:
+
+```bash
+garden plan widget/phase-01 --draft
+```
+
+Planning attempts a kickoff review first if none exists. `--dry-run` prints the planning prompt without calling a model. The onboarding path already creates drafts; it does not need this extra planning call.
+
+</details>
+
+### 3. Review the plan before starting work
+
+Merge these settings into the generated `garden.yaml`, keeping its product and harness configuration. They make approval explicit and start with one work slot and one review slot:
+
+```yaml
+max_parallel: 1
+review_parallel: 1
+plan:
+  auto_approve: false
+discovered:
+  auto_approve_blocking: false
+review:
+  enabled: true
+github:
+  draft_pr: true
+  project_users: [] # additional PR authors to observe; the authenticated user is always included
+  automerge: false
+  # Tier pools may spread work across harness/model members.
+models:
+  medium:
+    - {harness: claude, model: claude-sonnet-5, weight: 2}
+    - {harness: codex, model: gpt-5.6-terra, weight: 1}
+dispatch: {spread: quota_aware}   # round_robin | weighted | quota_aware
+harnesses:
+  claude: {models: {easy: haiku, medium: sonnet, hard: opus}}
+  codex:  {models: {easy: gpt-5.6-luna, medium: gpt-5.6-terra, hard: gpt-5.6-sol}}
+checks:
+  pre_pr: [{name: tests, command: "pytest -q -x"}]
+```
+
+These are suggested first-run settings, not package defaults: planning and blocking discovered work otherwise default to automatic approval. `--draft` overrides that behavior for one planning call. A phase budget is optional: `garden budget widget/phase-01 50` pauses new dispatch at $50; it does not cancel work already running.
+
+```bash
+garden doctor
+garden trellis
+garden validate
+```
+
+`doctor` checks configuration, repositories, the graph, and worker logins. It sends a small harness prompt and executes a configured notification command, so it is not an offline check. Resolve its failures before continuing. `validate` checks the graph and reading lists; approval also rejects incomplete briefs. Use `garden brief ID --stats` to inspect a task's context size.
+
+### 4. Approve work and follow the first PR
+
+```bash
+garden approve --all widget/phase-01
+garden serve
+```
+
+Use `garden approve ID` instead of `--all` to start with a single task. Open **http://127.0.0.1:8765**. `serve` starts the web UI **and the scheduler**: approved, unblocked work can now dispatch. For a look around before launching work, use `garden serve --no-watch` instead.
+
+Follow the task's runs and evidence, answer any questions in the **Inbox**, and inspect the resulting draft PR and automated review. Mark it ready with the UI or `garden triage ID --ready`; send it back with `garden triage ID --changes "feedback"`. Once review and CI are satisfactory, merge on GitHub. The next poll records the merge and advances dependent work.
+
+From another terminal with the same environment active, run `garden status`, `garden inbox`, or `garden observe --profile quiet`. `garden watch` runs the scheduler without the web UI; `garden tui` opens the terminal interface.
+
+## Use the CLI
+
+The CLI operates the same garden as the web UI and TUI. Inspect a plan, follow the workers, handle decisions, and compare outcomes from your terminal:
+
+```bash
+garden status
+garden observe --profile quiet
+garden inbox
+garden brief WID-003 --stats
+garden runs WID-003
+garden costs --since 24h --by model
+garden metrics widget/phase-01
+```
+
+Run commands from your garden directory with the installed environment active. Replace `WID-003` and `widget/phase-01` with your task and phase. `garden watch` runs the scheduler on its own; `garden observe --follow` follows progress alongside an existing controller. `garden --help` lists the command groups.
+Difficulty tiers route each task to a model, so cost follows difficulty. A top-level tier can instead be a pool of harness/model members: `round_robin` alternates, `weighted` repeats members by weight, and the default `quota_aware` behavior halves a member's share for `dispatch.quota_window_hours` after its usage-limit event, until its probe succeeds, while skipping a paused harness entirely. A task's `harness:` or `model:` remains a pin. `review.pool` accepts the same member list for alternating review accounts, and `garden trial -c tier:medium` expands a tier pool into contenders. `garden.<GARDEN_ENV>.yaml` and a gitignored `garden.local.yaml` layer on top for a work or per-machine setting; [examples/garden.work.yaml](examples/garden.work.yaml) shows ssh workers, a Jenkins log analyser and a product whose dependencies and tests are not Python.
+
+The [CLI guide](docs/cli.md) walks through planning and approval, following runs, answering workers, reviewing PRs, recovering tasks, and exporting JSON for scripts.
+
+## Keep the loop running
+
+A dispatch pause still allows collection, checks, reviews, and merges. Installation maintenance uses a separate drain-and-resume protocol. Run one long-lived controller per garden and keep its UI on loopback or behind authenticated access.
+
+The **Config** page shows effective settings and pending configuration changes.
+
+The [operating guide](docs/operations.md) covers merge policy, capacity, remote workers, recovery, maintenance, configuration reloads, GitHub Enterprise, and operator handoffs. The [architecture guide](docs/architecture.md) explains the full behavior and configuration boundaries.
+
+## Development and documentation
+
+- [Documentation map](docs/README.md): the canonical path for each audience.
+- [Getting started](docs/getting-started.md): installation through the first completed PR.
+- [Contributor guide](docs/contributing.md): setup, repository structure, tests, and docs.
+- [CLI guide](docs/cli.md): day-to-day commands, control modes, and scripting.
+- [Design](docs/design.md): vocabulary and the development loop.
+- [Architecture](docs/architecture.md): modules, state, scheduling, configuration, and merge policy.
+- [Worker protocol](docs/worker-protocol.md): briefs, results, transports, and failure recovery.
+- [Codex setup](docs/codex.md): harness configuration and interactive workflows.
+- [Test suites](docs/test-suites.md) and [worker CI](docs/worker-ci.md): focused checks and the full regression gate.
+- [Screenshot capture](docs/screenshots/README.md): reproduce this README's example garden and images.
+
+For development, follow the [contributor guide](docs/contributing.md). Tests use fake
+harnesses and spend no model tokens.
+
+MIT licensed. See [LICENSE](LICENSE).