biotonomy 0.2.1 → 0.2.2

package/README.md

@@ -1,211 +1,98 @@
 # Biotonomy
 
-Biotonomy is a command-line workflow for shipping code changes with Codex.
+Biotonomy (`bt`) is a CLI for running a Codex-driven development workflow in a repo:
 
-- What it is: A CLI that runs a repeatable flow: `spec -> research -> implement -> review -> fix -> pr`.
-- Who it is for: Developers who want a structured way to ship small changes fast.
-- What problem it solves: Keeps work organized in files, runs quality checks, and reduces "what do I do next?" during AI-assisted coding.
+`spec -> research -> plan-review -> implement -> review -> fix -> pr`
 
-## 60-Second Quickstart
+It supports both:
+- manual stage-by-stage execution
+- a one-command iterative loop with `bt loop`
 
-Install either way:
+## Quickstart
 
-```bash
-npm i -g biotonomy
-# then use: bt ...
-```
-
-```bash
-npx biotonomy ...
-```
-
-Minimal demo in a fresh repo:
-
-```bash
-mkdir biotonomy-demo && cd biotonomy-demo
-git init
-npm init -y
-
-npx biotonomy bootstrap
-npx biotonomy spec hello-world
-npx biotonomy review hello-world
-npx biotonomy status
-```
-
-Expected files after the demo:
-
-- `.bt.env`
-- `.bt/`
-- `specs/hello-world/SPEC.md`
-- `specs/hello-world/REVIEW.md`
-- `specs/hello-world/progress.txt`
-- `specs/hello-world/history/001-spec.md`
-- `specs/hello-world/history/002-review.md`
-- `specs/hello-world/.artifacts/codex-review.log`
-
-Notes:
-
-- `review` still creates `REVIEW.md` even if Codex is not installed.
-- `research` requires Codex.
-
-## Ship A Small Change
-
-Use this for a real change from idea to PR.
-
-1. `spec` (define the change)
-
-```bash
-bt spec my-change
-# or from GitHub issue:
-# bt spec 123
-```
-
-- Automated today: creates `specs/<feature>/SPEC.md`, history, and progress logs.
-- Manual today: fill in/clean up stories and acceptance criteria in `SPEC.md`.
-
-2. `research` (gather context)
+Prereqs: Node.js >= 18, `git`, Codex CLI available as `codex` (or set `BT_CODEX_BIN`).
 
 ```bash
-bt research my-change
-```
-
-- Automated today: runs Codex in read-only mode and writes `RESEARCH.md`.
-- Manual today: confirm research quality and adjust plan if needed.
-
-3. `implement` (make the change)
-
-```bash
-bt implement my-change
-```
-
-- Automated today: runs Codex in full-auto and then runs quality gates.
-- Manual today: if Codex is unavailable, this stage is a stub and you implement changes yourself.
-
-4. `review` (check what changed)
-
-```bash
-bt review my-change
-```
-
-- Automated today: writes `REVIEW.md` (with a fallback stub if Codex fails).
-- Manual today: decide whether findings are acceptable for your team.
-
-5. `fix` (address findings)
-
-```bash
-bt fix my-change
-```
-
-- Automated today: runs Codex fix pass and re-runs quality gates.
-- Manual today: rerun until you are satisfied; no built-in auto-loop to "done" yet.
-
-6. `pr` (open pull request)
-
-```bash
-bt pr my-change --dry-run
-bt pr my-change --run
-```
-
-- Automated today: runs tests/lint, creates branch, optionally commits, pushes, opens PR via `gh`.
-- Manual today: choose reviewers/labels, final PR polish, and merge strategy.
-
-## Current Limitations
-
-- No one-command autonomous loop yet (you run each stage yourself).
-- `research` needs Codex installed and available.
-- `implement`/`fix` can run as stubs without Codex (gates still run, code may not change).
-- PR flow depends on `gh` and repository permissions.
-
-## Troubleshooting
-
-`gh` auth fails (`bt spec 123` or `bt pr ...`):
-
-```bash
-gh auth status
-gh auth login
-```
-
-Codex missing (`codex required` or `codex not found`):
-
-- Install Codex and make sure `codex` is on your `PATH`.
-- Or set a custom binary in `.bt.env`: `BT_CODEX_BIN=/path/to/codex`.
-
-Quality gate failures on `implement`/`fix`:
-
-```bash
-bt gates my-change
-```
-
-- Fix failing lint/typecheck/test commands.
-- Override gate commands in `.bt.env` if auto-detection is wrong:
-  - `BT_GATE_LINT=...`
-  - `BT_GATE_TYPECHECK=...`
-  - `BT_GATE_TEST=...`
-
-## Release Publish Steps
-
-Use this when preparing an npm release. This workflow validates readiness but does not publish automatically.
-
-1. Confirm clean main branch and pull latest changes.
-
-```bash
-git checkout main
-git pull --ff-only
-```
+# Install
+npm i -g biotonomy
 
