Install

install — team.json, the dispatch gate, and conventions

Connect the node-graph engine already shipped by this plugin and scaffold the project-owned files that give it defaults. Do not copy, regenerate, or fork the engine: mcp/broker.mjs, mcp/graph.mjs, mcp/taskmanager.mjs, mcp/teamconfig.mjs, and the bundled Codex adapter remain plugin-owned and are updated with the teams plugin. The deterministic file work — team.json, the dispatch gate file, conventions, the CLAUDE.md block, .gitignore — is delegated to install.mjs so it runs identically every time; this skill owns the judgment.

Process

1. Judgment, before running anything. Inspect the project's languages and source roots and propose dispatch patterns (e.g. src/**, packages/**); confirm them with the user. Ask which roles to turn on (planning, qa) — both default off. planning inserts a planning phase-Team (PRD draft → revise → gate) before shape, and its PRD and user stories feed shape's packages — and a second planning pass (audit → gate) after integration, which cross-checks the built result against those user stories and files a STORY for each one still unmet. qa inserts a QA phase-Team between integrate and gate:goal, reusing the repair worktree, to run a QA pass over the integrated tree before the goal gate judges it; a defect it finds is filed as a STORY too, and the EPIC loops back through integration (capped by qa_rounds, which caps audit rounds as well). If harness is already installed in this project, say so: .claude/conventions/ and the session-marker directory are shared between the two plugins.
2. Run:

   node "<plugin>/skills/install/install.mjs" '{
     "projectDir": "<abs project path>",
     "dispatch": {"paths": ["src/**"], "min_chars": 400, "allow": []},
     "team": {"goal_threshold": 90, "roles": {"qa": true}},
     "refresh": false
   }'
   

   Omit dispatch to skip the gate file entirely (no file means no gate).
3. Treat the printed report JSON as ground truth, not your own judgment. Report, per action, whether team.json, the dispatch file, each convention file, the CLAUDE.md block, and .gitignore came back created, kept, present, appended, refreshed, unchanged, or skipped.
4. Tool discovery — confirm all fifteen tools are visible: six team_* tools (team_open, team_next, team_run, team_submit, team_retry, team_status) and nine tm_* tools (tm_open, tm_next, tm_submit, tm_retry, tm_status, tm_events, tm_board, tm_ticket, tm_docs). If any are missing, tell the user to reload Claude Code — this is the install gate; do not open a real task just to test setup. Once a task is open, main watches it with tm_status({task_id}) and never drives a node itself.
5. "refresh": true only backfills keys a newer plugin version introduced into an existing team.json; it never changes a value the project already set. Use it after bumping the plugin version, not on a routine install.

Install modes

Prefer the marketplace plugin. Its .mcp.json already registers the teams-engineering and task-manager stdio servers, so installation should not add project files beyond what install.mjs writes. Ask the user to install or update teams@newkayak12-claude-skills and reload Claude Code if needed.

Use a project-local connection only when the user explicitly wants to run from a source checkout instead of the marketplace plugin. Merge this entry into the target project's existing .mcp.json; preserve every unrelated server and use an absolute path:

{
  "mcpServers": {
    "teams-engineering": {
      "command": "node",
      "args": ["/absolute/path/to/teams/mcp/broker.mjs"]
    },
    "task-manager": {
      "command": "node",
      "args": ["/absolute/path/to/teams/mcp/taskmanager.mjs"]
    }
  }
}

The task manager keeps its state under ~/.harness/tasks/ (override with HARNESS_TASKS_DIR), never under a project. It needs the project to be a git repository: each package of a large request runs in its own git worktree branched from HEAD.

Do not use ${CLAUDE_PLUGIN_ROOT} in a project-owned .mcp.json; that variable belongs to the plugin's own manifest. Do not register both marketplace and project-local copies: two servers exposing the same team_* tools make routing ambiguous.

Dispatch gate (optional)

The plugin ships a PreToolUse hook, installed with it — nothing to register. It does nothing until .claude/teams-dispatch.json exists, which install.mjs now writes from the dispatch argument (step 2) instead of by hand:

{"paths": ["src/**", "packages/**"], "min_chars": 400, "allow": ["**/*.generated.*"]}

With that file present, a write to a gated path is denied while no task is open, and the message tells the session to call tm_open instead. Once a task is open every write passes — nodes have to write. The point is the handoff at the start: the driving session dispatches the work rather than doing it inline, which keeps its context flat and puts every change through a gate, a reviewer of a different identity, and its own branch. Every field is optional, no file means no gate, and the hook fails open on any error.

Verification

1. Confirm node --version is 18 or newer.
2. Validate the selected server path exists when using project-local mode, then complete step 4 of Process above.
3. If a later task uses a named vendor, verify that vendor separately. orchestrate uses balanced allocation: reasoning prefers the driving host/model, Implement/Test prefer the other vendor's efficient model. It declares host_vendor, host_model, and supported native_models; external executors pass readiness checks. Fable/Astra require explicit model requests. Verify that role isolation is available before running work; an MCP connection alone does not provide new AI sessions. A bare tm_open({vendor: "auto"}) call stays on self; a named vendor fails instead of silently degrading.

What Claude does

• Proposes dispatch patterns and role toggles, runs install.mjs for every deterministic file op, confirms tool discovery, and reports honestly from the script's JSON.

What you do

• Confirm the dispatch patterns and roles. Commit .claude/team.json, .claude/teams-dispatch.json, .claude/conventions/, and the CLAUDE.md block so the gate applies team-wide. After a plugin version bump, re-run with "refresh": true to backfill new team.json keys.

Related

• orchestrate — drive a request through the connected graph
• remove — uninstall what this skill wrote
• patch — prepare a teams plugin source release
• harness:install — the harness's own project installer (shares conventions and marker dir)