@codyswann/lisa 2.23.0 → 2.23.2

package/harper-fabric/package-lisa/package.lisa.json

@@ -2,7 +2,6 @@
   "force": {
     "scripts": {
       "bootstrap": "bash scripts/bootstrap.sh",
-      "build": "tsc && node dist/src/build/build.js",
       "typecheck": "tsc --noEmit",
       "test": "vitest run",
       "test:cov": "vitest run --coverage",
@@ -17,25 +16,6 @@
       "start": "harperdb start",
       "stop": "harperdb stop",
       "status": "harperdb status",
-      "seed": "bun run build && node dist/src/scripts/seed.js",
-      "verify": "bun run build && node dist/src/scripts/verify.js",
-      "seed:rest": "bun run build && node dist/src/scripts/seed_via_rest.js",
-      "verify:rest": "bun run build && node dist/src/scripts/verify_via_rest.js",
-      "preview": "bun run build && node dist/src/scripts/preview_feed.js",
-      "dev:server": "bun run build && node dist/src/scripts/dev_server.js",
-      "deploy": "bun run build && node dist/src/scripts/deploy.js",
-      "smoke": "bun run build && node dist/tests/web_smoke.js",
-      "smoke:brokercheck": "bun run build && node dist/tests/brokercheck_web_smoke.js",
-      "token": "bun run build && node dist/src/scripts/get_token.js",
-      "crawl:wpjson": "bun run build && node dist/src/scripts/crawl_via_wpjson.js",
-      "crawl:html": "bun run build && node dist/src/scripts/crawl_html.js",
-      "crawl:playwright": "bun run build && node dist/src/scripts/crawl_playwright.js",
-      "extract:fields": "bun run build && node dist/src/scripts/extract_fields.js",
-      "extract:helper": "bun run build && node dist/src/scripts/extract_helper.js",
-      "ingest": "bun run build && node dist/src/scripts/ingest.js",
-      "load:extractions": "bun run build && node dist/src/scripts/load_extractions.js",
-      "brokercheck": "bun run build && node dist/src/scripts/fetch_brokercheck.js",
-      "brokercheck:crawl": "bun run build && node dist/src/scripts/brokercheck_crawl_all.js",
       "reset": "harperdb stop || true; [ -n \"$HOME\" ] && rm -rf \"$HOME/.harperdb\" && bun run bootstrap && bun run seed && bun run verify",
       "prepare": "husky install || true"
     },
@@ -45,7 +25,6 @@
     },
     "devDependencies": {
       "@ast-grep/cli": "^0.40.4",
-      "@codyswann/lisa": "^2.19.0",
       "@commitlint/cli": "^20.3.1",
       "@commitlint/config-conventional": "^20.3.1",
       "@eslint-community/eslint-plugin-eslint-comments": "^4.5.0",
@@ -90,5 +69,29 @@
       "@codyswann/lisa",
       "@sentry/cli"
     ]
+  },
+  "defaults": {
+    "scripts": {
+      "build": "tsc && node dist/src/build/build.js",
+      "seed": "bun run build && node dist/src/scripts/seed.js",
+      "verify": "bun run build && node dist/src/scripts/verify.js",
+      "seed:rest": "bun run build && node dist/src/scripts/seed_via_rest.js",
+      "verify:rest": "bun run build && node dist/src/scripts/verify_via_rest.js",
+      "preview": "bun run build && node dist/src/scripts/preview_feed.js",
+      "dev:server": "bun run build && node dist/src/scripts/dev_server.js",
+      "deploy": "bun run build && node dist/src/scripts/deploy.js",
+      "smoke": "bun run build && node dist/tests/web_smoke.js",
+      "smoke:brokercheck": "bun run build && node dist/tests/brokercheck_web_smoke.js",
+      "token": "bun run build && node dist/src/scripts/get_token.js",
+      "crawl:wpjson": "bun run build && node dist/src/scripts/crawl_via_wpjson.js",
+      "crawl:html": "bun run build && node dist/src/scripts/crawl_html.js",
+      "crawl:playwright": "bun run build && node dist/src/scripts/crawl_playwright.js",
+      "extract:fields": "bun run build && node dist/src/scripts/extract_fields.js",
+      "extract:helper": "bun run build && node dist/src/scripts/extract_helper.js",
+      "ingest": "bun run build && node dist/src/scripts/ingest.js",
+      "load:extractions": "bun run build && node dist/src/scripts/load_extractions.js",
+      "brokercheck": "bun run build && node dist/src/scripts/fetch_brokercheck.js",
+      "brokercheck:crawl": "bun run build && node dist/src/scripts/brokercheck_crawl_all.js"
+    }
   }
 }

package/package.json