-2. Run release preflight checks (tests, lint, pack verification, and `npm pack --dry-run` summary).
+# In your project repo
+bt bootstrap
 
-```bash
-npm run release:ready
-```
+# Create a feature scaffold
+FEATURE=hello-world
+bt spec "$FEATURE"
 
-3. Ensure npm authentication is ready for publish.
+# Loop requires an approved plan review verdict first
+cat > "specs/$FEATURE/PLAN_REVIEW.md" <<'MD'
+Verdict: APPROVED_PLAN
+MD
 
-```bash
-npm whoami
-# if needed:
-npm login
+# Run autonomous implement/review/fix iterations (with gates)
+bt loop "$FEATURE" --max-iterations 3
 ```
 
-4. Bump version and create a tag.
+## `bt loop`
 
-```bash
-npm version patch
-# or: npm version minor / npm version major
-```
+`bt loop <feature> [--max-iterations N]` runs:
+1. preflight quality gates
+2. `implement`
+3. `review`
+4. `fix` only when review verdict is `NEEDS_CHANGES`
+5. repeat until verdict is `APPROVE`/`APPROVED` and gates pass, or max iterations is reached
 
-5. Push commit and tag.
+Loop hard-requires an approved `specs/<feature>/PLAN_REVIEW.md` verdict (`APPROVE_PLAN` or `APPROVED_PLAN`).
 
-```bash
-git push --follow-tags
-```
+## Artifacts And State
 
-6. Publish manually.
+Biotonomy writes feature state under `specs/<feature>/`:
+- `SPEC.md`
+- `RESEARCH.md`
+- `PLAN_REVIEW.md`
+- `REVIEW.md`
+- `history/` stage snapshots (`###-<stage>.md`) and loop iteration snapshots (`*-loop-iter-###.md`)
+- `loop-progress.json` loop summary and per-iteration status
+- `progress.txt` append-only stage log
+- `.artifacts/` Codex logs and command artifacts (for example `codex-implement.log`, `codex-review.log`, `codex-fix.log`)
+- `gates.json` feature gate results when running `bt gates <feature>`
 
-```bash
-npm publish --access public
-```
-
-- If your npm account uses 2FA for publish, npm will require a one-time code during `npm publish`.
+Global gate state is written to `.bt/state/gates.json` when running `bt gates` without a feature.
 
-## Commands
+## Manual Commands
 
 ```bash
 bt bootstrap
 bt spec <feature|issue#>
 bt research <feature>
+bt plan-review <feature>
 bt implement <feature>
 bt review <feature>
 bt fix <feature>
+bt loop <feature> [--max-iterations N]
 bt gates [feature]
 bt status
-bt pr <feature> [--dry-run|--run]
-bt reset
+bt pr <feature> [--run]
+```
+
+## Configuration
+
+Project config lives in `.bt.env` (created by `bt bootstrap`). Common overrides:
+
+```bash
+BT_SPECS_DIR=specs
+BT_STATE_DIR=.bt
+BT_GATE_LINT="npm run lint"
+BT_GATE_TYPECHECK="tsc --noEmit"
+BT_GATE_TEST="npm test"
+BT_CODEX_BIN="/path/to/codex"
 ```
 
-## Development
+## Release
+
+Run the release readiness checks:
 
 ```bash
-npm test
-npm run lint
+npm run release:ready
 ```
+
+That script runs tests, lint, pack verification, and `npm pack --dry-run`.

package/bt

@@ -1,5 +1,16 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bt_script_dir() {
+  local src="${BASH_SOURCE[0]}"
+  while [ -h "$src" ]; do
+    local dir
+    dir="$(cd -P "$(dirname "$src")" && pwd)"
+    src="$(readlink "$src")"
+    [[ "$src" != /* ]] && src="$dir/$src"
+  done
+  cd -P "$(dirname "$src")" && pwd
+}
+
+SCRIPT_DIR="$(bt_script_dir)"
 exec "$SCRIPT_DIR/bt.sh" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "biotonomy",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Codex-native autonomous development loop CLI",
   "license": "MIT",
   "repository": {
@@ -12,7 +12,8 @@
   },
   "homepage": "https://github.com/archive-dot-com/biotonomy#readme",
   "bin": {
-    "bt": "bt"
+    "bt": "bt",
+    "biotonomy": "bt"
   },
   "files": [
     "bt",