@siriuslan/team-discuss 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 blan
+
+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.
+
+---
+
+This license covers the original text of this package only. The ideas it
+summarizes come from "A Philosophy of Software Design" by John Ousterhout
+(Yaknyam Press, 2018). That book is copyrighted by its author and is not
+included in or licensed by this package.

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# team-discuss
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A terminal app for moderated discussions between AI agents. **The app is the
+moderator**: it decides who speaks, pauses when a participant needs you, and has a
+moderator agent write the summary. You watch live and can join in at any time.
+
+- **Reusable participants.** A participant is a saved profile: an agent, model,
+  thinking level and either a **project folder** (it reads and can change your code)
+  or a **role** (instructions plus its own reference folder, read-only).
+- **Teams.** Save an ordered set of participants and load it when starting.
+- **Global history.** One dashboard lists every discussion on this machine. Opening
+  old history never spends tokens: it always opens **paused**.
+- **Guided start.** Topic → Participants → Review & start. Agents only run after you
+  choose **Start discussion** on the final Review step.
+
+It is the standalone sibling of the
+[`discuss` pi extension](https://www.npmjs.com/package/@siriuslan/discuss). The two do
+not share data.
+
+## Status: 0.2.0 (early release)
+
+- **New in 0.2.0:** project participants can change files and run commands during
+  rounds. Role participants stay read-only; ask `@builder` to create output in the
+  discussion's `files/` folder. Commands run as you, without folder confinement.
+- **Compatibility:** 0.1.0 cannot read discussions after 0.2.0 records builder turns
+  or tool-action lists. Use 0.2.0 to reopen them; the data is not lost.
+
+- **Only [pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) is
+  offered** for participants and the moderator. Claude Code and Codex seats stay
+  disabled, because their read-only/no-tools behavior could not be verified: Claude
+  Code's startup writes project settings into the workspace, and the tested Codex
+  setup needs a disabled feature. The app shows the reason instead of weakening the
+  limits.
+- Tested on **macOS (Apple Silicon) with Node 26**. Node 22 and Linux are supported
+  targets but have **not** been re-tested against this release. Desktop clipboard
+  paste and IME (input method) typing have not been verified by hand.
+- The terminal layout follows the approved design within terminal limits; spacing
+  differs slightly in places.
+
+Please report problems on
+[GitHub](https://github.com/siriuslan/pi-packages/issues).
+
+## Requirements
+
+- macOS or Linux (no Windows).
+- Node.js **22.19 or newer**.
+- An interactive terminal. `team-discuss --help` and `--version` work without one.
+- To run discussions: [pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
+  installed on `PATH` and logged in to a model provider. Browsing history needs no
+  agent at all.
+
+## Install
+
+```bash
+npm install -g @siriuslan/team-discuss
+team-discuss
+```
+
+Uninstall with `npm uninstall -g @siriuslan/team-discuss`. Your data in
+`~/.team-discuss` is kept; delete that folder yourself if you want it gone.
+
+## Quick start
+
+1. Run `team-discuss`. Use **Tab** to move between Discussions, Participants and
+   Teams.
+2. On Participants press **n** and create a profile. The default model is
+   `anthropic/claude-opus-5-5` with `xhigh` thinking; type any model/thinking value pi
+   accepts, or press **Ctrl+G** for suggestions. **Ctrl+S** saves.
+3. On Discussions press **n**: write the topic, pick participants (Space adds,
+   Alt+↑/↓ reorders, Alt+T loads a team), review the cost warning, then **Start
+   discussion** (or Ctrl+Enter).
+4. Watch. Type a comment and press **Enter** to join in. **Esc** pauses after the
+   current turn, **Ctrl+X** stops the current response, **F1** lists every control.
+
+When everyone is satisfied, the moderator writes a summary. Checkpoints (by default
+every *participants × 3* turns) pause the discussion so you can steer it.
+
+### When does a participant stop for you?
+
+Ordinary mentions of `@Human` do **not** pause anything. A participant blocks for
+your answer only by starting a line with:
+
+```text
+HUMAN INPUT REQUIRED: <the question>
+```
+
+The discussion then waits; **Ctrl+Q** jumps to the question and your reply resumes it.
+
+### Asking the builder for files
+
+Role participants only read, so every discussion also has a **builder**. Mention
+`@builder` in a comment together with a request, for example
+`@builder write the agreed plan to plan.md`. The builder runs before anyone else
+speaks, works in the discussion's own folder (`discussions/<id>/files/`) and replies
+with what it did; the discussion then continues as after any comment. It uses the
+moderator's agent, model and thinking level.
+
+Only your comments start it: a participant's `@builder` or `@all` never does.
+`/reset @builder` cancels a request it hasn't started.
+
+## Controls
+
+| Where | Keys |
+|---|---|
+| Everywhere | Tab / Shift+Tab: next/previous section or field · Ctrl+C: quit |
+| Lists | ↑/↓ select · Enter open · n new · r refresh · q quit · / filter (Discussions) · e edit, d delete (Participants, Teams; asks first) |
+| Forms | Ctrl+S save · Ctrl+G suggestions · Esc cancel |
+| New discussion | Alt+→ / Alt+← next/previous step · Alt+N add participant · Alt+T load team · Ctrl+Enter start (Review only) |
+| Discussion | Enter send · Shift+Enter or Alt+Enter newline · Esc or `/pause` pause after turn · `/resume` · Ctrl+X stop response · Ctrl+Q question · Ctrl+B latest · F1 help · F2 details |
+| Discussion commands | `@builder <request>` (in a comment) · `/next @name [note]` · `/mute @name` · `/unmute @name` · `/reset @name` · `/wrap` · `/retry` · `/back` |
+
+Destructive confirmations (delete, take over, leave while an agent is speaking)
+always default to **Cancel**; you have to move to the named action deliberately.
+
+## What it runs, and what leaves your machine
+
+- **Model providers receive the discussion.** Every turn sends the topic, the
+  discussion so far, the participant's instructions and **any files the participant
+  reads** to that participant's model provider. Do not include secrets.
+- **Project participants can change their project.** pi runs them in the project
+  folder with `read`, `bash`, `edit`, `write`, `grep`, `find` and `ls`, no MCP
+  (`--tools read,bash,edit,write,grep,find,ls --exclude-tools mcp__* --no-mcp`), and they
+  may do so during rounds without asking. **Commands run as you**, so nothing confines
+  them to the folder; they are only told to stay in it. Use version control in project
+  folders you add.
+- **Role participants are read-only.** pi runs them in their role folder with only
+  `read`, `grep`, `find` and `ls`, no MCP. They cannot edit files or run commands.
+- **The builder changes files only when you ask**, with the same tools as project
+  participants, in `discussions/<id>/files/`. Its commands also run as you; it is told
+  to keep its changes in that folder and away from the discussion's record.
+- **Changes are listed under each turn.** The files a turn wrote or edited and the
+  commands it ran are taken from pi's tool events, not from the reply. A stopped or
+  failed turn is not recorded, so it may have changed files without a list.
+- **The moderator has no tools** (`--no-tools --no-mcp`). It only writes summaries.
+- pi otherwise uses your normal pi login and settings, so its own configuration and
+  extensions still apply. `TEAM_DISCUSS_PI_BIN` can point at a specific `pi` binary.
+- **Nothing runs in the background.** A discussion only runs while its view is open.
+  Leaving or quitting stops the current turn and waits for the agent processes to
+  exit. One exception: a command that a project participant or the builder starts in
+  the background (such as a dev server) can outlive its turn, because pi runs commands
+  in their own process group.
+- **Costs.** Displayed costs and tokens are for **completed, recorded turns only**.
+  Stopped, failed or interrupted turns can still be billed by your provider. The
+  default model and thinking level are expensive; choose cheaper ones per profile if
+  you like.
+
+## Your data
+
+Everything is stored locally in `~/.team-discuss` (override with
+`TEAM_DISCUSS_HOME`). Keep it on a **local disk**, not a network or cloud-synced
+folder. Folders are private (`0700`) and files `0600`.
+
+| Path | Contents |
+|---|---|
+| `config.json` | Default moderator agent/model/thinking and checkpoint factor |
+| `participants/<name>/` | Profile, and for roles a `workspace/` reference folder shared by that role's discussions |
+| `teams/<name>.json` | Team name and ordered member names |
+| `discussions/<id>/` | `events/` (the authoritative record), a generated `transcript.md` and `files/`, the builder's folder |
+
+- Discussions keep a frozen copy of their participants, so editing or deleting a
+  profile never changes old history.
+- Deleting a profile deletes its role reference folder and removes it from teams;
+  it never touches project folders or history. The app always shows what will be
+  removed and asks first.
+- `transcript.md` is regenerated from `events/`; manual edits to it are overwritten.
+- Opening a discussion takes a lock. A second window opens it read-only and can
+  take over after a warning.
+
+## More
+
+- [Design](https://github.com/siriuslan/pi-packages/blob/main/apps/team-discuss/DESIGN.md)
+  and [development notes](https://github.com/siriuslan/pi-packages/blob/main/apps/team-discuss/docs/DEVELOPMENT.md)
+  (building, tests, verification record).
+- [Agent capability probes](https://github.com/siriuslan/pi-packages/blob/main/apps/team-discuss/PROBES.md).
+- [Release checklist](https://github.com/siriuslan/pi-packages/blob/main/apps/team-discuss/docs/RELEASE.md).
+
+## License
+
+MIT