@nidvue/teamwork 0.0.0-stage → 1.1.0

package/skills/teamwork/templates/Docs/Board.md

@@ -0,0 +1,28 @@
+# BOARD - live status
+
+Owner: Project Manager. Machine view: `teamwork.py board`. This file is the human
+summary plus the blocker list.
+
+Related: [Project](Project.md) · [Plan](Plan.md) · [Architecture](Architecture.md) · [Decisions](Decisions.md) · [Research](Research.md) · [Design](Design.md) · [Risks](Risks.md) · [Costs](Costs.md) · [Archive](Archive.md)
+
+## Snapshot
+
+- Date: - Milestone: - Verified criteria: <n>/<m>
+
+## In flight
+
+| agent | task | prio | state | artifact |
+|---|---|---|---|---|
+| | | | | |
+
+## Blocked
+
+| task | waiting on | owner | unblock action |
+|---|---|---|---|
+| | | | |
+
+## Duplicate or conflicting work
+
+| what | owners | resolution |
+|---|---|---|
+| | | |

package/skills/teamwork/templates/Docs/Costs.md

@@ -0,0 +1,30 @@
+# COSTS - budget, unit economics, ROI
+
+Owner: CFO. Every number states its assumption and check date. Escalate early if a
+cap is projected to be hit.
+
+Related: [Project](Project.md) · [Plan](Plan.md) · [Board](Board.md) · [Architecture](Architecture.md) · [Decisions](Decisions.md) · [Research](Research.md) · [Design](Design.md) · [Risks](Risks.md) · [Archive](Archive.md)
+
+## Cost model
+
+| driver | unit | rate | volume | monthly | note |
+|---|---|---|---|---|---|
+| | | | | | |
+
+## Budget
+
+- Approved: - Hard caps and behaviour at cap: - Current burn:
+
+## Unit economics
+
+- Cost per user / task / run: - Break-even assumption:
+
+## Build vs buy
+
+| need | build | buy | recommendation | reason |
+|---|---|---|---|---|
+| | | | | |
+
+## Sources
+
+- [title](https://full-url) - accessed YYYY-MM-DD

package/skills/teamwork/templates/Docs/Decisions.md

@@ -0,0 +1,26 @@
+# DECISIONS
+
+Owner: Architect for technical entries, CEO for governance, tribunal and red-line
+entries. Append-only, newest last, binding. Every entry is traceable: it names who
+decided, on what evidence, and what would falsify it.
+
+Related: [Project](Project.md) · [Plan](Plan.md) · [Board](Board.md) · [Architecture](Architecture.md) · [Research](Research.md) · [Design](Design.md) · [Risks](Risks.md) · [Costs](Costs.md) · [Release](Release.md) · [Archive](Archive.md)
+
+## D-0001 - <title>
+
+- date: YYYY-MM-DD
+- kind: technical | governance | redline | tribunal | scope | cost | process
+- status: proposed | accepted | superseded | rejected
+- deciders: <role or instance>
+- decided by: <instance>
+- task: <T-id>
+- context: <the problem, one or two lines>
+- options considered: <A - pro/con; B - pro/con>
+- decision: <what>
+- why: <the reasoning from evidence to conclusion>
+- evidence: `<command or measurement> @<rev> -> <result>`
+- falsified by: <the observation that would overturn this>
+- consequences: <follow-ups, affected docs and lanes>
+
+Record entries with `teamwork.py decision add --by <instance> ...` so they also
+land in the tamper-evident ledger (`teamwork.py ledger verify`).

package/skills/teamwork/templates/Docs/Design.md

@@ -0,0 +1,106 @@
+# DESIGN - UX, interaction, accessibility, visual assets
+
+Owner: Designer. Developer-ready specs, not illustrations of finished code, plus
+the record for every visual asset (raster and vector) the deliverable needs.
+
+Related: [Project](Project.md) · [Plan](Plan.md) · [Board](Board.md) · [Architecture](Architecture.md) · [Decisions](Decisions.md) · [Research](Research.md) · [Risks](Risks.md) · [Costs](Costs.md) · [Archive](Archive.md)
+
+## Principles
+
+User first. Every choice - layout, typography, font, colour, image - is justified
+by the user's task, not by taste. Simplicity, efficiency, usability and a great
+experience, in that order. See `roles/designer.md` for the full policy.
+
+| principle | what it means here | check |
+|---|---|---|
+| Simple | shortest correct path, one primary action, remove before adding | steps in the primary flow |
+| Efficient | fewest actions, no dead ends, progressive disclosure | actions to complete the task |
+| Usable | keyboard, focus, contrast, targets, semantics, zoom | contrast >= 4.5:1, target >= 24px, 200% zoom |
+| Great experience | consistent states, honest errors, no dark patterns | every state specified |
+
+## Typography and fonts
+
+| field | value |
+|---|---|
+| type scale | e.g. 12 / 14 / 16 / 20 / 28 px |
+| body size / line height | >= 16 px / 1.4-1.6 |
+| measure | 45-75 characters |
+| font stack | `<platform stack>`, fallbacks stated explicitly |
+| shipped font? | name + licence + subset, or "none - platform stack" |
+| text-as-image | never; all text is real text |
+
+## Flows
+
+| flow | entry | steps | success | errors | a11y |
+|---|---|---|---|---|---|
+| | | | | | |
+
+## Components and states
+
+| component | default / hover / focus / active / disabled / loading / empty / error | tokens |
+|---|---|---|
+| | | |
+
+## Visual system
+
+- Spacing / type / colour tokens: ...
+- Layout and breakpoints: ...
+- Motion: ...
+
+## Copy
+
+| context | string |
+|---|---|
+| | |
+
+## Visual assets
+
+You decide what the deliverable needs and you own it end to end - see
+`roles/designer.md` for the policy, the model ranking and the improvement loop.
+Vector first; raster only where the surface needs one.
+
+### Capability
+
+| field | value |
+|---|---|
+| probe | `<teamwork imaging probe>` output (provider, model, source) |
+| model licence | |
+| local fallback | |
+| cloud prompt policy | no private data, no real people, metadata stripped |
+| medium decision | vector first; say why for each raster |
+
+### Assets
+
+| id | asset | medium | purpose / surface | path | size | candidates | status |
+|---|---|---|---|---|---|---|---|
+| IMG-1 | | svg / raster / diagram | | | | 4 (raster) | planned |
+
+### IMG-1 - <name>
+
+- medium: `<svg | raster | diagram-as-code>` and why
+- prompt (raster) or viewBox/tokens (vector): `<verbatim>`
+- negative: `text, letters, words, watermark, logo, ...`
+- seed base (raster): `<n>` (candidate i uses seed+i)
+- acceptance criteria: composition and safe area, legibility at 16 px and 2x,
+  no rendered text, correct anatomy, palette match, no watermark, resolution and
+  sharpness, accessible title/desc for vector
+- licence / terms:
+- candidates reviewed:
+- selected:
+- evidence: `<command @rev -> observed result>`
+
+### Review log
+
+| candidate | verdict | reason | reviewer |
+|---|---|---|---|
+| IMG-1-0 | | | |
+
+### Improvement log
+
+| round | what changed | why (criterion) | review after |
+|---|---|---|---|
+| 1 | | | |
+
+> Cap: three improvement rounds per asset. If it still fails, escalate to the CEO
+> with the criteria it cannot meet and the two best attempts. Never lower a
+> criterion to make an asset pass, and never delete a rejected attempt.

package/skills/teamwork/templates/Docs/Plan.md

@@ -0,0 +1,24 @@
+# PLAN - milestones and task graph
+
+Owner: Project Manager. One row per task; `deps` must be `done` before it runs.
+Priority: P0 code, P1 tests, P2 docs.
+
+Related: [Project](Project.md) · [Board](Board.md) · [Architecture](Architecture.md) · [Decisions](Decisions.md) · [Research](Research.md) · [Design](Design.md) · [Risks](Risks.md) · [Costs](Costs.md) · [Release](Release.md) · [Archive](Archive.md)
+
+## M1 - <name>
+
+Exit: <verifiable statement>
+
+| id | task | role | prio | deps | artifact | status |
+|---|---|---|---|---|---|---|
+| T-0001 | Freeze interfaces | architect | P0 | - | Architecture.md | todo |
+| T-0002 | Implement + unit tests | developer | P0 | architect:T-0001 | src/... | todo |
+| T-0003 | Integration/E2E tests | tester | P1 | architect:T-0001 | tests/... | todo |
+| T-0004 | UX spec | designer | P1 | architect:T-0001 | Design.md | todo |
+| T-0005 | Docs | product-manager | P2 | developer:T-0002 | docs/... | todo |
+
+## Parallel rules
+
+- Freeze interfaces first, then run dev / test / design lanes concurrently.
+- Tests are written from the frozen contract, in parallel with implementation.
+- Docs never block code or tests.

package/skills/teamwork/templates/Docs/Project.md

@@ -0,0 +1,40 @@
+# PROJECT - <name>
+
+Owner: CEO. Single source of truth for *what done means*. No task closes without
+mapping to an acceptance criterion here.
+
+Related: [Plan](Plan.md) · [Board](Board.md) · [Architecture](Architecture.md) · [Decisions](Decisions.md) · [Research](Research.md) · [Design](Design.md) · [Risks](Risks.md) · [Costs](Costs.md) · [Release](Release.md) · [Archive](Archive.md)
+
+## Objective
+
+<one paragraph: what we are building and what "finished" means>
+
+## Definition of done
+
+- [ ] AC-1 <verifiable statement> - proof: `<command or artifact>`
+- [ ] AC-2 ...
+- [ ] All criteria verified by executed evidence on a recorded revision
+- [ ] Unit + integration tests pass; docs match merged code
+
+## Scope
+
+- In: ...
+- Out (not doing): ...
+- Constraints (time / budget / technical): ...
+- Invariants that must not break: ...
+
+## Metrics
+
+| Metric | Target | How measured |
+|---|---|---|
+| | | |
+
+## Assumptions and open questions
+
+| # | Item | Owner | Status | Resolution |
+|---|---|---|---|---|
+| 1 | | | open | |
+
+## Sources
+
+- [title](https://full-url) - accessed YYYY-MM-DD

package/skills/teamwork/templates/Docs/Release.md

@@ -0,0 +1,43 @@
+# RELEASE - build, ship, roll back
+
+Owner: Release Engineer. The canonical answer to "how does this get built, shipped,
+verified and reverted". Keep it executable: every command here must run as written.
+
+Related: [Project](Project.md) · [Plan](Plan.md) · [Architecture](Architecture.md) · [Decisions](Decisions.md) · [Archive](Archive.md)
+
+## Build
+
+| step | command | expected result |
+|---|---|---|
+| clean checkout | | |
+| build | | |
+| package / artefact | | |
+| provenance (hash, signing) | | |
+
+## CI gates
+
+| gate | command | blocks a merge? |
+|---|---|---|
+| | | |
+
+## Deploy
+
+- environments and what differs between them:
+- order of operations (migrations first? feature flag?):
+- configuration and secrets *mechanism* (never values):
+
+## Rollback
+
+- one command to return to the previous version:
+- what is *not* reversible (data migrations) and how it is handled:
+- last drill: `<command> @<rev> -> <result>` (date, duration, outcome)
+
+## Observability
+
+- metrics, logs, traces, dashboards:
+- alerts and their thresholds:
+- runbooks:
+
+## Sources
+
+- [title](https://full-url) - accessed YYYY-MM-DD

package/skills/teamwork/templates/Docs/Research.md

@@ -0,0 +1,36 @@
+# RESEARCH - market, competitors, state of the art
+
+Owner: Product Manager. Every claim carries a source and an access date; anything
+unverified is marked UNVERIFIED.
+
+Related: [Project](Project.md) · [Plan](Plan.md) · [Board](Board.md) · [Architecture](Architecture.md) · [Decisions](Decisions.md) · [Design](Design.md) · [Risks](Risks.md) · [Costs](Costs.md) · [Archive](Archive.md)
+
+## 1. Problem and users
+
+## 2. Alternatives compared
+
+| solution | approach | strengths | weaknesses | licence / price | relevance |
+|---|---|---|---|---|---|
+| | | | | | |
+
+## 3. State of the art
+
+- Dominant techniques and why: ...
+- Changes in the last 12-18 months: ...
+- Benchmarks (numbers, not adjectives): ...
+
+## 4. What practitioners ship
+
+## 5. Gap analysis
+
+| gap | evidence | opportunity | risk | recommendation |
+|---|---|---|---|---|
+| | | | | |
+
+## 6. Recommendation
+
+<build this, not that, because ...>
+
+## Sources
+
+- [title](https://full-url) - accessed YYYY-MM-DD

package/skills/teamwork/templates/Docs/Risks.md

@@ -0,0 +1,18 @@
+# RISKS - risk register
+
+Owner: COO. Reviewed at every integration point. No entry without an owner and a
+mitigation - otherwise escalate to the CEO instead of recording it.
+
+Related: [Project](Project.md) · [Plan](Plan.md) · [Board](Board.md) · [Architecture](Architecture.md) · [Decisions](Decisions.md) · [Research](Research.md) · [Design](Design.md) · [Costs](Costs.md) · [Archive](Archive.md)
+
+| id | risk | category | likelihood | impact | mitigation / trigger | owner | status |
+|---|---|---|---|---|---|---|---|
+| R-1 | | tech / delivery / security / cost | low-med-high | low-med-high | | | open |
+
+## Process health
+
+- Cycle time: - Blocked hotspots: - Duplicate work seen: - Tooling gaps:
+
+## Sources
+
+- [title](https://full-url) - accessed YYYY-MM-DD

package/skills/teamwork/templates/TeamMap.md

@@ -0,0 +1,100 @@
+# Team map
+
+The team's own tree. **Hidden and independent of project output.** Every name is
+PascalCase; one tree per team, so two teams in one repository never collide.
+
+```text
+{project}/.pi/Teamwork/Teams/<Team>/     # this tree (hidden, never committed)
+├── TeamMap.md            # this map
+├── Settings.json         # provider caps
+├── Global/               # CEO-owned shared memory
+│   ├── GlobalMemory.md
+│   └── GlobalMemoryArchive.md   (created on first eviction)
+├── Criteria.md           # acceptance criteria + verification evidence
+├── Tests.md              # one record per test layer and area
+├── TestPlan.md          # required layers per area
+├── Ledger.jsonl         # append-only, hash-chained audit trail
+├── Skills.md            # team-skill registry
+├── Disputes.md           # design/decision challenges
+├── Reviews.md            # PRs awaiting / passed the Reviewer
+├── Roles/<Role>/         # SHARED memory + queue for every instance of a role
+│   ├── Role.md
+│   ├── ShortTermMemory.md
+│   ├── LongTermMemory.md
+│   ├── ArchivedMemory.md
+│   └── TaskQueue.md
+├── Agents/<Instance>/    # private to one instance
+│   ├── StartHere.md  WorkLog.md  Inbox.md
+│   └── Artifacts/  Reports/  Scratch/
+└── Runtime/              # ephemeral
+    ├── LedgerHead.json
+    ├── Locks/
+    ├── Worktrees/<Instance>/       # optional per-instance worktree
+    └── Slots/<Provider>/<Agent>.slot
+```
+
+Project output - code, tests and the reviewed documents in `{docs}/` - lives in
+the repository and is committed. The team tree above is local state and is
+gitignored.
+
+## Team
+
+- Team name: `<Team>`
+- Project: `{project}`
+- Team root: `.pi/Teamwork/Teams/<Team>/`
+
+## Audit trail
+
+Every mutation appends one hash-chained record to `Ledger.jsonl`, and every record
+carries provenance (actor, role, target, revision). Verify it, follow a claim, or
+export an externally checkable manifest:
+
+```sh
+python3 {skill}/scripts/teamwork.py ledger verify      # recompute the chain
+python3 {skill}/scripts/teamwork.py ledger show --tail 40
+python3 {skill}/scripts/teamwork.py trace <T-id>
+python3 {skill}/scripts/teamwork.py ledger export      # -> {docs}/AuditManifest.json
+```
+
+## Commands
+
+```sh
+python3 {skill}/scripts/teamwork.py map                       # this map + detected code/test dirs
+python3 {skill}/scripts/teamwork.py agents                    # roles, instances, queue sizes
+python3 {skill}/scripts/teamwork.py board                     # shared queues and next task per role
+python3 {skill}/scripts/teamwork.py parallel                  # free slots vs ready work
+python3 {skill}/scripts/teamwork.py task next <instance>      # claim the next task of your role
+python3 {skill}/scripts/teamwork.py load <instance>           # your role's short-term memory
+python3 {skill}/scripts/teamwork.py recall "<query>" --all    # search long-term + global memory
+```
+
+## Quality gates and integration path
+
+```text
+branch start -> commit -> SelfCheck -> Review -> done -> merged into main
+                            (owner)    (Reviewer)          (Reviewer only)
+```
+
+The owner self-reviews and self-tests, then the Reviewer verifies independently.
+Every agent works on its own branch; `main` only receives Reviewer merges, and a
+merged branch is deleted.
+
+Every role owns one test layer: `goal` CEO, `requirements` Product Manager, `plan`
+Project Manager, `tech` CTO, `release` Release Engineer, `data` Data Engineer,
+`process` COO, `cost` CFO, `system` Architect, `ui` Designer, `docs` Technical
+Writer, `unit` Developer, `integration` Tester, `acceptance` Reviewer, `security`
+Security Auditor. `tests plan` shows coverage and gaps; the default per area is the
+core set (`unit`, `integration`, `acceptance`).
+
+## Concurrency
+
+Caps in `Settings.json` (Ollama Cloud 64, DeepSeek official API ~2500, openai/anthropic 64). Hold a
+lease for model-heavy work: `slot acquire --agent <instance>`, `slot renew`,
+`slot release`. At the cap, do work needing no slot or fan out on another
+provider - never block.
+
+## Priority
+
+1. **Code** - working, reviewed, merged implementation.
+2. **Tests** - unit tests (Developer) and integration/E2E tests (Tester), run.
+3. **Documentation** - from verified code, never blocking 1 or 2.

package/skills/teamwork-pi/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: teamwork-pi
+description: "pi native layer for the teamwork skill - how a pi agent spawns and steers team lanes with subagent, schedules the pulse, and replies to lane decisions. Use together with /skill:teamwork when running a team on pi."
+---
+
+# Teamwork on pi
+
+Owner: CEO. Related: `../teamwork/SKILL.md` (the protocol) · `../teamwork/references/Adapters.md` · `../teamwork/references/Concurrency.md`
+
+The core skill is host-agnostic. This one maps its six host operations onto the
+tools a pi session actually has. Read it once per session, then work from the core
+skill.
+
+## Six operations
+
+| Operation | On pi |
+|---|---|
+| spawn a lane | `subagent({ agent, task, async: true, cwd })` |
+| fan many lanes out | `subagent({ workflow: "./packet.js", async: true })` with `runs.all([...])` inside |
+| send a fact to a lane | `subagent({ action: "steer", id, message })` while it runs; `subagent_supervisor({action:"reply"})` for a child that asked |
+| inspect | `subagent({ action: "status", id })`, `subagent_supervisor({action:"list"})` |
+| pulse | `subagent({ action: "schedule.create", id: "teamwork-pulse", workflow: "./.pi/workflows/teamwork-pulse.js", options: { every: "5m" } })` |
+| close | `subagent({ action: "stop", id })` per live lane, then the final report |
+
+There is no `teams()` tool on pi. A lane is a bounded run: it reads its role
+charter and the shared queue, takes work with `task next`, commits, self-checks,
+opens a PR and returns. The queue - not the tool - is what makes the team.
+
+## Agent names
+
+`software-architect` (architect), `product-manager`, `project-manager` is not a
+subagent, so the plan lane runs through `delegate` with the instance name stated
+in the packet; `developer`, `tester`, `reviewer`, `security-auditor`,
+`release-engineer` runs through `delegate`, `designer`, plus builtins `delegate`,
+`worker`, `oracle`, `scout`, `researcher`.
+
+State the instance name in the packet (`developer-1`, `reviewer-2`) and require it
+in every `--by` flag, because provenance is recorded per instance.
+
+## Packet shape that survives a bounded lane
+
+At most two features, numbered steps with exact commands, a tool-call budget
+(<= 16) and a hard minute budget, an explicit "stop and report the blocker"
+clause, and an anchor-first reading rule (`grep -n` then read +/-30 lines). Lanes
+that were given open-ended verification timed out at 30 minutes with zero commits;
+the same work finished in 8 calls when the packet named the commands.
+
+## Pulse workflow
+
+`.pi/workflows/teamwork-pulse.js`:
+
+```js
+export default async function (ctx) {
+  return await ctx.runs.all([{
+    key: 'pulse',
+    agent: 'delegate',
+    task: `Teamwork pulse in ${ctx.cwd}: run
+      python3 ${ctx.cwd}/scripts/teamwork.py pulse --commit, then message every
+      assigned lane to start now, give each idle lane its highest-priority
+      unblocked task, unblock what is stuck, aim a DIFFERENT Reviewer lane at each
+      unclaimed deliverable, and report one short line. Never stop the team while
+      loop says CONTINUE.`,
+  }]);
+}
+```
+
+## Rules that cost us real time
+
+- A lane that cannot run `teamwork` needs `TEAMWORK_ROOT=<repo>/.pi/Teamwork/Teams/<Team>`
+  exported; a worktree does not carry `.pi/`.
+- Worktree isolation is refused on a dirty tree; run lanes in the shared checkout
+  and commit with `--paths` so no lane sweeps a peer's uncommitted work.
+- A review verdict names the revision it measured; a lane that reviewed a stale
+  head is re-dispatched with the head sha and told to assert it first.
+- One task, one branch: `branch start` creates the branch from the default branch
+  and switches the checkout, so start it before writing and never from a lane
+  branch.