@a-company/paradigm 6.0.2 → 6.0.5

package/dist/university-content/notes/N-para-451-orchestration-modes.md

@@ -0,0 +1,85 @@
+---
+id: N-para-451-orchestration-modes
+title: Orchestration Modes — Faceted vs Sequential
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - orchestration
+  - faceted
+  - sequential
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-para-451-what-is-an-agent
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## Two ways the team actually runs
+
+When `paradigm_orchestrate_inline` decides "Architect plans, Builder implements, Reviewer reviews", **how** those three agents actually run depends on the host IDE. Paradigm supports two execution models, called **orchestration modes**, and the choice between them is set by `orchestration.default_mode` in `agents.yaml`.
+
+| Mode | Where it runs | What it looks like |
+|------|---------------|-------------------|
+| **Faceted** | Claude Code (Task tool available) | Each agent launches as an isolated Task subagent. Separate context. Separate memory. Separate tool access. True multi-agent. |
+| **Sequential** | Cursor and other IDEs without Task tool support | Each agent runs as an inline persona switch in the **same** context. You see voice and reasoning per agent, but they share memory. Sequential roleplay. |
+
+Both modes orchestrate the *same agents*. The profiles, notebooks, identity layers, and partner declarations are identical. What changes is whether each agent gets its own room or whether they all sit in one room and take turns speaking.
+
+## Faceted mode (Claude Code, the default)
+
+In Claude Code, every agent invocation is a **Task tool launch**. Architect runs in its own Task with its own conversation history, sees only what it was handed in the prompt, and returns a structured result. Builder is then launched as a *separate* Task — it does not see Architect's conversation, only the spec Architect produced. Reviewer is launched after Builder, again separately.
+
+Why this matters in practice:
+
+- **Context isolation prevents cross-contamination.** Architect's planning chatter does not pollute Builder's implementation context. Reviewer reads the code with fresh eyes — literally, because its Task starts fresh.
+- **Memory per agent is real.** Each agent's notebook is consulted at the start of *its* Task, not shared with the others. Builder does not accidentally inherit Architect's design notebook entries.
+- **Parallelism is possible.** Two unrelated Task launches can run concurrently when the orchestrator decides they should — you cannot do that in a single conversation.
+
+The trade-off: you lose the running thread. Each agent gets only what was passed in. The orchestrator has to do the handoff work explicitly (and the framework handles this for you — see `paradigm_handoff_prepare`).
+
+## Sequential mode (Cursor and friends, the fallback)
+
+Cursor and many other IDEs do not expose a Task-tool-equivalent surface. In those environments, faceted mode is not possible — there is no way to launch an isolated subagent. Sequential mode is the answer: the **same conversation** acts as Architect for one turn, switches to Builder for the next, switches to Reviewer for the next, and so on.
+
+Why this still works:
+
+- **Identity is preserved in voice and attribution.** Each turn is clearly marked as which agent is speaking. The orchestration log still shows "Architect: ..." then "Builder: ..." then "Reviewer: ...".
+- **Profiles still load.** When the conversation switches into Builder, Builder's profile and notebook are injected into the prompt for that turn. The agent's framing is the same as in faceted mode.
+- **Partners and routing still apply.** The partners primitive, tier mappings, and `agents.yaml` keyword routing all behave identically.
+
+The trade-off: shared memory. Builder *can* see what Architect just said in the same conversation — which is sometimes a feature (faster handoff, less re-explanation) and sometimes a bug (Architect's design exploration leaks into Builder's implementation focus). For most workflows this is acceptable; for high-stakes or bug-investigation work where context isolation matters, faceted mode is meaningfully better.
+
+## Which mode you are in
+
+Check `agents.yaml`:
+
+```yaml
+orchestration:
+  default_mode: faceted   # or: sequential
+```
+
+If unset, the framework defaults to **faceted**. If you are running in an IDE that does not support the Task tool, the orchestrator will fall back to sequential automatically — no explicit switch is required, but you can pin the mode if you want determinism.
+
+## A quick decision rule
+
+You almost never need to pick the mode by hand. But when you do:
+
+- **Working in Claude Code? Leave it on faceted.** The isolation and per-agent memory pay off in nearly every workflow.
+- **Working in Cursor (or any IDE without Task tool support)? You are on sequential — that is the only option, and it is fine.**
+- **Want to force a single shared conversation in Claude Code, e.g. for a roundtable discussion across agents?** Override `default_mode: sequential` in `agents.yaml` for that project.
+- **Want to force isolation outside Claude Code?** You cannot — the host IDE has to support the primitive. Sequential is the floor.
+
+## What this changes for a learner
+
+Almost nothing in your day-to-day. You write prompts, the orchestrator picks agents, agents do work, and the result comes back attributed. The mode determines the *plumbing*, not the team's behaviour. Knowing the difference matters in two situations: (1) when you are debugging a strange handoff and want to know whether memory leaked across agents, and (2) when you are choosing between IDEs and want to understand what you give up.
+
+## Up next
+
+The next entry — **N-para-451-roster-management** — covers the CLI commands and the `/paradigm:agents` skill for shaping which agents are active on your project: rostering, benching, activating, and the `paradigm shift` auto-rosterer.