@@ -82,7 +82,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -199,7 +199,7 @@
     "vitest": "^4.1.0"
   },
   "devDependencies": {
-    "@codyswann/lisa": "^2.19.0",
+    "@codyswann/lisa": "^2.23.1",
     "@types/js-yaml": "^4.0.9",
     "eslint-plugin-oxlint": "^1.62.0",
     "js-yaml": "^4.1.1",

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/agents/learnings-synthesizer.md

@@ -131,5 +131,5 @@ The `Disposition` column is the contract with `debrief-apply`. Keep it exactly a
 - **Exhaustive, not selective.** Every distinct (post-dedupe) finding becomes a row. If the doc is large, that reflects the size of the initiative — do not trim.
 - **Group by category, not by source.** The human is triaging by what to do, not by where the signal came from.
 - **Preserve evidence links.** Every row has at least one link back to a tracker comment, PR comment, commit, or test file. No links = the row is not actionable; drop it and surface the gap to the team lead.
-- **Run within the team.** Do not call `TeamCreate`.
+- **Run within the team.** Do not create a second team.
 - **Block on missing input.** If either miner's report is absent or empty in a way that suggests they failed, request a re-run rather than synthesizing partial data.

package/plugins/lisa/agents/pr-mining-specialist.md

@@ -80,6 +80,6 @@ If there are no findings under a checklist row, write `(none)`.
 - **Never judge.** Surface every match. The synthesizer reconciles signal vs. noise.
 - **Quote verbatim.** Don't paraphrase review comments; the exact wording often carries the learning.
 - **Link, don't summarize.** Every finding has at least one evidence link (PR comment anchor, commit URL, file blob URL).
-- **Run within the team.** Do not call `TeamCreate`. The Debrief skill created the team; you are a teammate.
+- **Run within the team.** Do not create a second team. The Debrief skill created the team; you are a teammate.
 - **Read-only.** No `gh pr merge`, no `gh pr review`, no commits. You observe; you do not mutate.
 - **Parallel-safe.** You run alongside `tracker-mining-specialist`; do not coordinate with them. The synthesizer reconciles.

package/plugins/lisa/agents/tracker-mining-specialist.md

@@ -80,6 +80,6 @@ If there are no findings under a checklist row, write `(none)` — silence is it
 - **Never judge.** "Probably not interesting" is not a category. Every signal that matches a checklist row goes in.
 - **Quote verbatim.** Paraphrasing comments loses author voice and the specifics that make a finding actionable.
 - **Link, don't summarize.** Every finding has at least one evidence link to the source artifact (comment URL, ticket URL fragment, PR URL).
-- **Run within the team.** Do not call `TeamCreate`. The Debrief skill created the team; you are a teammate.
+- **Run within the team.** Do not create a second team. The Debrief skill created the team; you are a teammate.
 - **Read-only.** Never call write MCP tools. You report; you do not mutate.
 - **Parallel-safe.** You run alongside `pr-mining-specialist`; do not coordinate with them. The synthesizer reconciles.

package/plugins/lisa/hooks/enforce-team-first.sh

@@ -1,18 +1,22 @@
 #!/usr/bin/env bash
-# Enforces team-first orchestration for lifecycle skills.
+# Enforces Claude's TeamCreate-first orchestration for lifecycle skills.
+#
+# This hook is intentionally Claude-specific. Other harnesses may use different
+# team tooling or an explicit no-team fallback; those paths are described in the
+# shared rules/skills but are not enforced by this Claude hook.
 #
 # Triggered on four hook events:
 #   - UserPromptSubmit  : detects /lisa:research|plan|implement|intake|debrief in the
 #                         raw prompt and arms enforcement for the session
 #   - PreToolUse        : detects the same skills via a `Skill` tool call,
 #                         arms enforcement, and blocks bypass tool calls
-#                         until ToolSearch+TeamCreate have fired
-#   - PostToolUse       : on a successful TeamCreate, marks the session as
+#                         until ToolSearch+TeamCreate have fired in Claude
+#   - PostToolUse       : on a successful Claude TeamCreate, marks the session as
 #                         team-created (lifts enforcement)
 #   - SubagentStart     : marks the new subagent session as a teammate so
 #                         it is exempt — teammates inherit the lead's team
-#                         and must never call TeamCreate (double-create
-#                         is rejected by the harness)
+#                         and must never create a second team (double-create
+#                         is rejected by the Claude harness)
 #
 # Per-session state lives under "$STATE_DIR" as flag files keyed by
 # session_id. Stale state (>24h) is cleaned on each invocation.
@@ -159,7 +163,7 @@ fi
 ACTIVE_SKILL=$(cat "$SKILL_FLAG" 2>/dev/null || echo "lisa:???")
 cat >&2 <<EOF
 Blocked: this session invoked /${ACTIVE_SKILL}, which is an agent-team flow.
-Before any other tool call, you must:
+In Claude, before any other tool call, you must:
 
   1. ToolSearch with query: "select:TeamCreate"  (load the deferred schema)
   2. TeamCreate                                   (actually create the team)
@@ -169,6 +173,10 @@ the ticket, exploring the code, fetching context — those are tasks for the
 team you are about to create, not for the lead session before the team
 exists.
 
+If you are running Lisa in a non-Claude harness, this Claude enforcement hook
+should not be installed; follow the runtime-aware orchestration preamble in the
+skill instead.
+
 Re-read the orchestration preamble in /${ACTIVE_SKILL} and start with
 ToolSearch.
 EOF

package/plugins/lisa/rules/base-rules.md

@@ -8,7 +8,7 @@ After echoing the chosen flow and BEFORE doing any work, state the orchestration
 
 Default to an agent team for Research, Plan, Implement (Build/Fix/Improve/Investigate-Only), and any flow that invokes the Review sub-flow. Use a single agent only for Verify (standalone) and Monitor (standalone). See the `intent-routing` rule's Orchestration section for the full decision matrix.
 
-When the mode is `agent team` **and you are not already operating inside an agent team**, your FIRST tool calls after the classification echo MUST be `ToolSearch` with `query: "select:TeamCreate"` (to load the deferred tool's schema), then `TeamCreate`. Do not reach for `TaskCreate`, `Agent`, `Skill`, MCP tools, `Read`, `Bash`, or any other content-gathering call before the team exists — those are bypass paths that skip durable task state and parallel review. Reading the ticket, exploring the code, querying the API are all tasks for the team, not for the lead session before the team exists.
+When the mode is `agent team` **and you are not already operating inside an agent team**, your FIRST tool calls after the classification echo MUST establish team orchestration before any content-gathering work. Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally. Do not reach for `TaskCreate`, `Agent`, `Skill`, MCP tools, `Read`, `Bash`, or any other content-gathering call before the team exists or the no-team fallback has been declared — those are bypass paths that skip durable task state and parallel review. Reading the ticket, exploring the code, querying the API are all tasks for the team, not for the lead session before orchestration exists.
 
 Requirement Verification:
 
@@ -130,4 +130,4 @@ When you detect any of the above:
 1. Do NOT guess or make assumptions about what the external code does
 2. Identify which repository contains the missing code
 3. Add that repository to your current session before proceeding
-4. If you cannot determine which repository contains the code, ask — do not proceed without it
+4. If you cannot determine which repository contains the code, ask — do not proceed without it

package/plugins/lisa/rules/intent-routing.md

@@ -32,11 +32,11 @@ What this rule still enforces:
    > **Orchestration: agent team** (or **single agent**)
    > One-sentence justification.
 
-2. **Cascade rule (load-bearing)**: Before calling `TeamCreate`, check whether you are already operating inside an agent team. Signs you are inside a team: a prior `TeamCreate` exists in this session; you were spawned via `Agent` with `team_name`; your context references a team lead. If any of these are true, **do NOT call `TeamCreate`** — the harness rejects double-creates and the work stalls. Continue within the existing team. Invoke flows via the Skill tool; the team lead inherits responsibility for orchestration.
+2. **Cascade rule (load-bearing)**: Before creating a team, check whether you are already operating inside an agent team. Signs you are inside a team: a prior successful team-creation tool call exists in this session; you were spawned into a team context; your context references a team lead. If any of these are true, **do NOT create a second team** — many harnesses reject double-creates and the work stalls. Continue within the existing team. Invoke flows via the Skill tool; the team lead inherits responsibility for orchestration.
 
 3. **Default mode**: `Research`, `Plan`, `Implement`, `Intake`, and `Debrief` run as agent teams. The `Implement` flow — including every work type (`Build`, `Fix`, `Improve`, `Investigate-Only`) — is **always** a team flow. Bug fixes that "look simple" are not an exception: the Reproduce sub-flow, debug-specialist, bug-fixer, parallel reviewers, and verification-specialist all need to compose. `Debrief` runs as a team because tracker-mining and pr-mining parallelize cleanly and synthesis gates on both completing. `Verify` (standalone) and `Monitor` (standalone) use the One-shot Sub-agents pattern (see `## Orchestration` below) — these flows are linear with no parallelism and the team overhead is not warranted. Single-agent mode is otherwise reserved for: `product-walkthrough` invoked standalone (not as part of Research/Plan), `debrief-apply` (deterministic routing of human-marked dispositions), and one-off diagnostic Bash/Read sessions that don't invoke any lifecycle skill. When in doubt, use a team.
 
-The mechanical TeamCreate bootstrap directive lives inside each lifecycle skill — see those skills' orchestration preambles for the exact wording: first `ToolSearch{select:TeamCreate}` (load deferred schema), then `TeamCreate`.
+The mechanical team bootstrap directive lives inside each lifecycle skill — see those skills' orchestration preambles for the exact wording. The Claude path uses `TeamCreate`; other runtimes must use their equivalent team-discovery and team-creation tools, or explicitly declare the no-team fallback when no such tool exists.
 
 ## Readiness Gate Protocol
 
@@ -364,7 +364,7 @@ Lifecycle skills dispatch their agents according to the flow's shape. The follow
 
 ### Agent Teams (default for multi-step flows)
 
-Use an **agent team** (TeamCreate + TaskCreate per step) for:
+Use an **agent team** (runtime team creation + durable task state per step) for:
 
 - **Implement** (Build, Fix, Improve) — long sequences with parallel review and a real risk of compaction
 - **Plan** — multiple specialists feeding a shared decomposition
@@ -390,7 +390,7 @@ Use direct `Agent` tool invocations (no team) for:
 - **Investigate Only** spikes — single investigation, findings out
 - Any flow chained as a sub-flow inside a larger team — its agents become tasks in the parent team, not a new team
 
-Why: TeamCreate plus per-step TaskCreate is real overhead. For a one-or-two-agent flow with no parallelism, the bookkeeping cost outweighs the recovery and orchestration benefits.
+Why: team creation plus per-step task state is real overhead. For a one-or-two-agent flow with no parallelism, the bookkeeping cost outweighs the recovery and orchestration benefits.
 
 ### When in doubt
 

package/plugins/lisa/skills/debrief/SKILL.md

@@ -10,14 +10,13 @@ Walk the original Plan for `$ARGUMENTS`, mine the completed work items and their
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Resolving the work-item set, fetching tickets, walking PRs — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Resolving the work-item set, fetching tickets, walking PRs — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team.
 
 ## Input
 

package/plugins/lisa/skills/implement/SKILL.md

@@ -7,16 +7,15 @@ description: This skill should be used for any non-trivial request — features,
 
 ## Orchestration: agent team
 
-Implement is **always** a team flow. Bug, Build, Improve, and Investigate-Only all compose multiple specialists (Reproduce → debug → fix → review → verify). Single-agent mode is not an option here, regardless of how "simple" the ticket looks.
+Implement is a **team-first** flow. Bug, Build, Improve, and Investigate-Only all compose multiple specialists (Reproduce → debug → fix → review → verify). Single-agent mode is not permitted based on task complexity — the only exception is when no team creation tool is available in the current runtime (see no-team fallback in the paragraph below).
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team. Every team must include the Explore agent.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally. Every team must include the Explore agent.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill` (including `lisa:tracker-read`, `lisa:jira-read-ticket`, `lisa:github-read-issue`), MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Reading the ticket, exploring the code, fetching context — every one of those is a task for the team you are about to create, not for the lead session before the team exists. Doing them inline is the exact bypass path that produces a 1-agent ad-hoc fix instead of a real team flow.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill` (including `lisa:tracker-read`, `lisa:jira-read-ticket`, `lisa:github-read-issue`), MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Reading the ticket, exploring the code, fetching context — every one of those is a task for the team you are about to create, not for the lead session before orchestration exists. Doing them inline is the exact bypass path that produces a 1-agent ad-hoc fix instead of a real team flow.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool, or `lisa:intake` is running this skill per Ready ticket), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool, or `lisa:intake` is running this skill per Ready ticket), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Resolve the input (first task assigned to the team)
 

