From 66cd7de6e38cefa29f1584c1b96b75d3559c4707 Mon Sep 17 00:00:00 2001
From: Harsha Bharadwaj <harsha.bajju@gmail.com>
Date: Fri, 23 Oct 2026 14:40:34 +0530
Subject: [PATCH] feat: add team config and role templates

Issue #59. sdd team init writes .sdd/team.yaml and the software, solo,
or research roles. sdd role create can copy a shipped role. Host stubs
state what they own, never do, check, and when they ask.
---
 .../brainstorm.md                             |  67 ++++++
 .../clarify-design.md                         |  30 +++
 .../clarify-intent.md                         |  30 +++
 .../clarify-tasks.md                          |  30 +++
 .../design.md                                 |  55 +++++
 .../feature.md                                |  38 +++
 .../local-test-plan.md                        |  12 +
 .../local-test-results.md                     |  16 ++
 .../meta.yaml                                 |  38 +++
 .../metrics.json                              |  50 ++++
 .../tasks.md                                  |  10 +
 docs/reference/cli.md                         |  16 +-
 .../cli/src/__tests__/cli.integration.test.ts |  21 ++
 packages/cli/src/commands.ts                  |   2 +
 packages/cli/src/role-cmd.ts                  |  39 +++-
 packages/cli/src/team-cmd.ts                  |  43 ++++
 .../teams/research/roles/researcher.md        |  29 +++
 .../core/defaults/teams/research/team.yaml    |   7 +
 .../teams/software/roles/architect.md         |  31 +++
 .../defaults/teams/software/roles/dev-lead.md |  32 +++
 .../teams/software/roles/developer.md         |  30 +++
 .../teams/software/roles/product-manager.md   |  32 +++
 .../teams/software/roles/product-owner.md     |  30 +++
 .../core/defaults/teams/software/team.yaml    |  21 ++
 .../defaults/teams/solo/roles/developer.md    |  28 +++
 packages/core/defaults/teams/solo/team.yaml   |   7 +
 packages/core/src/__tests__/agents.test.ts    |   2 +-
 packages/core/src/__tests__/team.test.ts      | 102 ++++++++
 packages/core/src/agents.ts                   |  16 ++
 packages/core/src/defaults.ts                 |   4 +
 packages/core/src/role/index.ts               |  13 +-
 packages/core/src/role/profile.ts             |  76 ++++--
 packages/core/src/role/schema.ts              |  62 +++++
 packages/core/src/role/team.ts                | 218 ++++++++++++++++++
 packages/core/src/role/types.ts               |  32 ++-
 35 files changed, 1245 insertions(+), 24 deletions(-)
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/brainstorm.md
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/clarify-design.md
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/clarify-intent.md
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/clarify-tasks.md
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/design.md
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/feature.md
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/local-test-plan.md
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/local-test-results.md
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/meta.yaml
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/metrics.json
 create mode 100644 changes/2026-10-23-issue-59-role-and-team-config/tasks.md
 create mode 100644 packages/cli/src/team-cmd.ts
 create mode 100644 packages/core/defaults/teams/research/roles/researcher.md
 create mode 100644 packages/core/defaults/teams/research/team.yaml
 create mode 100644 packages/core/defaults/teams/software/roles/architect.md
 create mode 100644 packages/core/defaults/teams/software/roles/dev-lead.md
 create mode 100644 packages/core/defaults/teams/software/roles/developer.md
 create mode 100644 packages/core/defaults/teams/software/roles/product-manager.md
 create mode 100644 packages/core/defaults/teams/software/roles/product-owner.md
 create mode 100644 packages/core/defaults/teams/software/team.yaml
 create mode 100644 packages/core/defaults/teams/solo/roles/developer.md
 create mode 100644 packages/core/defaults/teams/solo/team.yaml
 create mode 100644 packages/core/src/__tests__/team.test.ts
 create mode 100644 packages/core/src/role/schema.ts
 create mode 100644 packages/core/src/role/team.ts

