@codyswann/lisa 2.189.7 → 2.189.8

package/plugins/lisa-agy/skills/agent-design-best-practices/SKILL.md

@@ -1,219 +0,0 @@
----
-name: agent-design-best-practices
-description: Best practices for designing Claude Code agent files (.claude/agents/*.md). This skill should be used when writing or reviewing agent markdown files to ensure proper design with focused domains, correct tool access, reusable definitions, and separation of capabilities from lifecycle. Combines Anthropic's official guidance with battle-tested patterns from agent team usage.
----
-
-# Agent Design Best Practices
-
-## Overview
-
-This skill defines best practices for designing Claude Code agent files (`.claude/agents/*.md`). Agent files define reusable roles that can be spawned as subagents or teammates. The core principle is that **agent files define capabilities, not lifecycle** -- the team lead's spawn prompt controls when and how the agent runs.
-
-## Principles
-
-### 1. Define Capabilities, Not Lifecycle
-
-Agent files describe *what* an agent can do. The spawn prompt from the team lead controls *when* it runs and *what to focus on*.
-
-```markdown
-<!-- Wrong: Hardcodes workflow phase and interaction pattern -->
-# Security Planner Agent
-
-You are a security specialist in a plan-create Agent Team.
-Given a Research Brief from the team lead, identify security
-considerations for the planned changes.
-
-## Output Format
-
-Send your sub-plan to the team lead via `SendMessage` with this structure:
-...
-```
-
-```markdown
-<!-- Correct: Defines domain expertise, team lead controls usage -->
-# Security Specialist Agent
-
-You are a security specialist who identifies vulnerabilities,
-evaluates threats, and recommends mitigations for code changes.
-
-## Analysis Process
-1. Read affected files
-2. STRIDE analysis
-3. Check input validation
-...
-```
-
-The wrong version is coupled to one workflow ("plan-create Agent Team", "Given a Research Brief", "Send via SendMessage"). The correct version works in any context -- planning, review, ad-hoc analysis -- because the team lead's spawn prompt provides the specific instructions.
-
-### 2. One Agent Per Domain, Not Per Phase
-
-Prefer a single agent that covers a domain over multiple agents split by workflow phase. The team lead specializes the agent per phase via the spawn prompt.
-
-| Wrong | Right |
-|-------|-------|
-| `security-planner` + `security-reviewer` | `security-specialist` |
-| `test-strategist` + `test-coverage-agent` | `test-specialist` |
-| `architecture-planner` + `architecture-reviewer` | `architecture-specialist` |
-
-The same agent type can be spawned multiple times with different prompts for different phases. A `security-specialist` spawned during planning gets "evaluate this plan for security risks" while the same type spawned during review gets "review these code changes for vulnerabilities."
-
-### 3. Design Focused Domains
-
-Each agent should excel at one specific domain. The domain should be broad enough to avoid workflow coupling but narrow enough to provide real expertise.
-
-```yaml
-# Too narrow (coupled to one workflow step)
-description: Performs STRIDE analysis on Research Briefs during plan-create Phase 2
-
-# Too broad (no clear expertise)
-description: General-purpose agent that can do anything
-
-# Just right (focused domain, reusable across workflows)
-description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling.
-```
-
-### 4. Write Detailed Descriptions
-
-Claude uses the `description` field in YAML frontmatter to decide when to delegate tasks. Be specific about what the agent does and when it adds value.
-
-```yaml
-# Bad: Vague, Claude can't decide when to use it
-description: Reviews code
-
-# Good: Specific domain, clear trigger conditions
-description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling, and recommends mitigations.
-```
-
-### 5. Limit Tool Access
-
-Grant only the tools necessary for the agent's domain. This enforces focus and prevents agents from exceeding their intended scope.
-
-| Agent Type | Appropriate Tools | Rationale |
-|-----------|-------------------|-----------|
-| Researcher / Reviewer | `Read, Grep, Glob, Bash` | Read-only analysis, no file modifications |
-| Implementer | `Read, Write, Edit, Bash, Grep, Glob` | Needs to modify code |
-| Planner | `Read, Grep, Glob` | Research only, no execution |
-
-Read-only agents cannot implement code. Do not assign implementation tasks to agents without `Write` and `Edit` tools.
-
-### 6. No Hardcoded Interaction Patterns
-
-Do not prescribe how the agent communicates or what input format it expects. The team lead's spawn prompt handles interaction patterns.
-
-```markdown
-<!-- Wrong: Hardcodes communication protocol -->
-## Input
-You receive a **Research Brief** from the team lead containing...
-
-## Output Format
-Send your sub-plan to the team lead via `SendMessage` with this structure:
-```
-
-```markdown
-<!-- Correct: Defines output structure without prescribing delivery mechanism -->
-## Output Format
-Structure your findings as:
-
-### Threat Model (STRIDE)
-| Threat | Applies? | Description | Mitigation |
-...
-```
-
-The output format itself is fine to define -- it provides structure. But how the agent receives input and delivers output should be left to the team lead.
-
-### 7. Context Window Isolation
-
-Each teammate has its own context window. Teammates do not share context and cannot see what other teammates have done. Account for this in agent design:
-
-- Do not assume the agent has seen previous analysis from other agents
-- Include enough domain knowledge in the agent file for independent operation
-- The team lead bridges context between agents via spawn prompts and messages
-
-### 8. File Ownership in Teams
-
-When agents work in teams, each teammate should own distinct files or directories. Two teammates editing the same file leads to conflicts and lost work.
-
-Design agent domains so their file ownership naturally separates:
-
-| Agent | Owns |
-|-------|------|
-| `implementer` | Source files (`src/`) |
-| `test-specialist` | Test files (`tests/`) |
-| `quality-specialist` | No files (read-only) |
-
-## Agent File Structure
-
-### Required Frontmatter
-
-```yaml
----
-name: agent-name           # lowercase with hyphens
-description: When and why to use this agent. Be specific.
-tools: Read, Grep, Glob     # comma-separated, minimal set
----
-```
-
-### Optional Frontmatter
-
-```yaml
-model: sonnet              # sonnet, opus, haiku, or inherit (default)
-permissionMode: default     # default, acceptEdits, plan, bypassPermissions, etc.
-maxTurns: 50               # limit agentic turns
-skills:                     # skills to preload
-  - skill-name
-memory: user                # persistent memory: user, project, or local
-```
-
-### Body Structure
-
-The markdown body becomes the agent's system prompt. Structure it as:
-
-1. **Role statement** -- one sentence describing what the agent is
-2. **Analysis/workflow process** -- numbered steps for the agent's approach
-3. **Output format** -- structure for findings (without prescribing delivery mechanism)
-4. **Rules/constraints** -- guardrails for the agent's behavior
-
-## Anti-Patterns
-
-### Don't Create Phase-Specific Agents
-
-```markdown
-<!-- Wrong: Two agents for the same domain, split by phase -->
-# Pre-Implementation Security Planner
-...
-# Post-Implementation Security Reviewer
-...
-
-<!-- Correct: One agent, team lead controls timing -->
-# Security Specialist
-...
-```
-
-### Don't Hardcode Workflow Dependencies
-
-```markdown
-<!-- Wrong: Agent assumes specific workflow context -->
-You are part of the plan-create Phase 2 team.
-Wait for the Research Brief from Phase 1.
-After your analysis, the Consistency Checker will validate your output.
-
-<!-- Correct: Agent is self-contained -->
-You are a security specialist who identifies vulnerabilities
-and recommends mitigations for code changes.
-```
-
-### Don't Over-Specify the Model
-
-Only set `model` when there's a clear reason. Most agents work well with `inherit` (the default), which uses the same model as the parent session. Use `haiku` for fast, simple tasks (exploration, search). Use `sonnet` or `opus` only when the domain requires stronger reasoning.
-
-## Verification Checklist
-
-Before committing an agent file, verify:
-
-1. **Description is specific** -- Claude can determine when to delegate from the description alone
-2. **Tools are minimal** -- only the tools the agent actually needs
-3. **No workflow coupling** -- no references to specific team structures, phases, or input formats
-4. **No hardcoded communication** -- no "send via SendMessage" or "given a Research Brief"
-5. **Domain is reusable** -- the agent works in planning, review, and ad-hoc contexts
-6. **Role statement is clear** -- first line of body explains what the agent is
-7. **Output format is defined** -- structured output without prescribing delivery

package/plugins/lisa-agy/skills/analyze-claude-remote/SKILL.md

@@ -1,421 +0,0 @@
----
-name: analyze-claude-remote
-description: "Audit whether the current repository can run as a Claude Code remote routine (cloud session). Read-only analysis that inventories what Lisa AND the host project need to configure or build in the cloud environment — external CLIs/binaries to install, environment variables and secrets to set, startup hooks and their headless-safety, MCP server scope/transport/auth, user-scoped config and auto-memory gaps that don't replicate to the cloud, and platform constraints (bun proxy, IP allowlist, network tier, no interactivity). Reads `.lisa.config.json` `tracker`/`source` to determine which tracker/PRD-source integrations are active, resolves each to its headless-viable substrate (CLI/curl + token, never browser-OAuth MCP, never OS-keychain), and spells out the exact secret env vars, where to obtain each token, and the precise access scope required — without guessing. Emits grouped findings plus a machine-readable inventory that /lisa:generate-claude-remote-build-script consumes."
-allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
----
-
-# Analyze Claude Remote: $ARGUMENTS
-
-Run a read-only audit of whether **this repository can run as a Claude Code remote routine**
-(a cloud session that runs on Anthropic-managed infrastructure, not the user's machine), and
-inventory everything that would have to be **installed** or **configured** in the cloud
-environment for both Lisa and the host project to function.
-
-## Purpose
-
-Claude Code routines run in a fresh cloud environment that clones the repo from its default
-branch. Setup scripts (to install tools) and environment variables (to provide config/secrets)
-are configurable per environment — but **only repo-committed Claude Code config reaches the
-cloud**, user-scoped config and machine-local auto-memory do not, and some local affordances
-(interactive auth, stdio MCP, desktop control, statusline) cannot work headless at all.
-
-This skill produces the answer to: *"If I turn this repo into a routine, what do I need to put
-in the environment's setup script and env vars, and what simply won't work?"* It is the
-read-only analysis half; `/lisa:generate-claude-remote-build-script` turns its inventory into an
-actual setup script.
-
-This skill ships in the base Lisa plugin and is distributed to every host project, so it must
-discover requirements **dynamically from the repo** rather than assuming Lisa-repo specifics. It
-audits two layers together:
-
-- **Lisa's needs** — startup hooks (`install-pkgs.sh`, `setup-jira-cli.sh`, rule injection),
-  the configured `tracker`/`source`, and the CLIs/MCP/env those imply.
-- **The host project's needs** — its own package manager, build/test tooling, app runtime
-  dependencies, CI-assumed binaries, and project-scoped MCP servers.
-
-## Inputs
-
-- Optional flags in `$ARGUMENTS` to narrow scope (e.g. `--section=tools`, `--json` to print only
-  the machine-readable inventory).
-- The current repository root: `.claude/settings.json`, enabled plugins' `hooks/hooks.json`,
-  `.mcp.json`, `.lisa.config.json` / `.lisa.config.local.json`, `package.json` (or other
-  manifest), lockfiles, `scripts/`, `.github/workflows/`, and committed skills/commands/hooks.
-
-## Confirmation policy
-
-Do **not** ask whether to proceed. Once invoked, run the read-only audit, print the grouped
-findings and the inventory, and stop. Do not mutate any repository, environment, tracker, or
-automation state. The only legitimate reason to stop early is that the working directory cannot
-be resolved to an inspectable repository root.
-
-## Audit contract
-
-Report grouped sections, each check tagged with one status:
-
-- `REQUIRED` — must be installed/set or a routine run cannot do core work.
-- `OPTIONAL` — needed only for a specific integration/stack that is dormant in this repo's config.
-- `GAP` — works locally but **cannot** work in a cloud routine regardless of configuration;
-  the user must change approach (e.g. promote a fact to a repo rule, switch a substrate).
-- `OK` — already cloud-safe; nothing to do.
-- `RISK` — likely to work but with a known cloud caveat the user should verify (e.g. bun proxy).
-
-Group the findings as:
-
-1. **Runtime & package manager** — resolve the package manager from `packageManager`, `engines`,
-   and the lockfile. Identify the install command a `SessionStart` hook or the project would run.
-   Flag `bun` as `RISK` (known cloud-proxy package-fetch issues) and note whether `engines`
-   forbids fallback package managers. Confirm node/runtime version expectations.
-
-2. **Startup hooks** — enumerate `SessionStart` and `SubagentStart` hooks from
-   `.claude/settings.json` and every enabled plugin's `hooks/hooks.json`. For each, state what it
-   runs, whether it is headless-safe, whether it needs network or write access to system paths,
-   and whether it fits the cloud setup-script time budget (~5 minutes for environment caching;
-   `SessionStart` hooks re-run every session and must be fast). Lisa's `install-pkgs.sh` and
-   `setup-jira-cli.sh` are the usual headline items.
-
-3. **External CLIs / binaries** — scan hooks, `scripts/`, committed skills/commands, and
-   `.github/workflows/` for invoked binaries that a base cloud image likely lacks. Assume node,
-   git, and coreutils are present; `gh` is available but should be installed explicitly if scripts
-   call it. Classify each `REQUIRED` (core path uses it) vs `OPTIONAL` (only a dormant stack/skill
-   uses it). Typical finds: `gh`, `jq`, `docker` (ZAP), `aws`, `acli`, `ruby`/`rubocop`,
-   `python3`, `playwright`/chromium, secret scanners. Treat AWS as more than a
-   binary install: if the repo invokes `aws`, imports AWS SDK packages, uses CDK/Serverless/SST,
-   references `AWS_*` env vars, or documents `aws sso login` / `sso_*` profile setup, add the AWS
-   credential findings in group 4b as well as the `aws` CLI tool finding.
-
-4. **Environment variables & secrets** — scan for `process.env.*`, `${VAR}`/`$VAR` in shell,
-   `secrets.*`/`env:` in CI, and config-referenced tokens. Group by integration (GitHub, AWS,
-   Atlassian/JIRA/Confluence, Notion, Linear, Anthropic, notifications, feature flags, other).
-   Cross-reference `.lisa.config.json` `tracker`/`source` to mark which credentials are **active**
-   for this repo vs **dormant** (`OPTIONAL`). Separately classify host-project AWS usage in group 4b:
-   AWS can be required even when it is not the tracker or PRD source. Distinguish *where* each var
-   must be set, because the
-   answer differs and getting it wrong sends the user to do redundant work:
-
-   - **Committed `.claude/settings.json` `env` flags** (e.g. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`,
-     `ENABLE_LSP_TOOL`, `BASH_*`) — this file is repo-committed, so it reaches the cloud and Claude
-     Code applies its `env` block when it launches. These are **already provided — no action**.
-     Surface them as `OK` (cite the file), not `REQUIRED`. Do **not** tell the user to re-enter them
-     in the environment UI; a duplicate there only risks drifting from the committed value. The lone
-     caveat: the setup script runs *before* Claude Code launches, so it cannot see these — flag any
-     that the **setup script itself** would need (rare) as needing a UI value too.
-   - **Secrets** (tokens/keys) — cannot be committed, so the committed `settings.json` can't carry
-     them. These are the only vars that genuinely **must be set in the environment-variables UI**.
-     Mark active-integration secrets `REQUIRED`; dormant ones `OPTIONAL`.
-
-4a. **Tracker / PRD-source credentials** — this is the load-bearing part of the audit and must be
-   driven by config, not by what the scan happens to find. Resolve the active integrations first:
-
-   ```bash
-   TRACKER=$(jq -r '.tracker // "jira"' .lisa.config.json 2>/dev/null)   # tickets: jira | github | linear
-   SOURCE=$(jq -r '.source // empty'    .lisa.config.json 2>/dev/null)   # PRDs:   notion | confluence | github | linear
-   ```
-   (Apply `config-resolution`: `.lisa.config.local.json` overrides `.lisa.config.json`.) For the
-   **active** `tracker` and the **active** `source` — and only those — emit a `REQUIRED` credential
-   finding using the **Credential reference** table below. For every integration that is *not* the
-   active tracker/source, its credentials are `OPTIONAL` (dormant) — never mark them `REQUIRED`.
-
-   Two non-negotiable headless rules govern which substrate a routine can actually use:
-
-   - **Browser-OAuth MCP is dead headless.** A routine cannot complete an interactive OAuth/SSO
-     browser flow. So for any integration whose local substrate is an OAuth MCP (the committed
-     `linear-server` MCP; the Notion MCP; the Atlassian MCP) or an interactively-authed CLI
-     (`acli auth login --web`), the MCP/interactive tier is a `GAP` — the audit must route to that
-     integration's **token substrate** (CLI/curl + API token) and report the token's env vars.
-   - **OS keychain is absent headless.** Lisa's access skills read the token from the OS keychain
-     first (`security` / `secret-tool` / `cmdkey`) and fall back to an **env var**. A cloud routine
-     has no keyring daemon, so only the env-var fallback works. Always report the **env-var form**,
-     including the per-account suffixed names (`ATLASSIAN_API_TOKEN_<slug>`, `NOTION_API_TOKEN_<slug>`,
-     `LINEAR_API_KEY_<slug>`) when the integration keys tokens by email/workspace.
-
-   For each active integration, the finding must carry: the env var name(s), where to get the token
-   (`Acquire:` URL), and the **exact** access/scope required (`Access:`) — copied from the table, not
-   guessed. If a value the table needs (server URL, project key, workspace id, email, team key) is
-   missing from `.lisa.config.json`, flag it as a `GAP`/`Action:` to set it, rather than inventing one.
-
-4b. **AWS operations credentials** — scan the host project for AWS usage independent of Lisa's
-   tracker/source config:
-
-   - `aws` CLI invocations in `scripts/`, package scripts, committed skills/agents, or
-     `.github/workflows/`.
-   - AWS SDK imports/packages (`@aws-sdk/*`, `aws-sdk`, `boto3`, CDK, Serverless, SST, Amplify,
-     Terraform providers).
-   - `aws sso login`, `aws:signin:*`, `sso_start_url`, `sso_account_id`, `sso_role_name`, or
-     `sso_session` in docs or config.
-   - `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_DEFAULT_REGION`,
-     `AWS_PROFILE`, role ARN, external ID, account, or CloudWatch/STS references.
-
-   If AWS is present, emit an AWS credential finding and inventory entry. If the repo's current
-   local path is `aws sso login` or an `aws:signin:*` script, classify that local path as a `GAP`
-   for headless remote routines: it is an interactive browser/device-authorization flow and cannot
-   complete in the cloud. Route to the AWS row in the Credential reference instead of suggesting
-   SSO auth. The finding must name the headless substrate: a dedicated IAM principal (user or role)
-   with only permission to `sts:AssumeRole`, environment credentials in the routine UI, and
-   `~/.aws/config` profiles using `role_arn`, `credential_source = Environment`, optional
-   `external_id`, and `region`.
-
-   When the repository contains concrete non-secret AWS metadata (role ARNs, account aliases,
-   profile names, regions, or ExternalId values), include it in an `awsProfiles` inventory array so
-   `/lisa:generate-claude-remote-build-script` can write matching `~/.aws/config` profiles. Never
-   invent account IDs, ExternalIds, role names, or regions. If AWS is detected but profile metadata
-   is absent, emit the required AWS secret names plus an action to add project-specific profile
-   metadata to the generated artifact or environment notes.
-
-5. **MCP servers** — read every committed `.mcp.json`. For each server report transport and auth.
-   Project-scoped HTTP/SSE servers with no interactive auth are `OK`. Flag stdio servers as
-   `RISK`/`GAP` (need a local process — only viable if the cloud session can spawn them from the
-   repo). Flag interactively/OAuth-authed servers as `GAP` for headless auth — they cannot complete
-   a browser flow headless **regardless of transport** (an HTTP MCP like `linear-server` is still a
-   `GAP` because its *auth* is OAuth, not because of its transport). Before finalizing any
-   OAuth/interactive/stdio MCP as a flat `GAP`, check for a documented headless substrate: a
-   static-token MCP header, a vendor CLI that can login from an env token, or a token-authenticated
-   REST API that the MCP wraps. If documented evidence exists, mark the MCP `headlessUsable: true`
-   in the inventory, mark the supporting secret `required: false` / `secret: true` unless the
-   integration is active, and set `replacedBy` to the concrete substrate rather than leaving it as
-   an impossible capability. When an OAuth MCP backs an active tracker/source, do not stop at the
-   `GAP` — cross-reference group 4a and point to the integration's token substrate as the headless
-   replacement (e.g. `linear-server` MCP -> `LINEAR_API_KEY` + Linear GraphQL). Note any user-scoped
-   MCP (`~/.claude.json`) as `GAP` — it never reaches the cloud; it must be moved into project
-   `.mcp.json`.
-
-   Use this data-driven hint table as seed evidence, and extend it only when you can cite a vendor
-   doc or committed access-skill reference:
-
-   | Match | Substrate | Env | Setup / wiring | Domains |
-   |---|---|---|---|---|
-   | `mcp.jam.dev`, `jam`, or Jam MCP entries | Jam CLI (`jam`) authenticated by PAT | `JAM_PAT` | install with `curl -fsSL https://native.jam.dev/install | bash`; export `~/.local/bin`; run `printf '%s' "$JAM_PAT" | jam auth login --token`; optionally `jam skills install` | `native.jam.dev`, `api.jam.dev` |
-   | `mcp/sonarqube`, `sonarqube`, or SonarCloud/SonarQube MCP entries | SonarCloud Web API | `SONAR_TOKEN` | use REST calls against `https://sonarcloud.io/api/`; if a host needs legacy token-as-basic-auth, put that in the access adapter | `sonarcloud.io` |
-
-   For PAT-bearer MCP substrates that really use the same MCP transport, include `mcpHeaders` in
-   the inventory with a snippet such as `headers: { "Authorization": "Bearer ${VAR}" }` so the
-   generator can print a commented `.mcp.json` example. Do **not** use that for Jam: Jam's preferred
-   headless substrate is the `jam` CLI, so the generator should emit CLI setup lines instead of an
-   `.mcp.json` header snippet.
-
-   When no documented substrate is known, keep the MCP as `headlessUsable: false` / `GAP`, and add
-   an action line like: `check the vendor for a documented PAT, API-key, CLI, or REST substrate`.
-   Never assert that no substrate exists unless the vendor documentation explicitly says so.
-
-6. **Config scope & memory gaps** — identify reliance on user-scoped config that will not load
-   remotely: `~/.claude/CLAUDE.md`, user `enabledPlugins`, user skills/agents, user MCP. Most
-   importantly, flag **auto-memory** as a `GAP`: the persistent file-based memory directory is
-   machine-local and is not synced to cloud routines, so any learnings stored there are absent in
-   a remote run. Recommend promoting load-bearing memories into committed `.claude/rules/`.
-
-7. **Platform constraints** — surface the non-config constraints as `GAP`/`RISK` so the user is
-   not surprised: routines run with no interactive permission prompts and cannot ask the user
-   mid-run; interactive auth (SSO/OAuth browser, keychain) is unavailable; GitHub org IP
-   allowlisting blocks cloud sessions; raw GitHub clone/fetch/push operations are handled by
-   Claude's connected-GitHub proxy/identity and do not need a separate PAT; the `gh` CLI is not the
-   same substrate and still needs `GH_TOKEN`; outbound traffic is controlled by the routine
-   environment network tier, where the default Trusted tier includes common development domains and
-   package registries but arbitrary integration hosts need Custom or Full access; environment
-   variables and setup scripts are stored in the cloud environment configuration and are visible to
-   anyone who can edit that environment; resource limits (~4 vCPU / 16 GB RAM / 30 GB disk); no
-   desktop/computer-use; no statusline/theme rendering.
-
-8. **Host-project app needs** — note any build/test/run command a routine would invoke and any
-   runtime service it depends on (database, queue, external API) that will not exist in a fresh
-   cloud environment, so the user can decide whether the routine's task is even feasible there.
-
-## Credential reference (tracker / source → headless secret)
-
-Authoritative mapping for group 4a, transcribed from Lisa's `setup-*` skills and access layers
-(`setup-github`, `setup-atlassian`, `setup-jira`, `setup-notion`, `setup-linear`,
-`atlassian-access`, `notion-access`). Use the row for the **active** `tracker`/`source` only. Report
-the **env-var form** of each secret — keychain reads do not work in a cloud routine. Slugs:
-`<email-slug>` = email via `tr '[:upper:]@.' '[:lower:]__'`; `<ws-slug>` = workspace via
-`tr '[:upper:]-' '[:lower:]_'`. If a token has both an unsuffixed and a per-account form, the
-unsuffixed `…_TOKEN`/`…_KEY` is the simplest to set in a single-account routine.
-
-### GitHub — `tracker: github` and/or `source: github`
-- Headless substrate: `gh` CLI authed by token (every Lisa GitHub script gates on `gh auth status`).
-- Platform substrate: Claude's connected-GitHub proxy/identity authenticates raw git
-  clone/fetch/push for repositories the routine can access. Do not ask for a PAT solely for raw git
-  or sibling-repo clones.
-- Env: `GH_TOKEN` for the `gh` CLI only; set it because Lisa's PR/issue lifecycle shells out to
-  `gh`. Do not describe it as required for raw git clone/fetch/push.
-- Acquire: fine-grained — `https://github.com/settings/personal-access-tokens`; classic — `https://github.com/settings/tokens`.
-- Access: fine-grained → Repository access to the repo(s) where Lisa will run `gh` commands (the
-  project repo, and the Lisa repo only if filing Lisa issues); Repository permissions: Contents R/W,
-  Issues R/W, Pull requests R/W, Metadata R (mandatory); add Workflows R/W only if editing
-  `.github/workflows`, and Organization → Projects R/W only if using ProjectV2. Do not include
-  sibling repos that are only cloned/fetched with raw git. Classic equivalent: `repo` + `workflow`
-  (+ `project`, `read:org` for boards). The identity must hold WRITE/MAINTAIN/ADMIN on the repo.
-
-### JIRA — `tracker: jira`
-- Headless substrate: `jira-cli` + curl (Basic auth). The acli and Atlassian-MCP tiers need prior interactive/OAuth auth → not viable headless.
-- Env: `JIRA_API_TOKEN`, `JIRA_SERVER` (e.g. `https://acme.atlassian.net`), `JIRA_LOGIN` (account email), `JIRA_PROJECT` (default project key); optional `JIRA_INSTALLATION` (default `cloud`), `JIRA_BOARD`. (`setup-jira-cli.sh` writes the jira-cli config from these on SessionStart.)
-- Acquire: `https://id.atlassian.com/manage-profile/security/api-tokens`.
-- Access: the API token inherits the Atlassian user's permissions — the user must have Browse/Create/Edit/Transition on the target project. An unscoped token suffices for jira-cli; a scoped token must cover the JIRA project read/write operations.
-
-### Confluence — `source: confluence`
-- Headless substrate: curl + Basic auth + **scoped** API token.
-- Env: `ATLASSIAN_API_TOKEN` (or per-account `ATLASSIAN_API_TOKEN_<email-slug>`). Config (`.lisa.config.json`): `atlassian.cloudId`, `atlassian.site`, `atlassian.email`.
-- Acquire: `https://id.atlassian.com/manage-profile/security/api-tokens` → "Create API token **with scopes**" → App: **Confluence**.
-- Access (select EXACTLY): `read:page:confluence`, `read:hierarchical-content:confluence`, `read:comment:confluence`, `read:space:confluence`, `write:page:confluence`, `write:comment:confluence`, `write:label:confluence`, `search:confluence`.
-
-### Notion — `source: notion`
-- Headless substrate: curl + Bearer + internal-integration token. The Notion MCP tier is OAuth → not viable headless.
-- Env: `NOTION_API_TOKEN` (or per-account `NOTION_API_TOKEN_<ws-slug>`). Config: `notion.workspaceId`, `notion.prdDatabaseId`.
-- Acquire: `https://www.notion.so/profile/integrations` → New integration → type **Internal** → copy the `ntn_*` Internal Integration Token.
-- Access: internal-integration token. **Non-optional:** share the target PRD database with the integration (Notion's share-based model) or every call returns 404/`object_not_found`.
-
-### Linear — `tracker: linear` and/or `source: linear`
-- Headless substrate: curl GraphQL (`https://api.linear.app/graphql`) + personal API key. The committed `linear-server` MCP is OAuth/browser → cannot authenticate headless; the API key is the only headless path.
-- Env: `LINEAR_API_KEY` (or per-account `LINEAR_API_KEY_<ws-slug>`). Config: `linear.workspace`; `linear.teamKey` required when Linear is the tracker.
-- Acquire: `https://linear.app/<workspace>/settings/account/security` → Personal API keys → New API key.
-- Access: the personal API key inherits the user's workspace permissions — the user must be able to read/create/update Issues in the destination team.
-
-### AWS — host-project operations, logs, deploys, CDK/Serverless/SST, or AWS SDK usage
-- Headless substrate: a dedicated IAM principal (user or role) with long-lived bootstrap credentials
-  stored in the routine environment, used only to call `sts:AssumeRole` into per-account operational
-  roles. The routine writes `~/.aws/config` profiles with `role_arn`, `credential_source =
-  Environment`, optional `external_id`, and `region`; agents use `aws --profile <profile> ...`.
-- Env: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`; optional `AWS_SESSION_TOKEN` for temporary
-  bootstrap credentials; `AWS_DEFAULT_REGION` when no profile region is provided. Role ARNs,
-  ExternalIds, profile names, and regions are non-secret project metadata and belong in generated
-  artifacts or project docs, not in the skill's global guidance.
-- Allowlist: `*.amazonaws.com`, or narrower service hosts such as `sts.amazonaws.com`,
-  `logs.<region>.amazonaws.com`, `cloudwatch.<region>.amazonaws.com`,
-  `xray.<region>.amazonaws.com`, `ssm.<region>.amazonaws.com`, and service-specific endpoints the
-  repo uses.
-- Access: the bootstrap principal should have only `sts:AssumeRole` on the scoped operational role
-  ARNs, preferably guarded by an `ExternalId` condition. The assumed roles carry the real
-  permissions needed by the repo (CloudWatch Logs, deploy, SSM, etc.) as short-lived STS
-  credentials.
-- IAM Identity Center caveat: an IAM Identity Center permission set provisions an `AWSReservedSSO_*`
-  role whose trust allows the SSO service, not an arbitrary IAM principal. A headless IAM principal
-  cannot directly assume that reserved role. Use a separate assumable role that attaches the same
-  policy as the permission set, with the delegated Identity Center admin keeping that policy as the
-  source of truth.
-- Alternative: IAM Roles Anywhere (X.509 to STS) when long-lived bootstrap access keys are
-  unacceptable.
-
-## Output
-
-Render the report grouped exactly as above. Start with one `Summary:` line, then a `Counts:` line
-covering `REQUIRED`, `OPTIONAL`, `GAP`, `RISK`, `OK`. Print each group as `<n>. <title>` and one
-line per check as `- <STATUS> <id>: <summary>`, with optional `Observed:` and `Action:` lines
-beneath that separate fact from advice. Render an empty group as a single `OK`/`SKIP` line with the
-reason rather than omitting it.
-
-Immediately after the grouped findings, render a **`Credentials to provision`** subsection — a
-checklist of the secrets the user must set in the routine's environment for the **active**
-`tracker`/`source` (from group 4a). One block per active integration, each with its env-var name(s),
-an `Acquire:` URL, and an `Access:` scope line, plus a one-line note that the environment UI is where
-these are set (the generated build script only emits a names-only template, never values). If both
-`tracker` and `source` resolve to the same vendor (e.g. both GitHub), render it once. List **only
-secrets** here — do not include the committed `.claude/settings.json` `env` flags; close the
-subsection with a one-line reminder that those flags are already provided by the committed file and
-need no UI entry.
-
-End with a fenced, machine-readable inventory block (also printed when `--json` is passed) so
-`/lisa:generate-claude-remote-build-script` can consume it without re-deriving everything. Secret
-`env` entries for active integrations MUST carry `acquireUrl`, `accessScope`, and `headlessSubstrate`
-so the generator can render acquisition comments into its template:
-
-```json
-{
-  "packageManager": { "name": "bun", "installCmd": "bun install", "risk": "cloud-proxy" },
-  "tools": [
-    { "name": "gh", "required": true, "reason": "github-* skills and scripts shell out to gh" },
-    { "name": "jq", "required": true, "reason": "hooks and scripts parse JSON" }
-  ],
-  "tracker": "github",
-  "source": "github",
-  "env": [
-    { "name": "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS", "required": false, "secret": false, "providedBy": "settings.json", "uiAction": "none", "reason": "committed in .claude/settings.json env — applied automatically; do not re-enter in the UI" },
-    {
-      "name": "GH_TOKEN", "required": true, "secret": true, "integration": "github",
-      "reason": "active tracker+source; gh scripts gate on gh auth status",
-      "headlessSubstrate": "gh CLI (token)",
-      "acquireUrl": "https://github.com/settings/personal-access-tokens",
-      "accessScope": "fine-grained PAT on target repo: Contents R/W, Issues R/W, Pull requests R/W, Metadata R; +Workflows R/W if editing .github/workflows; +Projects R/W if using ProjectV2"
-    },
-    {
-      "name": "JAM_PAT", "required": false, "secret": true, "integration": "jam",
-      "reason": "optional non-tracker MCP recovery; Jam CLI can authenticate headlessly from a PAT",
-      "headlessSubstrate": "jam CLI (PAT)",
-      "acquireUrl": "https://jam.dev/docs/debug-a-jam/mcp/personal-access-tokens",
-      "accessScope": "Jam Personal Access Token for the workspace/team whose traces the routine needs to read",
-      "setupSnippet": "curl -fsSL https://native.jam.dev/install | bash; export PATH=\"$HOME/.local/bin:$PATH\"; printf '%s' \"$JAM_PAT\" | jam auth login --token; jam skills install"
-    },
-    {
-      "name": "SONAR_TOKEN", "required": false, "secret": true, "integration": "sonarcloud",
-      "reason": "optional non-tracker MCP recovery; SonarQube MCP wraps the token-authenticated SonarCloud Web API",
-      "headlessSubstrate": "SonarCloud Web API (token)",
-      "acquireUrl": "https://docs.sonarsource.com/sonarqube-cloud/managing-your-account/managing-tokens",
-      "accessScope": "token must be able to read the target SonarCloud organization/project quality gate, issues, hotspots, rules, and source snippets"
-    }
-  ],
-  "mcp": [
-    { "name": "linear-server", "transport": "http", "auth": "oauth", "headlessUsable": false, "replacedBy": "LINEAR_API_KEY + Linear GraphQL", "dormant": true },
-    { "name": "jam", "transport": "http", "auth": "oauth", "headlessUsable": true, "replacedBy": "jam CLI + JAM_PAT", "dormant": true },
-    { "name": "sonarqube", "transport": "stdio", "auth": "local-wrapper", "headlessUsable": true, "replacedBy": "SONAR_TOKEN + SonarCloud Web API", "dormant": true }
-  ],
-  "awsProfiles": [
-    {
-      "name": "dev",
-      "roleArn": "arn:aws:iam::<account-id>:role/<role-name>",
-      "credentialSource": "Environment",
-      "externalId": "<project-external-id>",
-      "region": "us-east-1"
-    }
-  ],
-  "gaps": [ "auto-memory not synced to cloud", "bun package fetch behind proxy", "OS keychain absent — env-var token form only" ],
-  "platform": {
-    "githubProxy": {
-      "rawGitAuthenticated": true,
-      "crossRepoAccess": "repositories reachable by the connected GitHub identity/routine access do not need a PAT for raw git",
-      "ghCliNeedsToken": true
-    },
-    "secretsVisibility": "environment variables and setup scripts are visible to environment editors"
-  },
-  "networkAccess": {
-    "tier": "custom",
-    "allowlistDomains": []
-  },
-  "allowlistDomains": []
-}
-```
-
-## Delegation and reuse
-
-- Reuse `config-resolution` semantics (local overrides global) when reading `.lisa.config.json` /
-  `.lisa.config.local.json` to decide which integrations are active vs dormant.
-- Complementary to `/lisa:doctor`: doctor answers "is this repo ready to use Lisa locally?";
-  this skill answers "can this repo run as a remote routine, and what must the cloud env provide?"
-  Do not duplicate doctor's local-readiness checks — focus on the local-vs-cloud delta.
-- The companion generator `/lisa:generate-claude-remote-build-script` consumes this skill's
-  inventory block; keep the block shape stable.
-
-## Rules
-
-- Never mutate repository, environment, tracker, or automation state. This skill is read-only.
-- Classify by **evidence in the repo**, not assumption — cite the file that proves each finding.
-- Distinguish active from dormant strictly by the resolved `.lisa.config.json` config; do not mark
-  a dormant tracker's credentials `REQUIRED`.
-- Never report a `GAP` as satisfiable by configuration — a gap is a constraint, and the action must
-  be a change of approach, not "set an env var".
-- Never invent tools or env vars that no committed file references.
-- Credential scopes and acquisition URLs come from the **Credential reference** table (sourced from
-  Lisa's `setup-*` skills) — transcribe them exactly; never guess at the access a token needs.
-- For the active `tracker`/`source`, always report the **env-var** form of the secret, never the OS
-  keychain form — keychain reads do not work in a cloud routine.
-- For GitHub, keep the split explicit: raw git uses the platform GitHub proxy/identity, while
-  `GH_TOKEN` is for `gh` CLI commands. Sibling repos that are only cloned or fetched with raw git do
-  not belong in the token scope.
-- Add GitHub/npm/PyPI/Docker Hub/common development domains to neither `allowlistDomains` nor
-  `networkAccess.allowlistDomains`; those are covered by the routine environment's default Trusted
-  list. Only non-default integration hosts require Custom-network allowlisting.
-- Always include a `RISK`/`GAP` finding when environment secrets or setup scripts would be visible
-  to environment editors; never imply the generated script can hide them.
-- A browser-OAuth MCP (or interactively-authed CLI) backing an active integration is a `GAP`; the
-  remediation is its token substrate from the table, not "authenticate the MCP".
-- `aws sso login`, `sso_*` profile configuration, and project scripts that wrap AWS SSO are
-  interactive-auth paths. In a headless routine they are a `GAP`, not a setup step. Route AWS access
-  to env-var bootstrap credentials plus assume-role profiles.
-- For non-tracker MCPs, a documented CLI, PAT/API-key, or REST substrate converts the finding from
-  a flat `GAP` into an `OPTIONAL` headless recovery path; unknown vendors remain gaps with a
-  vendor-substrate follow-up, not invented credentials.