package/plugins/lisa/skills/intake/SKILL.md

@@ -27,16 +27,15 @@ The only legitimate reasons to stop early:
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Scanning the queue, claiming items, dispatching per-item flows — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Scanning the queue, claiming items, dispatching per-item flows — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
-The cycle's outer team is created by Intake. Each item it processes (a PRD via `lisa:plan`, a ticket via `lisa:implement`) executes within the same team — those skills' orchestration preambles detect the existing team and skip TeamCreate. One team per cron cycle, processes everything currently Ready.
+The cycle's outer team is created by Intake. Each item it processes (a PRD via `lisa:plan`, a ticket via `lisa:implement`) executes within the same team — those skills' orchestration preambles detect the existing team and skip creating a second team. One team per cron cycle, processes everything currently Ready.
 
 ## Source dispatch
 

package/plugins/lisa/skills/monitor/SKILL.md

@@ -10,14 +10,13 @@ Spot-check application health in the named environment (`dev` / `staging` / `pro
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion / Sentry), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Hitting health endpoints, pulling logs, querying Sentry — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion / Sentry), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Hitting health endpoints, pulling logs, querying Sentry — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Flow
 

package/plugins/lisa/skills/plan/SKILL.md

@@ -10,14 +10,13 @@ Decompose the PRD/spec at `$ARGUMENTS` into ordered work items with acceptance c
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Reading the PRD, exploring the code, fetching context — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Reading the PRD, exploring the code, fetching context — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Source dispatch
 

package/plugins/lisa/skills/research/SKILL.md

@@ -10,14 +10,13 @@ Produce a PRD for the problem in `$ARGUMENTS`.
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Gathering context inline as the lead is the exact bypass path that produces ad-hoc work instead of a real team flow.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Gathering context inline as the lead is the exact bypass path that produces ad-hoc work instead of a real team flow.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Flow
 

package/plugins/lisa/skills/verify/SKILL.md

@@ -10,14 +10,13 @@ Ship the current branch and prove it works in the target environment.
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Inspecting the branch, running quality gates, opening the PR — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Inspecting the branch, running quality gates, opening the PR — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Flow
 

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/skills/ops-browser-uat/SKILL.md

@@ -14,7 +14,7 @@ Perform browser-based user acceptance testing using Playwright MCP tools.
 
 ## Prerequisites
 
-1. **Load Playwright MCP tools** — use `ToolSearch` to search for `playwright browser` and load all browser tools.
+1. **Load Playwright MCP tools** — use the current runtime's tool-discovery mechanism to search for `playwright browser` and load all browser tools.
 2. **Verify target environment is up** — curl check the frontend URL before launching the browser.
 3. **For localhost** — ensure the frontend is running on port 8081.
 

package/plugins/lisa-expo/skills/ops-check-logs/SKILL.md

@@ -40,7 +40,7 @@ For inspecting JavaScript errors, warnings, and `console.log` output in the brow
 
 Use when you need to capture browser logs programmatically during UAT or debugging.
 
-1. **Load Playwright tools** — use `ToolSearch` to search for `playwright browser`.
+1. **Load Playwright tools** — use the current runtime's tool-discovery mechanism to search for `playwright browser`.
 
 2. **Navigate to the app**:
    - `browser_navigate` to the target URL (discover from `e2e/constants.ts` or `.env.*` files)

package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/skills/nestjs-graphql/references/project-patterns.md

@@ -443,6 +443,54 @@ export class UsersModule {}
 export class AppModule {}
 ```
 
+## Resolver Boundary Patterns
+
+Resolvers translate GraphQL requests into service calls. Keep business rules in
+services so the same behavior is available to jobs, REST handlers, and future
+GraphQL fields without copying resolver logic.
+
+### Thin Resolver
+
+```typescript
+@Resolver(() => User)
+export class UsersResolver {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Query(() => User)
+  async user(@Args("id", { type: () => ID }) id: string): Promise<User> {
+    return this.usersService.findById(id);
+  }
+}
+```
+
+### Field Resolver
+
+Use field resolvers for data that depends on the parent object or benefits from
+DataLoader batching. Do not fetch relation-heavy data inside the parent query
+when only some clients ask for it.
+
+```typescript
+@ResolveField(() => [Post])
+async posts(@Parent() user: User): Promise<readonly Post[]> {
+  return this.postsByUserLoader.load(user.id);
+}
+```
+
+### Mutation Resolver
+
+Validate transport-level shape in DTOs and leave state transitions to the
+service. This keeps GraphQL decorators from becoming the source of business
+truth.
+
+```typescript
+@Mutation(() => User)
+async updateUser(
+  @Args("input") input: UpdateUserInput
+): Promise<User> {
+  return this.usersService.update(input);
+}
+```
+
 ## Error Handling Patterns
 
 ### Standard Error Response

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.23.0",
+  "version": "2.23.2",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/agents/learnings-synthesizer.md

@@ -131,5 +131,5 @@ The `Disposition` column is the contract with `debrief-apply`. Keep it exactly a
 - **Exhaustive, not selective.** Every distinct (post-dedupe) finding becomes a row. If the doc is large, that reflects the size of the initiative — do not trim.
 - **Group by category, not by source.** The human is triaging by what to do, not by where the signal came from.
 - **Preserve evidence links.** Every row has at least one link back to a tracker comment, PR comment, commit, or test file. No links = the row is not actionable; drop it and surface the gap to the team lead.
-- **Run within the team.** Do not call `TeamCreate`.
+- **Run within the team.** Do not create a second team.
 - **Block on missing input.** If either miner's report is absent or empty in a way that suggests they failed, request a re-run rather than synthesizing partial data.

package/plugins/src/base/agents/pr-mining-specialist.md

@@ -80,6 +80,6 @@ If there are no findings under a checklist row, write `(none)`.
 - **Never judge.** Surface every match. The synthesizer reconciles signal vs. noise.
 - **Quote verbatim.** Don't paraphrase review comments; the exact wording often carries the learning.
 - **Link, don't summarize.** Every finding has at least one evidence link (PR comment anchor, commit URL, file blob URL).
-- **Run within the team.** Do not call `TeamCreate`. The Debrief skill created the team; you are a teammate.
+- **Run within the team.** Do not create a second team. The Debrief skill created the team; you are a teammate.
 - **Read-only.** No `gh pr merge`, no `gh pr review`, no commits. You observe; you do not mutate.
 - **Parallel-safe.** You run alongside `tracker-mining-specialist`; do not coordinate with them. The synthesizer reconciles.

package/plugins/src/base/agents/tracker-mining-specialist.md

@@ -80,6 +80,6 @@ If there are no findings under a checklist row, write `(none)` — silence is it
 - **Never judge.** "Probably not interesting" is not a category. Every signal that matches a checklist row goes in.
 - **Quote verbatim.** Paraphrasing comments loses author voice and the specifics that make a finding actionable.
 - **Link, don't summarize.** Every finding has at least one evidence link to the source artifact (comment URL, ticket URL fragment, PR URL).
-- **Run within the team.** Do not call `TeamCreate`. The Debrief skill created the team; you are a teammate.
+- **Run within the team.** Do not create a second team. The Debrief skill created the team; you are a teammate.
 - **Read-only.** Never call write MCP tools. You report; you do not mutate.
 - **Parallel-safe.** You run alongside `pr-mining-specialist`; do not coordinate with them. The synthesizer reconciles.

package/plugins/src/base/hooks/enforce-team-first.sh

@@ -1,18 +1,22 @@
 #!/usr/bin/env bash
-# Enforces team-first orchestration for lifecycle skills.
+# Enforces Claude's TeamCreate-first orchestration for lifecycle skills.
+#
+# This hook is intentionally Claude-specific. Other harnesses may use different
+# team tooling or an explicit no-team fallback; those paths are described in the
+# shared rules/skills but are not enforced by this Claude hook.
 #
 # Triggered on four hook events:
 #   - UserPromptSubmit  : detects /lisa:research|plan|implement|intake|debrief in the
 #                         raw prompt and arms enforcement for the session
 #   - PreToolUse        : detects the same skills via a `Skill` tool call,
 #                         arms enforcement, and blocks bypass tool calls
-#                         until ToolSearch+TeamCreate have fired
-#   - PostToolUse       : on a successful TeamCreate, marks the session as
+#                         until ToolSearch+TeamCreate have fired in Claude
+#   - PostToolUse       : on a successful Claude TeamCreate, marks the session as
 #                         team-created (lifts enforcement)
 #   - SubagentStart     : marks the new subagent session as a teammate so
 #                         it is exempt — teammates inherit the lead's team
-#                         and must never call TeamCreate (double-create
-#                         is rejected by the harness)
+#                         and must never create a second team (double-create
+#                         is rejected by the Claude harness)
 #
 # Per-session state lives under "$STATE_DIR" as flag files keyed by
 # session_id. Stale state (>24h) is cleaned on each invocation.
@@ -159,7 +163,7 @@ fi
 ACTIVE_SKILL=$(cat "$SKILL_FLAG" 2>/dev/null || echo "lisa:???")
 cat >&2 <<EOF
 Blocked: this session invoked /${ACTIVE_SKILL}, which is an agent-team flow.
-Before any other tool call, you must:
+In Claude, before any other tool call, you must:
 
   1. ToolSearch with query: "select:TeamCreate"  (load the deferred schema)
   2. TeamCreate                                   (actually create the team)
@@ -169,6 +173,10 @@ the ticket, exploring the code, fetching context — those are tasks for the
 team you are about to create, not for the lead session before the team
 exists.
 
+If you are running Lisa in a non-Claude harness, this Claude enforcement hook
+should not be installed; follow the runtime-aware orchestration preamble in the
+skill instead.
+
 Re-read the orchestration preamble in /${ACTIVE_SKILL} and start with
 ToolSearch.
 EOF

package/plugins/src/base/rules/base-rules.md

@@ -8,7 +8,7 @@ After echoing the chosen flow and BEFORE doing any work, state the orchestration
 
 Default to an agent team for Research, Plan, Implement (Build/Fix/Improve/Investigate-Only), and any flow that invokes the Review sub-flow. Use a single agent only for Verify (standalone) and Monitor (standalone). See the `intent-routing` rule's Orchestration section for the full decision matrix.
 
-When the mode is `agent team` **and you are not already operating inside an agent team**, your FIRST tool calls after the classification echo MUST be `ToolSearch` with `query: "select:TeamCreate"` (to load the deferred tool's schema), then `TeamCreate`. Do not reach for `TaskCreate`, `Agent`, `Skill`, MCP tools, `Read`, `Bash`, or any other content-gathering call before the team exists — those are bypass paths that skip durable task state and parallel review. Reading the ticket, exploring the code, querying the API are all tasks for the team, not for the lead session before the team exists.
+When the mode is `agent team` **and you are not already operating inside an agent team**, your FIRST tool calls after the classification echo MUST establish team orchestration before any content-gathering work. Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally. Do not reach for `TaskCreate`, `Agent`, `Skill`, MCP tools, `Read`, `Bash`, or any other content-gathering call before the team exists or the no-team fallback has been declared — those are bypass paths that skip durable task state and parallel review. Reading the ticket, exploring the code, querying the API are all tasks for the team, not for the lead session before orchestration exists.
 
 Requirement Verification:
 
@@ -130,4 +130,4 @@ When you detect any of the above:
 1. Do NOT guess or make assumptions about what the external code does
 2. Identify which repository contains the missing code
 3. Add that repository to your current session before proceeding
-4. If you cannot determine which repository contains the code, ask — do not proceed without it
+4. If you cannot determine which repository contains the code, ask — do not proceed without it

package/plugins/src/base/rules/intent-routing.md

@@ -32,11 +32,11 @@ What this rule still enforces:
    > **Orchestration: agent team** (or **single agent**)
    > One-sentence justification.
 
-2. **Cascade rule (load-bearing)**: Before calling `TeamCreate`, check whether you are already operating inside an agent team. Signs you are inside a team: a prior `TeamCreate` exists in this session; you were spawned via `Agent` with `team_name`; your context references a team lead. If any of these are true, **do NOT call `TeamCreate`** — the harness rejects double-creates and the work stalls. Continue within the existing team. Invoke flows via the Skill tool; the team lead inherits responsibility for orchestration.
+2. **Cascade rule (load-bearing)**: Before creating a team, check whether you are already operating inside an agent team. Signs you are inside a team: a prior successful team-creation tool call exists in this session; you were spawned into a team context; your context references a team lead. If any of these are true, **do NOT create a second team** — many harnesses reject double-creates and the work stalls. Continue within the existing team. Invoke flows via the Skill tool; the team lead inherits responsibility for orchestration.
 
 3. **Default mode**: `Research`, `Plan`, `Implement`, `Intake`, and `Debrief` run as agent teams. The `Implement` flow — including every work type (`Build`, `Fix`, `Improve`, `Investigate-Only`) — is **always** a team flow. Bug fixes that "look simple" are not an exception: the Reproduce sub-flow, debug-specialist, bug-fixer, parallel reviewers, and verification-specialist all need to compose. `Debrief` runs as a team because tracker-mining and pr-mining parallelize cleanly and synthesis gates on both completing. `Verify` (standalone) and `Monitor` (standalone) use the One-shot Sub-agents pattern (see `## Orchestration` below) — these flows are linear with no parallelism and the team overhead is not warranted. Single-agent mode is otherwise reserved for: `product-walkthrough` invoked standalone (not as part of Research/Plan), `debrief-apply` (deterministic routing of human-marked dispositions), and one-off diagnostic Bash/Read sessions that don't invoke any lifecycle skill. When in doubt, use a team.
 
-The mechanical TeamCreate bootstrap directive lives inside each lifecycle skill — see those skills' orchestration preambles for the exact wording: first `ToolSearch{select:TeamCreate}` (load deferred schema), then `TeamCreate`.
+The mechanical team bootstrap directive lives inside each lifecycle skill — see those skills' orchestration preambles for the exact wording. The Claude path uses `TeamCreate`; other runtimes must use their equivalent team-discovery and team-creation tools, or explicitly declare the no-team fallback when no such tool exists.
 
 ## Readiness Gate Protocol
 
@@ -364,7 +364,7 @@ Lifecycle skills dispatch their agents according to the flow's shape. The follow
 
 ### Agent Teams (default for multi-step flows)
 
-Use an **agent team** (TeamCreate + TaskCreate per step) for:
+Use an **agent team** (runtime team creation + durable task state per step) for:
 
 - **Implement** (Build, Fix, Improve) — long sequences with parallel review and a real risk of compaction
 - **Plan** — multiple specialists feeding a shared decomposition
@@ -390,7 +390,7 @@ Use direct `Agent` tool invocations (no team) for:
 - **Investigate Only** spikes — single investigation, findings out
 - Any flow chained as a sub-flow inside a larger team — its agents become tasks in the parent team, not a new team
 
-Why: TeamCreate plus per-step TaskCreate is real overhead. For a one-or-two-agent flow with no parallelism, the bookkeeping cost outweighs the recovery and orchestration benefits.
+Why: team creation plus per-step task state is real overhead. For a one-or-two-agent flow with no parallelism, the bookkeeping cost outweighs the recovery and orchestration benefits.
 
 ### When in doubt
 

package/plugins/src/base/skills/debrief/SKILL.md

@@ -10,14 +10,13 @@ Walk the original Plan for `$ARGUMENTS`, mine the completed work items and their
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Resolving the work-item set, fetching tickets, walking PRs — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Resolving the work-item set, fetching tickets, walking PRs — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team.
 
 ## Input
 

package/plugins/src/base/skills/implement/SKILL.md

@@ -7,16 +7,15 @@ description: This skill should be used for any non-trivial request — features,
 
 ## Orchestration: agent team
 
-Implement is **always** a team flow. Bug, Build, Improve, and Investigate-Only all compose multiple specialists (Reproduce → debug → fix → review → verify). Single-agent mode is not an option here, regardless of how "simple" the ticket looks.
+Implement is a **team-first** flow. Bug, Build, Improve, and Investigate-Only all compose multiple specialists (Reproduce → debug → fix → review → verify). Single-agent mode is not permitted based on task complexity — the only exception is when no team creation tool is available in the current runtime (see no-team fallback in the paragraph below).
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team. Every team must include the Explore agent.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally. Every team must include the Explore agent.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill` (including `lisa:tracker-read`, `lisa:jira-read-ticket`, `lisa:github-read-issue`), MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Reading the ticket, exploring the code, fetching context — every one of those is a task for the team you are about to create, not for the lead session before the team exists. Doing them inline is the exact bypass path that produces a 1-agent ad-hoc fix instead of a real team flow.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill` (including `lisa:tracker-read`, `lisa:jira-read-ticket`, `lisa:github-read-issue`), MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Reading the ticket, exploring the code, fetching context — every one of those is a task for the team you are about to create, not for the lead session before orchestration exists. Doing them inline is the exact bypass path that produces a 1-agent ad-hoc fix instead of a real team flow.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool, or `lisa:intake` is running this skill per Ready ticket), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool, or `lisa:intake` is running this skill per Ready ticket), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Resolve the input (first task assigned to the team)
 