diff --git a/changes/2026-10-23-issue-59-role-and-team-config/brainstorm.md b/changes/2026-10-23-issue-59-role-and-team-config/brainstorm.md
new file mode 100644
index 00000000..6777fe0e
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/brainstorm.md
@@ -0,0 +1,67 @@
+# Brainstorm
+
+> **Issue 59 role and team config** · `2026-10-23-issue-59-role-and-team-config` · stage `brainstorm`  
+> **Optional stage** — skip if one approach is obvious:  
+> `sdd skip brainstorm -r "single approach is clear"`
+
+## Goal of exploration
+
+-
+
+## Approach A
+
+### Idea
+
+-
+
+### Pros
+
+-
+
+### Cons / risks
+
+-
+
+## Approach B
+
+### Idea
+
+-
+
+### Pros
+
+-
+
+### Cons / risks
+
+-
+
+## Approach C (optional)
+
+### Idea
+
+-
+
+### Pros
+
+-
+
+### Cons / risks
+
+-
+
+## Comparison
+
+| Criterion | A | B | C |
+|-----------|---|---|---|
+| Complexity | | | |
+| Risk | | | |
+| Fit to constraints | | | |
+
+## Recommendation for design stage
+
+-
+
+## Open questions (feed clarify / design)
+
+-
diff --git a/changes/2026-10-23-issue-59-role-and-team-config/clarify-design.md b/changes/2026-10-23-issue-59-role-and-team-config/clarify-design.md
new file mode 100644
index 00000000..ee6ff4bc
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/clarify-design.md
@@ -0,0 +1,30 @@
+# Clarify
+
+> **Issue 59 role and team config** · `2026-10-23-issue-59-role-and-team-config` · stage `clarify_design`  
+> **Optional stage** — skip if nothing is ambiguous:  
+> `sdd skip clarify_design -r "no open questions"`
+
+## Context
+
+What just finished? What is about to start?
+
+-
+
+## Clarifying questions
+
+1. **Q:**  
+   **A:**  
+
+2. **Q:**  
+   **A:**  
+
+3. **Q:**  
+   **A:**  
+
+## Decisions / constraints captured
+
+-
+
+## Ready for next stage?
+
+- [ ] No blocking unknowns remain (or explicitly accepted risks)
diff --git a/changes/2026-10-23-issue-59-role-and-team-config/clarify-intent.md b/changes/2026-10-23-issue-59-role-and-team-config/clarify-intent.md
new file mode 100644
index 00000000..6c1fbf8c
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/clarify-intent.md
@@ -0,0 +1,30 @@
+# Clarify
+
+> **Issue 59 role and team config** · `2026-10-23-issue-59-role-and-team-config` · stage `clarify_intent`  
+> **Optional stage** — skip if nothing is ambiguous:  
+> `sdd skip clarify_intent -r "no open questions"`
+
+## Context
+
+What just finished? What is about to start?
+
+-
+
+## Clarifying questions
+
+1. **Q:**  
+   **A:**  
+
+2. **Q:**  
+   **A:**  
+
+3. **Q:**  
+   **A:**  
+
+## Decisions / constraints captured
+
+-
+
+## Ready for next stage?
+
+- [ ] No blocking unknowns remain (or explicitly accepted risks)
diff --git a/changes/2026-10-23-issue-59-role-and-team-config/clarify-tasks.md b/changes/2026-10-23-issue-59-role-and-team-config/clarify-tasks.md
new file mode 100644
index 00000000..8ba59679
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/clarify-tasks.md
@@ -0,0 +1,30 @@
+# Clarify
+
+> **Issue 59 role and team config** · `2026-10-23-issue-59-role-and-team-config` · stage `clarify_tasks`  
+> **Optional stage** — skip if nothing is ambiguous:  
+> `sdd skip clarify_tasks -r "no open questions"`
+
+## Context
+
+What just finished? What is about to start?
+
+-
+
+## Clarifying questions
+
+1. **Q:**  
+   **A:**  
+
+2. **Q:**  
+   **A:**  
+
+3. **Q:**  
+   **A:**  
+
+## Decisions / constraints captured
+
+-
+
+## Ready for next stage?
+
+- [ ] No blocking unknowns remain (or explicitly accepted risks)
diff --git a/changes/2026-10-23-issue-59-role-and-team-config/design.md b/changes/2026-10-23-issue-59-role-and-team-config/design.md
new file mode 100644
index 00000000..c1423c4a
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/design.md
@@ -0,0 +1,55 @@
+# Design
+
+> **Issue 59 role and team config** · `2026-10-23-issue-59-role-and-team-config`
+
+## Approach
+
+Extend the role file the current parser already reads. Add the new fields as string lists. Leave them off the file when they are empty, so a role created with only a label and a job stays the same shape. Put the team in `.sdd/team.yaml`, validated by a Zod schema in `packages/core/src/role/schema.ts`. Ship templates as files under `packages/core/defaults/teams/<name>/`.
+
+## Team file
+
+```yaml
+template: software
+branch: bot/{bot}/{change}
+rooms:
+  commit: false
+bots:
+  - name: developer
+    role: developer
+    wip: 1
+humans:
+  - name: Ada Lovelace
+role_wip:
+  developer: 2
+```
+
+`branch` must include `{bot}`. Bot names are unique. `wip` is a positive integer. `rooms.commit` is the rooms commit switch and is false in every shipped template. `role_wip` is optional. Humans are names compared with `git config user.name` by exact match after trim. Init fills `humans` from that git name only when the template list is empty.
+
+## Commands
+
+| Command | Result |
+|---|---|
+| `sdd team init --template software` | Writes the team file and each role. Refuses when `.sdd/team.yaml` or any of those role files already exists, and writes nothing in that case. |
+| `sdd team show` | Prints the template, branch, rooms switch, bots, humans, and role limits. A matching git name is marked `(you)`. |
+| `sdd role create <name> --template software/developer` | Copies that role under the new name. `--name` still works. `--label` and `--job` override the template. |
+| `sdd role create --name <name> --label <label> --job <job>` | Unchanged. Label and job stay required when there is no template. |
+
+`developer` matches `software/developer` and `solo/developer`, so the command asks for one of those ids. `product-manager` and `researcher` are unique and work as short names.
+
+## Templates
+
+| Template | Roles |
+|---|---|
+| software | product-manager, architect, product-owner, dev-lead, developer |
+| solo | developer |
+| research | researcher |
+
+Each role's `never` list includes accepting a spec. `approvers` contains `human`, which means the people in `team.yaml`.
+
+## Host stubs
+
+`SDD_AGENT_ROLES` gains four lines on each of `sdd`, `sdd-planner`, `sdd-implementer`, and `sdd-reviewer`: Owns, Never, Checks, and Ask when. The previous rules stay. The concise-body check moves from 1200 to 1400 characters because the router stub now carries those four lines.
+
+## Failure
+
+A bad `team.yaml` prints `team.yaml is invalid:` and the first schema path. A missing team prints the init command. An unknown template lists the names that exist.
diff --git a/changes/2026-10-23-issue-59-role-and-team-config/feature.md b/changes/2026-10-23-issue-59-role-and-team-config/feature.md
new file mode 100644
index 00000000..294275e5
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/feature.md
@@ -0,0 +1,38 @@
+# Feature
+
+> **Issue 59 role and team config** · `2026-10-23-issue-59-role-and-team-config` · 2026-10-23
+
+## Problem / opportunity
+
+A role file only stores a label, a job, and a few flags. Nothing says what the role owns, what it reads, what it produces, or who approves it. There is no team file, so later work cannot tell bots, human approvers, work-in-progress limits, or the branch pattern apart. The four host stubs are two or three lines each.
+
+## Users & value
+
+Someone who wants their own team, not a fixed one, runs one command and gets a working team from a template. They add, remove, or rename roles by editing plain files. Later steps read this config.
+
+## Scope
+
+- Role files at `.sdd/roles/<name>.md` can store job, owns, inputs, outputs, collaborates, reviews, approvers, never, ask_human_when, skills, rules, and goals.
+- `.sdd/team.yaml` lists bots, human approvers by name, a work-in-progress limit per bot and optionally per role, the rooms commit switch, and the bot branch pattern.
+- `sdd team init --template <name>`, `sdd team show`, and `sdd role create <name> --template <t>`. `sdd role show` already prints a role file.
+- Shipped templates: software (product-manager, architect, product-owner, dev-lead, developer, plus a human), solo, and research.
+- The host stubs `sdd`, `sdd-planner`, `sdd-implementer`, and `sdd-reviewer` state owns, never, checks, and ask when.
+
+## Non-goals
+
+- Rooms, the router, model selection, evidence by SHA, and approval enforcement. Those are later issues. This change stores the rooms commit switch and does not open a room.
+- An `sdd agent create` alias.
+- Overwriting an existing team file or an existing role file.
+
+## Success criteria
+
+- `sdd team init --template software` writes `.sdd/team.yaml` and the five role files. A second run writes nothing.
+- A human whose name matches `git config user.name` is marked `(you)` by `sdd team show`.
+- `sdd role create builder --template product-manager` writes that role. `developer` alone names both software and solo.
+- A plain `sdd role create` file does not grow empty list fields. Editing the job keeps owns.
+- Each host stub contains Owns, Never, Checks, and Ask when.
+
+## Risks / open questions
+
+- A template role name that already exists blocks the whole init, including roles that are new. That is the chosen fail-before-write rule.
+- The approver value `human` means the people listed in `team.yaml`, not a role file of that name.
diff --git a/changes/2026-10-23-issue-59-role-and-team-config/local-test-plan.md b/changes/2026-10-23-issue-59-role-and-team-config/local-test-plan.md
new file mode 100644
index 00000000..9d437b64
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/local-test-plan.md
@@ -0,0 +1,12 @@
+# Local test plan
+
+> **Issue 59 role and team config** · `2026-10-23-issue-59-role-and-team-config`
+
+Node on this machine is v20.19.3. The `EBADENGINE` warning for `engines.node >= 24` is expected.
+
+| # | Check | Expected |
+|---|--------|----------|
+| 1 | `pnpm --filter @structured-vibe-coding/core exec vitest run src/__tests__/team.test.ts src/__tests__/role.test.ts src/__tests__/agents.test.ts` | Pass. Software init, no overwrite, template create, plain role, stub lines. |
+| 2 | `pnpm --filter @structured-vibe-coding/core test` | Pass. |
+| 3 | `pnpm --filter @structured-vibe-coding/cli test -- src/__tests__/cli.integration.test.ts` | Pass, including team init and role create from a template. |
+| 4 | `pnpm exec biome check` on the touched TypeScript, and `tsc --noEmit` for core and cli | Pass. |
diff --git a/changes/2026-10-23-issue-59-role-and-team-config/local-test-results.md b/changes/2026-10-23-issue-59-role-and-team-config/local-test-results.md
new file mode 100644
index 00000000..ac865866
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/local-test-results.md
@@ -0,0 +1,16 @@
+# Local test results
+
+> **Issue 59 role and team config** · `2026-10-23-issue-59-role-and-team-config`
+
+Node v20.19.3. `EBADENGINE` warnings for `engines.node >= 24` are expected.
+
+| # | Result |
+|---|--------|
+| 1 | PASS. `team.test.ts`, `role.test.ts`, and `agents.test.ts` — 38 tests, exit 0. |
+| 2 | PASS. Full core vitest, 281 tests, exit 0. |
+| 3 | PASS. CLI integration, 30 tests, exit 0, including `installs a team template and creates a role from one (#59)`. |
+| 4 | PASS. `tsc --noEmit` for core and cli. `biome check` on the touched TypeScript, exit 0. |
+
+The feature workflow's `verify.commands` is empty, so `sdd verify` reports NOT RUN. The checks above are the verification.
+
+Using `sdd` from main (`sdd new`, `sdd next`, `sdd skip`) advanced this change to local verify. No separate CLI defect showed up.
diff --git a/changes/2026-10-23-issue-59-role-and-team-config/meta.yaml b/changes/2026-10-23-issue-59-role-and-team-config/meta.yaml
new file mode 100644
index 00000000..1bf8d0ed
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/meta.yaml
@@ -0,0 +1,38 @@
+id: 2026-10-23-issue-59-role-and-team-config
+title: Issue 59 role and team config
+workflow: feature
+created: 2026-10-23T09:02:16.874Z
+updated: 2026-10-23T09:10:09.436Z
+status: in_progress
+stage: local_verify
+epic: issue-58
+depends: []
+flags: {}
+overrides:
+  skip_stages:
+    - clarify_intent
+    - brainstorm
+    - clarify_design
+    - clarify_tasks
+  gates: {}
+  extra_stages: []
+skipped:
+  - stage: clarify_intent
+    reason: The issue states the fields, commands, and templates.
+    at: 2026-10-23T09:08:43.569Z
+  - stage: brainstorm
+    reason: Extend the current role file and add team.yaml. One approach.
+    at: 2026-10-23T09:08:45.139Z
+  - stage: clarify_design
+    reason: The schema, commands, and fail-before-write rule are in design.md.
+    at: 2026-10-23T09:08:46.981Z
+  - stage: clarify_tasks
+    reason: The six tasks name the files and the commands.
+    at: 2026-10-23T09:08:48.777Z
+gates: {}
+verify_results:
+  local_verify:
+    ok: false
+    status: not_run
+    at: 2026-10-23T09:10:09.436Z
+    results: []
diff --git a/changes/2026-10-23-issue-59-role-and-team-config/metrics.json b/changes/2026-10-23-issue-59-role-and-team-config/metrics.json
new file mode 100644
index 00000000..9326d9f8
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/metrics.json
@@ -0,0 +1,50 @@
+{
+  "version": 1,
+  "phases": [
+    {
+      "phase": "intent",
+      "startedAt": "2026-10-23T09:02:16.874Z",
+      "endedAt": "2026-10-23T09:08:34.076Z"
+    },
+    {
+      "phase": "clarify_intent",
+      "startedAt": "2026-10-23T09:08:34.076Z",
+      "endedAt": "2026-10-23T09:08:43.574Z"
+    },
+    {
+      "phase": "brainstorm",
+      "startedAt": "2026-10-23T09:08:43.574Z",
+      "endedAt": "2026-10-23T09:08:45.140Z"
+    },
+    {
+      "phase": "design",
+      "startedAt": "2026-10-23T09:08:45.140Z",
+      "endedAt": "2026-10-23T09:08:45.931Z"
+    },
+    {
+      "phase": "clarify_design",
+      "startedAt": "2026-10-23T09:08:45.931Z",
+      "endedAt": "2026-10-23T09:08:46.982Z"
+    },
+    {
+      "phase": "tasks",
+      "startedAt": "2026-10-23T09:08:46.982Z",
+      "endedAt": "2026-10-23T09:08:47.888Z"
+    },
+    {
+      "phase": "clarify_tasks",
+      "startedAt": "2026-10-23T09:08:47.888Z",
+      "endedAt": "2026-10-23T09:08:48.777Z"
+    },
+    {
+      "phase": "implement",
+      "startedAt": "2026-10-23T09:08:48.777Z",
+      "endedAt": "2026-10-23T09:08:49.580Z"
+    },
+    {
+      "phase": "local_verify",
+      "startedAt": "2026-10-23T09:08:49.580Z"
+    }
+  ],
+  "requests": []
+}
diff --git a/changes/2026-10-23-issue-59-role-and-team-config/tasks.md b/changes/2026-10-23-issue-59-role-and-team-config/tasks.md
new file mode 100644
index 00000000..754d174b
--- /dev/null
+++ b/changes/2026-10-23-issue-59-role-and-team-config/tasks.md
@@ -0,0 +1,10 @@
+# Tasks
+
+> **Issue 59 role and team config** · `2026-10-23-issue-59-role-and-team-config`
+
+1. Add the role list fields to the parser and the renderer. Omit empty lists.
+2. Add `TeamSchema` and `sdd team init` / `sdd team show`.
+3. Ship the software, solo, and research templates under `packages/core/defaults/teams/`.
+4. Add `sdd role create <name> --template <id>`, including the ambiguous `developer` name.
+5. Add Owns, Never, Checks, and Ask when to the four host stubs.
+6. Cover init, refuse-on-existing, template create, plain roles, invalid team files, and the stub lines with Vitest. Document the commands in `docs/reference/cli.md`.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 2840275f..59a0c797 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -89,7 +89,9 @@ Commit `.sdd/config.yaml`, workflows, templates, `protocol.md`, `memory/`, and c
 | `sdd mcp sources list/add/test/remove` | External MCPs **sdd calls** | Design system / AST / org lib |
 | `sdd mcp fetch` | Pull matching sources for current stage | Enrich handoff / implement |
 | `sdd agent` | Refresh brief + open AI | Anytime |
