@nidvue/teamwork 0.0.0-stage → 1.1.1

package/README.md

@@ -1,3 +1,463 @@
-# Temporary Holding Version
+<div align="center">
+  <img src="https://raw.githubusercontent.com/Nidvue/Teamwork/main/assets/banner.svg" alt="Teamwork banner: three connected nodes and the pitch 'One prompt in. A whole company of agents out.'" width="100%">
+  <img src="https://raw.githubusercontent.com/Nidvue/Teamwork/main/docs/assets/nidvue-icon.svg" alt="Nidvue" width="88" height="88">
+  <h1>Nidvue Teamwork</h1>
+  <p><strong>One prompt in. A whole company of agents out.</strong></p>
+  <p>An autonomous, self-organising multi-agent company for coding agents:<br>
+  evidence-gated, role-shared, and auditable by design.</p>
+  <p>
+    <a href="https://github.com/Nidvue/Teamwork/actions/workflows/ci.yml"><img alt="CI status" src="https://img.shields.io/github/actions/workflow/status/Nidvue/Teamwork/ci.yml?branch=main&amp;label=CI&amp;logo=github"></a>
+    <a href="LICENSE"><img alt="License: AGPL-3.0" src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg"></a>
+    <a href="docs/Team/Architecture.md"><img alt="Python 3.9 to 3.13" src="https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue"></a>
+    <a href="docs/guide/install.md"><img alt="Skill: one clone to install" src="https://img.shields.io/badge/skill-install%20in%20one%20clone-8957e5"></a>
+    <a href="CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg"></a>
+    <a href="https://github.com/Nidvue/Teamwork/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/Nidvue/Teamwork?style=social"></a>
+  </p>
+</div>
 
