@codyswann/lisa 2.119.0 → 2.121.0

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

@@ -0,0 +1,145 @@
+---
+name: implement
+description: This skill should be used for any non-trivial request — features, bugs, stories, epics, spikes, or multi-step tasks. It accepts a ticket URL (Jira, Linear, GitHub), a file path containing a spec, or a plain-text prompt. It assembles an agent team, breaks the work into structured tasks, and manages the full lifecycle from research through implementation, code review, deploy, and empirical verification.
+---
+
+# Implement: $ARGUMENTS
+
+## Orchestration: agent team
+
+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 or subagent delegation 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 successful team-creation or subagent-delegation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
+
+Use the team tool for the current runtime:
+
+- Claude: use `TeamCreate`. If `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema.
+- Codex: do not call `TeamCreate`; Codex does not expose that Claude tool. Use `tool_search` with a query like `multi-agent tools` to load `multi_agent_v1`, then use `multi_agent_v1.spawn_agent` for teammate delegation. Treat the first successful `spawn_agent` call as establishing team orchestration.
+- Other runtimes: use the current runtime's tool-discovery mechanism to discover and call the appropriate multi-agent/team tool.
+
+If no team creation or subagent delegation 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 the team is established, the first Codex teammate has been spawned, 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 create a second team — many harnesses reject double-creates — and do NOT collapse the nested flow into a single inline worker. A nested team-first flow must still bring in the specialists it requires by adding them to the existing team, not by doing the work itself:
+
+- **Claude:** teams are flat and only the lead can add named teammates, so do NOT call `Agent` with a `name` from a teammate (the harness rejects it: *"Teammates cannot spawn other teammates — the team roster is flat"*). Send the team lead a message naming the specialist teammate(s) this flow needs, their task assignments, and completion criteria, then coordinate through the shared task list until they finish. An anonymous subagent (`Agent` with `name` omitted) is permitted only for bounded one-shot work whose result returns directly to you — it is not a substitute for the required lifecycle specialists.
+- **Codex:** do NOT call `TeamCreate`. If the lead/root agent is addressable (you were given its id/handle), send it a request to `multi_agent_v1.spawn_agent` the specialist agent(s), including each agent's prompt, ownership, and expected result. If no lead handle exists but `spawn_agent` is available to you, spawn only the bounded specialist agent(s) this flow needs, `wait_agent` for their results, and relay those results upward to the parent/lead.
+
+Treat the first successful lead-spawn request (or, on the Codex fallback, the first specialist spawn) as preserving team orchestration. Never satisfy a team-first lifecycle flow by doing all the work inline.
+
+## Resolve the input (first task assigned to the team)
+
+$ARGUMENTS is either a url to a ticket containing the request, a pointer to a file containing the request, or the request in text format.
+
+The team lead does NOT read the input directly. The first task on the team's plan is "resolve the input" — assigned to a teammate, which then:
+
+- If it's a ticket, calls `lisa:tracker-read` (preferred — vendor-agnostic; dispatches per `.lisa.config.json` `tracker`). **Mismatch guard**: if the ticket format doesn't match the configured tracker (e.g., a GitHub URL when `tracker` is `jira`), `tracker-read` stops and reports the error — never auto-translates vendors:
+  - JIRA ticket → `lisa:tracker-read` → `lisa:jira-read-ticket`
+  - GitHub Issue → `lisa:tracker-read` → `lisa:github-read-issue`
+  - Linear identifier or project URL → `lisa:tracker-read` → `lisa:linear-read-issue`
+  - Captures comments and metadata, not just the description.
+- If it's a file, reads the entire file without offset or limit.
+- If it's a plain-text request, uses the provided text verbatim as the resolved input.
+- Returns the resolved input to the team lead, who then proceeds to roster selection.
+
+## Select the agent roster
+
+Review all available agent types listed in the Task tool's `subagent_type` options. This includes built-in agents (like `Explore`, `general-purpose`), custom agents (from `.claude/agents/`), and plugin agents (from `.claude/settings.json` `enabledPlugins`). For each agent, explain in one sentence why it IS or IS NOT relevant to this task. Then select all agents that are relevant. You MUST justify excluding an agent — inclusion is the default.
+
+When deciding the agents to use, consider:
+* Before any task is implemented, the agent team must explore the codebase for relevant research (documentation, code, git history, etc) and update each task's `metadata.relevant_documentation` with the findings.
+* Each task must be reviewed by the team to make sure their verification passes.
+* Each task must have their learnings reviewed by the learner subagent.
+
+Using the general-purpose agent in Team Lead session, Determine the name of this plan
+
+Using the general-purpose agent in Team Lead session, **determine the base branch from the ticket's target environment, then sync the working branch onto the latest of it before any work** — so implementation always builds on current target-environment code:
+
+1. **Resolve the target environment** from the resolved work item — its `## Target Backend Environment` section (the field the `*-write-*` / `*-add-journey` skills record).
+2. **Map the environment to a base branch** via `.lisa.config.json` `deploy.branches` (e.g. `staging → staging`, `production → main`) — the forward direction of the same map the env-keyed `done` resolution uses in reverse (see the `config-resolution` rule). If the work item names **no** environment, the base branch is the **remote default branch** (`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`, or `git remote set-head origin -a` then read `origin/HEAD`). If the named environment is absent from `deploy.branches`, or its branch does not exist on the remote, **stop and report** — never guess a base.
+3. **Establish the feature branch off the latest base, conflict-free:**
+   - `git fetch origin`.
+   - Already on a feature branch with an **open PR** → reuse it. If the PR's base ≠ the resolved base branch, surface the mismatch and re-target only with confirmation — the ticket's environment is the source of truth.
+   - Already on a feature branch with **no open PR** → reuse it; its PR base will be the resolved base branch (do not ask the human — the environment determines it).
+   - On an **environment / default branch** → check out a feature branch named for this plan (with the work-item ref prefix, per the linkage rules below) **from `origin/<base>`**.
+   - **Rebase the feature branch onto `origin/<base>` and resolve any merge conflicts BEFORE starting work.** If the conflicts cannot be resolved cleanly and safely, create a fix task for the agent team (with the conflicting file list and current merge state) and resolve it before implementation begins — never start work on stale or conflicted code.
+4. **The PR targets the resolved base branch** — carry it as `target_branch=<base>` into `lisa:git-submit-pr` (Verify flow). `git-submit-pr` already chooses a closing keyword when the base is the production/default branch and a non-closing reference for a non-terminal environment branch.
+
+When the request came from a tracker work item, preserve its native identifier for development linkage:
+
+- Capture `tracker_provider` and `work_item_ref` from the resolved input before creating or reusing a branch. Examples: `github` + `CodySwannGT/lisa#614`, `linear` + `ENG-123`, `jira` + `ENG-123`.
+- If a new branch is needed and the provider can link branches by identifier, include the identifier in the branch name before the human-readable slug. Linear and JIRA integrations commonly link from branch names; GitHub issue linkage is PR-body driven, but including the issue number in the branch name is still useful. Keep branch names URL-safe, for example `codex/ENG-123-add-checkout-copy` or `codex/614-add-checkout-copy`.
+- Pass the work-item ref and target branch to `lisa:git-submit-pr` when opening or updating the PR, for example `work_item_ref=CodySwannGT/lisa#614 target_branch=<base resolved from the ticket's environment above>` (not hardcoded `main`). The PR workflow owns provider-specific body text and must decide whether to use a closing keyword or a non-closing reference.
+- If the provider has no native branch or PR development-linkage surface, continue without linkage and mention that the provider was skipped.
+
+Using the general-purpose agent in Team Lead session, Determine which flow applies:
+1. Research -- needs a PRD (no specification exists)
+2. Plan -- needs decomposition (specification exists but no work items)
+3. Implement -- has a well-defined work item
+4. Verify -- has code ready to ship
+
+If Implement, determine the work type:
+1. Build (feature, story, task)
+2. Fix (bug -- mandatory Reproduce sub-flow before investigation)
+3. Improve (refactoring, optimization, coverage improvement)
+4. Investigate Only (spike -- no code changes, just findings)
+
+Run the readiness gate check for the selected flow as defined in the `intent-routing` rule (loaded via the lisa plugin). If the gate fails, stop and report what is missing.
+
+IF it is a Fix (bug), execute the Reproduce sub-flow FIRST:
+1. Write a failing test that demonstrates the bug (preferred)
+2. If a failing test is not possible, write a minimal reproduction script
+3. Verify the reproduction is reliable (consistent failure)
+4. The reproduction MUST succeed before any investigation or fix attempt begins
+5. Examples of reproduction methods:
+   1. Write a simple API client and call the offending API
+   2. Start the server on localhost and use the Playwright CLI or Chrome DevTools
+
+Using the general-purpose agent in Team Lead session, determine how you will know that the task is fully complete
+1. Examples
+   1. Direct deploy the changes to dev and then Write a simple API client and call the offending API
+   2. Start the server on localhost and then Use the Playwright CLI or Chrome DevTools
+
+Using the general-purpose agent in Team Lead session, create tasks needed to complete the request.
+
+Every task MUST include this JSON metadata block. Do NOT omit `skills` (use `[]` if none), `learnings` (use `[]` if none) or `verification`.
+
+```json
+{
+  "plan": "<plan-name>",
+  "type": "spike|bug|task|epic|story",
+  "acceptance_criteria": ["..."],
+  "relevant_documentation": "",
+  "testing_requirements": ["..."],
+  "skills": ["..."],
+  "learnings": ["..."],
+  "verification": {
+    "type": "ui-recording|api-test|cli-test|database-check|manual-check|documentation",
+    "command": "the proof command — must run the actual system (NOT test/typecheck/lint, those are quality gates)",
+    "expected": "what success looks like — observable system behavior"
+  }
+}
+```
+
+Before any task is implemented, the agent team must explore the codebase for relevant research (documentation, code, git history, etc) and update each task's `metadata.relevant_documentation` with the findings.
+
+Each task must be reviewed by the team to make sure their verification passes.
+Each task must have their learnings reviewed by the learner subagent.
+
+Before shutting down the team, execute the Verify flow:
+
+1. Run quality gates: lint, typecheck, tests — all must pass. These are prerequisites, NOT verification.
+2. `verification-specialist`: verify locally by running the actual system and observing results (empirical proof that the change works). This is the real verification step.
+3. Write e2e test encoding the verification
+4. Record Implement usage on the originating work artifact via `lisa:usage-accounting` so the work item (or other implementation-owned artifact) gains a direct `implement` usage entry in the canonical `## Lisa Usage` section. If the parent / child graph is already known, prefer `record_and_rollup` so ancestor totals refresh in the same write; otherwise still write the direct entry, and if runtime usage is unavailable, use `source: unavailable` with nullable token/cost fields instead of skipping the row.
+5. Commit ALL outstanding changes in logical batches on the branch (minus sensitive data/information) — not just changes made by the agent team. This includes pre-existing uncommitted changes that were on the branch before the plan started. Do NOT filter commits to only "task-related" files. If it shows up in git status, it gets committed (unless it contains secrets).
+6. Push the changes - if any pre-push hook blocks you, create a task for the agent team to fix the error/problem whether it was pre-existing or not
+7. Open a pull request with auto-merge on via `lisa:git-submit-pr`, targeting the **base branch resolved from the ticket's environment** (`target_branch=<base>`, per the branch step above), and including the work-item ref when one exists so the PR can be linked natively to the source issue.
+8. PR Watch Loop: Monitor the PR using `git-submit-pr`'s drive-to-merge behavior. Create a task for the agent team to resolve any code review comments by either implementing the suggestions or commenting why they should not be implemented and close the comment. Fix any failing checks and repush. If the PR is `BEHIND`, blocked by stale review state, or cannot enable auto-merge, follow the harness-agnostic `git-submit-pr` re-sync, review-gate, and direct-merge fallback loop until the PR is actually merged or a blocking failure is surfaced.
+9. Merge the PR
+10. Monitor the deploy action that triggers automatically from the successful merge
+11. If deploy fails, create a task for the agent team to fix the failure, open a new PR and then go back to step 7
+12. Remote verification: `verification-specialist` verifies in target environment (same checks as local verification, but on remote)
+13. `ops-specialist`: post-deploy health check, monitor for errors in first minutes
+14. If remote verification fails, create a task for the agent team to find out why it failed, fix it and return to step 5 (repeat until you get all the way through)