package/dist/university-content/notes/N-para-451-paradigm-shift.md

@@ -0,0 +1,95 @@
+---
+id: N-para-451-paradigm-shift
+title: '`paradigm shift` — Auto-Rostering for a Fresh Project'
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - auto-roster
+  - ecosystem
+  - paradigm-shift
+  - cli
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites:
+  - N-para-451-roster-management
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## What `paradigm shift` does
+
+`paradigm shift` is the framework's **auto-rosterer** — the one command that gets a fresh (or freshly-cloned) project from "no roster" to "a sensible default roster" without you picking agents by hand. The previous entry covered roster management once a roster exists; this one covers how the roster comes into being in the first place.
+
+Three things happen when you run it:
+
+1. **Project-type detection.** The command scans the working tree for signals of what kind of project this is — language extensions (`*.swift`, `*.ts`, `*.py`), framework markers (`Package.swift`, `package.json`, `pyproject.toml`), platform indicators (Xcode project files, Android manifests), and so on. The result is a coarse classification: "this is a Swift macOS project", "this is a TypeScript monorepo", "this is a Python ML project", and so on.
+
+2. **Roster suggestion.** Based on the detection, the command picks an initial roster — always the **always-on backbone** (Architect, Builder, Reviewer, Aegis, Probe, Scribe, Cid) plus matching **ecosystem agents**. A Swift project gets the `swift` agent activated automatically. A TypeScript-heavy project gets whichever TypeScript-shaped agents are available. The selection is conservative — it favours adding agents you are likely to need over leaving relevant ones benched.
+
+3. **Adoption ceremony.** The suggested roster is presented for review (in the CLI; or interactively through the `/paradigm:agents` skill in Claude Code), and on confirmation it is written to `.paradigm/roster.yaml`. From that moment on, every orchestration call on this project sees the new roster.
+
+```
+$ paradigm shift
+Detected: Swift macOS project (Package.swift, *.swift sources)
+Proposed roster:
+  Always-on backbone:
+    - architect, builder, reviewer, security, tester, documentor, cid
+  Learning loop:
+    - forge (Loid), scholar, educator (Sheila)
+  First-time-user guard:
+    - ftux (Nora)
+  Ecosystem (auto-detected):
+    - swift  ← matched on *.swift, Package.swift
+Apply? [Y/n]
+```
+
+## Auto-rostering on language and platform detection
+
+The "ecosystem agent" piece is the interesting half. A handful of agents in the canonical roster are not part of the always-on backbone — they only make sense on projects where their ecosystem is present. **Swift** is the canonical example today: a `swift`-archetype agent that knows Apple-platform idioms, Swift concurrency, SwiftUI patterns, and Conductor (the macOS native app in this monorepo). On a Python web service, the Swift agent would be dead weight; on a Swift project, it is invaluable.
+
+`paradigm shift` reads the project signals and activates matching ecosystem agents automatically — `*.swift` triggers `swift`, and the same pattern extends as more ecosystem agents land (TypeScript, Python, Rust, and others). You can always bench an auto-rostered ecosystem agent later if your project drifts off that ecosystem, and you can always activate one by hand if you know you need it before the detection fires.
+
+The mechanics of *how* an ecosystem agent's notebook compounds across every project where its ecosystem is detected — the cross-project learning that makes specialty agents so valuable over time — are covered in **PARA 551: Agents in Practice**, the v6.1 follow-up course. For PARA 451, what matters is the high-level shape: *the framework picks ecosystem agents based on what it sees in your tree, and it does it without you having to ask.*
+
+## When to run it
+
+Three common moments:
+
+- **First time on a fresh project.** No `.paradigm/roster.yaml` exists yet. `paradigm shift` is the bootstrap.
+- **After cloning a project for the first time.** The repo may already have a roster, but if it does not (or if it looks wrong for your stack), shifting again is safe and idempotent.
+- **After a significant change in the project's tech stack.** You added a Swift package to a previously TypeScript-only repo; you migrated from one framework to another. Re-running `shift` reconsiders ecosystem agent selection against the new tree.
+
+You do **not** need to run it on every session. Once `roster.yaml` exists and reflects the project, day-to-day work uses `paradigm agent list`, `bench`, and `activate` (covered in the previous entry). `shift` is the heavyweight bootstrap; the others are the lightweight everyday.
+
+## What `shift` does **not** do
+
+- It does not modify global agent profiles (`~/.paradigm/agents/<id>.agent`). Agents must already be installed globally for `shift` to roster them; if a recommended agent is missing, the command surfaces it as "would activate, but not installed — use `/paradigm:agents` to install".
+- It does not pick *which model* each rostered agent runs on. That is governed by tier defaults and `model-resolution` overrides in `.paradigm/config.yaml` (see **N-para-451-tiers**).
+- It does not pick partners for you. The `partners:` declarations in each agent's profile are independent of rostering — `shift` rosters the instance, the profile carries the partner pre-declarations from when the agent was published.
+
+> **Coming in v6.1:** `paradigm shift` will additionally auto-populate **archetype-default authority claims** for archetypes that have them — most notably the compliance archetype, which gains a default authority claim on `.purpose` files and `portal.yaml` symbol declarations. At v6.0.3 the command rosters the instance without authority-claim wiring; the claims become operational once the v6.1 enforcement model lands. Existing rosters created today will pick up the defaults automatically when the new logic ships. See `agent-owned-enforcement-plan.md`.
+
+## A quick recipe
+
+Cloning a Paradigm project for the first time:
+
+```
+$ git clone <repo>
+$ cd <repo>
+$ paradigm agent list            # see what (if anything) the repo ships with
+# ... if the roster looks empty or wrong for your stack:
+$ paradigm shift                 # auto-roster
+$ paradigm agent list            # confirm the result
+```
+
+Three commands and you are oriented.
+
+## Up next
+
+You now know how to bootstrap, list, bench, and activate the team. The next set of entries shifts focus from *managing* the roster to *invoking* the team well — **N-para-451-orchestration-modes** covers how the team actually runs at runtime, **N-para-451-partners-primitive** covers how the framework expresses pair relationships, and **N-para-451-agent-routing** later will give you a quick-reference decision tree for "which agent should I invoke?"