-| `sdd role` | Create, list, and run a product role | One job and one stop |
+| `sdd role` | Create, list, and run a product role. `sdd role create <name> --template software/developer` copies a shipped role | One job and one stop |
+| `sdd team init --template software` | Write `.sdd/team.yaml` and that template's roles. Also `solo` and `research`. Does not overwrite | Model a team |
+| `sdd team show` | Print bots, human approvers, the rooms commit switch, and the branch pattern | See the team |
 | `sdd graph --epic <key>` | Print which stories can run together and which must wait | Epic planning |
 | `sdd branch <name>` | Create that story branch from `main` | Start one story |
 | `sdd pr` | Push the change branch and open a pull request | Story is ready |
@@ -149,7 +151,17 @@ Related change specs and memory pages can be packed as a short extractive summar
 
 ## sdd role
 
-A role file at `.sdd/roles/<name>.md` is the profile a product repo can commit. It is not a host stub from `sdd agents install`. `sdd role run` stops in plain language before it writes a file. Allow once writes only the named file. Always allow remembers that file and those inputs for that role. Connectors and routines are not in this slice.
+A role file at `.sdd/roles/<name>.md` is the profile a product repo can commit. It is not a host stub from `sdd agents install`. A shipped template can fill `owns`, `inputs`, `outputs`, `collaborates`, `reviews`, `approvers`, `never`, `ask_human_when`, `skills`, `rules`, and `goals`.
+
+```bash
+sdd team init --template software
+sdd team show
+sdd role create builder --template software/developer
+```
+
+`software` ships product-manager, architect, product-owner, dev-lead, and developer. `solo` ships one developer. `research` ships one researcher. `developer` alone is ambiguous. Pass `software/developer` or `solo/developer`. Init writes nothing when `.sdd/team.yaml` or one of the template's role files already exists. A human approver whose name matches `git config user.name` is marked `(you)`. The rooms commit switch is stored and stays off in the shipped templates. The branch pattern includes `{bot}`.
+
+A role file at `.sdd/roles/<name>.md` is still not a host stub. The four host stubs (`sdd`, `sdd-planner`, `sdd-implementer`, `sdd-reviewer`) each state what they own, what they never do, what they check, and when they ask. `sdd role run` stops in plain language before it writes a file. Allow once writes only the named file. Always allow remembers that file and those inputs for that role. Connectors and routines are not in this slice.
 
 `sdd role messaging off` stops a handoff before any model call. `sdd role handoff <from> --to <role> --change <id> --section <id> --task "..."` writes the same handoff record on both conversations and calls only the receiver. `sdd role group --change <id>` lists accepted owners. `sdd role network` prints one service, a connection with the lead absent, or asks the lead for a plan of depth at most 2. Nobody writes until `sdd role network accept`. `sdd role network run` runs a node only after its prerequisites, and the parent stays open until every node has a result.
 
diff --git a/packages/cli/src/__tests__/cli.integration.test.ts b/packages/cli/src/__tests__/cli.integration.test.ts
index d8c4b091..a29d9c25 100644
--- a/packages/cli/src/__tests__/cli.integration.test.ts
+++ b/packages/cli/src/__tests__/cli.integration.test.ts
@@ -754,6 +754,27 @@ stages:
     expect(started.status, started.stderr + started.stdout).toBe(0);
   });
 