package/plugins/src/base/skills/intake/SKILL.md

@@ -27,16 +27,15 @@ The only legitimate reasons to stop early:
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Scanning the queue, claiming items, dispatching per-item flows — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Scanning the queue, claiming items, dispatching per-item flows — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
-The cycle's outer team is created by Intake. Each item it processes (a PRD via `lisa:plan`, a ticket via `lisa:implement`) executes within the same team — those skills' orchestration preambles detect the existing team and skip TeamCreate. One team per cron cycle, processes everything currently Ready.
+The cycle's outer team is created by Intake. Each item it processes (a PRD via `lisa:plan`, a ticket via `lisa:implement`) executes within the same team — those skills' orchestration preambles detect the existing team and skip creating a second team. One team per cron cycle, processes everything currently Ready.
 
 ## Source dispatch
 

package/plugins/src/base/skills/monitor/SKILL.md

@@ -10,14 +10,13 @@ Spot-check application health in the named environment (`dev` / `staging` / `pro
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion / Sentry), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Hitting health endpoints, pulling logs, querying Sentry — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion / Sentry), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Hitting health endpoints, pulling logs, querying Sentry — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Flow
 

package/plugins/src/base/skills/plan/SKILL.md

@@ -10,14 +10,13 @@ Decompose the PRD/spec at `$ARGUMENTS` into ordered work items with acceptance c
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Reading the PRD, exploring the code, fetching context — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Reading the PRD, exploring the code, fetching context — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Source dispatch
 

package/plugins/src/base/skills/research/SKILL.md

@@ -10,14 +10,13 @@ Produce a PRD for the problem in `$ARGUMENTS`.
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Gathering context inline as the lead is the exact bypass path that produces ad-hoc work instead of a real team flow.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Gathering context inline as the lead is the exact bypass path that produces ad-hoc work instead of a real team flow.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Flow
 

package/plugins/src/base/skills/verify/SKILL.md

@@ -10,14 +10,13 @@ Ship the current branch and prove it works in the target environment.
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Inspecting the branch, running quality gates, opening the PR — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Inspecting the branch, running quality gates, opening the PR — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Flow
 

package/plugins/src/expo/skills/ops-browser-uat/SKILL.md

@@ -14,7 +14,7 @@ Perform browser-based user acceptance testing using Playwright MCP tools.
 
 ## Prerequisites
 
-1. **Load Playwright MCP tools** — use `ToolSearch` to search for `playwright browser` and load all browser tools.
+1. **Load Playwright MCP tools** — use the current runtime's tool-discovery mechanism to search for `playwright browser` and load all browser tools.
 2. **Verify target environment is up** — curl check the frontend URL before launching the browser.
 3. **For localhost** — ensure the frontend is running on port 8081.
 

package/plugins/src/expo/skills/ops-check-logs/SKILL.md

@@ -40,7 +40,7 @@ For inspecting JavaScript errors, warnings, and `console.log` output in the brow
 
 Use when you need to capture browser logs programmatically during UAT or debugging.
 
-1. **Load Playwright tools** — use `ToolSearch` to search for `playwright browser`.
+1. **Load Playwright tools** — use the current runtime's tool-discovery mechanism to search for `playwright browser`.
 
 2. **Navigate to the app**:
    - `browser_navigate` to the target URL (discover from `e2e/constants.ts` or `.env.*` files)

package/plugins/src/nestjs/skills/nestjs-graphql/references/project-patterns.md

@@ -443,6 +443,54 @@ export class UsersModule {}
 export class AppModule {}
 ```
 
+## Resolver Boundary Patterns
+
+Resolvers translate GraphQL requests into service calls. Keep business rules in
+services so the same behavior is available to jobs, REST handlers, and future
+GraphQL fields without copying resolver logic.
+
+### Thin Resolver
+
+```typescript
+@Resolver(() => User)
+export class UsersResolver {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Query(() => User)
+  async user(@Args("id", { type: () => ID }) id: string): Promise<User> {
+    return this.usersService.findById(id);
+  }
+}
+```
+
+### Field Resolver
+
+Use field resolvers for data that depends on the parent object or benefits from
+DataLoader batching. Do not fetch relation-heavy data inside the parent query
+when only some clients ask for it.
+
+```typescript
+@ResolveField(() => [Post])
+async posts(@Parent() user: User): Promise<readonly Post[]> {
+  return this.postsByUserLoader.load(user.id);
+}
+```
+
+### Mutation Resolver
+
+Validate transport-level shape in DTOs and leave state transitions to the
+service. This keeps GraphQL decorators from becoming the source of business
+truth.
+
+```typescript
+@Mutation(() => User)
+async updateUser(
+  @Args("input") input: UpdateUserInput
+): Promise<User> {
+  return this.usersService.update(input);
+}
+```
+
 ## Error Handling Patterns
 
 ### Standard Error Response