package/dist/university-content/notes/N-para-451-partners-primitive.md

@@ -0,0 +1,107 @@
+---
+id: N-para-451-partners-primitive
+title: The Partners Primitive — Scholar + Sheila as the Canonical Pair
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - partners
+  - v6.0.3
+  - scholar-sheila
+  - intermediate
+symbols: []
+difficulty: intermediate
+estimatedMinutes: 8
+prerequisites:
+  - N-para-451-roster-reference
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+> **About this entry.** This entry is itself a Scholar+Sheila collaboration: Scholar produced the source material from `packages/paradigm-mcp/src/types/agents.ts` and the agent profiles in `~/.paradigm/agents/`; Sheila shaped it into pedagogical form. We are teaching the partners primitive *by being one*. That is intentional — the canonical example of a partnership is the partnership that wrote the canonical example.
+
+## Why partners exists
+
+Some agents do meaningfully better when paired with another agent. **Scholar** produces source material — gathered citations, surfaced files, raw research notes. **Sheila** shapes that source material into learning experiences — sequenced quizzes, paths, pedagogical framing. Either one alone would work; the two together are how PARA 451 gets authored at all.
+
+The framework needed a structural way to express this. Before v6.0.3, "these two agents work as a unit" was a convention you could read in their narrative profiles, but nothing in the schema reflected it — so tooling, the planned nevr.land marketplace, and the future pair-notebook surface had nowhere to hang. The **partners primitive**, shipped at v6.0.3, fixes that. It is a small, declarative addition to `AgentProfile` that says: "this agent has these specific partners, and here is what kind of relationship each one is."
+
+## The schema (the actual field shape)
+
+Defined in `packages/paradigm-mcp/src/types/agents.ts`:
+
+```ts
+export interface PartnerRef {
+  id: string;
+  relation?: string;                              // free-form label
+  share_notebooks?: 'off' | 'read' | 'read-write';
+}
+```
+
+In an `.agent` profile or in `agents.yaml`:
+
+```yaml
+partners:
+  - id: educator
+    relation: research-pair
+    share_notebooks: read-write
+```
+
+Three fields, two of them optional. **`id`** is the partner agent's id (machine-stable handle). **`relation`** is a free-form label — `research-pair`, `mentor`, `lead`, `qa-pair` are all reasonable. **`share_notebooks`** is the notebook-sharing posture, with three legal values today (`off`, `read`, `read-write`).
+
+## Scholar + Sheila as the canonical example
+
+Both halves of the reciprocal declaration:
+
+```yaml
+# In ~/.paradigm/agents/scholar.agent
+partners:
+  - id: educator
+    relation: research-pair
+    share_notebooks: read-write
+
+# In ~/.paradigm/agents/educator.agent
+partners:
+  - id: scholar
+    relation: research-pair
+    share_notebooks: read-write
+```
+
+Each agent declares the other. The `relation` matches on both sides (`research-pair`). The `share_notebooks` posture matches too. This is what a fully reciprocal pair looks like, and it is referenced explicitly in project memory (`feedback_specialized_agent_responsibilities.md`) as the canonical example of the "split strategy / split ops, pair via schema" pattern that Paradigm prefers over merging two roles into one mega-agent.
+
+## Reciprocal versus pending
+
+Pairings come in two shapes:
+
+- **Reciprocal:** A lists B *and* B lists A. The CLI shows a checkmark. Both agents agree on the partnership; tooling and (eventually) the pair notebook surface treat it as a first-class unit.
+- **Pending:** A lists B but B does not list A. The CLI shows a yellow warning. This is **legal** — it can be intentional (a mentor / lead pattern where the junior declares the senior but not vice versa) or accidental (typo in one of the two profiles). The framework does not assume one or the other; it surfaces the asymmetry and lets you decide.
+
+You can verify any pairing's status with `paradigm agent get <id>` and looking at the Partners block.
+
+## The pair notebook namespace (reserved at v6.0.3)
+
+The path `.paradigm/notebooks/_pairs/{a-b}/` is **reserved** for pair notebooks. The directory naming is alphabetical regardless of which agent declared the partnership first — so the Scholar / Sheila pair notebook would live at `.paradigm/notebooks/_pairs/educator-scholar/` (because `educator` sorts before `scholar`).
+
+At v6.0.3, this namespace is **claimed but unwritten**. No pair-notebook entries exist yet. Reserving the path now means that when pair-learning ships, every existing partnership declaration becomes meaningful immediately without a migration.
+
+## What `share_notebooks` does today
+
+At v6.0.3, the `share_notebooks` field is **declarative only** — the schema accepts it, the registry contracts model it, but no runtime enforcement reads it yet. Declaring `share_notebooks: read-write` on a partnership today is **forward-compat-safe** but produces no observable change in agent behaviour at v6.0.3.
+
+> **Coming in v6.1:** `share_notebooks` becomes runtime-enforced. `read` will let the partner consult the agent's notebook during their own runs; `read-write` will additionally let the partner write entries into the pair notebook namespace. The default value is also expected to shift at v6.1 (currently tracked as TD-2026-04-25-704). Declarations made today will not need rewriting once enforcement ships. See `agent-owned-enforcement-plan.md`.
+
+## Marketplace primitives (contracts only)
+
+A handful of related types in `packages/paradigm/src/commands/agent/registry-types.ts` model partnership for the planned nevr.land registry: `PartnerBundle` (a unit installable as a pair), `ReciprocalInstallMeta` (metadata that travels with a bundle), and `PartnerCoverage` (which partner declarations are reciprocal at install time). These are **defined but unwired** — the marketplace consumer arrives later. They are mentioned here so you know the partners primitive is designed to extend cleanly into the marketplace, not just to live inside one project.
+
+## Try this
+
+Run `paradigm agent get scholar`. Look for the **Partners** block — you should see `educator` listed with `relation: research-pair`. Now run `paradigm agent get educator`. The Partners block should list `scholar` symmetrically, and the CLI should mark the pair as reciprocal (a checkmark). If either side is missing or the relation differs, the pair will show as pending — that is the asymmetry signal the primitive exists to surface.
+
+## Up next
+
+The next entry — **N-para-451-orchestration-modes** — covers how the framework actually runs the team at runtime: faceted multi-agent execution in Claude Code versus sequential roleplay in IDEs without Task tool support.