+  it("installs a team template and creates a role from one (#59)", async () => {
+    const root = await mkdtemp(join(tmpdir(), "sdd-cli-team-"));
+    temps.push(root);
+    expect(runSdd(root, ["init", "--here", "--no-agent"]).status).toBe(0);
+    const init = runSdd(root, ["team", "init", "--template", "research"]);
+    expect(init.status, init.stderr + init.stdout).toBe(0);
+    expect(await exists(join(root, ".sdd/roles/researcher.md"))).toBe(true);
+    const shown = runSdd(root, ["team", "show"]);
+    expect(shown.status, shown.stderr + shown.stdout).toBe(0);
+    expect(shown.stdout).toContain("researcher");
+    expect(shown.stdout).toContain("rooms.commit: false");
+    const created = runSdd(root, ["role", "create", "notes", "--template", "research/researcher"]);
+    expect(created.status, created.stderr + created.stdout).toBe(0);
+    const role = await readFile(join(root, ".sdd/roles/notes.md"), "utf8");
+    expect(role).toContain("name: notes");
+    expect(role).toContain("treat the notes as an accepted spec");
+    const again = runSdd(root, ["team", "init", "--template", "research"]);
+    expect(again.status).not.toBe(0);
+    expect(again.stdout + again.stderr).toContain("Nothing was written");
+  });
+
   it("init --force preserves custom config paths and lists edited workflows/templates (#15)", async () => {
     const root = await mkdtemp(join(tmpdir(), "sdd-cli-force-preserve-"));
     temps.push(root);
diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts
index 8c8271d9..5bf23080 100644
--- a/packages/cli/src/commands.ts
+++ b/packages/cli/src/commands.ts
@@ -54,6 +54,7 @@ import { roleCmd } from "./role-cmd.js";
 import { parsePositiveInt, searchCmd } from "./search-cmd.js";
 import { asStringList, noAgentArg, noAgentRequested, noRunRequested } from "./shared.js";
 import { branchCmd, graphCmd, prCmd } from "./story-cmd.js";
+import { teamCmd } from "./team-cmd.js";
 
 /** Repo-relative path for command output. Falls back when the path is outside the project. */
 function displayRepoPath(projectRoot: string, absolutePath: string): string {
@@ -1368,6 +1369,7 @@ export const commands = {
   agent,
   agents,
   role: roleCmd,
+  team: teamCmd,
   graph: graphCmd,
   branch: branchCmd,
   pr: prCmd,
diff --git a/packages/cli/src/role-cmd.ts b/packages/cli/src/role-cmd.ts
index e2ed3f35..5ece6c70 100644
--- a/packages/cli/src/role-cmd.ts
+++ b/packages/cli/src/role-cmd.ts
@@ -4,6 +4,7 @@ import {
   acceptNetwork,
   allowRole,
   createRole,
+  createRoleFromTemplate,
   deleteRole,
   duplicateRole,
   editRole,
@@ -78,21 +79,47 @@ function modelFromEnv(): RoleModel | undefined {
 const create = defineCommand({
   meta: { name: "create", description: "Write a new role file" },
   args: {
-    name: { type: "string", description: "Role name", required: true },
-    label: { type: "string", description: "Short label", required: true },
-    job: { type: "string", description: "One job for this role", required: true },
+    roleName: { type: "positional", description: "Role name", required: false },
+    name: { type: "string", description: "Role name", required: false },
+    label: { type: "string", description: "Short label" },
+    job: { type: "string", description: "One job for this role" },
     description: { type: "string", description: "Durable description" },
+    template: { type: "string", description: "Shipped role template, such as software/developer" },
     "ask-first": { type: "string", description: "true or false. Default false" },
   },
   async run({ args }) {
     const ask = boolArg(args["ask-first"]);
     if (ask === "bad") process.exit(1);
+    const positional = textArg(args.roleName);
+    const flagged = textArg(args.name);
+    if (positional && flagged && positional !== flagged) {
+      process.stdout.write("A role name is not valid.\n");
+      process.exit(1);
+    }
+    const name = flagged || positional || "";
     await withProject(async ({ root }) => {
+      const template = textArg(args.template);
+      if (template) {
+        emit(
+          await createRoleFromTemplate(root, {
+            name,
+            template,
+            label: textArg(args.label),
+            job: textArg(args.job),
+            description: textArg(args.description),
+          }),
+        );
+        return;
+      }
+      if (!textArg(args.label)) {
+        process.stdout.write("A role needs a label.\n");
+        process.exit(1);
+      }
       emit(
         await createRole(root, {
-          name: args.name,
-          label: args.label,
-          job: args.job,
+          name,
+          label: textArg(args.label) ?? "",
+          job: textArg(args.job) ?? "",
           description: textArg(args.description),
           askFirst: ask === true,
         }),
diff --git a/packages/cli/src/team-cmd.ts b/packages/cli/src/team-cmd.ts
new file mode 100644
index 00000000..354646bb
--- /dev/null
+++ b/packages/cli/src/team-cmd.ts
@@ -0,0 +1,43 @@
+import { gitUserName, initTeam, showTeam } from "@structured-vibe-coding/core";
+import { defineCommand } from "citty";
+import { withProject } from "./project.js";
+
+function emit(result: { exitCode: number; stdout: string }): void {
+  if (result.stdout.length > 0) {
+    process.stdout.write(result.stdout.endsWith("\n") ? result.stdout : `${result.stdout}\n`);
+  }
+  if (result.exitCode !== 0) process.exit(result.exitCode);
+}
+
+function textArg(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+const init = defineCommand({
+  meta: { name: "init", description: "Write .sdd/team.yaml and the template's role files" },
+  args: {
+    template: { type: "string", description: "software, solo, or research", required: true },
+  },
+  async run({ args }) {
+    await withProject(async ({ root }) => {
+      emit(await initTeam(root, textArg(args.template), gitUserName(root)));
+    });
+  },
+});
+
+const show = defineCommand({
+  meta: { name: "show", description: "Print the team config" },
+  async run() {
+    await withProject(async ({ root }) => {
+      emit(await showTeam(root, gitUserName(root)));
+    });
+  },
+});
+
+export const teamCmd = defineCommand({
+  meta: {
+    name: "team",
+    description: "Install a role team from a template and show it",
+  },
+  subCommands: { init, show },
+});
diff --git a/packages/core/defaults/teams/research/roles/researcher.md b/packages/core/defaults/teams/research/roles/researcher.md
new file mode 100644
index 00000000..24d09465
--- /dev/null
+++ b/packages/core/defaults/teams/research/roles/researcher.md
@@ -0,0 +1,29 @@
+---
+name: researcher
+label: Researcher
+job: Answer one question and leave the notes in the repo
+ask_first: false
+pinned: false
+hidden: false
+owns:
+  - the question
+  - the notes
+inputs:
+  - the question
+outputs:
+  - the notes
+approvers:
+  - human
+never:
+  - treat the notes as an accepted spec
+  - ship product code as the decision
+ask_human_when:
+  - the question has two meanings
+skills:
+  - write the notes
+rules:
+  - notes are not a decision until the person accepts them
+goals:
+  - notes the person can accept or set aside
+---
+The researcher writes notes. The person decides what they mean.
diff --git a/packages/core/defaults/teams/research/team.yaml b/packages/core/defaults/teams/research/team.yaml
new file mode 100644
index 00000000..7a5e2f30
--- /dev/null
+++ b/packages/core/defaults/teams/research/team.yaml
@@ -0,0 +1,7 @@
+branch: bot/{bot}/{change}
+rooms:
+  commit: false
+bots:
+  - name: researcher
+    role: researcher
+    wip: 1
diff --git a/packages/core/defaults/teams/software/roles/architect.md b/packages/core/defaults/teams/software/roles/architect.md
new file mode 100644
index 00000000..907024e8
--- /dev/null
+++ b/packages/core/defaults/teams/software/roles/architect.md
@@ -0,0 +1,31 @@
+---
+name: architect
+label: Architect
+job: Name the modules and the seams between them
+ask_first: false
+pinned: false
+hidden: false
+owns:
+  - module boundaries
+inputs:
+  - the accepted reading
+outputs:
+  - a module map
+collaborates:
+  - product-manager
+  - dev-lead
+approvers:
+  - human
+never:
+  - accept a spec
+  - rewrite another module's decisions
+ask_human_when:
+  - a seam would change an accepted decision
+skills:
+  - draw a module map
+rules:
+  - a connection between modules is its own spec
+goals:
+  - boundaries a developer can build inside
+---
+The architect names the seams. The person accepts them.
diff --git a/packages/core/defaults/teams/software/roles/dev-lead.md b/packages/core/defaults/teams/software/roles/dev-lead.md
new file mode 100644
index 00000000..2d91b3cf
--- /dev/null
+++ b/packages/core/defaults/teams/software/roles/dev-lead.md
@@ -0,0 +1,32 @@
+---
+name: dev-lead
+label: Dev lead
+job: Name who builds the next piece when more than one role is involved
+ask_first: false
+pinned: false
+hidden: false
+owns:
+  - the plan across roles
+inputs:
+  - the accepted reading
+  - the module map
+outputs:
+  - the next owner
+collaborates:
+  - architect
+  - developer
+approvers:
+  - human
+never:
+  - accept a spec
+  - write a specialist's artifact
+ask_human_when:
+  - two roles could own the same piece
+skills:
+  - name the next owner
+rules:
+  - a lead does not inherit another role's tools
+goals:
+  - one owner for the next piece
+---
+The dev lead plans. Specialists write.
diff --git a/packages/core/defaults/teams/software/roles/developer.md b/packages/core/defaults/teams/software/roles/developer.md
new file mode 100644
index 00000000..55167431
--- /dev/null
+++ b/packages/core/defaults/teams/software/roles/developer.md
@@ -0,0 +1,30 @@
+---
+name: developer
+label: Developer
+job: Build the accepted change for one service
+ask_first: false
+pinned: false
+hidden: false
+owns:
+  - the change pack for one service
+inputs:
+  - the accepted spec
+outputs:
+  - the change pack
+collaborates:
+  - dev-lead
+approvers:
+  - human
+never:
+  - accept a spec
+  - generate a release
+ask_human_when:
+  - the accepted spec does not say what to build
+skills:
+  - implement one change pack
+rules:
+  - stay inside the accepted spec
+goals:
+  - a change the person can try
+---
+The developer builds one service. The person accepts the spec.
diff --git a/packages/core/defaults/teams/software/roles/product-manager.md b/packages/core/defaults/teams/software/roles/product-manager.md
new file mode 100644
index 00000000..73d56c15
--- /dev/null
+++ b/packages/core/defaults/teams/software/roles/product-manager.md
@@ -0,0 +1,32 @@
+---
+name: product-manager
+label: Product manager
+job: Turn a request into a short reading the person can accept
+ask_first: false
+pinned: false
+hidden: false
+owns:
+  - the request
+  - the short reading
+inputs:
+  - the person's words
+outputs:
+  - a three-sentence reading
+collaborates:
+  - architect
+  - product-owner
+approvers:
+  - human
+never:
+  - accept a spec
+  - write product code
+ask_human_when:
+  - the reading could mean two products
+skills:
+  - write a short reading
+rules:
+  - the spec changes only when the person accepts it
+goals:
+  - a reading the person can confirm or correct
+---
+The product manager proposes. The person decides.
diff --git a/packages/core/defaults/teams/software/roles/product-owner.md b/packages/core/defaults/teams/software/roles/product-owner.md
new file mode 100644
index 00000000..2ffa5cec
--- /dev/null
+++ b/packages/core/defaults/teams/software/roles/product-owner.md
@@ -0,0 +1,30 @@
+---
+name: product-owner
+label: Product owner
+job: Say whether the reading matches the request
+ask_first: true
+pinned: false
+hidden: false
+owns:
+  - the acceptance question
+inputs:
+  - the short reading
+outputs:
+  - one question for the person
+collaborates:
+  - product-manager
+approvers:
+  - human
+never:
+  - accept a spec
+  - record a decision
+ask_human_when:
+  - the reading is ready to accept or correct
+skills:
+  - ask one product question
+rules:
+  - only the person records the decision
+goals:
+  - a yes or a correction in the person's words
+---
+The product owner asks. The person accepts.
diff --git a/packages/core/defaults/teams/software/team.yaml b/packages/core/defaults/teams/software/team.yaml
new file mode 100644
index 00000000..1ab44ed0
--- /dev/null
+++ b/packages/core/defaults/teams/software/team.yaml
@@ -0,0 +1,21 @@
+branch: bot/{bot}/{change}
+rooms:
+  commit: false
+bots:
+  - name: product-manager
+    role: product-manager
+    wip: 1
+  - name: architect
+    role: architect
+    wip: 1
+  - name: product-owner
+    role: product-owner
+    wip: 1
+  - name: dev-lead
+    role: dev-lead
+    wip: 1
+  - name: developer
+    role: developer
+    wip: 1
+role_wip:
+  developer: 2
diff --git a/packages/core/defaults/teams/solo/roles/developer.md b/packages/core/defaults/teams/solo/roles/developer.md
new file mode 100644
index 00000000..f86e3dbc
--- /dev/null
+++ b/packages/core/defaults/teams/solo/roles/developer.md
@@ -0,0 +1,28 @@
+---
+name: developer
+label: Developer
+job: Build the accepted change on your own
+ask_first: false
+pinned: false
+hidden: false
+owns:
+  - the change pack
+inputs:
+  - the accepted spec
+outputs:
+  - the change pack
+approvers:
+  - human
+never:
+  - accept a spec
+  - generate a release
+ask_human_when:
+  - the accepted spec does not say what to build
+skills:
+  - implement one change pack
+rules:
+  - stay inside the accepted spec
+goals:
+  - a change the person can try
+---
+One developer builds. The person accepts the spec.
diff --git a/packages/core/defaults/teams/solo/team.yaml b/packages/core/defaults/teams/solo/team.yaml
new file mode 100644
index 00000000..85d03199
--- /dev/null
+++ b/packages/core/defaults/teams/solo/team.yaml
@@ -0,0 +1,7 @@
+branch: bot/{bot}/{change}
+rooms:
+  commit: false
+bots:
+  - name: developer
+    role: developer
+    wip: 1
diff --git a/packages/core/src/__tests__/agents.test.ts b/packages/core/src/__tests__/agents.test.ts
index 8d17aa80..175c5f23 100644
--- a/packages/core/src/__tests__/agents.test.ts
+++ b/packages/core/src/__tests__/agents.test.ts
@@ -267,7 +267,7 @@ describe("agent integrations (registry)", () => {
   it("renderThinAgent stays concise", () => {
     for (const role of SDD_AGENT_ROLES) {
       const body = renderThinAgent(role);
-      expect(body.length).toBeLessThan(1200);
+      expect(body.length).toBeLessThan(1400);
       expect(body).not.toMatch(/Hard rules/);
       expect(body).toMatch(/protocol\.md/);
     }
diff --git a/packages/core/src/__tests__/team.test.ts b/packages/core/src/__tests__/team.test.ts
new file mode 100644
index 00000000..db9b541b
--- /dev/null
+++ b/packages/core/src/__tests__/team.test.ts
@@ -0,0 +1,102 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "pathe";
+import { afterEach, describe, expect, it } from "vitest";
+import { SDD_AGENT_ROLES, renderThinAgent } from "../agents.js";
+import { pathExists } from "../fs.js";
+import { createRole, createRoleFromTemplate, editRole, initTeam, showTeam } from "../role/index.js";
+
+const temps: string[] = [];
+
+afterEach(async () => {
+  while (temps.length) {
+    const dir = temps.pop();
+    if (dir) await rm(dir, { recursive: true, force: true });
+  }
+});
+
+async function project(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "sdd-team-"));
+  temps.push(root);
+  await mkdir(join(root, ".sdd"), { recursive: true });
+  return root;
+}
+
+describe("team config", () => {
+  it("installs the software team, records a matching human, and does not overwrite", async () => {
+    const root = await project();
+    const first = await initTeam(root, "software", "Ada Lovelace");
+    expect(first.exitCode).toBe(0);
+    const team = await readFile(join(root, ".sdd/team.yaml"), "utf8");
+    expect(team).toContain("template: software");
+    expect(team).toContain("name: Ada Lovelace");
+    expect(team).toContain("commit: false");
+    expect(await readFile(join(root, ".sdd/roles/product-manager.md"), "utf8")).toContain(
+      "accept a spec",
+    );
+    const shown = await showTeam(root, "Ada Lovelace");
+    expect(shown.stdout).toContain("Ada Lovelace (you)");
+    expect(shown.stdout).toContain("rooms.commit: false");
+    expect(shown.stdout).toContain("developer 2");
+
+    const again = await initTeam(root, "software", "Ada Lovelace");
+    expect(again.stdout).toContain("Nothing was written");
+    expect(await readFile(join(root, ".sdd/team.yaml"), "utf8")).toBe(team);
+  });
+
+  it("leaves humans empty when git has no name and blocks on an existing role", async () => {
+    const root = await project();
+    const solo = await initTeam(root, "solo", null);
+    expect(solo.exitCode).toBe(0);
+    expect((await showTeam(root, null)).stdout).toContain("- (none)");
+    await rm(join(root, ".sdd/team.yaml"));
+    const blocked = await initTeam(root, "software", null);
+    expect(blocked.stdout).toContain("Role already exists: developer");
+    expect(blocked.stdout).toContain("Nothing was written");
+    expect(await pathExists(join(root, ".sdd/roles/product-manager.md"))).toBe(false);
+    expect(await pathExists(join(root, ".sdd/team.yaml"))).toBe(false);
+  });
+
+  it("creates a role from a template and keeps an unambiguous short name", async () => {
+    const root = await project();
+    const ambiguous = await createRoleFromTemplate(root, { name: "dev", template: "developer" });
+    expect(ambiguous.stdout).toContain("software/developer");
+    expect(ambiguous.stdout).toContain("solo/developer");
+    expect(await pathExists(join(root, ".sdd/roles/dev.md"))).toBe(false);
+
+    const created = await createRoleFromTemplate(root, {
+      name: "builder",
+      template: "product-manager",
+    });
+    expect(created.exitCode).toBe(0);
+    const text = await readFile(join(root, ".sdd/roles/builder.md"), "utf8");
+    expect(text).toContain("name: builder");
+    expect(text).toContain("owns:");
+    expect(text).toContain("the short reading");
+    await editRole(root, "builder", { job: "Keep the reading" });
+    const edited = await readFile(join(root, ".sdd/roles/builder.md"), "utf8");
+    expect(edited).toContain("job: Keep the reading");
+    expect(edited).toContain("the short reading");
+  });
+
+  it("omits empty team lists on a plain role and rejects a bad team file", async () => {
+    const root = await project();
+    await createRole(root, { name: "builder", label: "Builder", job: "Build" });
+    const text = await readFile(join(root, ".sdd/roles/builder.md"), "utf8");
+    expect(text).not.toContain("owns:");
+    await writeFile(join(root, ".sdd/team.yaml"), "branch: plain\nbots: []\n");
+    const shown = await showTeam(root, null);
+    expect(shown.exitCode).toBe(1);
+    expect(shown.stdout).toContain("team.yaml is invalid");
+  });
+
+  it("states owns, never, checks, and ask when on each host stub", () => {
+    for (const role of SDD_AGENT_ROLES) {
+      const body = renderThinAgent(role);
+      expect(body).toContain("Owns:");
+      expect(body).toContain("Never:");
+      expect(body).toContain("Checks:");
+      expect(body).toContain("Ask when:");
+    }
+  });
+});
diff --git a/packages/core/src/agents.ts b/packages/core/src/agents.ts
index ffd87ad3..8ce9730f 100644
--- a/packages/core/src/agents.ts
+++ b/packages/core/src/agents.ts
@@ -466,6 +466,10 @@ export const SDD_AGENT_ROLES: SddAgentRole[] = [
       "Default SDD agent. Use for any Spec-Driven Development work on the active change pack.",
     roleLine: "Router: inspect stage in active-context; plan or implement accordingly.",
     roleRules: [
+      "Owns: which role works this stage.",
+      "Never: accept a spec or record a decision.",
+      "Checks: the stage matches the work.",
+      "Ask when: the stage is missing or a hard gate is blocked.",
       "If stage is intent/feature/design/tasks/stories/research: act as planner (artifacts, little or no product code).",
       "If stage is implement: act as implementer (scoped code only).",
       "If stage is local_verify: act as reviewer (gaps vs acceptance; fixes only).",
@@ -478,6 +482,10 @@ export const SDD_AGENT_ROLES: SddAgentRole[] = [
       "SDD planner. Use when filling intent, design, research, stories, or tasks — not large code changes.",
     roleLine: "Planner: produce/update stage markdown only.",
     roleRules: [
+      "Owns: stage markdown, not product code.",
+      "Never: accept a spec.",
+      "Checks: the artifact says what changes and how to tell.",
+      "Ask when: the scope is missing.",
       "Do not make large product code changes unless the user explicitly overrides.",
       "Keep artifacts short and actionable.",
     ],
@@ -487,6 +495,10 @@ export const SDD_AGENT_ROLES: SddAgentRole[] = [
     description: "SDD implementer. Use when coding the active change (implement stage).",
     roleLine: "Implementer: code only for the active change pack.",
     roleRules: [
+      "Owns: code for this change pack.",
+      "Never: accept a spec or widen the change.",
+      "Checks: the diff matches the tasks and acceptance.",
+      "Ask when: a task or a design constraint is missing.",
       "Follow tasks.md / acceptance; honor arb-decision and design constraints.",
       "Do not expand scope beyond the change title/intent.",
     ],
@@ -497,6 +509,10 @@ export const SDD_AGENT_ROLES: SddAgentRole[] = [
       "SDD reviewer. Use before verify/complete or to check work against the change pack.",
     roleLine: "Reviewer: compare work to acceptance and stage artifacts.",
     roleRules: [
+      "Owns: the gap list.",
+      "Never: accept a spec or treat a claim as evidence.",
+      "Checks: the change matches acceptance.",
+      "Ask when: acceptance does not say how to tell it worked.",
       "List gaps; suggest minimal fixes only.",
       "Remind user to run sdd verify before sdd complete.",
     ],
diff --git a/packages/core/src/defaults.ts b/packages/core/src/defaults.ts
index 1ee9c5b0..2675eb77 100644
--- a/packages/core/src/defaults.ts
+++ b/packages/core/src/defaults.ts
@@ -26,6 +26,10 @@ export function defaultWorkflowsDir(): string {
   return join(defaultsRoot(), "workflows");
 }
 
+export function defaultTeamsDir(): string {
+  return join(defaultsRoot(), "teams");
+}
+
 export function defaultTemplatesDir(): string {
   return join(defaultsRoot(), "templates");
 }
diff --git a/packages/core/src/role/index.ts b/packages/core/src/role/index.ts
index bd7d9968..752d14ed 100644
--- a/packages/core/src/role/index.ts
+++ b/packages/core/src/role/index.ts
@@ -18,4 +18,15 @@ export {
   pinRole,
   showRoles,
 } from "./profile.js";
-export type { RoleCommandResult, RoleModel, RoleProfile } from "./types.js";
+export { TeamSchema } from "./schema.js";
+export type { TeamConfig } from "./schema.js";
+export {
+  createRoleFromTemplate,
+  formatTeam,
+  gitUserName,
+  initTeam,
+  listRoleTemplates,
+  listTeamTemplates,
+  showTeam,
+} from "./team.js";
+export type { RoleCommandResult, RoleLists, RoleModel, RoleProfile } from "./types.js";
diff --git a/packages/core/src/role/profile.ts b/packages/core/src/role/profile.ts
index 38f11e9b..6b5a1495 100644
--- a/packages/core/src/role/profile.ts
+++ b/packages/core/src/role/profile.ts
@@ -2,7 +2,13 @@ import { readFile, writeFile } from "node:fs/promises";
 import { join } from "pathe";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { listDirs, listFiles, pathExists, readText, removePath, writeText } from "../fs.js";
-import { ROLE_TEXT, type RoleCommandResult, type RoleProfile } from "./types.js";
+import {
+  ROLE_TEXT,
+  type RoleCommandResult,
+  type RoleLists,
+  type RoleProfile,
+  emptyRoleLists,
+} from "./types.js";
 
 const NAME_LIMIT = 80;
 
@@ -42,6 +48,31 @@ function asText(value: unknown): string {
   return typeof value === "string" ? value.trim() : "";
 }
 
+const LIST_FIELDS: [keyof RoleLists, string][] = [
+  ["owns", "owns"],
+  ["inputs", "inputs"],
+  ["outputs", "outputs"],
+  ["collaborates", "collaborates"],
+  ["reviews", "reviews"],
+  ["approvers", "approvers"],
+  ["never", "never"],
+  ["askHumanWhen", "ask_human_when"],
+  ["skills", "skills"],
+  ["rules", "rules"],
+  ["goals", "goals"],
+];
+
+function stringList(value: unknown): string[] | null {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) return null;
+  const out: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string" || !item.trim()) return null;
+    out.push(item.trim());
+  }
+  return out;
+}
+
 export function parseRoleDocument(name: string, raw: string): RoleProfile | null {
   const text = raw.replace(/^\uFEFF/, "");
   const nl = text.indexOf("\n");
@@ -57,6 +88,12 @@ export function parseRoleDocument(name: string, raw: string): RoleProfile | null
   }
   if (!data || typeof data !== "object" || Array.isArray(data)) return null;
   const rec = data as Record<string, unknown>;
+  const lists = emptyRoleLists();
+  for (const [field, key] of LIST_FIELDS) {
+    const parsed = stringList(rec[key]);
+    if (!parsed) return null;
+    lists[field] = parsed;
+  }
   const body = rest.slice(close.index + close[0].length).trim();
   return {
     name,
@@ -66,21 +103,23 @@ export function parseRoleDocument(name: string, raw: string): RoleProfile | null
     askFirst: rec.ask_first === true,
     pinned: rec.pinned === true,
     hidden: rec.hidden === true,
+    ...lists,
   };
 }
 
 export function renderRole(role: RoleProfile): string {
-  const front = stringifyYaml(
-    {
-      name: role.name,
-      label: role.label,
-      job: role.job,
-      ask_first: role.askFirst,
-      pinned: role.pinned,
-      hidden: role.hidden,
-    },
-    { lineWidth: 100 },
-  ).trimEnd();
+  const record: Record<string, unknown> = {
+    name: role.name,
+    label: role.label,
+    job: role.job,
+    ask_first: role.askFirst,
+    pinned: role.pinned,
+    hidden: role.hidden,
+  };
+  for (const [field, key] of LIST_FIELDS) {
+    if (role[field].length > 0) record[key] = role[field];
+  }
+  const front = stringifyYaml(record, { lineWidth: 100 }).trimEnd();
   const description = role.description.trim();
   if (!description) return `---\n${front}\n---\n`;
   return `---\n${front}\n---\n${description}\n`;
@@ -104,13 +143,23 @@ async function writeRole(root: string, role: RoleProfile): Promise<void> {
 
 export async function createRole(
   root: string,
-  input: { name: string; label: string; job: string; description?: string; askFirst?: boolean },
+  input: {
+    name: string;
+    label: string;
+    job: string;
+    description?: string;
+    askFirst?: boolean;
+  } & Partial<RoleLists>,
 ): Promise<RoleCommandResult> {
   const name = canonicalRoleName(input.name);
   if (!name) return fail(ROLE_TEXT.badName);
   const job = input.job.trim();
   if (!job) return fail(ROLE_TEXT.needsJob);
   if (await pathExists(roleFilePath(root, name))) return fail(ROLE_TEXT.exists);
+  const lists = emptyRoleLists();
+  for (const [field] of LIST_FIELDS) {
+    lists[field] = input[field] ?? [];
+  }
   await writeRole(root, {
     name,
     label: input.label.trim(),
@@ -119,6 +168,7 @@ export async function createRole(
     askFirst: input.askFirst === true,
     pinned: false,
     hidden: false,
+    ...lists,
   });
   return ok();
 }
diff --git a/packages/core/src/role/schema.ts b/packages/core/src/role/schema.ts
new file mode 100644
index 00000000..edd5da0b
--- /dev/null
+++ b/packages/core/src/role/schema.ts
@@ -0,0 +1,62 @@
+import { z } from "zod";
+
+const nameSchema = z.string().trim().min(1);
+
+const botSchema = z
+  .object({
+    name: nameSchema,
+    role: nameSchema,
+    wip: z.number().int().positive(),
+  })
+  .strict();
+
+const humanSchema = z
+  .object({
+    name: nameSchema,
+  })
+  .strict();
+
+/** Project team file written to `.sdd/team.yaml`. */
+export const TeamSchema = z
+  .object({
+    template: nameSchema.optional(),
+    branch: z.string().trim().min(1),
+    rooms: z
+      .object({
+        commit: z.boolean(),
+      })
+      .strict(),
+    bots: z.array(botSchema).min(1),
+    humans: z.array(humanSchema).default([]),
+    role_wip: z.record(z.string().trim().min(1), z.number().int().positive()).optional(),
+  })
+  .strict()
+  .superRefine((team, ctx) => {
+    if (!team.branch.includes("{bot}")) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["branch"],
+        message: "must include {bot}",
+      });
+    }
+    const names = new Set<string>();
+    for (const [index, bot] of team.bots.entries()) {
+      if (names.has(bot.name)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["bots", index, "name"],
+          message: "bot name is repeated",
+        });
+      }
+      names.add(bot.name);
+    }
+  });
+
+export type TeamConfig = z.infer<typeof TeamSchema>;
+
+export function formatTeamError(error: z.ZodError): string {
+  const issue = error.issues[0];
+  const path = issue?.path.join(".") || "team";
+  const message = issue?.message ?? "invalid";
+  return `team.yaml is invalid: ${path} ${message}`;
+}
diff --git a/packages/core/src/role/team.ts b/packages/core/src/role/team.ts
new file mode 100644
index 00000000..5de1a0e0
--- /dev/null
+++ b/packages/core/src/role/team.ts
@@ -0,0 +1,218 @@
+import { spawnSync } from "node:child_process";
+import { join } from "pathe";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { defaultTeamsDir } from "../defaults.js";
+import { listDirs, listFiles, pathExists, readText, writeText } from "../fs.js";
+import { createRole, parseRoleDocument, roleFilePath } from "./profile.js";
+import { type TeamConfig, TeamSchema, formatTeamError } from "./schema.js";
+import type { RoleCommandResult } from "./types.js";
+
+function ok(stdout = ""): RoleCommandResult {
+  return { exitCode: 0, stdout };
+}
+
+function fail(stdout: string): RoleCommandResult {
+  return { exitCode: 1, stdout };
+}
+
+export function gitUserName(root: string): string | null {
+  const result = spawnSync("git", ["-C", root, "config", "user.name"], { encoding: "utf8" });
+  if (result.status !== 0) return null;
+  const name = result.stdout.trim();
+  return name || null;
+}
+
+export async function listTeamTemplates(): Promise<string[]> {
+  return (await listDirs(defaultTeamsDir())).sort();
+}
+
+async function templateRoleFiles(
+  template: string,
+): Promise<{ name: string; raw: string }[] | null> {
+  const dir = join(defaultTeamsDir(), template, "roles");
+  if (!(await pathExists(dir))) return null;
+  const files = (await listFiles(dir)).filter((file) => file.endsWith(".md")).sort();
+  const roles = [];
+  for (const file of files) {
+    roles.push({ name: file.slice(0, -".md".length), raw: await readText(join(dir, file)) });
+  }
+  return roles;
+}
+
+export async function listRoleTemplates(): Promise<string[]> {
+  const ids: string[] = [];
+  for (const template of await listTeamTemplates()) {
+    const roles = await templateRoleFiles(template);
+    if (!roles) continue;
+    for (const role of roles) ids.push(`${template}/${role.name}`);
+  }
+  return ids;
+}
+
+async function loadTemplateTeam(template: string): Promise<TeamConfig | string> {
+  const path = join(defaultTeamsDir(), template, "team.yaml");
+  if (!(await pathExists(path))) return `Team template "${template}" was not found.`;
+  let raw: unknown;
+  try {
+    raw = parseYaml(await readText(path));
+  } catch {
+    return `Team template "${template}" is invalid.`;
+  }
+  const parsed = TeamSchema.safeParse(raw);
+  if (!parsed.success) return `Team template "${template}" is invalid.`;
+  return parsed.data;
+}
+
+function availableTeams(names: string[]): string {
+  return names.join(", ") || "(none)";
+}
+
+export async function initTeam(
+  root: string,
+  template: string,
+  gitUser: string | null,
+): Promise<RoleCommandResult> {
+  const templates = await listTeamTemplates();
+  if (!template.trim()) {
+    return fail(`Pass --template. Available: ${availableTeams(templates)}.`);
+  }
+  if (!templates.includes(template)) {
+    return fail(
+      `Team template "${template}" was not found. Available: ${availableTeams(templates)}.`,
+    );
+  }
+  const loaded = await loadTemplateTeam(template);
+  if (typeof loaded === "string") return fail(loaded);
+  const roles = await templateRoleFiles(template);
+  if (!roles || roles.length === 0) return fail(`Team template "${template}" is invalid.`);
+  for (const role of roles) {
+    const parsed = parseRoleDocument(role.name, role.raw);
+    if (!parsed || !parsed.job) return fail(`Team template "${template}" is invalid.`);
+  }
+  const botRoles = new Set(loaded.bots.map((bot) => bot.role));
+  for (const roleName of botRoles) {
+    if (!roles.some((role) => role.name === roleName)) {
+      return fail(`Team template "${template}" is invalid.`);
+    }
+  }
+
+  const teamPath = join(root, ".sdd", "team.yaml");
+  if (await pathExists(teamPath)) {
+    return fail("Team config already exists at .sdd/team.yaml. Nothing was written.");
+  }
+  const existing: string[] = [];
+  for (const role of roles) {
+    if (await pathExists(roleFilePath(root, role.name))) existing.push(role.name);
+  }
+  if (existing.length > 0) {
+    return fail(`Role already exists: ${existing.join(", ")}. Nothing was written.`);
+  }
+
+  const humans = loaded.humans.length > 0 ? loaded.humans : gitUser ? [{ name: gitUser }] : [];
+  const team: TeamConfig = { ...loaded, template, humans };
+  const checked = TeamSchema.safeParse(team);
+  if (!checked.success) return fail(formatTeamError(checked.error));
+
+  for (const role of roles) {
+    await writeText(join(root, ".sdd", "roles", `${role.name}.md`), role.raw);
+  }
+  await writeText(teamPath, stringifyYaml(checked.data, { lineWidth: 100 }));
+  return ok(`Wrote .sdd/team.yaml from ${template}.`);
+}
+
+export function formatTeam(team: TeamConfig, gitUser: string | null): string {
+  const lines = [
+    `template: ${team.template ?? ""}`,
+    `branch: ${team.branch}`,
+    `rooms.commit: ${team.rooms.commit}`,
+    "bots:",
+  ];
+  for (const bot of team.bots) {
+    lines.push(`- ${bot.name} role ${bot.role} wip ${bot.wip}`);
+  }
+  lines.push("humans:");
+  if (team.humans.length === 0) lines.push("- (none)");
+  for (const human of team.humans) {
+    const you = gitUser !== null && human.name === gitUser ? " (you)" : "";
+    lines.push(`- ${human.name}${you}`);
+  }
+  if (team.role_wip && Object.keys(team.role_wip).length > 0) {
+    lines.push("role_wip:");
+    for (const name of Object.keys(team.role_wip).sort()) {
+      lines.push(`- ${name} ${team.role_wip[name]}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export async function showTeam(root: string, gitUser: string | null): Promise<RoleCommandResult> {
+  const path = join(root, ".sdd", "team.yaml");
+  if (!(await pathExists(path))) {
+    return fail("No team config. Run sdd team init --template software.");
+  }
+  let raw: unknown;
+  try {
+    raw = parseYaml(await readText(path));
+  } catch {
+    return fail("team.yaml is invalid: team could not be parsed");
+  }
+  const parsed = TeamSchema.safeParse(raw);
+  if (!parsed.success) return fail(formatTeamError(parsed.error));
+  return ok(formatTeam(parsed.data, gitUser));
+}
+
+export async function resolveRoleTemplate(
+  template: string,
+): Promise<{ id: string; raw: string } | { error: string }> {
+  const ids = await listRoleTemplates();
+  const trimmed = template.trim();
+  if (!trimmed) {
+    return { error: `Pass --template. Available: ${ids.join(", ") || "(none)"}.` };
+  }
+  if (ids.includes(trimmed)) {
+    const [team, role] = trimmed.split("/") as [string, string];
+    const roles = await templateRoleFiles(team);
+    const found = roles?.find((item) => item.name === role);
+    if (!found) return { error: `Role template "${trimmed}" was not found.` };
+    return { id: trimmed, raw: found.raw };
+  }
+  const matches = ids.filter((id) => id.endsWith(`/${trimmed}`));
+  if (matches.length === 1) {
+    const resolved = await resolveRoleTemplate(matches[0]!);
+    return resolved;
+  }
+  if (matches.length > 1) {
+    return {
+      error: `Role template "${trimmed}" matches ${matches.join(" and ")}. Pass one of those.`,
+    };
+  }
+  return { error: `Role template "${trimmed}" was not found. Available: ${ids.join(", ")}.` };
+}
+
+export async function createRoleFromTemplate(
+  root: string,
+  input: { name: string; template: string; label?: string; job?: string; description?: string },
+): Promise<RoleCommandResult> {
+  const resolved = await resolveRoleTemplate(input.template);
+  if ("error" in resolved) return fail(resolved.error);
+  const parsed = parseRoleDocument(input.name, resolved.raw);
+  if (!parsed || !parsed.job) return fail(`Role template "${resolved.id}" is invalid.`);
+  return createRole(root, {
+    name: input.name,
+    label: input.label?.trim() || parsed.label,
+    job: input.job?.trim() || parsed.job,
+    description: input.description?.trim() || parsed.description,
+    askFirst: parsed.askFirst,
+    owns: parsed.owns,
+    inputs: parsed.inputs,
+    outputs: parsed.outputs,
+    collaborates: parsed.collaborates,
+    reviews: parsed.reviews,
+    approvers: parsed.approvers,
+    never: parsed.never,
+    askHumanWhen: parsed.askHumanWhen,
+    skills: parsed.skills,
+    rules: parsed.rules,
+    goals: parsed.goals,
+  });
+}
diff --git a/packages/core/src/role/types.ts b/packages/core/src/role/types.ts
index 6b65ce15..df8eac49 100644
--- a/packages/core/src/role/types.ts
+++ b/packages/core/src/role/types.ts
@@ -1,4 +1,18 @@
-export interface RoleProfile {
+export interface RoleLists {
+  owns: string[];
+  inputs: string[];
+  outputs: string[];
+  collaborates: string[];
+  reviews: string[];
+  approvers: string[];
+  never: string[];
+  askHumanWhen: string[];
+  skills: string[];
+  rules: string[];
+  goals: string[];
+}
+
+export interface RoleProfile extends RoleLists {
   name: string;
   label: string;
   job: string;
@@ -8,6 +22,22 @@ export interface RoleProfile {
   hidden: boolean;
 }
 
+export function emptyRoleLists(): RoleLists {
+  return {
+    owns: [],
+    inputs: [],
+    outputs: [],
+    collaborates: [],
+    reviews: [],
+    approvers: [],
+    never: [],
+    askHumanWhen: [],
+    skills: [],
+    rules: [],
+    goals: [],
+  };
+}
+
 export interface RoleModel {
   complete(input: { roleId: string; prompt: string }): Promise<string>;
 }