@openthink/team 0.0.1 → 0.0.3

package/README.md

@@ -24,35 +24,64 @@ npm link
 
 `v0` is **private and not yet published to npm** (`package.json` has `"private": true`). Flip when the source repo goes public.
 
-## Vault setup
+## Quick start
 
-`open-team` reads from a `product-vault` directory. Layout:
+```sh
+oteam init
+```
+
+Creates `~/openteam/` with the workspace tree below, drops a `.oteam-workspace` sentinel, registers it in `~/.open-team/config.json` (promoting it to default if no default is set), seeds per-phase model defaults (see [Per-phase model selection](#per-phase-model-selection) for the table), and writes the oteam guidance block to `~/AGENTS.md` and `~/CLAUDE.md`. Re-running `oteam init` against an already-initialised path is a clean no-op; running against a non-empty unmarked directory exits non-zero rather than silently merging. Existing per-phase model customisation is preserved across re-runs — defaults are only seeded when the `models` block is absent or empty (run `oteam config models show` to see the current state).
+
+Flags:
+
+- `oteam init --dir <path>` (or `-w, --workspace <path>`) — workspace location, default `~/openteam/`.
+- `oteam init --docs-dir <path>` — where to write `AGENTS.md` / `CLAUDE.md`, default `$HOME`.
+- `oteam init -y` — skip the interactive workspace-path prompt.
+
+> **Breaking change vs. earlier `oteam` builds:** `--dir` used to mean "where to write `AGENTS.md`/`CLAUDE.md`". It now means the workspace location. Use the new `--docs-dir` flag for the previous behaviour.
+
+## Workspace setup
+
+`open-team` reads from a workspace directory ("vault" is Obsidian's word; oteam doesn't depend on Obsidian). Layout:
 
 ```
-product-vault/
-├── 00-meta/templates/ticket.md
+openteam/
+├── .oteam-workspace          # sentinel — written by `oteam init`
+├── 00-meta/README.md
 ├── tickets/
 │   ├── triage/  refined/  in-progress/  qa/  blocked/
+├── projects/
 └── archive/<YYYY-MM>/
 ```
 
 A ticket's `state:` frontmatter must always match its containing folder under `tickets/`.
 
-For the simplest single-vault setup, leave `~/Documents/product-vault` in place or set `PRODUCT_VAULT_PATH`. For multiple vaults (personal + work, etc.) see [Config & multiple vaults](#config--multiple-vaults).
+For the simplest single-workspace setup, run `oteam init` (creates and registers `~/openteam/`). To use an existing tree, register it via `oteam config vault add <path>` or set `PRODUCT_VAULT_PATH`. For multiple workspaces (personal + work, etc.) see [Config & multiple vaults](#config--multiple-vaults).
 
 ## Subcommands
 
 ```sh
-oteam pull <source> <ref>           # ingest external item → tickets/triage/
-oteam pull --project <name> ...     # tag the new ticket with a project
-oteam assign <ticket-or-id>         # drive role pipeline (full path or AGT-NNN)
-oteam assign --inline <path>        # … or run inline in current terminal
-oteam assign --no-stamp <id>        # bypass the stamp gate (not recommended)
-oteam list [--state <state>]        # list active tickets
-oteam list --project <name>         # filter by project frontmatter
-oteam archive <ticket-id>           # move done ticket to archive/YYYY-MM/
-oteam config vault add <path>       # register a vault under a name
-oteam config vault list             # show registered vaults + default
+oteam pull <source> <ref>             # ingest external item → tickets/triage/
+oteam pull --project <name> ...       # tag the new ticket with a project
+oteam assign <ticket-or-id>           # drive role pipeline (full path or AGT-NNN)
+oteam assign --inline <path>          # … or run inline in current terminal
+oteam assign --no-stamp <id>          # one-shot override of stamp.enforce (clones from GitHub)
+oteam list [--state <state>]          # list active tickets
+oteam list --project <name>           # filter by project frontmatter
+oteam archive <ticket-id>             # move done ticket to archive/YYYY-MM/
+oteam config vault add <path>         # register a vault under a name
+oteam config vault list               # show registered vaults + default
+oteam config stamp set --host <url>   # configure stamp host post-init
+oteam config stamp set --enforce on   # require repos be stamp-registered
+oteam config stamp clear              # remove the stamp block
+oteam config stamp show               # print current stamp config
+oteam config models set <phase> <id>  # pin a model per role-pipeline phase
+oteam config models clear <phase>     # remove a per-phase override
+oteam config models show              # print current per-phase overrides
+oteam config telemetry set on|off     # toggle per-phase telemetry recording
+oteam config telemetry show           # print telemetry on/off state
+oteam telemetry summary [--days N] [--phase X] [--model Y]
+oteam telemetry tail [-n 20]          # last N telemetry lines (raw JSONL)
 ```
 
 Most commands accept `--vault <name-or-path>` to operate on a specific vault.
@@ -104,16 +133,98 @@ claude --dangerously-skip-permissions --model claude-opus-4-7 "/assign-ticket <p
 
 Requires the `claude` CLI on PATH (https://claude.com/claude-code).
 
-### Spawn-time stamp gate
+### Spawn-time clone modes (stamp integration)
+
+For repo-bound tickets (`repo:` frontmatter set), `oteam assign` clones an isolated agent worktree before spawning and points the spawned session's cwd at it. The cloned worktree has exactly one remote — `origin` — and shares no `.git/objects` with any clone you keep elsewhere on disk, so the agent can never push back into your daily checkout by accident.
+
+Where the clone comes from is governed by oteam config (`~/.open-team/config.json`, `stamp` block):
 
-For repo-bound tickets (`repo:` frontmatter set), `oteam assign` clones an isolated agent worktree from the stamp server before spawning, and points the spawned session's cwd at it. The clone is the gate: success means the repo is registered on the stamp server (`~/.stamp/server.yml` is read for host + port, and the URL is built as `ssh://git@<host>:<port>/srv/git/<basename>.git`); failure exits non-zero before any spawn. The cloned worktree has exactly one remote — `origin → <stamp-url>` — and shares no `.git/objects` with any clone you keep elsewhere on disk. That's by design: a stamp-signed merge made inside the worktree can only be pushed back to stamp, never pushed direct to GitHub by accident.
+| `stamp` config                                 | Mode      | Clone source                                           | Behaviour                                                                                       |
+|------------------------------------------------|-----------|--------------------------------------------------------|-------------------------------------------------------------------------------------------------|
+| absent / `null`                                | no-stamp  | `git@github.com:<repo>.git`                            | Default. No stamp config files are read. `oteam` works against any git repo.                    |
+| `{ host, enforce: false }`                     | soft      | `git@github.com:<repo>.git`                            | Stamp host is recorded for tooling that asks for it; `oteam assign` does not gate.              |
+| `{ host, enforce: true }`                      | enforce   | `<host>/srv/git/<basename>.git` (the stamp server)     | The clone IS the gate: clone failure exits non-zero before any spawn. AGT-050 behaviour.        |
 
-The trade is a few seconds of SSH clone time per spawn instead of a near-instant `git worktree add`. For agent flows that immediately spend tens of seconds in an LLM thinking phase, the difference is noise.
+`oteam init` walks you through setting `stamp.host` and `stamp.enforce` interactively. Re-running `oteam init` pre-fills the prompts; press enter to keep current values. Pass `oteam init --skip-stamp` to skip the prompts on a re-run when you only want to refresh the workspace tree or docs blocks.
 
-Pass `--no-stamp` to bypass the gate and clone from `git@github.com:<repo>.git` instead. This is loud (you'll see a stderr line on the spawn) and is **not recommended** — the stamp gate is the safeguard against agents pushing direct to GitHub, so use it only when you've decided the repo is intentionally not stamp-governed (e.g. a public OSS clone, or a one-off scratch repo). Repos that fit this shape need to be told so on every assign; there's no per-repo config to make `--no-stamp` sticky on purpose.
+You can edit the stamp config any time after init:
+
+```sh
+oteam config stamp show               # print current host + enforce
+oteam config stamp set --host <url>   # set or update the stamp host
+oteam config stamp set --enforce on   # turn the per-repo gate on (host required)
+oteam config stamp set --enforce off  # … or back off
+oteam config stamp clear              # remove the stamp block entirely
+```
+
+`oteam assign --no-stamp` is a per-run override: it forces the github clone path even when `stamp.enforce: true` is set. The persistent setting is `oteam config stamp set --enforce off`; `--no-stamp` is convenient when you want to spawn a one-off agent without touching config.
+
+> **Migration note.** Earlier `oteam` builds read `~/.stamp/server.yml` directly. This version does not — to keep the AGT-050 stamp gate in place after upgrade, run `oteam init` and paste the host (or `oteam config stamp set --host <url> --enforce on`).
 
 Stale workspaces from prior assigns are GC'd at spawn time: any `/tmp/open-team-issues/agt-N/` directory whose ticket id has no matching ticket in the active vault is `rm -rf`'d before the new clone. The current run's workspace is also `rm -rf`'d before its clone, so re-assigns are hermetic.
 
+## Per-phase model selection
+
+Each role-pipeline phase can run on a different Claude model. The runner reads `models[phase]` from `~/.open-team/config.json` before each spawn and passes it as `claude --model <id>`. Phase resolution from the ticket's `state:`:
+
+| ticket state   | phase            |
+|----------------|------------------|
+| `triage`       | `product`        |
+| `refined`      | `spike`          |
+| `in-progress`  | `implementation` |
+| `qa`           | `qa`             |
+
+`oteam init` seeds these defaults if no `models` block exists yet:
+
+| phase            | default model        | rationale                                                       |
+|------------------|----------------------|-----------------------------------------------------------------|
+| `product`        | `claude-sonnet-4-6`  | synthesis when the input is rough; cheaper than Opus            |
+| `spike`          | `claude-opus-4-7`    | design judgment, gap-spotting, scope rating                     |
+| `implementation` | `claude-sonnet-4-6`  | multi-file edits + stamp round-trips                            |
+| `qa`             | `claude-sonnet-4-6`  | catching AC mismatches against the running system               |
+
+Inspect the current state with `oteam config models show`. Override with:
+
+```sh
+oteam config models set spike claude-opus-4-7
+oteam config models set implementation claude-sonnet-4-6
+oteam config models show         # one phase per line; "(unset)" for unpinned phases
+oteam config models clear spike  # falls back to the role-pipeline default
+```
+
+Each field is independent. Unset phases fall back to the role-pipeline default (currently `claude-opus-4-7`); validation is "non-empty string", and the SDK rejects unknown ids at spawn time. Re-running `oteam init` against a config that already has any per-phase model set leaves the entire `models` block alone — your customisation wins. A spike that auto-proceeds to implementation in the same session keeps the spike-phase model (one model per spawn).
+
+## Telemetry
+
+Every role-pipeline spawn records one JSON line capturing wall-clock + token usage to `~/.open-team/telemetry/runs.jsonl`. The intent is data-driven model tuning — the per-phase defaults above are educated guesses, and the only way to know whether Sonnet QA actually catches what Opus QA does is to measure both.
+
+Each line looks like:
+
+```json
+{ "ticket": "AGT-108", "phase": "implementation", "model": "claude-sonnet-4-6",
+  "started-at": "2026-05-04T10:00:00.000Z", "ended-at": "2026-05-04T10:05:42.000Z",
+  "wall-clock-ms": 342000,
+  "tokens": { "input": 230, "output": 120, "cache-read": 18100, "cache-write": 50 },
+  "outcome": "done" }
+```
+
+`outcome` is one of `done` / `paused` / `failed` / `unknown`, classified from the STOP banner the role-pipeline body emits (`✅ DONE` / `⏸️ PAUSED` / `🛑 BLOCKED`). A non-zero `claude` exit pins the outcome to `failed` regardless of marker.
+
+Inspect:
+
+```sh
+oteam telemetry tail            # last 20 lines (raw JSONL)
+oteam telemetry summary         # aggregate by phase × model
+oteam telemetry summary --days 7
+oteam telemetry summary --phase implementation --model claude-sonnet-4-6
+```
+
+Knobs:
+
+- `OTEAM_TELEMETRY_DIR=<path>` overrides the default `~/.open-team/telemetry/` location.
+- `oteam config telemetry set off` opts out — no JSONL writes occur. Re-enable with `oteam config telemetry set on`. Default is on.
+- Telemetry is best-effort: a write failure (read-only dir, missing session file, malformed log) writes one line to stderr and does not fail the role-pipeline phase. Token fields the agent SDK doesn't expose are omitted from the line rather than recorded as zero.
+
 ## Config & multiple vaults
 
 `open-team` supports any number of named vaults via `~/.open-team/config.json`. Register them with:

package/dist/assign-ticket.md

@@ -13,7 +13,7 @@ You are working a `product-vault` ticket. The user invoked `oteam assign <path>`
 3. **No commits, no PRs, no Linear.** Vault tickets do not necessarily map to a code repo. Only act on code if the ticket's `repo:` field is set AND the work demands it.
 4. **STOP at every role-handoff boundary.** When your role is done, write a STOP marker (visual banner per Output discipline below) and let the human decide whether to continue.
 5. **3-attempt cap on any failing operation.** If a step fails (e.g., file mv fails, frontmatter parse fails, build/test fails), you get 3 tries before STOPPing.
-6. **Never read or write inside `$HOME/Development/<repo>`.** That tree may have uncommitted in-flight work; entangling with it is a sterile-field violation. For repo-bound tickets, the `oteam` runner has already prepared an isolated agent worktree at `/tmp/open-team-issues/<ticket-id-lowercased>/repo` and spawned you cd'd into it — that's your only valid working directory. The runner clones from the stamp server by default (or from GitHub when invoked with `--no-stamp`); either way, the worktree is isolated from your primary, so AC-shaped requirements like "primary's `git remote -v` is byte-equal before/after a spawn" are satisfied by construction. If your `$PWD` is not the prepared workspace (e.g. you invoked the slash command by hand outside of `oteam assign`), set up the workspace yourself before reading any repo file — see Phase 3 Step 0.
+6. **Never read or write inside `$HOME/Development/<repo>`.** That tree may have uncommitted in-flight work; entangling with it is a sterile-field violation. For repo-bound tickets, the `oteam` runner has already prepared an isolated agent worktree at `/tmp/open-team-issues/<ticket-id-lowercased>/repo` and spawned you cd'd into it — that's your only valid working directory. The runner clones from the stamp server when `stamp.enforce: true` is set in `~/.open-team/config.json`, otherwise from GitHub directly; either way, the worktree is isolated from your primary, so AC-shaped requirements like "primary's `git remote -v` is byte-equal before/after a spawn" are satisfied by construction. If your `$PWD` is not the prepared workspace (e.g. you invoked the slash command by hand outside of `oteam assign`), set up the workspace yourself before reading any repo file — see Phase 3 Step 0.
 
 ## Phase 0 — Read the ticket
 
@@ -63,7 +63,7 @@ Write the comment in this shape:
 
 ## Phase 3 — Engineering agent (state: refined → spike phase)
 
-**Step 0 — Workspace is already prepared.** When `oteam assign` spawned you against a repo-bound ticket, it already cloned `/tmp/open-team-issues/<ticket-id-lowercased>/repo` (from the stamp server by default, or from GitHub when invoked with `--no-stamp`) and set your cwd to it. Confirm with `pwd` and `git remote -v`; for stamp-governed repos you should see exactly one remote, `origin`, pointing at `ssh://git@<stamp-host>:<port>/srv/git/<basename>.git`.
+**Step 0 — Workspace is already prepared.** When `oteam assign` spawned you against a repo-bound ticket, it already cloned `/tmp/open-team-issues/<ticket-id-lowercased>/repo` (from the stamp server when `stamp.enforce: true` is set in `~/.open-team/config.json`; from GitHub otherwise, or when `--no-stamp` was passed) and set your cwd to it. Confirm with `pwd` and `git remote -v`; for stamp-governed repos you should see exactly one remote, `origin`, pointing at `ssh://git@<stamp-host>:<port>/srv/git/<basename>.git`.
 
 Cost trade: a fresh stamp clone adds a few seconds vs. the older `git worktree add` fast path. That's an intentional trade for AC-grade isolation — the agent worktree shares no `.git/objects` and no remotes with your primary, and removing or renaming any remote inside the worktree cannot leak back to your daily flow.