package/dist/university-content/notes/N-para-451-roster-management.md

@@ -0,0 +1,132 @@
+---
+id: N-para-451-roster-management
+title: Roster Management — Listing, Benching, Activating, Shifting
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - cli
+  - roster
+  - skill
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-para-451-roster-reference
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## Roster vs profile (one more time)
+
+Two scopes. Keep them straight:
+
+- **Profile (global):** `~/.paradigm/agents/<id>.agent`. The agent itself — its identity, role, notebook home. Installed once per machine.
+- **Roster (per project):** `.paradigm/roster.yaml`. Which globally-installed agents are *active* on this project, plus their default tier.
+
+Roster management is about the **per-project** choice. None of the commands below modify global profiles — they only shape which agents your project asks for.
+
+## The CLI commands
+
+### `paradigm agent list`
+
+Show the current project's roster. One line per agent, with id, nickname, tier, and active/benched status.
+
+```
+$ paradigm agent list
+architect      Architect    tier-1   active
+builder        Builder      tier-3   active
+reviewer       Reviewer     tier-2   active
+security       Aegis        tier-1   active
+tester         Probe        tier-3   active
+documentor     Scribe       tier-2   active
+cid            Cid          tier-1   active
+forge          Loid         tier-1   active
+scholar        Scholar      tier-1   active
+educator       Sheila       tier-1   active
+ftux           Nora         tier-1   active
+designer       Mika         tier-2   benched
+...
+```
+
+Use this any time you want a snapshot of the team. The display name is the **nickname**; the leftmost column is the **id** — the same handle you pass to every other command.
+
+### `paradigm agent get <id>`
+
+Show one agent in detail: profile fields, partners block, tier, notebook stats, recent activity. Use this to inspect a single agent before benching, activating, or trying to debug a strange invocation.
+
+```
+$ paradigm agent get scholar
+```
+
+### `paradigm agent bench <id>`
+
+Mark an agent as **benched** on this project. Benched agents stay installed globally but do not participate in orchestration here. Useful when an agent is irrelevant to the current project (a UI-design specialist on a backend-only project, for example).
+
+```
+$ paradigm agent bench designer
+```
+
+### `paradigm agent activate <id>`
+
+The inverse of `bench`. Marks the agent as active on this project. If the agent is not yet installed globally, you will need to install it first (via the `/paradigm:agents` skill or directly from a registry source).
+
+```
+$ paradigm agent activate designer
+```
+
+### `paradigm shift`
+
+The **auto-rosterer**. Detects the language and platform of the current project (Swift, TypeScript, Python, and others) and selects an appropriate initial roster — the always-on backbone plus any matching ecosystem agents (Swift code activates `swift`, etc.).
+
+```
+$ paradigm shift
+```
+
+Run this once on a fresh project to bootstrap the roster, or run it again later if you have changed the project's tech stack and want the framework to reconsider which ecosystem agents belong. **N-para-451-auto-rostering** covers the detection logic and the cross-project notebook compounding that ecosystem agents bring with them.
+
+## The `/paradigm:agents` skill
+
+In Claude Code, the `/paradigm:agents` skill is the conversational wrapper around the same operations. It exposes:
+
+- Roster overview (the same view as `paradigm agent list`, with extra Neverland health metrics).
+- Onboarding flow for installing agents from GitHub or (in future) the nevr.land registry.
+- Bench / activate / detail operations on individual agents.
+
+The skill and the CLI are interchangeable surfaces over the same underlying state. Use the skill when you want a guided, conversational pass — installing for the first time, exploring what is available, asking "what should I do here?" Use the CLI when you know exactly what you want and just need it done.
+
+## The roster.yaml file
+
+For completeness, the file the CLI is editing:
+
+```yaml
+# .paradigm/roster.yaml
+active:
+  - id: architect
+    tier: tier-1
+  - id: builder
+    tier: tier-3
+  - id: reviewer
+    tier: tier-2
+  # ...
+benched:
+  - id: designer
+default_tier: tier-2
+```
+
+You can edit this file directly if you prefer — the CLI commands above are conveniences over the same YAML. The framework re-reads `roster.yaml` on every orchestration call, so changes take effect immediately.
+
+## Quick recipes
+
+- **Joining an existing project for the first time?** Run `paradigm agent list` to see the inherited roster. If it looks empty or wrong, run `paradigm shift` to auto-roster.
+- **An agent keeps getting invoked when you do not want it?** Bench it: `paradigm agent bench <id>`. Activate again later when the work calls for it.
+- **Want a roster preview before committing to it?** Use the `/paradigm:agents` skill — it shows what `shift` would do without applying.
+- **Curious which agents you have installed globally that are *not* on this roster?** Use the `/paradigm:agents` skill's "available but inactive" view.
+
+## Up next
+
+This is the last new entry in the course's batch-2 chunk. The next thing you should do is take **Q-para-451-foundations** — a 5-question quiz covering everything from the welcome through to here (what an agent is, the three identity layers, model tiers, faceted vs sequential mode, and roster management). Pass it and you have the agent foundations down cold.