-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.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Nidvue/Teamwork/main/assets/demo.svg" alt="Animated terminal: one git clone installs the skill, one request that names the skill starts the company, and the loop gate reports CONTINUE until every acceptance criterion is verified." width="820">
+</p>
+
+Nidvue Teamwork is **a skill for your coding agent** - not a standalone
+application. Install it like any other skill (one clone, no package manager), then
+ask your agent for the team:
+
+```text
+> use the teamwork skill: Build a URL shortener with a CLI, tests and docs
+```
+
+That prompt becomes a team of AI agents that plans, builds, tests and
+**independently reviews its own work until every acceptance criterion has
+executed evidence**. The agent host supplies the LLM API, and **every agent's model
+is configured independently** (`teamwork model set <agent>`): a strong model for the
+Reviewer, a cheap one for the mechanical lanes. The engine (`teamwork.py`, standard
+library only) ships inside the skill and is what the CEO calls; installing it as a package is optional.
+
+## Why Teamwork
+
+| # | Differentiator | What it means in practice |
+|---|---|---|
+| 1 | **Evidence or `UNVERIFIED`** | A task cannot reach `done` without a recorded `command @revision -> result`. Evidence is a packet - baseline, action, result, hashed artifact, replay - and a bug fix must prove the failure before the fix. `teamwork loop` refuses `STOP` while any criterion or required test layer is unverified. |
+| 2 | **Role-shared memory** | Memory and the priority queue belong to the **role**, not the instance (`Roles/Developer/` is shared by `Developer-1..N`). Agents reuse verified facts instead of re-asking, and the CEO pulse feeds every idle lane. |
+| 3 | **Hash-chained audit trail** | Every mutation is appended to `Ledger.jsonl` with `by` / `src` / `rev` provenance. `ledger verify` detects tampering, `trace T-0007` follows a claim end to end, and `ledger export` writes a manifest anyone can check without trusting the team. |
+
+## Features
+
+| Feature | What you get |
+|---|---|
+| Autonomous org | 15 role charters - CEO, CTO, COO, CFO, Architect, Product Manager, Project Manager, Designer, Developer, Tester, Release Engineer, Technical Writer, Data Engineer, Reviewer, Security Auditor. |
+| Two-stage quality gate | The author self-checks with a real test, then a **different** role reviews from scratch. Only the Reviewer may merge. |
+| Parallel lanes | Freeze interfaces first, then developer, tester and designer lanes run concurrently against one frozen contract. |
+| Layered tests | Each role designs, builds and runs its own test layer (`unit`, `integration`, `acceptance`, `ui`, `security`, ...); `tests plan` shows coverage and gaps. |
+| Designed images | The Designer owns every visual asset, raster **and** vector, and decides what the deliverable needs: vector first (SVG, diagram-as-code), and for a raster `imaging probe` picks the best available text-to-image model (cloud first, else local, else SVG), then plan -> 4+ candidates -> visual review -> improve until it passes -> integrate, with privacy and licence rules. |
+| Stop condition as a record | Acceptance criteria are machine records, not checkboxes. The loop stops only when they are all verified. |
+| Role-shared state | One memory and one priority queue per role; a private, disposable workspace per instance. |
+| Concurrency control | Provider slot leases respect per-provider caps, so N agents never overload a model endpoint. |
+| Disputes and tribunal | A challenged design goes through evidence rounds; a 3-round deadlock is ruled on by the CEO + CTO + CFO and recorded. |
+| Portable, dependency-free | CPython 3.9-3.13 on Linux, macOS and Windows. **Zero third-party runtime dependencies.** |
+| Enforced standards | One canonical toolchain per language, run by the team: `ruff format` + `ruff check` gate CI, `mypy` runs as a non-blocking report (the engine is a tracked post-1.0 typing refactor); the full per-language table is in `references/Engineering.md`. |
+| Automatic model routing | `teamwork model auto` detects the running agent host where the environment identifies it and routes the strongest available model to the decision lanes and the economy model to the mechanical lanes - best output where it compounds, lowest cost where it does not. Every lane's model is configurable independently (`model set <agent>`). |
+| Clean, modular history | Work commits are rebased and squashed before review, feature work squash-merges into `main`, and the naming policy (PascalCase directories, ecosystem-correct files) is written down rather than argued about. |
+| Skill first, engine optional | The product is a skill: `SKILL.md`, role charters, references, templates and the stdlib-only engine in one directory. Any agent host that loads skills or reads `AGENTS.md` runs the same protocol (optional adapter mapping: `references/Adapters.md`); the Python package is only a convenience for driving the engine from a terminal. |
+| Remote-agnostic integrity | Branch protection, required checks, squash-only merges and protected `v*` tags are enforced on GitHub, GitLab, Bitbucket, Gitea/Forgejo or Azure DevOps alike. |
+
+## Install the skill
+
+Teamwork is a directory with a `SKILL.md`, the role charters, the references and
+the engine - no package manager, no daemon, no hosted service. Clone it where
+your agent discovers skills:
+
+| Scope | Path | Use it when |
+|---|---|---|
+| Project | `.agents/skills/teamwork/` | Commit it so every teammate, session and worktree gets the same protocol |
+| User | `~/.agents/skills/teamwork/` | You want the team available in every project |
+
+```bash
+# project-local: plain files in your repository, not a nested git repo
+mkdir -p .agents/skills
+git clone --depth 1 https://github.com/Nidvue/Teamwork.git .agents/skills/teamwork
+rm -rf .agents/skills/teamwork/.git
+
+# user-level: keep .git so `git pull` updates the skill
+git clone https://github.com/Nidvue/Teamwork.git ~/.agents/skills/teamwork
+```
+
+`rm -rf` of the nested `.git` is deliberate: without it git records the skill as a
+gitlink (a submodule without `.gitmodules`) and a fresh clone of your project gets
+an empty directory. The skill must be plain tracked files. Prefer a submodule?
+`git submodule add https://github.com/Nidvue/Teamwork.git .agents/skills/teamwork`
+works too - teammates then run `git submodule update --init`.
+
+Any host that discovers skills from a directory reads this one. A host without a
+skill loader uses the same protocol through `AGENTS.md` (`teamwork agents-md`).
+Exact search paths are host policy, not part of the skill; where a host names its
+own skills directory, put the clone there instead. The optional per-host adapter
+mapping is in [`references/Adapters.md`](https://github.com/Nidvue/Teamwork/blob/main/references/Adapters.md).
+
+Re-scan or reload skills in the host, then ask for the team by name:
+
+```text
+> use the teamwork skill: <prompt>
+```
+
+Where a host exposes skills as slash commands, the same request is
+`/teamwork <prompt>`. The host runs the bundled `scripts/teamwork.py` - Python
+3.9+, standard library only, no network access, nothing to build.
+
+### Optional: put the engine on your PATH
+
+The skill works without this step. Install the same engine as a package when you
+want to drive the team yourself from a terminal, or when your host cannot run a
+bundled script:
+
+```bash
+# pipx - isolated CLI, put on PATH
+pipx install teamwork-agents
+
+# uv - run without installing
+uvx --from teamwork-agents teamwork --version
+
+# pip
+python -m pip install teamwork-agents
+
+# from source
+git clone https://github.com/Nidvue/Teamwork.git
+cd Teamwork && python -m pip install .
+```
+
+Run it straight from a checkout without installing anything:
+
+```bash
+python3 scripts/teamwork.py --version    # teamwork 1.0.2
+```
+
+> The distribution name is `teamwork-agents` (the name `teamwork` is taken on
+> PyPI); the import name and the console script are both `teamwork`. PyPI
+> publishing is prepared but not enabled for this release - until then, install
+> from the [GitHub release](https://github.com/Nidvue/Teamwork/releases) wheel
+> or from source.
+
+## 30-second quickstart
+
+```bash
+# 1. install the skill (one clone, nothing to build; drop the nested .git so the
+#    skill is committed as plain files, not a submodule)
+$ mkdir -p .agents/skills && git clone --depth 1 https://github.com/Nidvue/Teamwork.git .agents/skills/teamwork && rm -rf .agents/skills/teamwork/.git
+
+# 2. in any project, ask your agent for the team
+$ cd my-project
+> use the teamwork skill: Build a URL shortener with a CLI, tests and docs
+```
+
+The CEO takes it from there: it writes `AGENTS.md`, staffs the roster, freezes the
+interfaces, records the acceptance criteria and opens the lanes. `init` creates
+the hidden, gitignored workspace at `.pi/Teamwork/Teams/<Team>/` and leaves your
+project tree untouched. Project output (`AGENTS.md`, code, tests, docs) is
+committed; team state is local.
+
+The skill calls the engine for you. When you want to see or steer the machine
+yourself, the same run is three commands:
+
+```bash
+$ teamwork agents-md     # write or patch the AGENTS.md constitution
+$ teamwork map           # the workspace layout, roles and instances
+$ teamwork criteria list # the machine records that define "done"
+```
+
+Read the full walkthrough in [`docs/guide/quickstart.md`](https://github.com/Nidvue/Teamwork/blob/main/docs/guide/quickstart.md).
+
+## For agents
+
+If you are the agent reading this repository, not the human who installed it: you
+can install and drive this skill yourself. Do the steps in order, and repeat them
+safely - every one is idempotent.
+
+### 1. Find the skill directory, then install
+
+A skill is a directory; the only host-specific part is where that directory is
+scanned from. Use your host's skills directory if it names one, otherwise the
+portable conventions below work.
+
+| Scope | Convention | When |
+|---|---|---|
+| Project | `.agents/skills/teamwork/` | The team protocol should travel with the repository |
+| User | `~/.agents/skills/teamwork/` | The team should be available in every project |
+
+```bash
+# already installed? any hit means yes
+ls .agents/skills/teamwork/SKILL.md ~/.agents/skills/teamwork/SKILL.md 2>/dev/null
+
+# not installed: clone once into the directory your host scans
+mkdir -p .agents/skills
+git clone --depth 1 https://github.com/Nidvue/Teamwork.git .agents/skills/teamwork
+rm -rf .agents/skills/teamwork/.git   # plain files, not a nested repo
+```
+
+### 2. Verify before you promise anything
+
+```console
+$ python3 .agents/skills/teamwork/scripts/teamwork.py selftest
+teamwork selftest: 5/5 checks passed
+```
+
+Use the directory you actually cloned to; the engine is the same in all of them.
+
+Exit `0` means the bundle and the engine are intact. Anything else: report the
+failure with the command and its output, and stop. Do not improvise a replacement.
+
+### 3. Follow the skill, from its own directory
+
+1. Read `<skill>/SKILL.md` completely, then `<skill>/roles/<your-role>.md` for the
+   role you are acting as.
+2. Run `scripts/teamwork.py init --roster slim` (or `standard`/`full`, or
+   `--agents` for an exact list; the skill usually does this for you) and
+   `agents-md` so the constitution is in place before any work starts.
+3. Claim work with `task next <you>`; never sit idle while ready work exists.
+4. Record evidence as `command @revision -> result`; submit with `selfcheck`, then
+   `pr open`. A different role reviews and merges - you never merge your own work.
+5. Stop only when `loop` prints `STOP` and `audit` reports no problems.
+
+Read [`references/Adapters.md`](https://github.com/Nidvue/Teamwork/blob/main/references/Adapters.md) for the six host
+operations, [`references/Concurrency.md`](https://github.com/Nidvue/Teamwork/blob/main/references/Concurrency.md) for slot
+leases and model routing, and [`docs/guide/quickstart.md`](https://github.com/Nidvue/Teamwork/blob/main/docs/guide/quickstart.md)
+for the workspace layout. Do not read the whole tree first; the skill is written
+to be loaded on demand.
+
+### 4. Rules that are not optional
+
+- No claim about code, tests or CI without a recorded command, revision and result.
+- Never fake a test run, never merge your own work, never weaken a gate.
+- A red line (secrets, force-push, publishing, production calls) is refused and
+  recorded with `redline` - then escalated, never executed.
+- The user talks to the CEO only. Every other role reports to its manager
+  (`teamwork.py map` draws the tree): the CTO for engineering, the COO for
+  planning, the Product Manager for requirements and docs. Escalate upward,
+  not sideways to the CEO.
+
+## Common ways to use it
+
+The transcripts are trimmed from a real run of the engine in this repository
+(paths elided); the prompts in A-C are illustrative.
+
+### A. New project from one prompt
+
+```console
+$ cd ~/code/url-shortener
+> use the teamwork skill: build a URL shortener - a CLI with shorten and expand,
+  SQLite storage, a pytest suite and a README. Keep it dependency-free.
+```
+
+The CEO writes `AGENTS.md`, records `AC-1..AC-n`, freezes the interfaces and opens
+the lanes. You keep working in the host; the team reports through the CEO.
+
+### B. A feature in an existing repository
+
+```console
+$ cd existing-repo
+$ mkdir -p .agents/skills && git clone --depth 1 https://github.com/Nidvue/Teamwork.git .agents/skills/teamwork && rm -rf .agents/skills/teamwork/.git
+> use the teamwork skill: add per-key rate limiting to the public API - 100
+  requests/minute, 429 with Retry-After, and tests that prove the boundary.
+```
+
+Committing `.agents/skills/teamwork` gives every teammate the same protocol on a
+fresh clone.
+
+### C. A bug or a red CI run
+
+```console
+$ cd repo
+> use the teamwork skill: fix the failing CI job on main, prove the fix with the
+  exact test command, and do not touch unrelated files.
+```
+
+The protocol degrades the same way everywhere: without a teammate tool one agent
+switches hats, and the evidence gates still hold (`references/Adapters.md`).
+
+### D. Steer the machine yourself
+
+The skill calls these for you; run them when you want to see or change the plan.
+
+```console
+$ teamwork init --roster slim          # or: teamwork init --agents ceo,architect,developer-1,tester-1,reviewer-1
+$ teamwork criteria add --id AC-1 --text "shorten then expand returns the original URL" --owner developer --by ceo
+$ teamwork criteria add --id AC-2 --text "pytest -q passes on the matrix" --owner tester --by ceo
+$ teamwork task add developer "Implement shorten/expand with tests" --priority P0
+$ teamwork loop
+
+> CONTINUE
+  ! 2 acceptance criteria unverified
+  ! no layered test records
+  ! 1 task(s) not finished
+```
+
+### E. Keep the lanes full
+
+```console
+$ teamwork pulse --interval 5
+$ teamwork parallel
+
+## provider slots
+- anthropic        used=0    cap=64    free=64
+- deepseek         used=0    cap=2500  free=2500
+- ollama-cloud     used=0    cap=64    free=64
+- openai           used=0    cap=64    free=64
+- TOTAL free slots: 2692
+
+## executable work
+- developer        1 ready  next: developer/T-0001 [P0] Implement shorten/expand with tests
+```
+
+`pulse --commit` dispatches to idle instances. `parallel` shows how many lanes may
+start without exceeding a provider cap.
+
+### F. Resume after a crash or a new session
+
+All state is on disk, so a fresh agent resumes without a handover meeting.
+
+```console
+$ teamwork load developer-1     # the role's short-term memory
+$ teamwork task next developer-1
+$ teamwork map                  # roles, instances, open work
+```
+
+### G. Prove the audit trail to someone who does not trust the team
+
+```console
+$ teamwork ledger verify
+# Ledger verify (.../Ledger.jsonl)
+# records: 5 | head: a23748ba85cf962f
+- chain intact, every digest matches
+
+$ teamwork trace T-0001
+## task T-0001 [todo] Implement shorten/expand with tests  (developer)
+## ledger events (1)
+- #0005 task.add  developer  [P0] Implement shorten/expand with tests
+```
+
+`ledger export` writes a manifest that a reviewer can verify without access to
+the workspace.
+
+### H. Route the models, not just the roles
+
+```console
+$ teamwork model auto
+- architect          strong   deepseek-v4.1-flash
+- ceo                strong   deepseek-v4.1-flash
+- developer          economy  deepseek-v4.1-flash
+- product-manager    economy  deepseek-v4.1-flash
+- project-manager    economy  deepseek-v4.1-flash
+- reviewer           strong   deepseek-v4.1-flash
+- tester             economy  deepseek-v4.1-flash
+# dry run: rerun with --apply to write these into Settings.json
+```
+
+Decision lanes get the strongest model the host exposes; mechanical lanes get the
+economy one. `model set <agent>` overrides a single lane.
+
+## How it works
+
+```mermaid
+flowchart TD
+    U[User prompt] --> CEO[CEO: intake, acceptance criteria, roster]
+    CEO --> RM[Product Manager: research and gaps]
+    CEO --> AR[Architect: frozen interfaces and ADRs]
+    CEO --> PJ[Project Manager: dependency-ordered tasks]
+    AR --> LANES
+    PJ --> LANES
+    CEO -.->|model auto: strong lanes, economy lanes| LANES
+    subgraph LANES[Parallel lanes]
+        DEV[Developer: code + unit tests]
+        TST[Tester: integration + E2E tests]
+        DES[Designer: UX and accessibility specs]
+    end
+    LANES --> SC[Author self-check: run your own test]
+    SC --> RV{Independent Reviewer}
+    RV -- fail + findings --> LANES
+    RV -- pass --> MG[Reviewer merges to main]
+    MG --> LP{teamwork loop}
+    LP -- criterion or layer failing --> LANES
+    LP -- every criterion verified --> STOP[STOP + final report]
+```
+
+Nothing is dispatched before the interfaces are frozen, and nothing reaches
+`main` without the Reviewer's own evidence. Everything else runs in parallel.
+
+## Teamwork vs alternatives
+
+| Project | Orchestration model | Evidence gate | Audit trail | Coding-agent skill | Zero runtime deps | License |
+|---|---|---|---|---|---|---|
+| **Nidvue Teamwork** | Persistent role org: shared role memory, priority queues, parallel lanes, CEO pulse | **Enforced** - `loop` blocks `STOP` until every criterion and required test layer has evidence | **Hash-chained** `Ledger.jsonl`, `ledger verify`, `trace`, `ledger export` | **Yes** - ships `SKILL.md`, `roles/`, `references/`, `templates/` | **Yes** - standard library only | AGPL-3.0 |
+| CrewAI | Role-based crews, sequential or hierarchical process | No | Task output and logs, not tamper-evident | No - Python library | No | MIT |
+| AutoGen | Event-driven multi-agent conversations | No | Conversation logs, not tamper-evident | No - Python library | No | CC-BY-4.0 (archived) |
+| MetaGPT | SOP-driven "software company" pipeline | No | Artifact files, not tamper-evident | No - Python library | No | MIT |
+| LangGraph | Stateful graph / state machine over LLM agents | No | Checkpointing, not hash-chained | No - Python library | No | MIT |
+| Aider | Single AI pair programmer in the terminal, git-aware | No | Git commits | No - terminal CLI | No | Apache-2.0 |
+
+Competitor facts were checked against each upstream repository and its GitHub
+licence metadata on 2026-10-17:
+
+- [crewAIInc/crewAI](https://github.com/crewAIInc/crewAI) - accessed 2026-10-17
+- [microsoft/autogen (archived)](https://github.com/microsoft/autogen) - accessed 2026-10-17
+- [FoundationAgents/MetaGPT](https://github.com/FoundationAgents/MetaGPT) - accessed 2026-10-17
+- [langchain-ai/langgraph](https://github.com/langchain-ai/langgraph) - accessed 2026-10-17
+- [Aider-AI/aider](https://github.com/Aider-AI/aider) - accessed 2026-10-17
+
+## Architecture at a glance
+
+One skill, one engine, one workspace format - the package is a thin face on the
+same files:
+
+```text
+Teamwork/
+├── SKILL.md                  # canonical skill entry (the host loads this)
+├── roles/ references/ templates/
+├── src/teamwork/             # engine, cli, resources, portable
+├── scripts/teamwork.py       # compatibility shim, stdlib only
+├── tests/{unit,integration,acceptance}/
+├── docs/                     # mkdocs site + docs/Team/ project documents
+├── assets/                   # SVG banner, logo, terminal demo
+└── .github/workflows/        # ci.yml, release.yml, docs.yml
+```
+
+The engine resolves its bundle from `$TEAMWORK_SKILL_DIR`, then the installed
+`teamwork/data/`, then the checkout - so it works identically from a git clone
+and from a wheel. The frozen contracts live in
+[`docs/Team/Architecture.md`](https://github.com/Nidvue/Teamwork/blob/main/docs/Team/Architecture.md); the design brief for
+this README and its visuals lives in [`docs/Team/Design.md`](https://github.com/Nidvue/Teamwork/blob/main/docs/Team/Design.md).
+
+## Roadmap
+
+| Version | Status | Focus |
+|---|---|---|
+| `v1.0.0` | released | Package, skill bundle, CLI, 15 role charters, layered tests, CI/release workflows, docs site. |
+| `v1.x` | current | Release wheel, checksums and SBOMs are shipped; the remaining step is PyPI trusted publishing. |
+| next | exploring | More provider adapters, end-to-end worked examples, an opt-in ledger dashboard. |
+
+Direction, not a promise: no hosted service, and stars cannot be bought - this
+project optimises the conversion inputs (demo, README, topics, license, releases).
+
+## Contributing, security and license
+
+- **Contributing** - work on your own branch, run `pytest -q` and `ruff check`,
+  and open a PR; a Reviewer - never the author - merges it. Read
+  [`CONTRIBUTING.md`](https://github.com/Nidvue/Teamwork/blob/main/CONTRIBUTING.md) and the
+  [code of conduct](https://github.com/Nidvue/Teamwork/blob/main/CODE_OF_CONDUCT.md).
+- **Security** - please report vulnerabilities privately via
+  [GitHub security advisories](https://github.com/Nidvue/Teamwork/security/advisories/new);
+  see [`SECURITY.md`](https://github.com/Nidvue/Teamwork/blob/main/SECURITY.md).
+- **License** - [AGPL-3.0](https://github.com/Nidvue/Teamwork/blob/main/LICENSE), copyright (C) 2026 **Nidvue** (see [NOTICE](https://github.com/Nidvue/Teamwork/blob/main/NOTICE)). The strong copyleft is deliberate: this is a
+  governance tool, and its audit guarantees should survive modification.
+- **No personal data, no local leakage** - a hard project rule: no personal
+  names, emails, domains, absolute home paths or credentials in the tree or the
+  history, and no agent-host configuration or local working state (`.pi/` auth,
+  settings and sessions, virtualenvs, build output, caches). `scripts/privacy_scan.py`
+  fails the build on any of them.
+  Identity defaults to `agents.nidvue.com` and is overridable with
+  `TEAMWORK_IDENTITY_DOMAIN`.
+
+## Star history
+
+<a href="https://star-history.com/#Nidvue/Teamwork&amp;Date">
+  <img src="https://api.star-history.com/svg?repos=Nidvue/Teamwork&amp;type=Date" alt="Star history chart for Teamwork" width="720">
+</a>

package/SECURITY.md

@@ -0,0 +1,64 @@
+# Security Policy
+
+Owner: Technical Writer.
+
+Related: [Contributing](CONTRIBUTING.md) · [Code of conduct](CODE_OF_CONDUCT.md)
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 1.0.x | Yes |
+| < 1.0 | No |
+
+Security fixes are released for the latest minor line.
+
+## Reporting a vulnerability
+
+Use [GitHub Security Advisories](https://github.com/Nidvue/Teamwork/security/advisories/new)
+to report a vulnerability privately. This is the **only** supported channel: no
+personal email address is published, and reports sent by other means cannot be
+guaranteed to reach the maintainers.
+
+Please include:
+
+- the affected version and platform;
+- a description of the issue and its impact;
+- reproduction steps or a proof of concept;
+- any suggested fix or mitigation.
+
+Do not open a public issue, and do not disclose the issue publicly before a fix
+is released.
+
+## Our process
+
+1. We acknowledge the report through the advisory thread as soon as possible.
+2. We confirm the issue and assess severity.
+3. We prepare and test a fix on a private branch.
+4. We release the fix and publish the advisory, crediting the reporter unless
+   they ask to remain anonymous.
+
+## Scope
+
+In scope: the `teamwork` package, the `teamwork` CLI, the bundled skill bundle,
+and the documented workspace format.
+
+Out of scope: vulnerabilities in third-party tools or services you run alongside
+Teamwork; social engineering; and reports that require access to a private
+machine.
+
+## Privacy allowlist
+
+`scripts/privacy_scan.py` runs with `--allow .github/privacy-allow.txt` in
+`make privacy` and in CI. The file holds one regular expression per line plus a
+reason; it exists so a false positive cannot force a history rewrite. It carries
+exactly one entry today (`^\.pi/agent/npm$`, a package path quoted by T-0001; the tree still carries the scanner's own
+fixture for it, and three history blobs match, so the gate needs the entry). A second entry needs a recorded decision and, if it
+masks a credential rule, the Security Auditor's review - growing the list is
+weakening the gate.
+
+## Safe harbour
+
+Good-faith security research is welcome. We will not pursue action against
+researchers who follow this policy, avoid privacy violations and data
+destruction, and do not exploit an issue beyond what is needed to demonstrate it.

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@nidvue/teamwork",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "description": "Nidvue Teamwork - an autonomous, self-governing agent company for pi: CEO-led decomposition, parallel lanes, two-stage review, hash-chained audit ledger and layered role-owned tests. Python 3.9+, stdlib only.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "nidvue",
+    "teamwork",
+    "multi-agent",
+    "orchestration",
+    "agents",
+    "skill"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "author": {
+    "name": "Nidvue contributors"
+  },
+  "homepage": "https://github.com/Nidvue/Teamwork",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nidvue/Teamwork.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Nidvue/Teamwork/issues"
+  },
+  "files": [
+    "skills",
+    "prompts",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "image": "https://raw.githubusercontent.com/Nidvue/Teamwork/main/assets/social-preview.png"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/prompts/teamwork-pulse.md

@@ -0,0 +1,12 @@
+Run one teamwork pulse in this project.
+
+1. `python3 scripts/teamwork.py pulse --commit` and read the dispatch plan.
+2. For every assignment it reports, message that lane to start now.
+3. For every idle lane with no matching work, give it the highest-priority
+   unblocked task of its role, or fold the lane.
+4. Unblock anything stuck (blocked task, open dispute, stale claim).
+5. For every unclaimed deliverable in `teamwork.py review --queue`, aim a
+   different Reviewer lane at it and never stack the backlog on one lane.
+6. Report one short line: what moved, what is blocked, what is next.
+
+Never stop the team while `teamwork.py loop` says CONTINUE.

package/prompts/teamwork-review.md

@@ -0,0 +1,16 @@
+Review one teamwork deliverable as an independent Reviewer.
+
+Claim it with `python3 scripts/teamwork.py review <role> <T-id> --claim --by <lane>`,
+then in at most 12 tool calls, without editing anything:
+
+1. Assert the revision: `git rev-parse --short <branch>` must equal the head you
+   were given; record it.
+2. Measure the gates yourself; never trust the author's numbers: tests, lint,
+   types, links, ledger, and the privacy gate exactly as the shipped target runs
+   it, with and without its allowlist.
+3. Read only the diff, with `grep -n` then a +/-30 line window.
+4. A claim that does not reproduce at that head is a finding with `file:line` and
+   the command that shows it.
+5. Record one verdict: `--result pass --evidence '<commands @sha -> results>'` or
+   `--result fail --findings '<defect + file:line + command>'`. A different
+   Reviewer merges; you never merge your own pass.