package/plugins/lisa-agy/skills/improve-code-complexity/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: improve-code-complexity
+description: This skill should be used when reducing the cognitive complexity threshold of the codebase. It lowers the threshold by 2, identifies functions that exceed the new limit, generates a brief with refactoring strategies, and creates a plan with tasks to fix all violations.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+---
+
+# Lower Code Complexity
+
+Reduces the cognitive complexity threshold by 2 and fixes all violations.
+
+## Step 1: Gather Requirements
+
+1. **Read current threshold** from eslint config (cognitive-complexity rule)
+2. **Calculate new threshold**: current - 2 (e.g., 15 -> 13)
+3. **Run lint** with the new threshold to find violations:
+   ```bash
+   bun run lint 2>&1 | grep "cognitive-complexity"
+   ```
+4. **Note for each violation**:
+   - File path and line number
+   - Function name
+   - Current complexity score
+
+If no violations at new threshold, report success and exit.
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Reduce cognitive complexity threshold from [current] to [new].
+
+Functions exceeding threshold (ordered by complexity):
+1. [file:function] (complexity: X, target: [new]) - Line Y
+2. ...
+
+Configuration change: [eslint config path], cognitive-complexity from [current] to [new]
+
+Refactoring strategies: extract functions, early returns, extract conditions, use lookup tables
+
+Verification: `bun run lint 2>&1 | grep "cognitive-complexity" | wc -l` → Expected: 0
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa-agy/skills/improve-max-lines/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: improve-max-lines
+description: This skill should be used when reducing the maximum file lines threshold and fixing all violations. It updates the eslint threshold configuration, identifies files exceeding the new limit, generates a brief with refactoring strategies, and creates a plan with tasks to split oversized files.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+
+---
+
+# Reduce Max Lines
+
+Target threshold: $ARGUMENTS lines per file
+
+If no argument provided, prompt the user for a target.
+
+## Step 1: Gather Requirements
+
+1. **Read current config** from eslint thresholds (eslint.thresholds.json or similar)
+2. **Run lint** with the new threshold to find violations:
+   ```bash
+   bun run lint 2>&1 | grep "max-lines"
+   ```
+3. **Note for each violation**:
+   - File path
+   - Current line count
+
+If no violations at $ARGUMENTS, report success and exit.
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Reduce max file lines threshold to $ARGUMENTS.
+
+Files exceeding threshold (ordered by line count):
+1. [file] - [current] lines (target: $ARGUMENTS)
+2. ...
+
+Configuration change: eslint.thresholds.json, maxLines to $ARGUMENTS
+
+Refactoring strategies: extract modules, remove duplication, delete dead code, simplify logic
+
+Verification: `bun run lint 2>&1 | grep "max-lines" | wc -l` → Expected: 0
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa-agy/skills/improve-max-lines-per-function/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: improve-max-lines-per-function
+description: This skill should be used when reducing the maximum lines per function threshold and fixing all violations. It updates the eslint threshold configuration, identifies functions exceeding the new limit, generates a brief with refactoring strategies, and creates a plan with tasks to split oversized functions.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+
+---
+
+# Reduce Max Lines Per Function
+
+Target threshold: $ARGUMENTS lines per function
+
+If no argument provided, prompt the user for a target.
+
+## Step 1: Gather Requirements
+
+1. **Read current config** from eslint thresholds (eslint.thresholds.json or similar)
+2. **Run lint** with the new threshold to find violations:
+   ```bash
+   bun run lint 2>&1 | grep "max-lines-per-function"
+   ```
+3. **Note for each violation**:
+   - File path and line number
+   - Function name
+   - Current line count
+
+If no violations at $ARGUMENTS, report success and exit.
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Reduce max lines per function threshold to $ARGUMENTS.
+
+Functions exceeding threshold (ordered by line count):
+1. [file:function] (lines: X, target: $ARGUMENTS) - Line Y
+2. ...
+
+Configuration change: eslint.thresholds.json, maxLinesPerFunction to $ARGUMENTS
+
+Refactoring strategies: extract functions, early returns, extract conditions, use lookup tables, consolidate logic
+
+Verification: `bun run lint 2>&1 | grep "max-lines-per-function" | wc -l` → Expected: 0
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa-agy/skills/improve-test-coverage/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: improve-test-coverage
+description: This skill should be used when increasing test coverage to a specified threshold percentage. It runs the coverage report, identifies files with the lowest coverage, generates a brief with coverage gaps, and creates a plan with tasks to add the missing tests.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+
+---
+
+# Increase Test Coverage
+
+Target threshold: $ARGUMENTS%
+
+If no argument provided, prompt the user for a target.
+
+## Step 1: Gather Requirements
+
+1. **Find coverage config** (jest.config.js, vitest.config.ts, .nycrc, etc.)
+2. **Run coverage report** to get current state:
+   ```bash
+   bun run test:cov 2>&1 | head -100
+   ```
+3. **Identify the 20 files with lowest coverage**, noting:
+   - File path
+   - Current coverage % (lines, branches, functions)
+   - Which lines/branches are uncovered
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```
+Increase test coverage from [current]% to $ARGUMENTS%.
+
+Files needing coverage (ordered by coverage gap):
+1. [file] - [current]% coverage (target: $ARGUMENTS%)
+   - Uncovered: [lines]
+   - Missing branch coverage: [lines]
+2. ...
+
+Configuration: [config file path], update thresholds to $ARGUMENTS%
+
+Verification: `bun run test:cov` → Expected: All thresholds pass at $ARGUMENTS%
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/lisa-agy/skills/improve-tests/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: improve-tests
+description: This skill should be used when improving test quality. It scans the test suite for weak, brittle, or poorly-written tests, generates a brief with improvement opportunities, and creates a plan with tasks to strengthen the tests.
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+---
+
+# Improve Test Quality
+
+Target: $ARGUMENTS
+
+If no argument provided, scan the full test suite.
+
+## Step 1: Gather Requirements
+
+1. **Run test suite** to establish baseline:
+   ```bash
+   bun run test 2>&1 | tail -20
+   ```
+2. **Scan test files** for quality issues:
+   - Weak assertions (`toBeTruthy`, `toBeDefined` instead of specific values)
+   - Missing edge cases (no boundary values, no error paths)
+   - Implementation coupling (testing internals rather than behavior)
+   - Missing error path coverage
+   - Duplicated setup that could indicate missing abstractions
+3. **Identify 10-20 test files** with highest improvement potential, noting:
+   - File path
+   - Issues found (weak assertions, missing edge cases, etc.)
+   - Estimated impact of improvement
+
+## Step 2: Compile Brief and Delegate
+
+Compile the gathered information into a structured brief:
+
+```text
+Improve test quality across the test suite.
+
+Test files needing improvement (ordered by impact):
+1. [test file] - [issues found]
+   - Weak assertions: [count]
+   - Missing edge cases: [description]
+   - Implementation coupling: [description]
+2. ...
+
+Verification: `bun run test` -> Expected: All tests pass, improved assertions and coverage
+```
+
+Invoke `/implement` with this brief to create the implementation plan.

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

@@ -0,0 +1,132 @@
+---
+name: intake
+description: "Vendor-agnostic scanner for Ready queues. Given a Notion PRD database URL → finds the first Ready PRD and runs lisa:plan. Given a Confluence space or parent page URL → finds the first prd-ready PRD and runs lisa:plan. Given a Linear workspace URL or team key → finds the first prd-ready Linear project and runs lisa:plan. Given a GitHub repo URL or `org/repo` token → finds the first prd-ready GitHub issue and runs lisa:plan. Given a JIRA project key or JQL filter → finds the first Ready ticket and runs lisa:implement. Given a GitHub repo URL or `org/repo` token when `tracker = github` → finds the first `status:ready` issue and runs lisa:implement. On the PRD side it also closes the loop: each cycle rolls a ticketed PRD up to shipped and dispatches lisa:verify-prd for one shipped PRD (shipped → verified on pass; on fail, re-opened shipped → ticketed with build-ready fix tickets that auto-build and re-verify — never blocked). Designed as the cron target for /schedule — one eligible item per invocation, exits cleanly on empty. Symmetric counterpart to the single-item lisa:plan and lisa:implement skills."
+allowed-tools: ["Skill", "Bash", "mcp__claude_ai_Notion__notion-fetch", "mcp__claude_ai_Notion__notion-search", "mcp__atlassian__getConfluencePage", "mcp__atlassian__getConfluenceSpaces", "mcp__atlassian__searchConfluenceUsingCql", "mcp__atlassian__getAccessibleAtlassianResources", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getJiraIssue", "mcp__linear-server__list_projects", "mcp__linear-server__list_teams", "mcp__linear-server__list_project_labels"]
+---
+
+# Intake: $ARGUMENTS
+
+Run one intake cycle against the queue identified by `$ARGUMENTS`. Scans for `Status = Ready`, claims the first eligible item, dispatches it to the appropriate single-item lifecycle skill, then exits. Remaining Ready items are left for later scheduler invocations.
+
+For build-queue runs, Intake also accepts an optional `assignee=<vendor-user-id-or-login>` filter.
+Resolution order is:
+
+1. `$ARGUMENTS` `assignee=<...>`
+2. `.lisa.config.local.json` `intake.assignee`
+3. empty default
+
+When the resolved assignee is empty, Intake keeps the shared queue behavior and scans any ready
+item. When non-empty, it forwards the filter to the vendor build-intake skill so that only ready
+items already assigned to that assignee are considered. Intake never assigns or reassigns tickets
+as part of this filter.
+
+## Confirmation policy
+
+Do NOT ask the caller whether to proceed. Once invoked with a queue, run the cycle to completion. The caller (a human at the CLI or a scheduled cron) has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background batch.
+
+Specifically forbidden:
+
+- Previewing projected scope (number of items, projected ticket counts, write counts) and asking whether to continue.
+- Offering A/B/C-style choices like "proceed / skip / dry-run only" — the documented behavior IS the default. Dry-run is a different skill, not an option here.
+- Pausing because the queue is large, items have many open questions, or items are likely to end in `Blocked`. `Blocked` is a valid terminal state of the downstream lifecycles, not a failure mode — routing items to `Blocked` with clarifying comments is success.
+- Pausing because validation looks expensive. The cost of one cycle is bounded; the cost of stalling a scheduled cron waiting on a human is unbounded.
+
+The only legitimate reasons to stop early:
+
+- Missing required input (no queue argument, missing project configuration). Surface the missing value and exit.
+- The queue itself is misconfigured (Status property missing expected values, JIRA workflow can't reach required transitions). Surface and exit.
+- Empty `Ready` set. Exit cleanly with the idle-case message.
+
+## Orchestration: agent team
+
+If you are NOT already operating inside an agent team (no prior successful team-creation or subagent-delegation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
+
+Use the team tool for the current runtime:
+
+- Claude: use `TeamCreate`. If `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema.
+- Codex: do not call `TeamCreate`; Codex does not expose that Claude tool. Use `tool_search` with a query like `multi-agent tools` to load `multi_agent_v1`, then use `multi_agent_v1.spawn_agent` for teammate delegation. Treat the first successful `spawn_agent` call as establishing team orchestration.
+- Other runtimes: use the current runtime's tool-discovery mechanism to discover and call the appropriate multi-agent/team tool.
+
+If no team creation or subagent delegation 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 the team is established, the first Codex teammate has been spawned, 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 create a second team — many harnesses reject double-creates — and do NOT collapse the nested flow into a single inline worker. A nested team-first flow must still bring in the specialists it requires by adding them to the existing team, not by doing the work itself:
+
+- **Claude:** teams are flat and only the lead can add named teammates, so do NOT call `Agent` with a `name` from a teammate (the harness rejects it: *"Teammates cannot spawn other teammates — the team roster is flat"*). Send the team lead a message naming the specialist teammate(s) this flow needs, their task assignments, and completion criteria, then coordinate through the shared task list until they finish. An anonymous subagent (`Agent` with `name` omitted) is permitted only for bounded one-shot work whose result returns directly to you — it is not a substitute for the required lifecycle specialists.
+- **Codex:** do NOT call `TeamCreate`. If the lead/root agent is addressable (you were given its id/handle), send it a request to `multi_agent_v1.spawn_agent` the specialist agent(s), including each agent's prompt, ownership, and expected result. If no lead handle exists but `spawn_agent` is available to you, spawn only the bounded specialist agent(s) this flow needs, `wait_agent` for their results, and relay those results upward to the parent/lead.
+
+Treat the first successful lead-spawn request (or, on the Codex fallback, the first specialist spawn) as preserving team orchestration. Never satisfy a team-first lifecycle flow by doing all the work inline.
+
+The cycle's outer team is created by Intake. The one item it processes (a PRD via `lisa:plan`, a ticket via `lisa:implement`) executes within that team — those skills' orchestration preambles detect the existing team and skip creating a second team. One team per cron cycle, one eligible Ready item per cycle.
+
+## Source dispatch
+
+Detect the queue type from `$ARGUMENTS` and route:
+
+| If `$ARGUMENTS` is... | Queue type | Per-item dispatch |
+|------------------------|------------|---------------------|
+| A Notion **database** URL or database ID | PRD queue (Notion) | Invoke `lisa:notion-prd-intake` (which scans the DB for Status=Ready, claims the first eligible PRD, runs `lisa:plan` via the dry-run validate → branch → write pipeline, then exits) |
+| A Confluence **space** URL or space key (e.g. `https://acme.atlassian.net/wiki/spaces/PRD` or `PRD`) | PRD queue (Confluence) | Invoke `lisa:confluence-prd-intake` (which CQL-queries the space for `label = "prd-ready"`, claims the first eligible PRD by relabeling to `prd-in-review`, runs the dry-run validate → branch → write pipeline, then exits) |
+| A Confluence **parent page** URL or page ID (the page whose descendants are PRDs) | PRD queue (Confluence, narrowed) | Invoke `lisa:confluence-prd-intake` with the parent ID (CQL: `ancestor = <id> AND label = "prd-ready"`) |
+| A Linear **workspace** URL (e.g. `https://linear.app/acme`) | PRD queue (Linear) | Invoke `lisa:linear-prd-intake` (which queries `list_projects({label: "prd-ready"})` across the workspace, claims the first eligible project by relabeling to `prd-in-review`, runs the dry-run validate → branch → write pipeline, then exits) |
+| A Linear **team** URL (e.g. `https://linear.app/acme/team/ENG/projects`) or a token already routed as a Linear team key | PRD queue (Linear, narrowed) | Invoke `lisa:linear-prd-intake` with the team key (`list_projects({team, label: "prd-ready"})`) |
+| The literal token `linear` | PRD queue (Linear, default workspace) | Invoke `lisa:linear-prd-intake linear` — only valid if `linear.workspace` is configured in `.lisa.config.json` |
+| A JIRA project key (e.g. `SE`) | Work queue (JIRA) | Invoke `lisa:jira-build-intake` (which scans the project for Status=Ready, claims the first eligible ticket via In Progress, runs `lisa:implement`, transitions to On Dev on success, then exits) |
+| A full JQL filter (e.g. `project = SE AND component = "frontend"`) | Work queue (JIRA, narrowed) | Invoke `lisa:jira-build-intake` with the JQL |
+| A GitHub **repository** URL or `org/repo` token (e.g. `https://github.com/acme/product-prds` or `acme/product-prds`) when used for **PRDs** | PRD queue (GitHub) | Invoke `lisa:github-prd-intake` (which queries `gh issue list --label prd-ready`, claims the first eligible PRD by relabeling to `prd-in-review`, runs the dry-run validate → branch → write pipeline, then exits). PRD discovery is independent of the destination tracker — the resulting tickets land wherever `.lisa.config.json` `tracker` says. |
+| A GitHub **repository** URL or `org/repo` token when `tracker = github` is configured (build-queue mode) | Work queue (GitHub) | Invoke `lisa:tracker-build-intake` which dispatches to `lisa:github-build-intake` (which queries `gh issue list --label status:ready`, optionally narrows by the resolved assignee filter, claims the first eligible issue via `status:in-progress`, runs `lisa:implement`, relabels to `status:on-dev` on success, then exits). |
+| The literal token `github` | Defaults to `.lisa.config.json` `github.org` / `github.repo`. Routes by **the `intake_mode` flag** in `$ARGUMENTS` (`prd` or `build`); if the flag is absent, prefer the PRD queue when both label namespaces are present, otherwise pick whichever exists. | Invoke the matching skill (`lisa:github-prd-intake` or `lisa:tracker-build-intake`). |
+
+Disambiguation rules:
+
+- A `notion.so` / `notion.site` URL → Notion queue.
+- An Atlassian Confluence URL containing `/wiki/spaces/<KEY>` with no `/pages/...` segment → Confluence space queue.
+- An Atlassian Confluence URL containing `/wiki/spaces/<KEY>/pages/<ID>/...` → Confluence parent-page queue (the page is the parent whose descendants are PRDs). If the user actually meant "this single page is a PRD, plan it", route to `lisa:plan` instead — this skill is batch-only.
+- A `linear.app` URL → Linear queue. If the path is `/<workspace>` only or `/<workspace>/team/<KEY>/...`, route here. If the path includes `/project/<slug>-<id>` it's a single-PRD URL — direct the caller to `lisa:plan` instead, this skill is batch-only.
+- The literal token `linear` (case-insensitive) → Linear queue, default workspace from `linear.workspace` in `.lisa.config.json`.
+- A `github.com` URL or an `<org>/<repo>` token → GitHub queue. The PRD-vs-build dispatch is determined by which label namespace the repo currently uses: PRD-side (`prd-ready`) → `lisa:github-prd-intake`; build-side (`status:ready` and `tracker = github` in `.lisa.config.json`) → `lisa:tracker-build-intake`. If both namespaces are present, prefer the PRD queue unless `$ARGUMENTS` includes `intake_mode=build`. If the URL points at a single issue (`https://github.com/<org>/<repo>/issues/<n>`), this skill is batch-only — direct the caller to `lisa:plan` (for a single PRD issue) or `lisa:implement` (for a single build issue).
+- The literal token `github` (case-insensitive) → GitHub queue, default repo from `.lisa.config.json` `github.org` / `github.repo`.
+- A bare alphanumeric token that matches the JIRA project key regex (uppercase letters / digits / hyphen, ≤10 chars — typically the value of `jira.project` in `.lisa.config.json`) is treated as a JIRA project key by default. A token that does not match the regex is treated as a Confluence space key. If it does not resolve as a Confluence space key either, attempt to resolve as a Linear team key via `mcp__linear-server__list_teams({query})` before giving up. The only time to stop and ask is when the token resolves to more than one of {JIRA project, Confluence space, Linear team, GitHub `org/repo`} simultaneously — in that overlap the user must disambiguate which queue to scan.
+- An `<org>/<repo>` token (slash-separated, both halves are GitHub-name-shaped) → GitHub queue.
+- A string starting with `project = ` or containing JQL operators (`AND`, `OR`, `=`, `!=`, `~`, etc.) → JQL filter.
+
+The single-item skills (`lisa:plan`, `lisa:implement`) and the per-vendor batch skills (`lisa:notion-prd-intake`, `lisa:confluence-prd-intake`, `lisa:linear-prd-intake`, `lisa:github-prd-intake`, `lisa:jira-build-intake`, `lisa:github-build-intake`) are internal — Intake is the public entry point. Developers schedule `/lisa:intake <queue>`; the rest is composition.
+
+## Cycle behavior
+
+1. **Resolve the queue** — fetch the database/project metadata, confirm the Status property/workflow has the expected `Ready` value.
+2. **Pre-flight check** — for JIRA, confirm `In Progress` and `On Dev` are reachable transitions before doing any per-ticket work. Stop with a clear error if the workflow is misconfigured.
+3. **Find Ready items** — query the queue. Empty → exit cleanly with `"No items with Status=Ready. Nothing to do."` This is the common idle case for a scheduled run.
+4. **Process the first eligible Ready item only** (claim-first ordering for idempotency):
+   - Notion PRDs → `lisa:notion-prd-intake` handles per-item: claim (Status=In Review), dry-run validate, branch to Blocked or Ticketed, coverage audit
+   - Confluence PRDs → `lisa:confluence-prd-intake` handles per-item: claim (relabel to `prd-in-review`), dry-run validate, branch to `prd-blocked` or `prd-ticketed`, coverage audit
+   - Linear PRDs → `lisa:linear-prd-intake` handles per-item: claim (relabel project to `prd-in-review`), dry-run validate, branch to `prd-blocked` or `prd-ticketed` (with a sentinel feedback issue under each project hosting clarifying-question comments), coverage audit
+   - GitHub PRDs → `lisa:github-prd-intake` handles per-item: claim (relabel issue to `prd-in-review`), dry-run validate, branch to `prd-blocked` or `prd-ticketed` (with clarifying-question comments posted directly on the PRD issue), coverage audit
+   - JIRA tickets → `lisa:jira-build-intake` handles per-item: claim, dispatch to `lisa:jira-agent`, transition to On Dev on success
+   - GitHub build issues (when `tracker = github`) → `lisa:tracker-build-intake` → `lisa:github-build-intake` handles per-item: optional ready-queue assignee filtering, claim (relabel to `status:in-progress`), dispatch to `lisa:github-agent`, relabel to `status:on-dev` on success
+   - **Closing the PRD loop:** beyond claiming one Ready PRD, every PRD scanner also runs the closure rollup (`ticketed → shipped`, Phase 3f) and **dispatches `lisa:verify-prd` for one shipped PRD** (Phase 3g) each cycle — so a shipped PRD does not sit unverified. On pass the PRD goes `shipped → verified`; on fail it is re-opened `shipped → ticketed` with **build-ready fix tickets** that auto-build and trigger a re-verify (never `blocked`). The scanner only dispatches; `lisa:verify-prd` owns the transition (per the `prd-lifecycle-rollup` rule's "Closing the loop" section), and the self-healing loop continues until the PRD verifies.
+5. **Stop after one item** — a claimed Ready item, a safe-blocked container, or a per-item error ends the *ready-claim* portion of the cycle. The per-vendor PRD scanner still runs its rollup and one verify-prd dispatch. Remaining Ready items stay untouched for later scheduler invocations.
+6. **Summary report** — the single processed/skipped/error item, total processed, total errors. Before returning, record intake usage on the persisted cycle-summary artifact via `lisa:usage-accounting` so the summary carries a direct `intake` entry in the canonical `## Lisa Usage` section. If the claimed / skipped work item's parent-child graph is already known, prefer `record_and_rollup` so ancestor totals refresh in the same cycle; otherwise still write the direct entry, and if runtime usage is unavailable, use `source: unavailable` with nullable token/cost fields instead of skipping the row.
+
+## Schedule examples
+
+```text
+/schedule "every 30 minutes" /lisa:intake https://www.notion.so/<workspace>/<database-id>
+/schedule "every 30 minutes" /lisa:intake https://acme.atlassian.net/wiki/spaces/PRD
+/schedule "every 30 minutes" /lisa:intake https://linear.app/acme
+/schedule "every 30 minutes" /lisa:intake https://linear.app/acme/team/ENG/projects
+/schedule "every 30 minutes" /lisa:intake https://github.com/acme/product-prds
+/schedule "every 30 minutes" /lisa:intake acme/product-prds
+/schedule "every 30 minutes" /lisa:intake SE
+/schedule "every 30 minutes" /lisa:intake acme/frontend-v2 intake_mode=build
+/schedule "every 30 minutes" /lisa:intake acme/frontend-v2 intake_mode=build assignee=codyswanngt
+/schedule "every hour" /lisa:intake "project = SE AND component = 'frontend'"
+```
+
+## Rules
+
+- Never run a cycle without an explicit queue. Side effects too high to default.
+- Never modify the source/destination lifecycles directly — Intake delegates per-item to the vendor adapter, which owns status transitions.
+- Never run two Intake cycles concurrently against overlapping queues — concurrent claims could race. The scheduling layer is responsible for serialization.
+- Stop and surface failures rather than retry-loop.