package/dist/university-content/notes/N-para-451-roster-reference.md

@@ -0,0 +1,106 @@
+---
+id: N-para-451-roster-reference
+title: The Paradigm Roster — Canonical Reference
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - roster
+  - reference
+  - canonical
+  - agents
+symbols: []
+difficulty: beginner
+estimatedMinutes: 8
+prerequisites:
+  - N-para-451-identity-layers
+  - N-para-451-tiers
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## How to read this page
+
+> **One row per active agent.** Names in the **Nickname** column are the user-display layer; the **id** is the machine-stable handle used in CLI and MCP calls; the **archetype** is the role pattern the agent fills; the **tier** is the default model (see **N-para-451-tiers**). Same id may have a different nickname on your project — that is expected and supported.
+
+This page is the **most-referenced entry in the course**. Bookmark it. You will come back to it every time you wonder "who picks this up?" or "which agent handles X?". The roster shown here is the canonical first-party roster as of v6.0.3 — twenty-one active agents grouped by role family. Your project's actual roster may differ; run `paradigm agent list` to see what is active locally.
+
+## Always-on backbone (the seven you will meet first)
+
+These agents ship in every project's roster by default. They are the backbone of orchestration — almost every task touches at least one of them.
+
+| Nickname | id | Archetype | Tier | Specialty | When to invoke | Partners |
+|----------|----|-----------|------|-----------|----------------|----------|
+| Architect | `architect` | architect | 1 (opus) | System design, specs, multi-file planning. No code. | "design X", "plan a feature", anything spanning 3+ files | — |
+| Builder | `builder` | builder | 3 (haiku) | Implementation. Follows specs exactly. Pushes back when unclear. | "implement", "build", "wire up" | — |
+| Reviewer | `reviewer` | reviewer | 2 (sonnet) | Two-stage review (spec compliance, then code quality). Hands back; never fixes. | "review", "is this ready" | — |
+| Aegis | `security` | security | 1 (opus) | Auth, gates, OWASP. Reads `portal.yaml`. Flags only. | new endpoint, auth change, "audit" | — |
+| Probe | `tester` | tester | 3 (haiku) | Unit and integration tests. | "test", "verify", "edge cases" | qa (Shield) |
+| Scribe | `documentor` | documentor | 2 (sonnet) | Final orchestration stage. Updates `.purpose` files, `portal.yaml`, lore. Never source. | always last; auto-runs | cid (Cid) |
+| Cid | `cid` | captain | 1 (opus) | Session-level. Pre-task brief; post-task debrief. Maps blast radius. | first turn of a session, before anything else | forge (Loid) |
+
+## First-time-user guard
+
+| Nickname | id | Archetype | Tier | Specialty | When to invoke | Partners |
+|----------|----|-----------|------|-----------|----------------|----------|
+| Nora | `ftux` | ftux | 1 (opus) | Simulates a first-time user. Reads ONLY user-facing surfaces (README, --help, docs). Confusion **is** data. | after Builder, when the task touches a user-visible surface | — |
+
+## Learning loop
+
+These three agents power the framework's learning machinery — Loid runs the intelligence operation, Scholar produces source material, Sheila shapes it into learning experiences.
+
+| Nickname | id | Archetype | Tier | Specialty | When to invoke | Partners |
+|----------|----|-----------|------|-----------|----------------|----------|
+| Loid | `forge` | intelligence-officer | 1 (opus) | Agent intelligence officer. Designs agents, processes Cid's debrief, promotes journal → notebook → wisdom. | end of session; when adding or redesigning agents | cid (Cid) |
+| Scholar | `scholar` | scholar | 1 (opus) | Research, curation, citation discipline. Source-material producer. | "research", "curate", university content | educator (Sheila) — reciprocal |
+| Sheila | `educator` | educator | 1 (opus) | Pedagogical sequencing — quizzes, paths, PLSAT modules. Source-material shaper. | university content, course design, learning materials | scholar (Scholar) — reciprocal |
+
+## Specialty and ecosystem
+
+| Nickname | id | Archetype | Tier | Specialty | When to invoke | Partners |
+|----------|----|-----------|------|-----------|----------------|----------|
+| Rune | `compliance` | compliance | 2 (sonnet) | Symbol planner and coverage owner. Pre-impl plan; post-impl report. Never source. | when symbol coverage matters | — |
+| Jinx | `advocate` | advocate | 2 (sonnet) | Devil's advocate. Stress-tests assumptions; finds edge cases. | "what could break", before high-risk decisions | — |
+| Trace | `debugger` | debugger | 2 (sonnet) | Root-cause hunter. Hypothesis-driven, binary-search. | "this is broken", "why does X happen" | — |
+| Shield | `qa` | qa | 2 (sonnet) | Test **strategy** (not execution). Pyramid shape, coverage targets. | when designing the test plan, not writing tests | tester (Probe) |
+| Helix | `dx` | dx | 2 (sonnet) | DX/SDK engineer. APIs, integration guides, webhook flows. | API surface design, SDK, integration docs | — |
+| Mika | `designer` | designer | 2 (sonnet) | Design engineer. UI/UX, design systems, motion, accessibility. | UI work, design system changes | — |
+| Bolt | `performance` | performance | 2 (sonnet) | Core Web Vitals, bundles, query optimisation. | perf concerns, "why is this slow" | — |
+| Ship | `release` | release | 2 (sonnet) | Release manager. Versioning, changelogs, deployment coordination. | cutting a release, changelog work | — |
+| Scout | `researcher` | researcher | 2 (sonnet) | Business research, competitive analysis, growth mechanics. | market or strategy questions | — |
+| Swift | `swift` | swift | 2 (sonnet) | Swift / SwiftUI / Apple-platform specialist. Auto-rosters on Swift detection. Notebooks compound globally. | any Swift code, Conductor work | — |
+
+> **Coming in v6.1:** Rune's role sharpens substantially — three authority modes (Advise / Auto-author / Guard), a soft-block primitive, archetype-default authority claims, and the tier-1/tier-2 notebook split all land together. PARA 551: Agents in Practice covers the new surfaces. The roster row shown for Rune above is accurate at v6.0.3. See `agent-owned-enforcement-plan.md`.
+
+## Reading the partner column
+
+- A **reciprocal** pairing means both agents declare each other in their `partners:` block. The CLI shows a checkmark.
+- A **pending** pairing (the CLI shows a yellow warning) is one-way — A declares B, but B does not declare A. Both are legal. One-way is intentional in mentor / lead patterns and accidental in typos.
+- A blank in the **Partners** column means the agent has no current declared partners — this is fine; partners are an enrichment, not a requirement. Most agents on the roster work fine alone.
+
+The partners primitive is covered end-to-end in **N-para-451-partners-primitive** later in the course.
+
+## "When to invoke" is heuristic
+
+The **When to invoke** column is a heuristic — most invocation is automatic. Three things drive routing in practice:
+
+1. `paradigm_orchestrate_inline` — picks the right agent for the task based on keywords, file paths, and the orchestration mode.
+2. Natural keyword triggers in `agents.yaml` — e.g. "review" routes to Reviewer, "audit" routes to Aegis.
+3. Explicit invocation — when you call out an agent by id or nickname in a prompt, the orchestrator honours it.
+
+You should rarely need to invoke an agent by hand. When you do, it is usually because you want to bypass automatic routing for a specific reason (a second opinion, a forced specialty pass, a debugging dive).
+
+## Where these definitions live
+
+- **Profiles (per-id):** `~/.paradigm/agents/<id>.agent`
+- **This project's roster:** `.paradigm/roster.yaml`
+- **Adoption metadata:** `.paradigm/adoptions.yaml`
+- **Prompts and tier mapping (source of truth):** `packages/paradigm-mcp/src/tools/orchestration.ts`
+
+## Snapshot disclaimer
+
+This roster is a **snapshot** of the canonical first-party agent set. Your project's actual roster varies — `paradigm shift` selects an initial roster based on detected language and platform; you may bench, activate, or install agents at any time. Run `paradigm agent list` to see your local roster. The roster-management entry later in the course (**N-para-451-roster-management**) covers how to customise.

package/dist/university-content/notes/N-para-451-the-team-pattern.md

@@ -0,0 +1,87 @@
+---
+id: N-para-451-the-team-pattern
+title: The Team Pattern — Why Paradigm Has Many Agents Instead of One
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - capstone
+  - team-pattern
+  - multi-agent
+  - philosophy
+symbols: []
+difficulty: beginner
+estimatedMinutes: 7
+prerequisites:
+  - N-para-451-agent-routing
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## The question, asked seriously
+
+Now that you have met the roster, learned the identity model, walked through the orchestration modes, seen the partners primitive, and read the routing tree — there is one question worth ending on: **why bother with all of this?** Why does Paradigm ship a roster of twenty-one specialised agents instead of giving you one big general-purpose Claude with a long system prompt and calling it a day?
+
+The honest answer is that Paradigm tried both shapes during its development, and the team pattern won on every dimension that turned out to matter. This entry walks through *why* — five reasons, each one earned from real field use.
+
+## Reason 1: Specialised attention beats generalist attention
+
+The same Claude model, asked to design a system, produces *measurably different* output than the same Claude model asked to implement a spec. Not because the model is different — it is the same model — but because the *framing* is different.
+
+When **Architect** is invoked, its profile narrows the model's attention to multi-file planning, spec coherence, blast-radius reasoning, and ripple analysis. When **Builder** is invoked, its profile narrows attention to "follow the spec exactly, push back if unclear, ship the code". The two framings produce different reasoning paths. A single mega-agent prompt has to hold both framings (and twenty more) simultaneously, and the cost is real: the model's attention is stretched, the framing is muddled, the output trends toward generic.
+
+A team is a way of giving the same Claude **multiple framings** in the same project — each at the right time, each with its own depth, each focused on the slice of the work it is best at. That is not decoration. It is the simplest architecturally-correct answer to "how do I get specialised output from a generalist model?"
+
+## Reason 2: Parallel context — separate rooms for separate jobs
+
+In Claude Code's faceted orchestration mode, each agent runs as an isolated Task subagent. Architect's planning chatter does not pollute Builder's implementation context. Reviewer reads the code with literally fresh eyes — its Task starts blank, sees only the diff and the spec, and forms an opinion uncontaminated by the back-and-forth that produced the diff in the first place.
+
+You cannot get this from a single mega-agent. Single conversation, single memory, single attention budget. Even when the agent is told "now switch into review mode", it remembers what it was just doing — and its review is shaped by that memory whether you want it to be or not. Parallel context is what makes the framework's multi-stage workflows trustworthy: the next stage actually sees fresh, not "fresh in spirit".
+
+This matters less in sequential mode (Cursor, IDEs without Task tool support), where shared memory is unavoidable — but even there, the *attribution* of voice and the *separation of profiles* preserves most of the value. The team pattern degrades gracefully; the single-agent pattern has nowhere to degrade to.
+
+## Reason 3: Partners — pair-coverage as a first-class primitive
+
+Some work is meaningfully better when two agents collaborate as a unit. **Scholar** produces source material; **Sheila** shapes it into learning experiences. **Builder** writes; **Tester** verifies. **Cid** briefs the session; **Loid** processes the debrief. The pairings are not accidents — they reflect that the cognitive shape of certain jobs is naturally two-handed.
+
+The **partners primitive** (covered in detail in `N-para-451-partners-primitive`) is the framework's structural way of expressing this. A pair is declared in each agent's profile, the marketplace will eventually install them as a unit, and the pair-notebook namespace (`.paradigm/notebooks/_pairs/{a-b}/`) is reserved so that joint learning has somewhere to live. None of this is possible with a single mega-agent — there is no "pair" to declare when the agent has no peer.
+
+The partners primitive is also a quiet bet about the *direction of the framework*: not toward bigger, more capable individual agents, but toward better-coordinated small ones. The team gets stronger by adding pairings, not by inflating any individual member.
+
+## Reason 4: Compounding learning, lane by lane
+
+The framework's learning loop — journal observation → notebook entry → wisdom promotion — runs **per agent**. Architect's notebook accrues design patterns. Reviewer's notebook accrues review heuristics. Loid's notebook accrues learning-loop observations. The Swift agent's notebook compounds Swift idioms across every Swift project on your machine.
+
+If everything were one agent, all of these patterns would muddle into a single notebook. The signal would dilute. "Architect knows" and "Builder knows" and "Reviewer knows" would collapse into "the agent knows", and the role-shaped sharpness that makes each pattern useful in its lane would be lost. The team pattern is what lets each agent's learned expertise stay focused — and what lets cross-project compounding (the bet that ecosystem agents pay off more the more projects you have) actually work.
+
+**Loid** (`forge`), the intelligence officer, is the agent that runs this loop end-to-end. She processes Cid's session debriefs, decides which observations should promote, and tracks override patterns that hint at tier-defaults that should change. She is the agent the framework's learning bet runs through — and she only makes sense in a multi-agent world. A single mega-agent has no one to learn *for*.
+
+## Reason 5: A team you can talk about, hire from, and trust differently
+
+The five reasons above are technical. The sixth is human, and it might matter most: **a team is something you can develop a relationship with.** You learn that Architect is patient with ambiguity. You learn that Jinx will surface the failure mode no one else thought of. You learn that Nora will catch the README confusion you would never have caught yourself. You build trust per agent, and you trust each one for what it is good at — not as a uniform "trust the AI" sentiment that has to apply equally to every task.
+
+This shape also lets the framework express a **registry** (the planned nevr.land marketplace) where archetypes travel as units, instances compete on quality within an archetype, and pairings install as bundles. None of that is coherent in a single-agent world. It is exactly coherent in a team world, and it is what Paradigm is built to grow into.
+
+## What this means for how you use the framework
+
+A few practical takeaways from the philosophy:
+
+- **Trust automatic routing first.** The framework picks agents well. Override only when you have a reason.
+- **Lean on partners.** When work is naturally two-handed (research + pedagogy, implementation + verification), invoke the pair, not just one half.
+- **Let agents specialise their notebooks.** Resist the urge to ask the wrong agent to do work outside its lane just because it happens to be in front of you. The lane *is* the value.
+- **Loid is your training loop.** When you see an agent making a recurring mistake, surface it to Loid through the journal. The pattern that lands in the right notebook is worth ten patterns delivered as ad-hoc instructions.
+- **Cid bookends every session.** Pre-task brief, post-task debrief. The team works substantially better when the captain is given the first and last turn.
+
+## The transition to PARA 551
+
+PARA 451 is intentionally stable — the identity layers, archetype / instance split, canonical roster, partners primitive, orchestration modes, model tiers, roster management, and routing decisions covered here are the parts of the agent system that do not change as the framework evolves. They are the foundations.
+
+> **Coming in v6.1:** **PARA 551: Agents in Practice** picks up where 451 leaves off. It covers Rune's three authority modes (Advise / Auto-author / Guard), the soft-block primitive, archetype-default authority claims, the tier-1 / tier-2 notebook split, and the runtime mechanics of cross-project compounding (the layer beneath the high-level "ecosystem agents learn over time" framing in this course). PARA 551 treats PARA 451 as a hard prerequisite — you will be ready when you finish here. See `agent-owned-enforcement-plan.md`.
+
+## Up next
+
+You have one quiz left in PARA 451: **Q-para-451-when-to-invoke** — five scenario-routing questions that test the decision-tree material from `N-para-451-agent-routing`. Pass it and you have closed Phase A of the agents course.