{"owner":"getsentry","repo":"XcodeBuildMCP","hasSkills":true,"totalSkillsCount":22,"totalTokensCount":16983,"categories":["anthropic-skill","root-instruction","claude-rule","cursor-rule"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/mobilebuildmcp-docs-command-review/SKILL.md",".agents/skills/mobilebuildmcp-docs-release-review/SKILL.md",".agents/skills/mobilebuildmcp-packaging-resource-review/SKILL.md",".agents/skills/mobilebuildmcp-rendering-streaming-review/SKILL.md",".agents/skills/mobilebuildmcp-runtime-boundary-review/SKILL.md",".agents/skills/mobilebuildmcp-snapshot-fixture-review/SKILL.md",".agents/skills/mobilebuildmcp-structured-output-review/SKILL.md",".agents/skills/mobilebuildmcp-test-boundary-review/SKILL.md",".agents/skills/mobilebuildmcp-tool-contract-review/SKILL.md",".agents/skills/warden-sweep/SKILL.md",".agents/skills/warden-sweep/references/patch-prompt.md",".agents/skills/warden-sweep/references/verify-prompt.md",".agents/skills/warden/SKILL.md",".agents/skills/warden/references/cli-reference.md",".agents/skills/warden/references/config-schema.md",".agents/skills/warden/references/configuration.md",".agents/skills/warden/references/creating-skills.md","AGENTS.md","CLAUDE.md","example_projects/iOS/.cursor/rules/errors.mdc","skills/mobilebuildmcp-cli/SKILL.md","skills/mobilebuildmcp/SKILL.md"],"skills":{".agents/skills/mobilebuildmcp-docs-command-review/SKILL.md":"---\nname: mobilebuildmcp-docs-command-review\ndescription: Use when reviewing MobileBuildMCP changelog CLI command references for invalid current guidance while allowing historical migration examples.\nallowed-tools: Read Grep Glob\n---\n\n# MobileBuildMCP Docs Command Review\n\nReview changed changelog entries for CLI command references that would mislead users or agents.\n\n## What to inspect\n\n- `CHANGELOG.md`\n- `manifests/tools/*.yaml` and `manifests/workflows/*.yaml` when you need to verify current CLI workflow/tool names\n- `src/cli/**` only when command wiring is unclear from manifests\n\n## Issue criteria\n\nReport a finding only when a command reference is presented as current guidance and appears invalid for the current CLI surface.\n\n### High severity\n\n- A changelog bullet, example, or migration instruction tells users to run a removed or invalid `mobilebuildmcp` command as the current path.\n- A Breaking change mentions a removed command but does not give a valid replacement.\n- A command reference uses the wrong workflow/tool pairing in a way a user or agent would likely copy.\n\n### Medium severity\n\n- A command reference is ambiguous enough that users may not know whether it is historical or current.\n- A migration example gives the right replacement but does not clearly label the old command as \"Before\", \"old\", \"removed\", or equivalent.\n\n## Explicitly allowed\n\nDo not report removed commands when they are clearly historical context, especially in:\n\n- Breaking-change migration sections\n- \"Before\" examples paired with valid \"After\" examples\n- Already-released changelog sections describing past behavior\n\nExample that should not be reported:\n\n```markdown\nBefore:\nmobilebuildmcp logging start-sim-log-cap\n\nAfter:\nmobilebuildmcp simulator build-and-run\n```\n\n## Output\n\nFor each finding, include:\n\n- Severity\n- File and line\n- The command reference\n- Why it reads as current guidance\n- Suggested replacement wording or command\n\nIf all command references are historical or valid, report no findings.\n",".agents/skills/mobilebuildmcp-docs-release-review/SKILL.md":"---\nname: mobilebuildmcp-docs-release-review\ndescription: Use when reviewing MobileBuildMCP documentation, CLI command references, website manifest generation, changelog, release notes, and release script changes.\n---\n\n# MobileBuildMCP Docs and Release Review\n\nReview guardrails for documentation, generated references, and release flow consistency.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `README.md`\n- `CHANGELOG.md` when present\n- `scripts/build-website-manifest.mjs`\n- `scripts/generate-github-release-notes.mjs`\n- `scripts/release.sh`\n- `package.json`\n- `xcodebuildmcp.com/app/docs/_content/**`\n\n## Guardrails\n\n- CLI examples match generated CLI catalog/commands.\n- Docs do not reference unavailable tools or workflows.\n- User-facing behavior changes include changelog updates.\n- Release notes derive from a valid changelog section.\n- README install snippets align with release script tag replacement.\n- Website manifest generation preserves expected normalized fields.\n- Docs explain runtime/contracts without deprecated patterns.\n- Keep docs-only work from introducing product behavior changes.\n- CLI command references in changelog entries are reviewed by `mobilebuildmcp-docs-command-review`.\n\n## Validation\n\n- `npm run build`\n- Release notes check when touched:\n - `node scripts/generate-github-release-notes.mjs --version --changelog CHANGELOG.md`\n- `npx skill-check .agents/skills/mobilebuildmcp-docs-release-review`\n",".agents/skills/mobilebuildmcp-packaging-resource-review/SKILL.md":"---\nname: mobilebuildmcp-packaging-resource-review\ndescription: Use when reviewing MobileBuildMCP packaging, resource-root, build artifact, bundled AXe, schema, manifest, and portable macOS distribution changes.\n---\n\n# MobileBuildMCP Packaging and Resource Review\n\nReview guardrails for package/build/resource integrity and portable distribution.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `package.json`\n- `scripts/copy-build-assets.js`\n- `scripts/package-macos-portable.sh`\n- `scripts/build-website-manifest.mjs`\n- `schemas/**`\n- `manifests/**`\n- `skills/**`\n- `bundled/**` when present\n- Resource-root utilities when touched\n\n## Guardrails\n\n- Published package `files` includes required runtime resources.\n- Portable package includes `build`, `manifests`, `bundled`, `skills`, `package.json`, and production dependencies.\n- AXe binary/framework expectations remain verified.\n- Wrapper scripts preserve `MOBILEBUILDMCP_RESOURCE_ROOT` and `DYLD_FRAMEWORK_PATH`.\n- Schemas and manifests stay available in installed and portable layouts.\n- Do not assume build outputs exist before `npm run build`.\n- Avoid network-dependent packaging behavior without verification/checksums.\n\n## Validation\n\n- `npm run build`\n- Packaging-specific when touched:\n - `npm run package:macos -- --help` (if supported)\n - `npm run verify:portable` after artifact creation\n- `npx skill-check .agents/skills/mobilebuildmcp-packaging-resource-review`\n",".agents/skills/mobilebuildmcp-rendering-streaming-review/SKILL.md":"---\nname: mobilebuildmcp-rendering-streaming-review\ndescription: Use when reviewing MobileBuildMCP rendering, streaming fragment, next-step, and CLI output mode changes for boundary violations.\n---\n\n# MobileBuildMCP Rendering and Streaming Review\n\nReview guardrails for rendering boundaries, streaming fragments, and output modes.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/rendering/**`\n- `src/types/domain-fragments.ts`\n- `src/types/runtime-status.ts`\n- `src/runtime/tool-invoker.ts`\n- `src/runtime/__tests__/tool-invoker.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/architecture-rendering-output.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-tool-lifecycle.mdx`\n- `xcodebuildmcp.com/app/docs/_content/output-formats.mdx`\n\n## Guardrails\n\n- Tool handlers do not branch on CLI vs MCP output mode.\n- Fragments represent progress, not final contract data.\n- Final structured output remains canonical.\n- Do not invent `json`/`jsonl` render strategies.\n- Streaming tools emit typed fragments and one final structured result.\n- Non-streaming tools do not emit unnecessary fragments.\n- Keep `ctx.emit` and xcodebuild pipeline `emitFragment` contexts separate.\n- Keep next-step rendering in runtime/rendering boundary.\n\n## Validation\n\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npm run test:snapshots`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-rendering-streaming-review`\n",".agents/skills/mobilebuildmcp-runtime-boundary-review/SKILL.md":"---\nname: mobilebuildmcp-runtime-boundary-review\ndescription: Use when reviewing MobileBuildMCP runtime boundary changes across MCP, direct CLI invocation, daemon-routed tools, and Xcode IDE bridge routing.\n---\n\n# MobileBuildMCP Runtime Boundary Review\n\nReview guardrails for runtime routing and invocation boundaries.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/runtime/tool-catalog.ts`\n- `src/runtime/tool-invoker.ts`\n- `src/runtime/types.ts`\n- `src/cli/**`\n- `src/daemon/**`\n- `manifests/tools/*.yaml`\n- `manifests/workflows/*.yaml`\n- `xcodebuildmcp.com/app/docs/_content/architecture-runtime-boundaries.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-manifest-visibility.mdx`\n\n## Guardrails\n\n- MCP, CLI, and daemon paths use shared handlers.\n- Stateful CLI tools route through daemon only when `routing.stateful` requires it.\n- Do not treat daemon as a third manifest availability mode.\n- Dynamic Xcode IDE tools keep daemon routing semantics.\n- Catalog filtering respects availability, workflow selection, and predicates.\n- Runtime failures surface via runtime/rendering status and fragments.\n- Avoid silent fallbacks and parallel invocation paths.\n\n## Validation\n\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-runtime-boundary-review`\n",".agents/skills/mobilebuildmcp-snapshot-fixture-review/SKILL.md":"---\nname: mobilebuildmcp-snapshot-fixture-review\ndescription: Use when reviewing MobileBuildMCP snapshot fixture changes for MCP, CLI, and JSON output contract integrity.\n---\n\n# MobileBuildMCP Snapshot Fixture Review\n\nReview guardrails for fixture and snapshot contract integrity.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/snapshot-tests/__fixtures__/**`\n- `src/snapshot-tests/contracts.ts`\n- `src/snapshot-tests/fixture-io.ts`\n- `src/snapshot-tests/__tests__/fixture-io.test.ts`\n- `src/snapshot-tests/__tests__/json-normalize.test.ts`\n- `src/snapshot-tests/__tests__/json-fixture-schema.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/testing.mdx`\n\n## Guardrails\n\n- Fixture updates map to intentional behavior changes.\n- Do not update fixtures only to make tests pass.\n- MCP, CLI, and JSON fixture updates stay aligned.\n- JSON fixtures preserve stable structured output envelopes.\n- Volatile values are normalized in code, not patched ad hoc in fixtures.\n- Missing fixtures are generated through the snapshot update flow.\n- Verify project-defined normalization sentinels in normalization code and tests before reporting\n them as implausible fixture values. In particular, `99999` is an intentional sentinel for\n volatile UI capture counts.\n- Group every occurrence of the same root cause into one finding and list the affected fixtures.\n Do not emit separate findings for equivalent CLI, MCP, text, or JSON drift.\n- Do not repeat a finding that is already resolved by the current diff.\n\n## Review limits\n\n- Review the changed fixtures and the directly relevant normalization or contract code only.\n- Do not run snapshot or smoke suites as part of an automated PR review.\n- Prefer one high-confidence cross-fixture finding over multiple speculative discrepancies.\n",".agents/skills/mobilebuildmcp-structured-output-review/SKILL.md":"---\nname: mobilebuildmcp-structured-output-review\ndescription: Use when reviewing MobileBuildMCP structured output schema changes, schema versioning, manifest outputSchema metadata, and JSON fixture compatibility.\n---\n\n# MobileBuildMCP Structured Output Review\n\nReview guardrails for structured output schema correctness and compatibility.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `schemas/structured-output/**`\n- `src/core/structured-output-schema.ts`\n- `src/core/__tests__/structured-output-schema.test.ts`\n- `src/snapshot-tests/__fixtures__/json/**`\n- `src/snapshot-tests/__tests__/json-fixture-schema.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/schema-versioning.mdx`\n- `xcodebuildmcp.com/app/docs/_content/output-formats.mdx`\n\n## Guardrails\n\n- `schema` uses `mobilebuildmcp.output.` format.\n- `schemaVersion` uses integer strings only.\n- Breaking schema changes create a new versioned schema file.\n- Published schema versions are not removed or mutated incompatibly.\n- Manifest `outputSchema` matches emitted `ctx.structuredOutput` payload.\n- JSON fixtures validate against current schema contracts.\n- `$ref` usage remains compatible with bundling in `structured-output-schema.ts`.\n\n## Validation\n\n- `npm run test:schema-fixtures`\n- `npm test -- src/core/__tests__/structured-output-schema.test.ts`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-structured-output-review`\n",".agents/skills/mobilebuildmcp-test-boundary-review/SKILL.md":"---\nname: mobilebuildmcp-test-boundary-review\ndescription: Use when reviewing MobileBuildMCP tests for correct unit, snapshot, schema, smoke, and external process boundaries.\n---\n\n# MobileBuildMCP Test Boundary Review\n\nReview guardrails for test isolation, scope, and contract validation.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/**/__tests__/**`\n- `src/test-utils/**`\n- `src/snapshot-tests/**`\n- `scripts/**/__tests__/**`\n- `package.json`\n- `xcodebuildmcp.com/app/docs/_content/testing.mdx`\n- `xcodebuildmcp.com/app/docs/_content/contributing.mdx`\n\n## Guardrails\n\n- Unit tests inject command/filesystem/external dependencies.\n- Unit tests do not call real `xcodebuild`, `xcrun`, AXe, devices, or simulators.\n- Prefer testing logic/executor functions over handler wrappers unless testing runtime integration.\n- Use existing mock executor helpers.\n- Treat snapshot updates as contract changes requiring review.\n- Do not add fake e2e/snapshot state to force test success.\n- Avoid unsafe TypeScript suppressions.\n\n## Validation\n\n- Run targeted Vitest command for touched tests.\n- `npm test`\n- `npm run typecheck`\n- If fixtures/schemas changed: `npm run test:snapshots` and `npm run test:schema-fixtures`\n- `npx skill-check .agents/skills/mobilebuildmcp-test-boundary-review`\n",".agents/skills/mobilebuildmcp-tool-contract-review/SKILL.md":"---\nname: mobilebuildmcp-tool-contract-review\ndescription: Use when reviewing MobileBuildMCP tool contract changes across implementation, manifests, workflow membership, output schema metadata, and next-step templates.\n---\n\n# MobileBuildMCP Tool Contract Review\n\nReview guardrails for tool contract changes across implementation, manifests, and workflow exposure.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/mcp/tools/**`\n- `manifests/tools/*.yaml`\n- `manifests/workflows/*.yaml`\n- `src/core/manifest/schema.ts`\n- `src/runtime/tool-catalog.ts`\n- `src/runtime/types.ts`\n- `xcodebuildmcp.com/app/docs/_content/tool-authoring.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-manifest-visibility.mdx`\n\n## Guardrails\n\n- Manifest `id` matches filename.\n- Manifest `module` points to implementation path without extension.\n- Tool module exports named `schema` and `handler`.\n- `names.mcp` remains globally unique.\n- `names.cli` stays workflow-local and consistent with CLI docs/fixtures.\n- Tool appears in at least one workflow unless intentionally hidden by availability.\n- `outputSchema` is present for tools that set `ctx.structuredOutput`.\n- `nextSteps.toolId` references existing manifest tool IDs.\n- Avoid parallel legacy paths or duplicate implementation paths.\n\n## Validation\n\n- `npm run typecheck`\n- `npm test -- src/core/manifest/__tests__/schema.test.ts`\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npx skill-check .agents/skills/mobilebuildmcp-tool-contract-review`\n",".agents/skills/warden-sweep/SKILL.md":"---\nname: warden-sweep\ndescription: Full-repository code sweep. Scans every file with warden, verifies findings via deep tracing, creates draft PRs for validated issues. Use when asked to \"sweep the repo\", \"scan everything\", \"find all bugs\", \"full codebase review\", \"batch code analysis\", or run warden across the entire repository.\ndisable-model-invocation: true\n---\n\n# Warden Sweep\n\nFull-repository code sweep: scan every file, verify findings with deep tracing, create draft PRs for validated issues.\n\n**Requires**: `warden`, `gh`, `git`, `jq`, `uv`\n\n**Important**: Run all scripts from the repository root using `${CLAUDE_SKILL_ROOT}`. Output goes to `.warden/sweeps//`.\n\n## Bundled Scripts\n\n### `scripts/scan.py`\n\nRuns setup and scan in one call: generates run ID, creates sweep dir, checks deps, creates `warden` label, enumerates files, runs warden per file, extracts findings.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py [file ...]\n --sweep-dir DIR # Resume into existing sweep dir\n```\n\n### `scripts/index_prs.py`\n\nFetches open warden-labeled PRs, builds file-to-PR dedup index, caches diffs for overlapping PRs.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/index_prs.py \n```\n\n### `scripts/create_issue.py`\n\nCreates a GitHub tracking issue summarizing sweep results. Run after verification, before patching.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/create_issue.py \n```\n\n### `scripts/organize.py`\n\nTags security findings, labels security PRs, updates finding reports with PR links, posts final results to tracking issue, generates summary report, finalizes manifest.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/organize.py \n```\n\n### `scripts/extract_findings.py`\n\nParses warden JSONL log files and extracts normalized findings. Called automatically by `scan.py`.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/extract_findings.py -o \n```\n\n### `scripts/generate_report.py`\n\nBuilds `summary.md` and `report.json` from sweep data. Called automatically by `organize.py`.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/generate_report.py \n```\n\n### `scripts/find_reviewers.py`\n\nFinds top 2 git contributors for a file (last 12 months).\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/find_reviewers.py \n```\n\nReturns JSON: `{\"reviewers\": [\"user1\", \"user2\"]}`\n\n---\n\n## Phase 1: Scan\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py\n```\n\nTo resume a partial scan:\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py --sweep-dir .warden/sweeps/\n```\n\nParse the JSON stdout. Save `runId` and `sweepDir` for subsequent phases.\n\n**Report** to user:\n\n```\n## Scan Complete\n\nScanned **{filesScanned}** files, **{filesTimedOut}** timed out, **{filesErrored}** errors.\n\n### Findings ({totalFindings} total)\n\n| # | Severity | Skill | File | Title |\n|---|----------|-------|------|-------|\n| 1 | **HIGH** | security-review | `src/db/query.ts:42` | SQL injection in query builder |\n...\n```\n\nRender every finding from the `findings` array. Bold severity for high and above.\n\n**On failure**: If exit code 1, show the error JSON and stop. If exit code 2, show the partial results. List timed-out files separately from errored files so users know which can be retried.\n\n---\n\n## Phase 2: Verify\n\nDeep-trace each finding using Task subagents to qualify or disqualify.\n\n**For each finding in `data/all-findings.jsonl`:**\n\nCheck if `data/verify/.json` already exists (incrementality). If it does, skip.\n\nLaunch a Task subagent (`subagent_type: \"general-purpose\"`) for each finding. Process findings in parallel batches of up to 8 to improve throughput.\n\n**Task prompt for each finding:**\n\nRead `${CLAUDE_SKILL_ROOT}/references/verify-prompt.md` for the prompt template. Substitute the finding's values into the `${...}` placeholders.\n\n**Process results:**\n\nParse the JSON from the subagent response and:\n- Write result to `data/verify/.json`\n- Append to `data/verified.jsonl` or `data/rejected.jsonl`\n- For verified findings, generate `findings/.md`:\n\n```markdown\n# ${TITLE}\n\n**ID**: ${FINDING_ID} | **Severity**: ${SEVERITY} | **Confidence**: ${CONFIDENCE}\n**Skill**: ${SKILL} | **File**: ${FILE_PATH}:${START_LINE}\n\n## Description\n${DESCRIPTION}\n\n## Verification\n**Verdict**: Verified (${VERIFICATION_CONFIDENCE})\n**Reasoning**: ${REASONING}\n**Code trace**: ${TRACE_NOTES}\n\n## Suggested Fix\n${FIX_DESCRIPTION}\n```diff\n${FIX_DIFF}\n```\n```\n\nUpdate manifest: set `phases.verify` to `\"complete\"`.\n\n**Report** to user after all verifications:\n\n```\n## Verification Complete\n\n**{verified}** verified, **{rejected}** rejected.\n\n### Verified Findings\n\n| # | Severity | Confidence | File | Title | Reasoning |\n|---|----------|------------|------|-------|-----------|\n| 1 | **HIGH** | high | `src/db/query.ts:42` | SQL injection in query builder | User input flows directly into... |\n...\n\n### Rejected ({rejected_count})\n\n- `{findingId}` {file}: {reasoning}\n...\n```\n\n---\n\n## Phase 3: Issue\n\nCreate a tracking issue that ties all PRs together and gives reviewers a single overview.\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/create_issue.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout. Save `issueUrl` and `issueNumber` for Phase 4.\n\n**Report** to user:\n\n```\n## Tracking Issue Created\n\n{issueUrl}\n```\n\n**On failure**: Show the error. Continue to Phase 4 (PRs can still be created without a tracking issue).\n\n---\n\n## Phase 4: Patch\n\nFor each verified finding, create a worktree, fix the code, and open a draft PR. Process findings **sequentially** (one at a time) since parallel subagents cross-contaminate worktrees.\n\n**Severity triage**: Patch HIGH and above. For MEDIUM, only patch findings from bug-detection skills (e.g., `code-review`, `security-review`). Skip LOW and INFO findings.\n\n**Step 0: Setup** (run once before the loop):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/index_prs.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout. Use `fileIndex` for dedup checks.\n\nDetermine the default branch and fetch latest so worktrees branch from current upstream:\n\n```bash\nDEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')\ngit fetch origin \"${DEFAULT_BRANCH}\"\n```\n\n**For each finding in `data/verified.jsonl`:**\n\nCheck if finding ID already exists in `data/patches.jsonl` (incrementality). If it does, skip.\n\n**Dedup check**: Use the file index from `index_prs.py` output to determine if an existing open PR already addresses the same issue.\n\n1. **File match**: Look up the finding's file path in the `fileIndex`. If no PR touches that file, no conflict; proceed to Step 1.\n2. **Chunk overlap**: If a PR does touch the same file, read its cached diff from `data/pr-diffs/.diff` and check whether the PR's changed hunks overlap with the finding's line range (startLine-endLine). Overlapping or adjacent hunks (within ~10 lines) indicate the same code region.\n3. **Same concern**: If the hunks overlap, compare the PR title and the finding title/description. Are they fixing the same kind of defect? A PR fixing an off-by-one error and a finding about a null check in the same function are different issues; both should proceed.\n\nSkip the finding only when there is both chunk overlap AND the PR addresses the same concern. Record it in `data/patches.jsonl` with `\"status\": \"existing\"` and `\"prUrl\"` pointing to the matching PR, then continue to the next finding.\n\n**Step 1: Create worktree**\n\n```bash\nBRANCH=\"warden-sweep/${RUN_ID}/${FINDING_ID}\"\nWORKTREE=\"${SWEEP_DIR}/worktrees/${FINDING_ID}\"\ngit worktree add \"${WORKTREE}\" -b \"${BRANCH}\" \"origin/${DEFAULT_BRANCH}\"\n```\n\nEach finding branches from the repo's default branch so PRs contain only the fix commit.\n\n**Step 2: Generate fix**\n\nLaunch a Task subagent (`subagent_type: \"general-purpose\"`) to apply the fix in the worktree. Read `${CLAUDE_SKILL_ROOT}/references/patch-prompt.md` for the prompt template. Substitute the finding's values and worktree path into the `${...}` placeholders.\n\n**Step 2b: Handle skipped findings**\n\nIf the subagent returned `\"status\": \"skipped\"` (not `\"applied\"`), do NOT proceed to Steps 3-4. Instead:\n1. Record the finding in `data/patches.jsonl` with `\"status\": \"error\"` and `\"error\": \"Subagent skipped: ${skipReason}\"`\n2. Clean up the worktree\n3. Continue to the next finding\n\n**Step 3: Find reviewers**\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/find_reviewers.py \"${FILE_PATH}\"\n```\n\n**Step 4: Create draft PR**\n\n```bash\ncd \"${WORKTREE}\" && git push -u origin HEAD:\"${BRANCH}\"\n```\n\nCreate the PR with a 1-2 sentence \"What\" summary based on the finding and fix, followed by the finding description and verification reasoning:\n\n```bash\nREVIEWERS=\"\"\n# If find_reviewers.py returned reviewers, build the flags\n# e.g., REVIEWERS=\"--reviewer user1 --reviewer user2\"\n\ngh pr create --draft \\\n --label \"warden\" \\\n --title \"fix: ${TITLE}\" \\\n --body \"$(cat <<'EOF'\n${FIX_WHAT_DESCRIPTION}\n\n${DESCRIPTION}\n\n${REASONING}\n\nAutomated fix for Warden finding ${FINDING_ID} (${SEVERITY}, detected by ${SKILL}).\n\n\nRef #${ISSUE_NUMBER}\n\n> This PR was auto-generated by a Warden Sweep (run ${RUN_ID}).\n> The finding has been validated through automated deep tracing,\n> but human confirmation is requested as this is batch work.\nEOF\n)\" ${REVIEWERS}\n```\n\nSave the PR URL.\n\n**Step 5: Record and cleanup**\n\nAppend to `data/patches.jsonl` (use `\"created\"` as status for successful PRs, not the subagent's `\"applied\"`):\n```json\n{\"findingId\": \"...\", \"prUrl\": \"https://...\", \"branch\": \"...\", \"reviewers\": [\"user1\", \"user2\"], \"filesChanged\": [\"...\"], \"status\": \"created|existing|error\"}\n```\n\nRemove the worktree:\n```bash\ncd \"$(git rev-parse --show-toplevel)\"\ngit worktree remove \"${WORKTREE}\" --force\n```\n\n**Error handling**: On failure at any step, write to `data/patches.jsonl` with `\"status\": \"error\"` and `\"error\": \"...\"`, clean up the worktree, and continue to the next finding.\n\nUpdate manifest: set `phases.patch` to `\"complete\"`.\n\n**Report** to user after all patches:\n\n```\n## PRs Created\n\n**{created}** created, **{skipped}** skipped (existing), **{failed}** failed.\n\n| # | Finding | PR | Status |\n|---|---------|-----|--------|\n| 1 | `security-review-a1b2c3d4` SQL injection in query builder | #142 | created |\n| 2 | `code-review-e5f6g7h8` Null pointer in handler | - | existing (#138) |\n...\n```\n\n---\n\n## Phase 5: Organize\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/organize.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout.\n\n**Report** to user:\n\n```\n## Sweep Complete\n\n| Metric | Count |\n|--------|-------|\n| Files scanned | {filesScanned} |\n| Findings verified | {verified} |\n| PRs created | {prsCreated} |\n| Security findings | {securityFindings} |\n\nFull report: `{summaryPath}`\n```\n\n**On failure**: Show the error and note which steps completed.\n\n---\n\n## Resuming a Sweep\n\nEach phase is incremental. To resume from where you left off:\n\n1. Check `data/manifest.json` to see which phases are complete\n2. For scan: pass `--sweep-dir` to `scan.py`\n3. For verify: existing `data/verify/.json` files are skipped\n4. For issue: `create_issue.py` is idempotent (skips if `issueUrl` in manifest)\n5. For patch: existing entries in `data/patches.jsonl` are skipped\n6. For organize: safe to re-run (idempotent)\n\n## Output Directory Structure\n\n```\n.warden/sweeps//\n summary.md # Stats, key findings, PR links\n findings/ # One markdown per verified finding\n .md\n security/ # Security-specific view\n index.jsonl # Security findings index\n .md # Copies of security findings\n data/ # Structured data for tooling\n manifest.json # Run metadata, phase state\n scan-index.jsonl # Per-file scan tracking\n all-findings.jsonl # Every finding from scan\n verified.jsonl # Findings that passed verification\n rejected.jsonl # Findings that failed verification\n patches.jsonl # Finding -> PR URL -> reviewers\n existing-prs.json # Cached open warden PRs\n report.json # Machine-readable summary\n verify/ # Individual verification results\n .json\n logs/ # Warden JSONL logs per file\n .jsonl\n pr-diffs/ # Cached PR diffs for dedup\n .diff\n```\n",".agents/skills/warden-sweep/references/patch-prompt.md":"Fix a verified code issue. You are working in a git worktree at: ${WORKTREE}\n\n## Finding\n- Title: ${TITLE}\n- File: ${FILE_PATH}:${START_LINE}\n- Description: ${DESCRIPTION}\n- Verification: ${REASONING}\n- Suggested Fix: ${FIX_DESCRIPTION}\n```diff\n${FIX_DIFF}\n```\n\n## Instructions\n\n### Step 1: Understand the code\nRead the file at ${WORKTREE}/${FILE_PATH}. Read at least 50 lines above and below the reported location. Trace callers and callees of the affected code using Grep/Glob to understand how it is used. Do NOT skip this step.\n\n### Step 2: Apply a minimal fix\nApply the smallest change that addresses the finding. If the suggested diff doesn't apply cleanly, adapt it while preserving intent. Do NOT refactor surrounding code, rename variables, add comments, or make any change beyond what the finding requires.\n\n### Step 3: Write tests\nWrite or update tests that verify the fix:\n- Follow existing test patterns (co-located files, same framework)\n- At minimum, write a test that would have caught the original bug\n- Test the specific edge case, not just the happy path\n\nOnly modify the fix target and its test file.\n\n### Step 4: Self-review\nBefore staging, run `git diff` in the worktree and review every changed line. Verify:\n1. The change addresses the specific finding described, not something else\n2. No unrelated code was modified (no drive-by cleanups, no formatting changes)\n3. Trace through changed code paths: does the fix introduce any new bug, null reference, type error, or broken import?\n4. Tests exercise the fix (the failure case), not just that the code runs\n\nIf ANY check fails, fix the problem before proceeding. If the suggested fix is wrong or would introduce a regression you cannot resolve, do NOT commit. Instead, skip to the output step and report why.\n\n### Step 5: Commit\nDo NOT run tests locally. CI will validate the changes.\n\nStage and commit with this exact message:\n\nfix: ${TITLE}\n\nWarden finding ${FINDING_ID}\nSeverity: ${SEVERITY}\n\nCo-Authored-By: Warden \n\n### Step 6: Output\nReturn ONLY valid JSON (no surrounding text). Use `\"status\": \"applied\"` if you committed a fix, or `\"status\": \"skipped\"` if you did not.\n\n```json\n{\n \"status\": \"applied\",\n \"filesChanged\": [\"src/example.ts\"],\n \"testFilesChanged\": [\"src/example.test.ts\"],\n \"selfReview\": \"Verified the fix addresses the null check and test covers the failure case\",\n \"skipReason\": null\n}\n```\n\nWhen skipping:\n```json\n{\n \"status\": \"skipped\",\n \"filesChanged\": [],\n \"testFilesChanged\": [],\n \"selfReview\": null,\n \"skipReason\": \"The suggested fix would introduce a regression in the error handling path\"\n}\n```\n",".agents/skills/warden-sweep/references/verify-prompt.md":"Verify a code analysis finding. Determine if this is a TRUE issue or a FALSE POSITIVE.\nDo NOT write or edit any files. Research only.\n\n## Finding\n- Title: ${TITLE}\n- Severity: ${SEVERITY} | Confidence: ${CONFIDENCE}\n- Skill: ${SKILL}\n- Location: ${FILE_PATH}:${START_LINE}-${END_LINE}\n- Description: ${DESCRIPTION}\n- Verification hint: ${VERIFICATION}\n\n## Instructions\n1. Read the file at the reported location. Examine at least 50 lines of surrounding context.\n2. Trace data flow to/from the flagged code using Grep/Glob.\n3. Check if the issue is mitigated elsewhere (guards, validation, try/catch upstream).\n4. Check if the issue is actually reachable in practice.\n\nReturn your verdict as JSON:\n{\n \"findingId\": \"${FINDING_ID}\",\n \"verdict\": \"verified\" or \"rejected\",\n \"confidence\": \"high\" or \"medium\" or \"low\",\n \"reasoning\": \"2-3 sentence explanation\",\n \"traceNotes\": \"What code paths you examined\"\n}\n",".agents/skills/warden/SKILL.md":"---\nname: warden\ndescription: Run Warden to analyze code changes before committing. Use when asked to \"run warden\", \"check my changes\", \"review before commit\", \"warden config\", \"warden.toml\", \"create a warden skill\", \"add trigger\", or any Warden-related local development task.\n---\n\nRun Warden to analyze code changes before committing.\n\n## References\n\nRead the relevant reference when the task requires deeper detail:\n\n| Document | Read When |\n|----------|-----------|\n| `${CLAUDE_SKILL_ROOT}/references/cli-reference.md` | Full option details, per-command flags, examples |\n| `${CLAUDE_SKILL_ROOT}/references/configuration.md` | Editing warden.toml, triggers, patterns, troubleshooting |\n| `${CLAUDE_SKILL_ROOT}/references/config-schema.md` | Exact field names, types, and defaults |\n| `${CLAUDE_SKILL_ROOT}/references/creating-skills.md` | Writing custom skills, remote skills, skill discovery |\n\n## Running Warden\n\n```bash\n# Analyze uncommitted changes (uses warden.toml triggers)\nwarden\n\n# Run a specific skill\nwarden --skill \n\n# Analyze specific files\nwarden src/auth.ts src/database.ts\n\n# Analyze changes from a git ref\nwarden main..HEAD\nwarden HEAD~3\n\n# Auto-apply suggested fixes\nwarden --fix\n\n# Fail on high-severity findings\nwarden --fail-on high\n```\n\nSet `WARDEN_ANTHROPIC_API_KEY` or log in via `claude login` before running.\n\n## Pre-Commit Workflow\n\nAfter making code changes and before committing:\n\n1. Run `warden` to analyze uncommitted changes\n2. Review the findings\n3. Fix issues Warden reports (or use `warden --fix` to auto-apply)\n4. Commit the changes\n\nRun Warden once to validate work. Do not loop re-running Warden on the same changes.\n\n## Reading Output\n\n**Severity levels:**\n- `high` - Must fix before merge\n- `medium` - Worth reviewing\n- `low` - Minor improvement\n\n**Exit codes:** `0` = no findings at or above fail threshold. `1` = findings at or above fail threshold.\n\n**Verbosity:** `-v` shows real-time findings. `-vv` shows debug info (tokens, latency). `-q` shows errors and summary only.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `warden` | Run analysis (default) |\n| `warden init` | Initialize warden.toml and GitHub workflow |\n| `warden add [skill]` | Add skill trigger to warden.toml |\n| `warden sync [remote]` | Update cached remote skills |\n| `warden setup-app` | Create GitHub App via manifest flow |\n\nFor full options and flags, read `${CLAUDE_SKILL_ROOT}/references/cli-reference.md`.\n",".agents/skills/warden/references/cli-reference.md":"# CLI Reference\n\n## Usage\n\n```\nwarden [command] [targets...] [options]\n```\n\nAnalyze code for security issues and code quality.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `(default)` | Run analysis on targets or using warden.toml skills |\n| `init` | Initialize warden.toml and GitHub workflow |\n| `add [skill]` | Add a skill to warden.toml |\n| `sync [remote]` | Update cached remote skills to latest |\n| `setup-app` | Create a GitHub App for Warden via manifest flow |\n\n## Targets\n\n| Target | Description |\n|--------|-------------|\n| `` | Analyze specific files (e.g., `src/auth.ts`) |\n| `` | Analyze files matching pattern (e.g., `\"src/**/*.ts\"`) |\n| `` | Analyze changes from git ref (e.g., `HEAD~3`, `main..feature`) |\n| `(none)` | Analyze uncommitted changes using warden.toml skills |\n\nAmbiguous targets (no path separator, no extension) are resolved by checking if a file exists at the path. Use `--git` to force git ref interpretation.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--skill ` | Run only this skill (default: run all built-in skills) |\n| `--config ` | Path to warden.toml (default: `./warden.toml`) |\n| `-m, --model ` | Model to use (fallback when not set in config) |\n| `--json` | Output results as JSON |\n| `-o, --output ` | Write full run output to a JSONL file |\n| `--fail-on ` | Exit with code 1 if findings >= severity |\n| `--report-on ` | Only show findings >= severity in output |\n| `--fix` | Automatically apply all suggested fixes |\n| `--parallel ` | Max concurrent skill executions (default: 4) |\n| `--git` | Force ambiguous targets to be treated as git refs |\n| `--offline` | Use cached remote skills without network access |\n| `-q, --quiet` | Errors and final summary only |\n| `-v, --verbose` | Show real-time findings and hunk details |\n| `-vv` | Show debug info (token counts, latencies) |\n| `--debug` | Enable debug output (equivalent to `-vv`) |\n| `--log` | Use log output (no animations, timestamped) |\n| `--color / --no-color` | Override color detection |\n| `-h, --help` | Show help message |\n| `-V, --version` | Show version number |\n\n## Per-Command Options\n\n**Init:**\n| Option | Description |\n|--------|-------------|\n| `-f, --force` | Overwrite existing files |\n\n**Add:**\n| Option | Description |\n|--------|-------------|\n| `--list` | List available skills |\n| `--remote ` | Remote repository (`owner/repo`, URL, or with `@sha`) |\n| `--force` | Bypass skill cache and fetch latest |\n\n**Sync:**\n| Option | Description |\n|--------|-------------|\n| `--remote ` | Specific remote to sync (default: all) |\n\n**Setup-app:**\n| Option | Description |\n|--------|-------------|\n| `--org ` | Create under organization (default: personal) |\n| `--port ` | Local server port (default: 3000) |\n| `--timeout ` | Callback timeout in seconds (default: 300) |\n| `--name ` | Custom app name (default: Warden) |\n| `--no-open` | Print URL instead of opening browser |\n\n## Severity Levels\n\nUsed in `--fail-on` and `--report-on`:\n\n| Level | Meaning |\n|-------|---------|\n| `high` | Must fix before merge |\n| `medium` | Worth reviewing |\n| `low` | Minor improvement |\n| `off` | Disable the threshold |\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | No findings at or above `--fail-on` threshold |\n| `1` | Findings at or above `--fail-on` threshold |\n\n## Examples\n\n```bash\n# Initialize\nwarden init\n\n# Interactive skill selection\nwarden add\nwarden add \nwarden add --list\n\n# Remote skills\nwarden add --remote / --skill \nwarden add --remote https://github.com// --skill \nwarden add --remote /@ --skill \n\n# Run analysis\nwarden # Skills from warden.toml\nwarden src/auth.ts # Specific file\nwarden src/auth.ts --skill \nwarden \"src/**/*.ts\" # Glob pattern\nwarden HEAD~3 # Git changes\nwarden HEAD~3 --skill \nwarden main..HEAD # Branch diff\n\n# Output control\nwarden --json\nwarden --fail-on high\nwarden -o results.jsonl\n\n# Fix mode\nwarden --fix\n\n# Cached skills only\nwarden --offline\nwarden sync # Update all unpinned remote skills\n\n# GitHub App setup\nwarden setup-app\nwarden setup-app --org myorg\n```\n",".agents/skills/warden/references/config-schema.md":"# warden.toml Configuration Schema\n\n## Top-Level Structure\n\n```toml\nversion = 1 # Required, must be 1\n\n[defaults] # Optional, inherited by all skills\n[[skills]] # Required, array of skill configs\n```\n\n## Defaults Section\n\n```toml\n[defaults]\nmodel = \"claude-sonnet-4-20250514\" # Default model\nmaxTurns = 50 # Max agentic turns per hunk\ndefaultBranch = \"main\" # Base branch for comparisons\nfailOn = \"high\" # Exit 1 if findings >= this severity\nreportOn = \"medium\" # Show findings >= this severity\nmaxFindings = 50 # Max findings to report (0 = unlimited)\nreportOnSuccess = false # Post report even with no findings\npaths = [\"src/**/*.ts\"] # Include only matching files\nignorePaths = [\"*.test.ts\"] # Exclude matching files\n\n[defaults.chunking]\nenabled = true # Enable hunk-based chunking\n\n[defaults.chunking.coalesce]\nenabled = true # Merge nearby hunks\nmaxGapLines = 30 # Lines between hunks to merge\nmaxChunkSize = 8000 # Max chars per chunk\n\n[[defaults.chunking.filePatterns]]\npattern = \"*.config.*\" # Glob pattern\nmode = \"whole-file\" # per-hunk | whole-file | skip\n```\n\n## Skills Section\n\n```toml\n[[skills]]\nname = \"skill-name\" # Required, unique identifier\nremote = \"owner/repo@sha\" # Optional, fetch skill from GitHub repo\npaths = [\"src/**\"] # Include only matching files\nignorePaths = [\"**/*.test.ts\"] # Exclude matching files\n\n# Optional overrides (inherit from defaults if not set)\nmodel = \"claude-opus-4-20250514\"\nmaxTurns = 100\nfailOn = \"high\"\nreportOn = \"medium\"\nmaxFindings = 20\nreportOnSuccess = true\n\n[[skills.triggers]]\ntype = \"pull_request\" # Required: pull_request | local | schedule\nactions = [\"opened\", \"synchronize\"] # Required for pull_request\n\n# Schedule-specific (only for type = \"schedule\")\n[[skills.triggers]]\ntype = \"schedule\"\n\n[skills.triggers.schedule]\nissueTitle = \"Daily Security Review\" # GitHub issue title for tracking\ncreateFixPR = true # Create PR with fixes\nfixBranchPrefix = \"security-fix\" # Branch name prefix\n```\n\n**Trigger types:**\n- `pull_request` - Triggers on PR events\n- `local` - Local CLI only (will not run in CI)\n- `schedule` - Cron schedule (GitHub Action only)\n\nAll skills run locally regardless of trigger type. Skills with no triggers run everywhere (wildcard). Use `type = \"local\"` for skills that should *only* run locally.\n\n**Actions (for pull_request):**\n- `opened`, `synchronize`, `reopened`, `closed`\n\n## Severity Values\n\nUsed in `failOn` and `reportOn`:\n- `high` - Must fix before merge\n- `medium` - Worth reviewing\n- `low` - Minor improvement\n- `off` - Disable threshold\n\n## Built-in Skip Patterns\n\nAlways skipped (cannot be overridden):\n- Package locks: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `Cargo.lock`, etc.\n- Minified files: `**/*.min.js`, `**/*.min.css`\n- Build artifacts: `dist/`, `build/`, `node_modules/`, `.next/`, `__pycache__/`\n- Generated code: `*.generated.*`, `*.g.ts`, `__generated__/`\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required) |\n| `WARDEN_MODEL` | Default model (lowest priority) |\n| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |\n| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |\n\n## Model Precedence (highest to lowest)\n\n1. Skill-level `model`\n2. `[defaults]` `model`\n3. CLI `--model` flag\n4. `WARDEN_MODEL` env var\n5. SDK default\n",".agents/skills/warden/references/configuration.md":"# Configuration (warden.toml)\n\nSee [config-schema.md](config-schema.md) for the complete schema reference.\n\n## Minimal Example\n\nThe `name` field references a skill you've created (via `warden add`) or defined in `.agents/skills//SKILL.md`. Use that same name everywhere — in config, CLI flags, and triggers.\n\n```toml\nversion = 1\n\n[defaults]\nmodel = \"claude-sonnet-4-20250514\"\n\n[[skills]]\nname = \"my-skill\" # matches .agents/skills/my-skill/SKILL.md\npaths = [\"src/**/*.ts\"]\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n## Skill Configuration\n\nSkills define what to analyze and when. Each skill requires a name. Triggers are optional — skills with no triggers run everywhere (PR, local, schedule). All skills run locally regardless of trigger type.\n\n```toml\n[[skills]]\nname = \"my-skill\"\npaths = [\"src/auth/**\", \"src/payments/**\"]\nfailOn = \"high\"\nreportOn = \"medium\"\nmaxFindings = 20\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Trigger types:** `pull_request`, `local` (local-only), `schedule` (CI-only)\n\n**Actions (pull_request):** `opened`, `synchronize`, `reopened`, `closed`\n\n## Common Patterns\n\n**Strict checks on critical files:**\n```toml\n[[skills]]\nname = \"my-skill\"\nmodel = \"claude-opus-4-20250514\"\nmaxTurns = 100\npaths = [\"src/auth/**\", \"src/payments/**\"]\nfailOn = \"high\"\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Skip test files:**\n```toml\n[[skills]]\nname = \"my-skill\"\npaths = [\"src/**/*.ts\"]\nignorePaths = [\"**/*.test.ts\", \"**/*.spec.ts\"]\n```\n\n**Whole-file analysis for configs:**\n```toml\n[defaults.chunking.filePatterns]\npattern = \"*.config.*\"\nmode = \"whole-file\"\n```\n\n## Model Precedence\n\nFrom highest to lowest priority:\n\n1. Skill-level `model`\n2. `[defaults]` `model`\n3. CLI `--model` flag\n4. `WARDEN_MODEL` env var\n5. SDK default\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required unless using Claude Code subscription) |\n| `WARDEN_MODEL` | Default model (lowest priority) |\n| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |\n| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |\n\n## Troubleshooting\n\n**No findings reported:**\n- Check `--report-on` threshold (default shows all)\n- Verify skill matches file types in `paths`\n- Use `-v` to see which files are being analyzed\n\n**Files being skipped:**\n- Built-in skip patterns: lock files, minified, `node_modules/`, `dist/`\n- Check `ignorePaths` in config\n- Use `-vv` to see skip reasons\n\n**Token/cost issues:**\n- Reduce `maxTurns` (default: 50)\n- Use chunking settings to control chunk size\n- Filter to relevant files with `paths`\n",".agents/skills/warden/references/creating-skills.md":"# Creating Skills\n\nSkills are markdown files that tell Warden what to look for. They follow the [agentskills.io](https://agentskills.io) specification.\n\n## Skill Discovery\n\nWarden searches these directories in order (first match wins):\n\n```\n.agents/skills/{name}/SKILL.md # Primary (recommended)\n.claude/skills/{name}/SKILL.md # Backup (Claude Code convention)\n```\n\n## SKILL.md Format\n\n```markdown\n---\nname: my-skill\ndescription: What this skill analyzes\nallowed-tools: Read Grep Glob\n---\n\n[Analysis instructions for the agent]\n\n## What to Look For\n- Specific issue type 1\n- Specific issue type 2\n\n## Output Format\nReport findings with severity, location, and suggested fix.\n```\n\n## Available Tools\n\n`Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Bash`, `Write`, `Edit`\n\nMost review skills only need `Read`, `Grep`, and `Glob` for exploring context.\n\n## Writing Checklist\n\n- One skill, one concern (\"security review\" not \"code quality\")\n- Clear criteria for what counts as an issue and at what severity\n- Actionable findings that include how to fix\n- Examples of good and bad code where helpful\n\n## Remote Skills\n\nSkills can be fetched from GitHub repositories:\n\n```bash\n# Add a remote skill\nwarden add --remote / --skill \n\n# Add with version pinning (recommended for reproducibility)\nwarden add --remote /@ --skill \n\n# List skills in a remote repo\nwarden add --remote / --list\n\n# Update all unpinned remote skills\nwarden sync\n\n# Update specific repo\nwarden sync /\n\n# Run with cached skills only (no network)\nwarden --offline\n```\n\n**Remote skill in warden.toml:**\n\n```toml\n[[skills]]\nname = \"my-skill\"\nremote = \"/@\"\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Cache location:** `~/.local/warden/skills/` (override with `WARDEN_STATE_DIR`)\n\n**Cache TTL:** 24 hours for unpinned refs (override with `WARDEN_SKILL_CACHE_TTL` in seconds)\n","AGENTS.md":"# Development Rules\n\n## Build & Test\n- `npm run build` - Build (wireit + tsup, ESM)\n- `npm run test` - Unit/integration tests (Vitest)\n- `npm run test:smoke` - Smoke tests (builds first, serial execution)\n- `npm run lint` / `npm run lint:fix` - ESLint\n- `npm run format` / `npm run format:check` - Prettier\n- `npm run typecheck` - TypeScript type checking (src + test config)\n\n## Architecture\nESM TypeScript project (`type: module`). Key layers:\n\n- `src/cli/` - CLI entrypoint, yargs wiring, daemon routing\n- `src/server/` - MCP stdio server, lifecycle, workflow/resource registration\n- `src/runtime/` - Config bootstrap, session state, tool catalog assembly\n- `src/core/manifest/` - YAML manifest loading, validation, tool module imports\n- `src/mcp/tools/` - Tool implementations grouped by workflow (mirrors `manifests/workflows/`)\n- `src/mcp/resources/` - MCP resource implementations\n- `src/integrations/` - External integrations (Xcode tools bridge)\n- `src/utils/` - Shared helpers (execution, logging, validation, responses)\n- `src/visibility/` - Tool/workflow exposure predicates\n- `src/daemon/` - Background daemon for persistent sessions\n- `src/rendering/` - Output rendering and formatting\n- `src/types/` - Shared type definitions\n\n## Contributing Workflow\n1. Create a branch from `main`\n2. Make changes following the conventions in this file\n3. Run the pre-commit checklist before committing:\n ```bash\n npm run lint:fix\n npm run typecheck\n npm run format\n npm run build\n npm test\n ```\n4. Update `CHANGELOG.md` under `## [Unreleased]`\n5. Update documentation if adding or modifying features\n6. Clone and test against example projects (e.g., `XcodeBuildMCP-iOS-Template`) when changes affect runtime behavior\n7. Push and create a pull request with a clear description\n8. Link any related issues\n\n## Code Quality\n- No `any` types unless absolutely necessary\n- Check node_modules for external API type definitions instead of guessing\n- **NEVER use inline imports** - no `await import(\"./foo.js\")`, no `import(\"pkg\").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.\n- NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead\n- Always ask before removing functionality or code that appears to be intentional\n- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.\n- Review the complete merge-base diff and trace changed or reused helper contracts, including error and sentinel returns, through callers, consumers, tests, and operational configuration.\n- Verify standard quality commands include every changed path and exercise exact entry points and argument variants; validate explicitly when they do not.\n- For asynchronous, workflow, or process-boundary changes, enumerate lifecycle states, retries, supersession, and race transitions; test terminal outcomes and missing or optional metadata.\n\n## Import Conventions\n- ESM with explicit `.ts` extensions in `src/` (tsup rewrites to `.js` at build)\n- No `.js` imports in `src/` (enforced by ESLint)\n- No barrel imports from `utils/index` - import from specific submodules (e.g., `src/utils/execution/index.ts`, `src/utils/logging/index.ts`)\n\n\n## Rendering and Streaming Contract\n- Streaming fragments are transient live-progress output only. They may be displayed while a tool is running, but MUST NOT provide final settled MCP/JSON/CLI text.\n- Final settled output MUST render from the final structured/domain result and next-step metadata. If final output needs data, add it to the final result type instead of reading it from fragments.\n- Streaming-capable renderers may observe fragment callbacks only for live progress. Fragment handling must not affect final structured output or final settled text.\n\n## Error Handling\n- Structured errors (domain results with `didError`) are for domain errors only: failures in the user's build/test/device/simulator workflow (compile errors, test failures, missing destinations, etc.).\n- System errors with the MCP server or CLI itself (invalid internal state, unresolvable configuration, infrastructure failures) must NOT be wrapped in structured domain results — let them surface as runtime tool errors so they are clearly distinguishable from workflow outcomes.\n\n## Test Conventions\n- Vitest with colocated `__tests__/` directories using `*.test.ts`\n- Snapshot tests (`*.snapshot.test.ts`) must only assert generated tool output against fixtures. Move helper, parser, schema, setup, or behavior assertions to non-snapshot unit/integration tests.\n- Smoke tests in `src/smoke-tests/__tests__/` (separate Vitest config, serial execution)\n- Use `vi.mock`/`vi.hoisted` for isolation; inject executors and mock file systems\n- MCP integration tests use `McpServer`, `InMemoryTransport`, and `Client`\n- External dependencies (command execution, file system) must use dependency injection via `createMockExecutor()` / `createMockFileSystemExecutor()` from `src/test-utils/`\n\n## Tool Development\n- Tool manifests in `manifests/tools/*.yaml` define `id`, `module`, `names.mcp` (snake_case), optional `names.cli` (kebab-case), predicates, and annotations\n- MCP `readOnlyHint` describes whether a tool mutates host/project state such as files, build artifacts, configuration, or external services. Simulator HID/UI actions that only tap, type, press, or gesture inside the simulator may remain `readOnlyHint: true`; do not flip them to `false` merely because app UI state changes.\n- Workflow manifests in `manifests/workflows/*.yaml` group tools and define exposure rules\n- Tool modules export a Zod `schema`, a pure `*Logic` function, and a `handler` built with `createTypedTool` or `createSessionAwareTool`\n- Resource modules export a `handler` (and a pure `*Logic` function); `uri`, `name`, `description`, and `mimeType` are declared in `manifests/resources/*.yaml`\n\n## Commands\n- NEVER commit unless user asks\n\n## GitHub\nWhen reading issues:\n- Always read all comments on the issue\n-\n## Tools\n- GitHub CLI for issues/PRs\n- CLI design note: do not rely on CLI session-default writes. CLI is intentionally deterministic for CI/scripting and should use explicit command arguments as the primary input surface.\n- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.\n- After modifying any skill source, run `npx skill-check ` and address all errors/warnings before handoff.\n- Before handoff, run the matching manual Warden review for high-risk changes: runtime/CLI/daemon boundaries → `mobilebuildmcp-runtime-boundary-review`; test infrastructure or harnesses → `mobilebuildmcp-test-boundary-review`; tool manifests, schemas, or contracts → `mobilebuildmcp-tool-contract-review`. Invoke only applicable skills with `warden --skill `.\n-\n## Multi-process filesystem state\n- MobileBuildMCP explicitly supports multiple concurrent MCP server, daemon, CLI, test, and helper processes for the same or different workspaces.\n- Shared filesystem state under `~/Library/Developer/MobileBuildMCP` must be multi-process safe.\n- Use workspace-key scoped directories for workspace-owned state.\n- Do not store runtime state under `~/.mobilebuildmcp`; `.mobilebuildmcp/config.yaml` is only project configuration.\n- Use shared lock and atomic-write helpers for mutable shared files.\n- Prefer one-record-per-file registries over shared aggregate files.\n- Cleanup must verify ownership before deleting shared artifacts.\n- Multi-process safety means concurrent processes must not corrupt or delete each other's state.\n It does not mean ephemeral runtime handles should become portable between invocation surfaces.\n- Keep runtime/session-scoped handles isolated unless the product explicitly defines a cross-process\n contract. For example, UI automation `elementRef` values from runtime snapshots are handles for\n the runtime/session that produced them, not durable IDs to share between separate MCP and CLI\n invocations.\n- User-facing artifact/log paths in final text or structured output must use `displayPath()` from `src/utils/build-preflight.ts`, so paths are cwd-relative when possible or `~/...` instead of absolute home paths. Keep stored files at their real absolute paths; only normalize response/display values.\n\n## Style\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n\n## Docs\n- Do not commit transient investigation notes, prompt exports, or scratch analysis docs after the work is complete.\n- If an investigation leaves unresolved follow-up work, move it to a GitHub issue instead of preserving the transient doc in the branch.\n- Structured output JSON schemas are auto-published to the website/public schema mirror when merged; do not manually update public schema copies unless explicitly asked.\n\n### Changelog\nLocation: `CHANGELOG.md`\n\n#### Format\nUse these sections under `## [Unreleased]`:\n- `### Added` - New features\n- `### Changed` - Changes to existing functionality\n- `### Fixed` - Bug fixes\n- `### Removed` - Removed features\n-\n#### Rules\n- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist\n- New entries ALWAYS go under `## [Unreleased]` section\n- Append to existing subsections (e.g., `### Fixed`), do not create duplicates\n- NEVER modify already-released version sections (e.g., `## [0.12.2]`)\n- Each version section is immutable once released\n- NEVER update snapshot fixtures unless asked to do so, these are integration tests, on failure assume code is wrong before questioning the fixture\n-\n#### Attribution\n- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/MobileBuildMCP/issues/123))`\n- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/MobileBuildMCP/pull/456) by [@username](https://github.com/username))`\n\n## Test Execution Rules\n- **NEVER run the snapshot or smoke test suites without explicit user permission.** They are expensive (~7 min baseline, spawn real `xcodebuild`/`simctl`/`devicectl` processes and can wedge). This covers `npm run test:snapshot`, `npm run test:smoke`, and any direct `vitest run --config vitest.snapshot.config.ts` / `vitest.smoke.config.ts` invocation. Ask first, then run only if the user agrees.\n- The default unit suite (`npm test` / `vitest run`), `npm run typecheck`, `npm run lint`, and `npm run build` are cheap and may be run freely without asking.\n- When running long test suites (snapshot tests, smoke tests), ALWAYS write full output to a log file and read it afterwards. NEVER pipe through `tail` or `grep` directly — that loses output you may need to debug failures.\n- Pattern: `DEVICE_ID=... npm run test:snapshot 2>&1 | tee /tmp/snapshot-results.txt` then read `/tmp/snapshot-results.txt` with the native read tool.\n- If you need a summary, read the log file and grep/filter it — the full output is always preserved.\n- Snapshot test command: `DEVICE_ID= npm run test:snapshot`\n- **Snapshot suite expected duration**: ~7 min baseline (measured at 423s). Anything longer than ~10 min should be treated as a likely hang, not a slow run.\n - Do NOT just kill the run — first inspect the process tree (`ps -ef | grep -E \"vitest|xcodebuild|simctl|devicectl\"`) to identify what's stuck.\n - Common hang causes: locked physical device, stale simulator state, `devicectl diagnose` waiting for password, orphaned daemon process.\n - Capture what you find before killing, so the root cause can be fixed rather than papered over.\n- If physical-device snapshot tests hang after the final test summary, the likely cause is Apple post-failure diagnostics invoking `devicectl diagnose`, which may prompt for a macOS password and wedge in automated runs.\n- When asked to review changes or test failures, focus on regressions: behavior changes caused by the branch. Do not treat known/acceptable test flakes, environment setup issues, or nondeterministic tool output churn as regressions unless explicitly asked to investigate them.\n\n## **CRITICAL** Tool Usage Rules **CRITICAL**\n- NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.\n- You MUST read every file you modify in full before editing.\n","CLAUDE.md":"# Development Rules\n\n## Code Quality\n- No `any` types unless absolutely necessary\n- Check node_modules for external API type definitions instead of guessing\n- **NEVER use inline imports** - no `await import(\"./foo.js\")`, no `import(\"pkg\").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.\n- NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead\n- Always ask before removing functionality or code that appears to be intentional\n- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.\n- Review the complete merge-base diff and trace changed or reused helper contracts, including error and sentinel returns, through callers, consumers, tests, and operational configuration.\n- Verify standard quality commands include every changed path and exercise exact entry points and argument variants; validate explicitly when they do not.\n- For asynchronous, workflow, or process-boundary changes, enumerate lifecycle states, retries, supersession, and race transitions; test terminal outcomes and missing or optional metadata.\n\n## Test Conventions\n- Snapshot tests (`*.snapshot.test.ts`) must only assert generated tool output against fixtures. Move helper, parser, schema, setup, or behavior assertions to non-snapshot unit/integration tests.\n\n## Commands\n- NEVER commit unless user asks\n\n## GitHub\nWhen reading issues:\n- Always read all comments on the issue\n-\n## Tools\n- GitHub CLI for issues/PRs\n- MCP `readOnlyHint` describes whether a tool mutates host/project state such as files, build artifacts, configuration, or external services. Simulator HID/UI actions that only tap, type, press, or gesture inside the simulator may remain `readOnlyHint: true`; do not flip them to `false` merely because app UI state changes.\n- CLI design note: do not rely on CLI session-default writes. CLI is intentionally deterministic for CI/scripting and should use explicit command arguments as the primary input surface.\n- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.\n- After modifying any skill source, run `npx skill-check ` and address all errors/warnings before handoff.\n- Before handoff, run the matching manual Warden review for high-risk changes: runtime/CLI/daemon boundaries → `mobilebuildmcp-runtime-boundary-review`; test infrastructure or harnesses → `mobilebuildmcp-test-boundary-review`; tool manifests, schemas, or contracts → `mobilebuildmcp-tool-contract-review`. Invoke only applicable skills with `warden --skill `.\n-\n## Multi-process filesystem state\n- MobileBuildMCP explicitly supports multiple concurrent MCP server, daemon, CLI, test, and helper processes for the same or different workspaces.\n- Shared filesystem state under `~/Library/Developer/MobileBuildMCP` must be multi-process safe.\n- Use workspace-key scoped directories for workspace-owned state.\n- Do not store runtime state under `~/.mobilebuildmcp`; `.mobilebuildmcp/config.yaml` is only project configuration.\n- Use shared lock and atomic-write helpers for mutable shared files.\n- Prefer one-record-per-file registries over shared aggregate files.\n- Cleanup must verify ownership before deleting shared artifacts.\n- User-facing artifact/log paths in final text or structured output must use `displayPath()` from `src/utils/build-preflight.ts`, so paths are cwd-relative when possible or `~/...` instead of absolute home paths. Keep stored files at their real absolute paths; only normalize response/display values.\n\n## Style\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n\n## Docs\n- Do not commit transient investigation notes, prompt exports, or scratch analysis docs after the work is complete.\n- If an investigation leaves unresolved follow-up work, move it to a GitHub issue instead of preserving the transient doc in the branch.\n- Structured output JSON schemas are auto-published to the website/public schema mirror when merged; do not manually update public schema copies unless explicitly asked.\n\n### Changelog\nLocation: `CHANGELOG.md`\n\n#### Format\nUse these sections under `## [Unreleased]`:\n- `### Added` - New features\n- `### Changed` - Changes to existing functionality\n- `### Fixed` - Bug fixes\n- `### Removed` - Removed features\n-\n#### Rules\n- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist\n- New entries ALWAYS go under `## [Unreleased]` section\n- Append to existing subsections (e.g., `### Fixed`), do not create duplicates\n- NEVER modify already-released version sections (e.g., `## [0.12.2]`)\n- Each version section is immutable once released\n- NEVER update snapshot fixtures unless asked to do so, these are integration tests, on failure assume code is wrong before questioning the fixture\n-\n#### Attribution\n- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/MobileBuildMCP/issues/123))`\n- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/MobileBuildMCP/pull/456) by [@username](https://github.com/username))`\n\n\n## Rendering and Streaming Contract\n- Streaming fragments are transient live-progress output only. They may be displayed while a tool is running, but MUST NOT provide final settled MCP/JSON/CLI text.\n- Final settled output MUST render from the final structured/domain result and next-step metadata. If final output needs data, add it to the final result type instead of reading it from fragments.\n- Streaming-capable renderers may observe fragment callbacks only for live progress. Fragment handling must not affect final structured output or final settled text.\n\n## Error Handling\n- Structured errors (domain results with `didError`) are for domain errors only: failures in the user's build/test/device/simulator workflow (compile errors, test failures, missing destinations, etc.).\n- System errors with the MCP server or CLI itself (invalid internal state, unresolvable configuration, infrastructure failures) must NOT be wrapped in structured domain results — let them surface as runtime tool errors so they are clearly distinguishable from workflow outcomes.\n\n## Test Execution Rules\n- **NEVER run the snapshot or smoke test suites without explicit user permission.** They are expensive (~7 min baseline, spawn real `xcodebuild`/`simctl`/`devicectl` processes and can wedge). This covers `npm run test:snapshot`, `npm run test:smoke`, and any direct `vitest run --config vitest.snapshot.config.ts` / `vitest.smoke.config.ts` invocation. Ask first, then run only if the user agrees.\n- The default unit suite (`npm test` / `vitest run`), `npm run typecheck`, `npm run lint`, and `npm run build` are cheap and may be run freely without asking.\n- When running long test suites (snapshot tests, smoke tests), ALWAYS write full output to a log file and read it afterwards. NEVER pipe through `tail` or `grep` directly — that loses output you may need to debug failures.\n- Pattern: `DEVICE_ID=... npm run test:snapshot 2>&1 | tee /tmp/snapshot-results.txt` then read `/tmp/snapshot-results.txt` with the native read tool.\n- If you need a summary, read the log file and grep/filter it — the full output is always preserved.\n- Snapshot test command: `DEVICE_ID= npm run test:snapshot`\n- **Snapshot suite expected duration**: ~7 min baseline (measured at 423s). Anything longer than ~10 min should be treated as a likely hang, not a slow run.\n - Do NOT just kill the run — first inspect the process tree (`ps -ef | grep -E \"vitest|xcodebuild|simctl|devicectl\"`) to identify what's stuck.\n - Common hang causes: locked physical device, stale simulator state, `devicectl diagnose` waiting for password, orphaned daemon process.\n - Capture what you find before killing, so the root cause can be fixed rather than papered over.\n- When asked to review changes or test failures, focus on regressions: behavior changes caused by the branch. Do not treat known/acceptable test flakes, environment setup issues, or nondeterministic tool output churn as regressions unless explicitly asked to investigate them.\n\n## **CRITICAL** Tool Usage Rules **CRITICAL**\n- NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.\n- You MUST read every file you modify in full before editing.\n","example_projects/iOS/.cursor/rules/errors.mdc":"---\ndescription: \nglobs: \nalwaysApply: true\n---\nPlease don't fix any code errors unless reported by MobileBuildMCP server tool responses.","skills/mobilebuildmcp-cli/SKILL.md":"---\nname: mobilebuildmcp-cli\ndescription: Official skill for the MobileBuildMCP CLI. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).\n---\n\n# MobileBuildMCP CLI\n\nUse MobileBuildMCP tools via the `mobilebuildmcp` executable instead of raw `xcodebuild`, `xcrun`, or `simctl`.\n\n## Step 1: Ensure the CLI Exists\n\nCheck availability:\n```bash\nmobilebuildmcp --help\n```\n\nIf missing, install with one of:\n```bash\nbrew tap getsentry/xcodebuildmcp\nbrew install mobilebuildmcp\n```\n\n```bash\nnpm install -g mobilebuildmcp@latest\n```\n\nRe-check after install:\n```bash\nmobilebuildmcp --help\n```\n\n## Step 2: Use Help-First Discovery\n\nDiscover workflows and arguments from the CLI itself:\n```bash\nmobilebuildmcp --help\nmobilebuildmcp tools\nmobilebuildmcp --help\nmobilebuildmcp --help\n```\n\nUse this discovery path instead of memorizing static tool lists.\n\n## Step 3: Keep Execution Minimal\n\n- Choose the smallest command sequence that satisfies the request.\n- Prefer direct workflow commands over manual multi-step chains unless explicitly requested.\n- For simulator run intent, prefer the combined `build-and-run` command.\n- Do not chain `build` then `build-and-run` unless explicitly requested.\n\n## Capability Overview\n\n`mobilebuildmcp` supports:\n- simulator and device build/test/run\n- debugging and log capture\n- UI automation\n- project discovery and scaffolding\n- session defaults and workflow configuration\n\n## Exit Criteria\n\n- CLI presence is verified or installation steps are provided.\n- Commands are discovered via `--help` / `tools`.\n- Session defaults are checked before first build/run/test action.\n","skills/mobilebuildmcp/SKILL.md":"---\nname: mobilebuildmcp\ndescription: Official skill for MobileBuildMCP. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).\n---\n\n# MobileBuildMCP\n\nUse MobileBuildMCP tools instead of raw `xcodebuild`, `xcrun`, or `simctl`.\n\nCapabilities:\n- Session defaults: Configure project, scheme, simulator, and device defaults to avoid repetitive parameters\n- Project discovery: Find Xcode projects/workspaces, list schemes, inspect build settings\n- Simulator workflows: Build, run, test, install, and launch apps on iOS simulators; manage simulator state (boot, erase, location, appearance)\n- Device workflows: Build, test, install, and launch apps on physical devices with code signing\n- macOS workflows: Build, run, and test macOS applications\n- Log capture: Stream and capture logs from simulators and devices\n- LLDB debugging: Attach debugger, set breakpoints, inspect stack traces and variables, execute LLDB commands\n- UI automation: Capture screenshots, inspect view hierarchy with coordinates, perform taps/swipes/gestures, type text, press hardware buttons\n- SwiftPM: Build, run, test, and manage Swift Package Manager projects\n- Project scaffolding: Generate new iOS/macOS project templates\n\nOnly simulator workflow tools are enabled by default. If capabilities like device, macOS, debugging, or UI automation are not available, the user must configure MobileBuildMCP to enable them. See https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/configuration.mdx for workflow configuration.\n\n## Step 1: Establish Session Context\n\n- Call `session_show_defaults` before the first build/run/test action in a session.\n- Use `discover_projs` only when defaults show missing or incorrect project/workspace context.\n- Do not run discovery speculatively or in parallel with `session_show_defaults`.\n- For simulator run intent, prefer the combined build-and-run tool instead of separate build then run calls.\n- Do not chain build-only then build-and-run unless the user explicitly requests both.\n\n## Step 2: Understand Workflow-Scoped Tool Availability\n\n- Not all tools are enabled by default; tool availability depends on enabled workflows.\n- If a tool is expected but missing, check enabled workflows first.\n- Update enabled workflows in `.mobilebuildmcp/config.yaml`, then ask user to reload/restart the session to surface refreshes.\n\n## Step 3: Report Context Clearly\n\n- Return the active defaults context used for execution (project/workspace, scheme, simulator/device).\n- For failures, include the exact failing step and the next actionable command/tool call.\n"},"files":{".agents/skills/mobilebuildmcp-docs-command-review/SKILL.md":"---\nname: mobilebuildmcp-docs-command-review\ndescription: Use when reviewing MobileBuildMCP changelog CLI command references for invalid current guidance while allowing historical migration examples.\nallowed-tools: Read Grep Glob\n---\n\n# MobileBuildMCP Docs Command Review\n\nReview changed changelog entries for CLI command references that would mislead users or agents.\n\n## What to inspect\n\n- `CHANGELOG.md`\n- `manifests/tools/*.yaml` and `manifests/workflows/*.yaml` when you need to verify current CLI workflow/tool names\n- `src/cli/**` only when command wiring is unclear from manifests\n\n## Issue criteria\n\nReport a finding only when a command reference is presented as current guidance and appears invalid for the current CLI surface.\n\n### High severity\n\n- A changelog bullet, example, or migration instruction tells users to run a removed or invalid `mobilebuildmcp` command as the current path.\n- A Breaking change mentions a removed command but does not give a valid replacement.\n- A command reference uses the wrong workflow/tool pairing in a way a user or agent would likely copy.\n\n### Medium severity\n\n- A command reference is ambiguous enough that users may not know whether it is historical or current.\n- A migration example gives the right replacement but does not clearly label the old command as \"Before\", \"old\", \"removed\", or equivalent.\n\n## Explicitly allowed\n\nDo not report removed commands when they are clearly historical context, especially in:\n\n- Breaking-change migration sections\n- \"Before\" examples paired with valid \"After\" examples\n- Already-released changelog sections describing past behavior\n\nExample that should not be reported:\n\n```markdown\nBefore:\nmobilebuildmcp logging start-sim-log-cap\n\nAfter:\nmobilebuildmcp simulator build-and-run\n```\n\n## Output\n\nFor each finding, include:\n\n- Severity\n- File and line\n- The command reference\n- Why it reads as current guidance\n- Suggested replacement wording or command\n\nIf all command references are historical or valid, report no findings.\n",".agents/skills/mobilebuildmcp-docs-release-review/SKILL.md":"---\nname: mobilebuildmcp-docs-release-review\ndescription: Use when reviewing MobileBuildMCP documentation, CLI command references, website manifest generation, changelog, release notes, and release script changes.\n---\n\n# MobileBuildMCP Docs and Release Review\n\nReview guardrails for documentation, generated references, and release flow consistency.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `README.md`\n- `CHANGELOG.md` when present\n- `scripts/build-website-manifest.mjs`\n- `scripts/generate-github-release-notes.mjs`\n- `scripts/release.sh`\n- `package.json`\n- `xcodebuildmcp.com/app/docs/_content/**`\n\n## Guardrails\n\n- CLI examples match generated CLI catalog/commands.\n- Docs do not reference unavailable tools or workflows.\n- User-facing behavior changes include changelog updates.\n- Release notes derive from a valid changelog section.\n- README install snippets align with release script tag replacement.\n- Website manifest generation preserves expected normalized fields.\n- Docs explain runtime/contracts without deprecated patterns.\n- Keep docs-only work from introducing product behavior changes.\n- CLI command references in changelog entries are reviewed by `mobilebuildmcp-docs-command-review`.\n\n## Validation\n\n- `npm run build`\n- Release notes check when touched:\n - `node scripts/generate-github-release-notes.mjs --version --changelog CHANGELOG.md`\n- `npx skill-check .agents/skills/mobilebuildmcp-docs-release-review`\n",".agents/skills/mobilebuildmcp-packaging-resource-review/SKILL.md":"---\nname: mobilebuildmcp-packaging-resource-review\ndescription: Use when reviewing MobileBuildMCP packaging, resource-root, build artifact, bundled AXe, schema, manifest, and portable macOS distribution changes.\n---\n\n# MobileBuildMCP Packaging and Resource Review\n\nReview guardrails for package/build/resource integrity and portable distribution.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `package.json`\n- `scripts/copy-build-assets.js`\n- `scripts/package-macos-portable.sh`\n- `scripts/build-website-manifest.mjs`\n- `schemas/**`\n- `manifests/**`\n- `skills/**`\n- `bundled/**` when present\n- Resource-root utilities when touched\n\n## Guardrails\n\n- Published package `files` includes required runtime resources.\n- Portable package includes `build`, `manifests`, `bundled`, `skills`, `package.json`, and production dependencies.\n- AXe binary/framework expectations remain verified.\n- Wrapper scripts preserve `MOBILEBUILDMCP_RESOURCE_ROOT` and `DYLD_FRAMEWORK_PATH`.\n- Schemas and manifests stay available in installed and portable layouts.\n- Do not assume build outputs exist before `npm run build`.\n- Avoid network-dependent packaging behavior without verification/checksums.\n\n## Validation\n\n- `npm run build`\n- Packaging-specific when touched:\n - `npm run package:macos -- --help` (if supported)\n - `npm run verify:portable` after artifact creation\n- `npx skill-check .agents/skills/mobilebuildmcp-packaging-resource-review`\n",".agents/skills/mobilebuildmcp-rendering-streaming-review/SKILL.md":"---\nname: mobilebuildmcp-rendering-streaming-review\ndescription: Use when reviewing MobileBuildMCP rendering, streaming fragment, next-step, and CLI output mode changes for boundary violations.\n---\n\n# MobileBuildMCP Rendering and Streaming Review\n\nReview guardrails for rendering boundaries, streaming fragments, and output modes.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/rendering/**`\n- `src/types/domain-fragments.ts`\n- `src/types/runtime-status.ts`\n- `src/runtime/tool-invoker.ts`\n- `src/runtime/__tests__/tool-invoker.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/architecture-rendering-output.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-tool-lifecycle.mdx`\n- `xcodebuildmcp.com/app/docs/_content/output-formats.mdx`\n\n## Guardrails\n\n- Tool handlers do not branch on CLI vs MCP output mode.\n- Fragments represent progress, not final contract data.\n- Final structured output remains canonical.\n- Do not invent `json`/`jsonl` render strategies.\n- Streaming tools emit typed fragments and one final structured result.\n- Non-streaming tools do not emit unnecessary fragments.\n- Keep `ctx.emit` and xcodebuild pipeline `emitFragment` contexts separate.\n- Keep next-step rendering in runtime/rendering boundary.\n\n## Validation\n\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npm run test:snapshots`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-rendering-streaming-review`\n",".agents/skills/mobilebuildmcp-runtime-boundary-review/SKILL.md":"---\nname: mobilebuildmcp-runtime-boundary-review\ndescription: Use when reviewing MobileBuildMCP runtime boundary changes across MCP, direct CLI invocation, daemon-routed tools, and Xcode IDE bridge routing.\n---\n\n# MobileBuildMCP Runtime Boundary Review\n\nReview guardrails for runtime routing and invocation boundaries.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/runtime/tool-catalog.ts`\n- `src/runtime/tool-invoker.ts`\n- `src/runtime/types.ts`\n- `src/cli/**`\n- `src/daemon/**`\n- `manifests/tools/*.yaml`\n- `manifests/workflows/*.yaml`\n- `xcodebuildmcp.com/app/docs/_content/architecture-runtime-boundaries.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-manifest-visibility.mdx`\n\n## Guardrails\n\n- MCP, CLI, and daemon paths use shared handlers.\n- Stateful CLI tools route through daemon only when `routing.stateful` requires it.\n- Do not treat daemon as a third manifest availability mode.\n- Dynamic Xcode IDE tools keep daemon routing semantics.\n- Catalog filtering respects availability, workflow selection, and predicates.\n- Runtime failures surface via runtime/rendering status and fragments.\n- Avoid silent fallbacks and parallel invocation paths.\n\n## Validation\n\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-runtime-boundary-review`\n",".agents/skills/mobilebuildmcp-snapshot-fixture-review/SKILL.md":"---\nname: mobilebuildmcp-snapshot-fixture-review\ndescription: Use when reviewing MobileBuildMCP snapshot fixture changes for MCP, CLI, and JSON output contract integrity.\n---\n\n# MobileBuildMCP Snapshot Fixture Review\n\nReview guardrails for fixture and snapshot contract integrity.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/snapshot-tests/__fixtures__/**`\n- `src/snapshot-tests/contracts.ts`\n- `src/snapshot-tests/fixture-io.ts`\n- `src/snapshot-tests/__tests__/fixture-io.test.ts`\n- `src/snapshot-tests/__tests__/json-normalize.test.ts`\n- `src/snapshot-tests/__tests__/json-fixture-schema.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/testing.mdx`\n\n## Guardrails\n\n- Fixture updates map to intentional behavior changes.\n- Do not update fixtures only to make tests pass.\n- MCP, CLI, and JSON fixture updates stay aligned.\n- JSON fixtures preserve stable structured output envelopes.\n- Volatile values are normalized in code, not patched ad hoc in fixtures.\n- Missing fixtures are generated through the snapshot update flow.\n- Verify project-defined normalization sentinels in normalization code and tests before reporting\n them as implausible fixture values. In particular, `99999` is an intentional sentinel for\n volatile UI capture counts.\n- Group every occurrence of the same root cause into one finding and list the affected fixtures.\n Do not emit separate findings for equivalent CLI, MCP, text, or JSON drift.\n- Do not repeat a finding that is already resolved by the current diff.\n\n## Review limits\n\n- Review the changed fixtures and the directly relevant normalization or contract code only.\n- Do not run snapshot or smoke suites as part of an automated PR review.\n- Prefer one high-confidence cross-fixture finding over multiple speculative discrepancies.\n",".agents/skills/mobilebuildmcp-structured-output-review/SKILL.md":"---\nname: mobilebuildmcp-structured-output-review\ndescription: Use when reviewing MobileBuildMCP structured output schema changes, schema versioning, manifest outputSchema metadata, and JSON fixture compatibility.\n---\n\n# MobileBuildMCP Structured Output Review\n\nReview guardrails for structured output schema correctness and compatibility.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `schemas/structured-output/**`\n- `src/core/structured-output-schema.ts`\n- `src/core/__tests__/structured-output-schema.test.ts`\n- `src/snapshot-tests/__fixtures__/json/**`\n- `src/snapshot-tests/__tests__/json-fixture-schema.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/schema-versioning.mdx`\n- `xcodebuildmcp.com/app/docs/_content/output-formats.mdx`\n\n## Guardrails\n\n- `schema` uses `mobilebuildmcp.output.` format.\n- `schemaVersion` uses integer strings only.\n- Breaking schema changes create a new versioned schema file.\n- Published schema versions are not removed or mutated incompatibly.\n- Manifest `outputSchema` matches emitted `ctx.structuredOutput` payload.\n- JSON fixtures validate against current schema contracts.\n- `$ref` usage remains compatible with bundling in `structured-output-schema.ts`.\n\n## Validation\n\n- `npm run test:schema-fixtures`\n- `npm test -- src/core/__tests__/structured-output-schema.test.ts`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-structured-output-review`\n",".agents/skills/mobilebuildmcp-test-boundary-review/SKILL.md":"---\nname: mobilebuildmcp-test-boundary-review\ndescription: Use when reviewing MobileBuildMCP tests for correct unit, snapshot, schema, smoke, and external process boundaries.\n---\n\n# MobileBuildMCP Test Boundary Review\n\nReview guardrails for test isolation, scope, and contract validation.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/**/__tests__/**`\n- `src/test-utils/**`\n- `src/snapshot-tests/**`\n- `scripts/**/__tests__/**`\n- `package.json`\n- `xcodebuildmcp.com/app/docs/_content/testing.mdx`\n- `xcodebuildmcp.com/app/docs/_content/contributing.mdx`\n\n## Guardrails\n\n- Unit tests inject command/filesystem/external dependencies.\n- Unit tests do not call real `xcodebuild`, `xcrun`, AXe, devices, or simulators.\n- Prefer testing logic/executor functions over handler wrappers unless testing runtime integration.\n- Use existing mock executor helpers.\n- Treat snapshot updates as contract changes requiring review.\n- Do not add fake e2e/snapshot state to force test success.\n- Avoid unsafe TypeScript suppressions.\n\n## Validation\n\n- Run targeted Vitest command for touched tests.\n- `npm test`\n- `npm run typecheck`\n- If fixtures/schemas changed: `npm run test:snapshots` and `npm run test:schema-fixtures`\n- `npx skill-check .agents/skills/mobilebuildmcp-test-boundary-review`\n",".agents/skills/mobilebuildmcp-tool-contract-review/SKILL.md":"---\nname: mobilebuildmcp-tool-contract-review\ndescription: Use when reviewing MobileBuildMCP tool contract changes across implementation, manifests, workflow membership, output schema metadata, and next-step templates.\n---\n\n# MobileBuildMCP Tool Contract Review\n\nReview guardrails for tool contract changes across implementation, manifests, and workflow exposure.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/mcp/tools/**`\n- `manifests/tools/*.yaml`\n- `manifests/workflows/*.yaml`\n- `src/core/manifest/schema.ts`\n- `src/runtime/tool-catalog.ts`\n- `src/runtime/types.ts`\n- `xcodebuildmcp.com/app/docs/_content/tool-authoring.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-manifest-visibility.mdx`\n\n## Guardrails\n\n- Manifest `id` matches filename.\n- Manifest `module` points to implementation path without extension.\n- Tool module exports named `schema` and `handler`.\n- `names.mcp` remains globally unique.\n- `names.cli` stays workflow-local and consistent with CLI docs/fixtures.\n- Tool appears in at least one workflow unless intentionally hidden by availability.\n- `outputSchema` is present for tools that set `ctx.structuredOutput`.\n- `nextSteps.toolId` references existing manifest tool IDs.\n- Avoid parallel legacy paths or duplicate implementation paths.\n\n## Validation\n\n- `npm run typecheck`\n- `npm test -- src/core/manifest/__tests__/schema.test.ts`\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npx skill-check .agents/skills/mobilebuildmcp-tool-contract-review`\n",".agents/skills/warden-sweep/SKILL.md":"---\nname: warden-sweep\ndescription: Full-repository code sweep. Scans every file with warden, verifies findings via deep tracing, creates draft PRs for validated issues. Use when asked to \"sweep the repo\", \"scan everything\", \"find all bugs\", \"full codebase review\", \"batch code analysis\", or run warden across the entire repository.\ndisable-model-invocation: true\n---\n\n# Warden Sweep\n\nFull-repository code sweep: scan every file, verify findings with deep tracing, create draft PRs for validated issues.\n\n**Requires**: `warden`, `gh`, `git`, `jq`, `uv`\n\n**Important**: Run all scripts from the repository root using `${CLAUDE_SKILL_ROOT}`. Output goes to `.warden/sweeps//`.\n\n## Bundled Scripts\n\n### `scripts/scan.py`\n\nRuns setup and scan in one call: generates run ID, creates sweep dir, checks deps, creates `warden` label, enumerates files, runs warden per file, extracts findings.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py [file ...]\n --sweep-dir DIR # Resume into existing sweep dir\n```\n\n### `scripts/index_prs.py`\n\nFetches open warden-labeled PRs, builds file-to-PR dedup index, caches diffs for overlapping PRs.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/index_prs.py \n```\n\n### `scripts/create_issue.py`\n\nCreates a GitHub tracking issue summarizing sweep results. Run after verification, before patching.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/create_issue.py \n```\n\n### `scripts/organize.py`\n\nTags security findings, labels security PRs, updates finding reports with PR links, posts final results to tracking issue, generates summary report, finalizes manifest.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/organize.py \n```\n\n### `scripts/extract_findings.py`\n\nParses warden JSONL log files and extracts normalized findings. Called automatically by `scan.py`.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/extract_findings.py -o \n```\n\n### `scripts/generate_report.py`\n\nBuilds `summary.md` and `report.json` from sweep data. Called automatically by `organize.py`.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/generate_report.py \n```\n\n### `scripts/find_reviewers.py`\n\nFinds top 2 git contributors for a file (last 12 months).\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/find_reviewers.py \n```\n\nReturns JSON: `{\"reviewers\": [\"user1\", \"user2\"]}`\n\n---\n\n## Phase 1: Scan\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py\n```\n\nTo resume a partial scan:\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py --sweep-dir .warden/sweeps/\n```\n\nParse the JSON stdout. Save `runId` and `sweepDir` for subsequent phases.\n\n**Report** to user:\n\n```\n## Scan Complete\n\nScanned **{filesScanned}** files, **{filesTimedOut}** timed out, **{filesErrored}** errors.\n\n### Findings ({totalFindings} total)\n\n| # | Severity | Skill | File | Title |\n|---|----------|-------|------|-------|\n| 1 | **HIGH** | security-review | `src/db/query.ts:42` | SQL injection in query builder |\n...\n```\n\nRender every finding from the `findings` array. Bold severity for high and above.\n\n**On failure**: If exit code 1, show the error JSON and stop. If exit code 2, show the partial results. List timed-out files separately from errored files so users know which can be retried.\n\n---\n\n## Phase 2: Verify\n\nDeep-trace each finding using Task subagents to qualify or disqualify.\n\n**For each finding in `data/all-findings.jsonl`:**\n\nCheck if `data/verify/.json` already exists (incrementality). If it does, skip.\n\nLaunch a Task subagent (`subagent_type: \"general-purpose\"`) for each finding. Process findings in parallel batches of up to 8 to improve throughput.\n\n**Task prompt for each finding:**\n\nRead `${CLAUDE_SKILL_ROOT}/references/verify-prompt.md` for the prompt template. Substitute the finding's values into the `${...}` placeholders.\n\n**Process results:**\n\nParse the JSON from the subagent response and:\n- Write result to `data/verify/.json`\n- Append to `data/verified.jsonl` or `data/rejected.jsonl`\n- For verified findings, generate `findings/.md`:\n\n```markdown\n# ${TITLE}\n\n**ID**: ${FINDING_ID} | **Severity**: ${SEVERITY} | **Confidence**: ${CONFIDENCE}\n**Skill**: ${SKILL} | **File**: ${FILE_PATH}:${START_LINE}\n\n## Description\n${DESCRIPTION}\n\n## Verification\n**Verdict**: Verified (${VERIFICATION_CONFIDENCE})\n**Reasoning**: ${REASONING}\n**Code trace**: ${TRACE_NOTES}\n\n## Suggested Fix\n${FIX_DESCRIPTION}\n```diff\n${FIX_DIFF}\n```\n```\n\nUpdate manifest: set `phases.verify` to `\"complete\"`.\n\n**Report** to user after all verifications:\n\n```\n## Verification Complete\n\n**{verified}** verified, **{rejected}** rejected.\n\n### Verified Findings\n\n| # | Severity | Confidence | File | Title | Reasoning |\n|---|----------|------------|------|-------|-----------|\n| 1 | **HIGH** | high | `src/db/query.ts:42` | SQL injection in query builder | User input flows directly into... |\n...\n\n### Rejected ({rejected_count})\n\n- `{findingId}` {file}: {reasoning}\n...\n```\n\n---\n\n## Phase 3: Issue\n\nCreate a tracking issue that ties all PRs together and gives reviewers a single overview.\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/create_issue.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout. Save `issueUrl` and `issueNumber` for Phase 4.\n\n**Report** to user:\n\n```\n## Tracking Issue Created\n\n{issueUrl}\n```\n\n**On failure**: Show the error. Continue to Phase 4 (PRs can still be created without a tracking issue).\n\n---\n\n## Phase 4: Patch\n\nFor each verified finding, create a worktree, fix the code, and open a draft PR. Process findings **sequentially** (one at a time) since parallel subagents cross-contaminate worktrees.\n\n**Severity triage**: Patch HIGH and above. For MEDIUM, only patch findings from bug-detection skills (e.g., `code-review`, `security-review`). Skip LOW and INFO findings.\n\n**Step 0: Setup** (run once before the loop):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/index_prs.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout. Use `fileIndex` for dedup checks.\n\nDetermine the default branch and fetch latest so worktrees branch from current upstream:\n\n```bash\nDEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')\ngit fetch origin \"${DEFAULT_BRANCH}\"\n```\n\n**For each finding in `data/verified.jsonl`:**\n\nCheck if finding ID already exists in `data/patches.jsonl` (incrementality). If it does, skip.\n\n**Dedup check**: Use the file index from `index_prs.py` output to determine if an existing open PR already addresses the same issue.\n\n1. **File match**: Look up the finding's file path in the `fileIndex`. If no PR touches that file, no conflict; proceed to Step 1.\n2. **Chunk overlap**: If a PR does touch the same file, read its cached diff from `data/pr-diffs/.diff` and check whether the PR's changed hunks overlap with the finding's line range (startLine-endLine). Overlapping or adjacent hunks (within ~10 lines) indicate the same code region.\n3. **Same concern**: If the hunks overlap, compare the PR title and the finding title/description. Are they fixing the same kind of defect? A PR fixing an off-by-one error and a finding about a null check in the same function are different issues; both should proceed.\n\nSkip the finding only when there is both chunk overlap AND the PR addresses the same concern. Record it in `data/patches.jsonl` with `\"status\": \"existing\"` and `\"prUrl\"` pointing to the matching PR, then continue to the next finding.\n\n**Step 1: Create worktree**\n\n```bash\nBRANCH=\"warden-sweep/${RUN_ID}/${FINDING_ID}\"\nWORKTREE=\"${SWEEP_DIR}/worktrees/${FINDING_ID}\"\ngit worktree add \"${WORKTREE}\" -b \"${BRANCH}\" \"origin/${DEFAULT_BRANCH}\"\n```\n\nEach finding branches from the repo's default branch so PRs contain only the fix commit.\n\n**Step 2: Generate fix**\n\nLaunch a Task subagent (`subagent_type: \"general-purpose\"`) to apply the fix in the worktree. Read `${CLAUDE_SKILL_ROOT}/references/patch-prompt.md` for the prompt template. Substitute the finding's values and worktree path into the `${...}` placeholders.\n\n**Step 2b: Handle skipped findings**\n\nIf the subagent returned `\"status\": \"skipped\"` (not `\"applied\"`), do NOT proceed to Steps 3-4. Instead:\n1. Record the finding in `data/patches.jsonl` with `\"status\": \"error\"` and `\"error\": \"Subagent skipped: ${skipReason}\"`\n2. Clean up the worktree\n3. Continue to the next finding\n\n**Step 3: Find reviewers**\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/find_reviewers.py \"${FILE_PATH}\"\n```\n\n**Step 4: Create draft PR**\n\n```bash\ncd \"${WORKTREE}\" && git push -u origin HEAD:\"${BRANCH}\"\n```\n\nCreate the PR with a 1-2 sentence \"What\" summary based on the finding and fix, followed by the finding description and verification reasoning:\n\n```bash\nREVIEWERS=\"\"\n# If find_reviewers.py returned reviewers, build the flags\n# e.g., REVIEWERS=\"--reviewer user1 --reviewer user2\"\n\ngh pr create --draft \\\n --label \"warden\" \\\n --title \"fix: ${TITLE}\" \\\n --body \"$(cat <<'EOF'\n${FIX_WHAT_DESCRIPTION}\n\n${DESCRIPTION}\n\n${REASONING}\n\nAutomated fix for Warden finding ${FINDING_ID} (${SEVERITY}, detected by ${SKILL}).\n\n\nRef #${ISSUE_NUMBER}\n\n> This PR was auto-generated by a Warden Sweep (run ${RUN_ID}).\n> The finding has been validated through automated deep tracing,\n> but human confirmation is requested as this is batch work.\nEOF\n)\" ${REVIEWERS}\n```\n\nSave the PR URL.\n\n**Step 5: Record and cleanup**\n\nAppend to `data/patches.jsonl` (use `\"created\"` as status for successful PRs, not the subagent's `\"applied\"`):\n```json\n{\"findingId\": \"...\", \"prUrl\": \"https://...\", \"branch\": \"...\", \"reviewers\": [\"user1\", \"user2\"], \"filesChanged\": [\"...\"], \"status\": \"created|existing|error\"}\n```\n\nRemove the worktree:\n```bash\ncd \"$(git rev-parse --show-toplevel)\"\ngit worktree remove \"${WORKTREE}\" --force\n```\n\n**Error handling**: On failure at any step, write to `data/patches.jsonl` with `\"status\": \"error\"` and `\"error\": \"...\"`, clean up the worktree, and continue to the next finding.\n\nUpdate manifest: set `phases.patch` to `\"complete\"`.\n\n**Report** to user after all patches:\n\n```\n## PRs Created\n\n**{created}** created, **{skipped}** skipped (existing), **{failed}** failed.\n\n| # | Finding | PR | Status |\n|---|---------|-----|--------|\n| 1 | `security-review-a1b2c3d4` SQL injection in query builder | #142 | created |\n| 2 | `code-review-e5f6g7h8` Null pointer in handler | - | existing (#138) |\n...\n```\n\n---\n\n## Phase 5: Organize\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/organize.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout.\n\n**Report** to user:\n\n```\n## Sweep Complete\n\n| Metric | Count |\n|--------|-------|\n| Files scanned | {filesScanned} |\n| Findings verified | {verified} |\n| PRs created | {prsCreated} |\n| Security findings | {securityFindings} |\n\nFull report: `{summaryPath}`\n```\n\n**On failure**: Show the error and note which steps completed.\n\n---\n\n## Resuming a Sweep\n\nEach phase is incremental. To resume from where you left off:\n\n1. Check `data/manifest.json` to see which phases are complete\n2. For scan: pass `--sweep-dir` to `scan.py`\n3. For verify: existing `data/verify/.json` files are skipped\n4. For issue: `create_issue.py` is idempotent (skips if `issueUrl` in manifest)\n5. For patch: existing entries in `data/patches.jsonl` are skipped\n6. For organize: safe to re-run (idempotent)\n\n## Output Directory Structure\n\n```\n.warden/sweeps//\n summary.md # Stats, key findings, PR links\n findings/ # One markdown per verified finding\n .md\n security/ # Security-specific view\n index.jsonl # Security findings index\n .md # Copies of security findings\n data/ # Structured data for tooling\n manifest.json # Run metadata, phase state\n scan-index.jsonl # Per-file scan tracking\n all-findings.jsonl # Every finding from scan\n verified.jsonl # Findings that passed verification\n rejected.jsonl # Findings that failed verification\n patches.jsonl # Finding -> PR URL -> reviewers\n existing-prs.json # Cached open warden PRs\n report.json # Machine-readable summary\n verify/ # Individual verification results\n .json\n logs/ # Warden JSONL logs per file\n .jsonl\n pr-diffs/ # Cached PR diffs for dedup\n .diff\n```\n",".agents/skills/warden-sweep/references/patch-prompt.md":"Fix a verified code issue. You are working in a git worktree at: ${WORKTREE}\n\n## Finding\n- Title: ${TITLE}\n- File: ${FILE_PATH}:${START_LINE}\n- Description: ${DESCRIPTION}\n- Verification: ${REASONING}\n- Suggested Fix: ${FIX_DESCRIPTION}\n```diff\n${FIX_DIFF}\n```\n\n## Instructions\n\n### Step 1: Understand the code\nRead the file at ${WORKTREE}/${FILE_PATH}. Read at least 50 lines above and below the reported location. Trace callers and callees of the affected code using Grep/Glob to understand how it is used. Do NOT skip this step.\n\n### Step 2: Apply a minimal fix\nApply the smallest change that addresses the finding. If the suggested diff doesn't apply cleanly, adapt it while preserving intent. Do NOT refactor surrounding code, rename variables, add comments, or make any change beyond what the finding requires.\n\n### Step 3: Write tests\nWrite or update tests that verify the fix:\n- Follow existing test patterns (co-located files, same framework)\n- At minimum, write a test that would have caught the original bug\n- Test the specific edge case, not just the happy path\n\nOnly modify the fix target and its test file.\n\n### Step 4: Self-review\nBefore staging, run `git diff` in the worktree and review every changed line. Verify:\n1. The change addresses the specific finding described, not something else\n2. No unrelated code was modified (no drive-by cleanups, no formatting changes)\n3. Trace through changed code paths: does the fix introduce any new bug, null reference, type error, or broken import?\n4. Tests exercise the fix (the failure case), not just that the code runs\n\nIf ANY check fails, fix the problem before proceeding. If the suggested fix is wrong or would introduce a regression you cannot resolve, do NOT commit. Instead, skip to the output step and report why.\n\n### Step 5: Commit\nDo NOT run tests locally. CI will validate the changes.\n\nStage and commit with this exact message:\n\nfix: ${TITLE}\n\nWarden finding ${FINDING_ID}\nSeverity: ${SEVERITY}\n\nCo-Authored-By: Warden \n\n### Step 6: Output\nReturn ONLY valid JSON (no surrounding text). Use `\"status\": \"applied\"` if you committed a fix, or `\"status\": \"skipped\"` if you did not.\n\n```json\n{\n \"status\": \"applied\",\n \"filesChanged\": [\"src/example.ts\"],\n \"testFilesChanged\": [\"src/example.test.ts\"],\n \"selfReview\": \"Verified the fix addresses the null check and test covers the failure case\",\n \"skipReason\": null\n}\n```\n\nWhen skipping:\n```json\n{\n \"status\": \"skipped\",\n \"filesChanged\": [],\n \"testFilesChanged\": [],\n \"selfReview\": null,\n \"skipReason\": \"The suggested fix would introduce a regression in the error handling path\"\n}\n```\n",".agents/skills/warden-sweep/references/verify-prompt.md":"Verify a code analysis finding. Determine if this is a TRUE issue or a FALSE POSITIVE.\nDo NOT write or edit any files. Research only.\n\n## Finding\n- Title: ${TITLE}\n- Severity: ${SEVERITY} | Confidence: ${CONFIDENCE}\n- Skill: ${SKILL}\n- Location: ${FILE_PATH}:${START_LINE}-${END_LINE}\n- Description: ${DESCRIPTION}\n- Verification hint: ${VERIFICATION}\n\n## Instructions\n1. Read the file at the reported location. Examine at least 50 lines of surrounding context.\n2. Trace data flow to/from the flagged code using Grep/Glob.\n3. Check if the issue is mitigated elsewhere (guards, validation, try/catch upstream).\n4. Check if the issue is actually reachable in practice.\n\nReturn your verdict as JSON:\n{\n \"findingId\": \"${FINDING_ID}\",\n \"verdict\": \"verified\" or \"rejected\",\n \"confidence\": \"high\" or \"medium\" or \"low\",\n \"reasoning\": \"2-3 sentence explanation\",\n \"traceNotes\": \"What code paths you examined\"\n}\n",".agents/skills/warden/SKILL.md":"---\nname: warden\ndescription: Run Warden to analyze code changes before committing. Use when asked to \"run warden\", \"check my changes\", \"review before commit\", \"warden config\", \"warden.toml\", \"create a warden skill\", \"add trigger\", or any Warden-related local development task.\n---\n\nRun Warden to analyze code changes before committing.\n\n## References\n\nRead the relevant reference when the task requires deeper detail:\n\n| Document | Read When |\n|----------|-----------|\n| `${CLAUDE_SKILL_ROOT}/references/cli-reference.md` | Full option details, per-command flags, examples |\n| `${CLAUDE_SKILL_ROOT}/references/configuration.md` | Editing warden.toml, triggers, patterns, troubleshooting |\n| `${CLAUDE_SKILL_ROOT}/references/config-schema.md` | Exact field names, types, and defaults |\n| `${CLAUDE_SKILL_ROOT}/references/creating-skills.md` | Writing custom skills, remote skills, skill discovery |\n\n## Running Warden\n\n```bash\n# Analyze uncommitted changes (uses warden.toml triggers)\nwarden\n\n# Run a specific skill\nwarden --skill \n\n# Analyze specific files\nwarden src/auth.ts src/database.ts\n\n# Analyze changes from a git ref\nwarden main..HEAD\nwarden HEAD~3\n\n# Auto-apply suggested fixes\nwarden --fix\n\n# Fail on high-severity findings\nwarden --fail-on high\n```\n\nSet `WARDEN_ANTHROPIC_API_KEY` or log in via `claude login` before running.\n\n## Pre-Commit Workflow\n\nAfter making code changes and before committing:\n\n1. Run `warden` to analyze uncommitted changes\n2. Review the findings\n3. Fix issues Warden reports (or use `warden --fix` to auto-apply)\n4. Commit the changes\n\nRun Warden once to validate work. Do not loop re-running Warden on the same changes.\n\n## Reading Output\n\n**Severity levels:**\n- `high` - Must fix before merge\n- `medium` - Worth reviewing\n- `low` - Minor improvement\n\n**Exit codes:** `0` = no findings at or above fail threshold. `1` = findings at or above fail threshold.\n\n**Verbosity:** `-v` shows real-time findings. `-vv` shows debug info (tokens, latency). `-q` shows errors and summary only.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `warden` | Run analysis (default) |\n| `warden init` | Initialize warden.toml and GitHub workflow |\n| `warden add [skill]` | Add skill trigger to warden.toml |\n| `warden sync [remote]` | Update cached remote skills |\n| `warden setup-app` | Create GitHub App via manifest flow |\n\nFor full options and flags, read `${CLAUDE_SKILL_ROOT}/references/cli-reference.md`.\n",".agents/skills/warden/references/cli-reference.md":"# CLI Reference\n\n## Usage\n\n```\nwarden [command] [targets...] [options]\n```\n\nAnalyze code for security issues and code quality.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `(default)` | Run analysis on targets or using warden.toml skills |\n| `init` | Initialize warden.toml and GitHub workflow |\n| `add [skill]` | Add a skill to warden.toml |\n| `sync [remote]` | Update cached remote skills to latest |\n| `setup-app` | Create a GitHub App for Warden via manifest flow |\n\n## Targets\n\n| Target | Description |\n|--------|-------------|\n| `` | Analyze specific files (e.g., `src/auth.ts`) |\n| `` | Analyze files matching pattern (e.g., `\"src/**/*.ts\"`) |\n| `` | Analyze changes from git ref (e.g., `HEAD~3`, `main..feature`) |\n| `(none)` | Analyze uncommitted changes using warden.toml skills |\n\nAmbiguous targets (no path separator, no extension) are resolved by checking if a file exists at the path. Use `--git` to force git ref interpretation.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--skill ` | Run only this skill (default: run all built-in skills) |\n| `--config ` | Path to warden.toml (default: `./warden.toml`) |\n| `-m, --model ` | Model to use (fallback when not set in config) |\n| `--json` | Output results as JSON |\n| `-o, --output ` | Write full run output to a JSONL file |\n| `--fail-on ` | Exit with code 1 if findings >= severity |\n| `--report-on ` | Only show findings >= severity in output |\n| `--fix` | Automatically apply all suggested fixes |\n| `--parallel ` | Max concurrent skill executions (default: 4) |\n| `--git` | Force ambiguous targets to be treated as git refs |\n| `--offline` | Use cached remote skills without network access |\n| `-q, --quiet` | Errors and final summary only |\n| `-v, --verbose` | Show real-time findings and hunk details |\n| `-vv` | Show debug info (token counts, latencies) |\n| `--debug` | Enable debug output (equivalent to `-vv`) |\n| `--log` | Use log output (no animations, timestamped) |\n| `--color / --no-color` | Override color detection |\n| `-h, --help` | Show help message |\n| `-V, --version` | Show version number |\n\n## Per-Command Options\n\n**Init:**\n| Option | Description |\n|--------|-------------|\n| `-f, --force` | Overwrite existing files |\n\n**Add:**\n| Option | Description |\n|--------|-------------|\n| `--list` | List available skills |\n| `--remote ` | Remote repository (`owner/repo`, URL, or with `@sha`) |\n| `--force` | Bypass skill cache and fetch latest |\n\n**Sync:**\n| Option | Description |\n|--------|-------------|\n| `--remote ` | Specific remote to sync (default: all) |\n\n**Setup-app:**\n| Option | Description |\n|--------|-------------|\n| `--org ` | Create under organization (default: personal) |\n| `--port ` | Local server port (default: 3000) |\n| `--timeout ` | Callback timeout in seconds (default: 300) |\n| `--name ` | Custom app name (default: Warden) |\n| `--no-open` | Print URL instead of opening browser |\n\n## Severity Levels\n\nUsed in `--fail-on` and `--report-on`:\n\n| Level | Meaning |\n|-------|---------|\n| `high` | Must fix before merge |\n| `medium` | Worth reviewing |\n| `low` | Minor improvement |\n| `off` | Disable the threshold |\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | No findings at or above `--fail-on` threshold |\n| `1` | Findings at or above `--fail-on` threshold |\n\n## Examples\n\n```bash\n# Initialize\nwarden init\n\n# Interactive skill selection\nwarden add\nwarden add \nwarden add --list\n\n# Remote skills\nwarden add --remote / --skill \nwarden add --remote https://github.com// --skill \nwarden add --remote /@ --skill \n\n# Run analysis\nwarden # Skills from warden.toml\nwarden src/auth.ts # Specific file\nwarden src/auth.ts --skill \nwarden \"src/**/*.ts\" # Glob pattern\nwarden HEAD~3 # Git changes\nwarden HEAD~3 --skill \nwarden main..HEAD # Branch diff\n\n# Output control\nwarden --json\nwarden --fail-on high\nwarden -o results.jsonl\n\n# Fix mode\nwarden --fix\n\n# Cached skills only\nwarden --offline\nwarden sync # Update all unpinned remote skills\n\n# GitHub App setup\nwarden setup-app\nwarden setup-app --org myorg\n```\n",".agents/skills/warden/references/config-schema.md":"# warden.toml Configuration Schema\n\n## Top-Level Structure\n\n```toml\nversion = 1 # Required, must be 1\n\n[defaults] # Optional, inherited by all skills\n[[skills]] # Required, array of skill configs\n```\n\n## Defaults Section\n\n```toml\n[defaults]\nmodel = \"claude-sonnet-4-20250514\" # Default model\nmaxTurns = 50 # Max agentic turns per hunk\ndefaultBranch = \"main\" # Base branch for comparisons\nfailOn = \"high\" # Exit 1 if findings >= this severity\nreportOn = \"medium\" # Show findings >= this severity\nmaxFindings = 50 # Max findings to report (0 = unlimited)\nreportOnSuccess = false # Post report even with no findings\npaths = [\"src/**/*.ts\"] # Include only matching files\nignorePaths = [\"*.test.ts\"] # Exclude matching files\n\n[defaults.chunking]\nenabled = true # Enable hunk-based chunking\n\n[defaults.chunking.coalesce]\nenabled = true # Merge nearby hunks\nmaxGapLines = 30 # Lines between hunks to merge\nmaxChunkSize = 8000 # Max chars per chunk\n\n[[defaults.chunking.filePatterns]]\npattern = \"*.config.*\" # Glob pattern\nmode = \"whole-file\" # per-hunk | whole-file | skip\n```\n\n## Skills Section\n\n```toml\n[[skills]]\nname = \"skill-name\" # Required, unique identifier\nremote = \"owner/repo@sha\" # Optional, fetch skill from GitHub repo\npaths = [\"src/**\"] # Include only matching files\nignorePaths = [\"**/*.test.ts\"] # Exclude matching files\n\n# Optional overrides (inherit from defaults if not set)\nmodel = \"claude-opus-4-20250514\"\nmaxTurns = 100\nfailOn = \"high\"\nreportOn = \"medium\"\nmaxFindings = 20\nreportOnSuccess = true\n\n[[skills.triggers]]\ntype = \"pull_request\" # Required: pull_request | local | schedule\nactions = [\"opened\", \"synchronize\"] # Required for pull_request\n\n# Schedule-specific (only for type = \"schedule\")\n[[skills.triggers]]\ntype = \"schedule\"\n\n[skills.triggers.schedule]\nissueTitle = \"Daily Security Review\" # GitHub issue title for tracking\ncreateFixPR = true # Create PR with fixes\nfixBranchPrefix = \"security-fix\" # Branch name prefix\n```\n\n**Trigger types:**\n- `pull_request` - Triggers on PR events\n- `local` - Local CLI only (will not run in CI)\n- `schedule` - Cron schedule (GitHub Action only)\n\nAll skills run locally regardless of trigger type. Skills with no triggers run everywhere (wildcard). Use `type = \"local\"` for skills that should *only* run locally.\n\n**Actions (for pull_request):**\n- `opened`, `synchronize`, `reopened`, `closed`\n\n## Severity Values\n\nUsed in `failOn` and `reportOn`:\n- `high` - Must fix before merge\n- `medium` - Worth reviewing\n- `low` - Minor improvement\n- `off` - Disable threshold\n\n## Built-in Skip Patterns\n\nAlways skipped (cannot be overridden):\n- Package locks: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `Cargo.lock`, etc.\n- Minified files: `**/*.min.js`, `**/*.min.css`\n- Build artifacts: `dist/`, `build/`, `node_modules/`, `.next/`, `__pycache__/`\n- Generated code: `*.generated.*`, `*.g.ts`, `__generated__/`\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required) |\n| `WARDEN_MODEL` | Default model (lowest priority) |\n| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |\n| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |\n\n## Model Precedence (highest to lowest)\n\n1. Skill-level `model`\n2. `[defaults]` `model`\n3. CLI `--model` flag\n4. `WARDEN_MODEL` env var\n5. SDK default\n",".agents/skills/warden/references/configuration.md":"# Configuration (warden.toml)\n\nSee [config-schema.md](config-schema.md) for the complete schema reference.\n\n## Minimal Example\n\nThe `name` field references a skill you've created (via `warden add`) or defined in `.agents/skills//SKILL.md`. Use that same name everywhere — in config, CLI flags, and triggers.\n\n```toml\nversion = 1\n\n[defaults]\nmodel = \"claude-sonnet-4-20250514\"\n\n[[skills]]\nname = \"my-skill\" # matches .agents/skills/my-skill/SKILL.md\npaths = [\"src/**/*.ts\"]\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n## Skill Configuration\n\nSkills define what to analyze and when. Each skill requires a name. Triggers are optional — skills with no triggers run everywhere (PR, local, schedule). All skills run locally regardless of trigger type.\n\n```toml\n[[skills]]\nname = \"my-skill\"\npaths = [\"src/auth/**\", \"src/payments/**\"]\nfailOn = \"high\"\nreportOn = \"medium\"\nmaxFindings = 20\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Trigger types:** `pull_request`, `local` (local-only), `schedule` (CI-only)\n\n**Actions (pull_request):** `opened`, `synchronize`, `reopened`, `closed`\n\n## Common Patterns\n\n**Strict checks on critical files:**\n```toml\n[[skills]]\nname = \"my-skill\"\nmodel = \"claude-opus-4-20250514\"\nmaxTurns = 100\npaths = [\"src/auth/**\", \"src/payments/**\"]\nfailOn = \"high\"\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Skip test files:**\n```toml\n[[skills]]\nname = \"my-skill\"\npaths = [\"src/**/*.ts\"]\nignorePaths = [\"**/*.test.ts\", \"**/*.spec.ts\"]\n```\n\n**Whole-file analysis for configs:**\n```toml\n[defaults.chunking.filePatterns]\npattern = \"*.config.*\"\nmode = \"whole-file\"\n```\n\n## Model Precedence\n\nFrom highest to lowest priority:\n\n1. Skill-level `model`\n2. `[defaults]` `model`\n3. CLI `--model` flag\n4. `WARDEN_MODEL` env var\n5. SDK default\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required unless using Claude Code subscription) |\n| `WARDEN_MODEL` | Default model (lowest priority) |\n| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |\n| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |\n\n## Troubleshooting\n\n**No findings reported:**\n- Check `--report-on` threshold (default shows all)\n- Verify skill matches file types in `paths`\n- Use `-v` to see which files are being analyzed\n\n**Files being skipped:**\n- Built-in skip patterns: lock files, minified, `node_modules/`, `dist/`\n- Check `ignorePaths` in config\n- Use `-vv` to see skip reasons\n\n**Token/cost issues:**\n- Reduce `maxTurns` (default: 50)\n- Use chunking settings to control chunk size\n- Filter to relevant files with `paths`\n",".agents/skills/warden/references/creating-skills.md":"# Creating Skills\n\nSkills are markdown files that tell Warden what to look for. They follow the [agentskills.io](https://agentskills.io) specification.\n\n## Skill Discovery\n\nWarden searches these directories in order (first match wins):\n\n```\n.agents/skills/{name}/SKILL.md # Primary (recommended)\n.claude/skills/{name}/SKILL.md # Backup (Claude Code convention)\n```\n\n## SKILL.md Format\n\n```markdown\n---\nname: my-skill\ndescription: What this skill analyzes\nallowed-tools: Read Grep Glob\n---\n\n[Analysis instructions for the agent]\n\n## What to Look For\n- Specific issue type 1\n- Specific issue type 2\n\n## Output Format\nReport findings with severity, location, and suggested fix.\n```\n\n## Available Tools\n\n`Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Bash`, `Write`, `Edit`\n\nMost review skills only need `Read`, `Grep`, and `Glob` for exploring context.\n\n## Writing Checklist\n\n- One skill, one concern (\"security review\" not \"code quality\")\n- Clear criteria for what counts as an issue and at what severity\n- Actionable findings that include how to fix\n- Examples of good and bad code where helpful\n\n## Remote Skills\n\nSkills can be fetched from GitHub repositories:\n\n```bash\n# Add a remote skill\nwarden add --remote / --skill \n\n# Add with version pinning (recommended for reproducibility)\nwarden add --remote /@ --skill \n\n# List skills in a remote repo\nwarden add --remote / --list\n\n# Update all unpinned remote skills\nwarden sync\n\n# Update specific repo\nwarden sync /\n\n# Run with cached skills only (no network)\nwarden --offline\n```\n\n**Remote skill in warden.toml:**\n\n```toml\n[[skills]]\nname = \"my-skill\"\nremote = \"/@\"\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Cache location:** `~/.local/warden/skills/` (override with `WARDEN_STATE_DIR`)\n\n**Cache TTL:** 24 hours for unpinned refs (override with `WARDEN_SKILL_CACHE_TTL` in seconds)\n","AGENTS.md":"# Development Rules\n\n## Build & Test\n- `npm run build` - Build (wireit + tsup, ESM)\n- `npm run test` - Unit/integration tests (Vitest)\n- `npm run test:smoke` - Smoke tests (builds first, serial execution)\n- `npm run lint` / `npm run lint:fix` - ESLint\n- `npm run format` / `npm run format:check` - Prettier\n- `npm run typecheck` - TypeScript type checking (src + test config)\n\n## Architecture\nESM TypeScript project (`type: module`). Key layers:\n\n- `src/cli/` - CLI entrypoint, yargs wiring, daemon routing\n- `src/server/` - MCP stdio server, lifecycle, workflow/resource registration\n- `src/runtime/` - Config bootstrap, session state, tool catalog assembly\n- `src/core/manifest/` - YAML manifest loading, validation, tool module imports\n- `src/mcp/tools/` - Tool implementations grouped by workflow (mirrors `manifests/workflows/`)\n- `src/mcp/resources/` - MCP resource implementations\n- `src/integrations/` - External integrations (Xcode tools bridge)\n- `src/utils/` - Shared helpers (execution, logging, validation, responses)\n- `src/visibility/` - Tool/workflow exposure predicates\n- `src/daemon/` - Background daemon for persistent sessions\n- `src/rendering/` - Output rendering and formatting\n- `src/types/` - Shared type definitions\n\n## Contributing Workflow\n1. Create a branch from `main`\n2. Make changes following the conventions in this file\n3. Run the pre-commit checklist before committing:\n ```bash\n npm run lint:fix\n npm run typecheck\n npm run format\n npm run build\n npm test\n ```\n4. Update `CHANGELOG.md` under `## [Unreleased]`\n5. Update documentation if adding or modifying features\n6. Clone and test against example projects (e.g., `XcodeBuildMCP-iOS-Template`) when changes affect runtime behavior\n7. Push and create a pull request with a clear description\n8. Link any related issues\n\n## Code Quality\n- No `any` types unless absolutely necessary\n- Check node_modules for external API type definitions instead of guessing\n- **NEVER use inline imports** - no `await import(\"./foo.js\")`, no `import(\"pkg\").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.\n- NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead\n- Always ask before removing functionality or code that appears to be intentional\n- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.\n- Review the complete merge-base diff and trace changed or reused helper contracts, including error and sentinel returns, through callers, consumers, tests, and operational configuration.\n- Verify standard quality commands include every changed path and exercise exact entry points and argument variants; validate explicitly when they do not.\n- For asynchronous, workflow, or process-boundary changes, enumerate lifecycle states, retries, supersession, and race transitions; test terminal outcomes and missing or optional metadata.\n\n## Import Conventions\n- ESM with explicit `.ts` extensions in `src/` (tsup rewrites to `.js` at build)\n- No `.js` imports in `src/` (enforced by ESLint)\n- No barrel imports from `utils/index` - import from specific submodules (e.g., `src/utils/execution/index.ts`, `src/utils/logging/index.ts`)\n\n\n## Rendering and Streaming Contract\n- Streaming fragments are transient live-progress output only. They may be displayed while a tool is running, but MUST NOT provide final settled MCP/JSON/CLI text.\n- Final settled output MUST render from the final structured/domain result and next-step metadata. If final output needs data, add it to the final result type instead of reading it from fragments.\n- Streaming-capable renderers may observe fragment callbacks only for live progress. Fragment handling must not affect final structured output or final settled text.\n\n## Error Handling\n- Structured errors (domain results with `didError`) are for domain errors only: failures in the user's build/test/device/simulator workflow (compile errors, test failures, missing destinations, etc.).\n- System errors with the MCP server or CLI itself (invalid internal state, unresolvable configuration, infrastructure failures) must NOT be wrapped in structured domain results — let them surface as runtime tool errors so they are clearly distinguishable from workflow outcomes.\n\n## Test Conventions\n- Vitest with colocated `__tests__/` directories using `*.test.ts`\n- Snapshot tests (`*.snapshot.test.ts`) must only assert generated tool output against fixtures. Move helper, parser, schema, setup, or behavior assertions to non-snapshot unit/integration tests.\n- Smoke tests in `src/smoke-tests/__tests__/` (separate Vitest config, serial execution)\n- Use `vi.mock`/`vi.hoisted` for isolation; inject executors and mock file systems\n- MCP integration tests use `McpServer`, `InMemoryTransport`, and `Client`\n- External dependencies (command execution, file system) must use dependency injection via `createMockExecutor()` / `createMockFileSystemExecutor()` from `src/test-utils/`\n\n## Tool Development\n- Tool manifests in `manifests/tools/*.yaml` define `id`, `module`, `names.mcp` (snake_case), optional `names.cli` (kebab-case), predicates, and annotations\n- MCP `readOnlyHint` describes whether a tool mutates host/project state such as files, build artifacts, configuration, or external services. Simulator HID/UI actions that only tap, type, press, or gesture inside the simulator may remain `readOnlyHint: true`; do not flip them to `false` merely because app UI state changes.\n- Workflow manifests in `manifests/workflows/*.yaml` group tools and define exposure rules\n- Tool modules export a Zod `schema`, a pure `*Logic` function, and a `handler` built with `createTypedTool` or `createSessionAwareTool`\n- Resource modules export a `handler` (and a pure `*Logic` function); `uri`, `name`, `description`, and `mimeType` are declared in `manifests/resources/*.yaml`\n\n## Commands\n- NEVER commit unless user asks\n\n## GitHub\nWhen reading issues:\n- Always read all comments on the issue\n-\n## Tools\n- GitHub CLI for issues/PRs\n- CLI design note: do not rely on CLI session-default writes. CLI is intentionally deterministic for CI/scripting and should use explicit command arguments as the primary input surface.\n- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.\n- After modifying any skill source, run `npx skill-check ` and address all errors/warnings before handoff.\n- Before handoff, run the matching manual Warden review for high-risk changes: runtime/CLI/daemon boundaries → `mobilebuildmcp-runtime-boundary-review`; test infrastructure or harnesses → `mobilebuildmcp-test-boundary-review`; tool manifests, schemas, or contracts → `mobilebuildmcp-tool-contract-review`. Invoke only applicable skills with `warden --skill `.\n-\n## Multi-process filesystem state\n- MobileBuildMCP explicitly supports multiple concurrent MCP server, daemon, CLI, test, and helper processes for the same or different workspaces.\n- Shared filesystem state under `~/Library/Developer/MobileBuildMCP` must be multi-process safe.\n- Use workspace-key scoped directories for workspace-owned state.\n- Do not store runtime state under `~/.mobilebuildmcp`; `.mobilebuildmcp/config.yaml` is only project configuration.\n- Use shared lock and atomic-write helpers for mutable shared files.\n- Prefer one-record-per-file registries over shared aggregate files.\n- Cleanup must verify ownership before deleting shared artifacts.\n- Multi-process safety means concurrent processes must not corrupt or delete each other's state.\n It does not mean ephemeral runtime handles should become portable between invocation surfaces.\n- Keep runtime/session-scoped handles isolated unless the product explicitly defines a cross-process\n contract. For example, UI automation `elementRef` values from runtime snapshots are handles for\n the runtime/session that produced them, not durable IDs to share between separate MCP and CLI\n invocations.\n- User-facing artifact/log paths in final text or structured output must use `displayPath()` from `src/utils/build-preflight.ts`, so paths are cwd-relative when possible or `~/...` instead of absolute home paths. Keep stored files at their real absolute paths; only normalize response/display values.\n\n## Style\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n\n## Docs\n- Do not commit transient investigation notes, prompt exports, or scratch analysis docs after the work is complete.\n- If an investigation leaves unresolved follow-up work, move it to a GitHub issue instead of preserving the transient doc in the branch.\n- Structured output JSON schemas are auto-published to the website/public schema mirror when merged; do not manually update public schema copies unless explicitly asked.\n\n### Changelog\nLocation: `CHANGELOG.md`\n\n#### Format\nUse these sections under `## [Unreleased]`:\n- `### Added` - New features\n- `### Changed` - Changes to existing functionality\n- `### Fixed` - Bug fixes\n- `### Removed` - Removed features\n-\n#### Rules\n- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist\n- New entries ALWAYS go under `## [Unreleased]` section\n- Append to existing subsections (e.g., `### Fixed`), do not create duplicates\n- NEVER modify already-released version sections (e.g., `## [0.12.2]`)\n- Each version section is immutable once released\n- NEVER update snapshot fixtures unless asked to do so, these are integration tests, on failure assume code is wrong before questioning the fixture\n-\n#### Attribution\n- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/MobileBuildMCP/issues/123))`\n- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/MobileBuildMCP/pull/456) by [@username](https://github.com/username))`\n\n## Test Execution Rules\n- **NEVER run the snapshot or smoke test suites without explicit user permission.** They are expensive (~7 min baseline, spawn real `xcodebuild`/`simctl`/`devicectl` processes and can wedge). This covers `npm run test:snapshot`, `npm run test:smoke`, and any direct `vitest run --config vitest.snapshot.config.ts` / `vitest.smoke.config.ts` invocation. Ask first, then run only if the user agrees.\n- The default unit suite (`npm test` / `vitest run`), `npm run typecheck`, `npm run lint`, and `npm run build` are cheap and may be run freely without asking.\n- When running long test suites (snapshot tests, smoke tests), ALWAYS write full output to a log file and read it afterwards. NEVER pipe through `tail` or `grep` directly — that loses output you may need to debug failures.\n- Pattern: `DEVICE_ID=... npm run test:snapshot 2>&1 | tee /tmp/snapshot-results.txt` then read `/tmp/snapshot-results.txt` with the native read tool.\n- If you need a summary, read the log file and grep/filter it — the full output is always preserved.\n- Snapshot test command: `DEVICE_ID= npm run test:snapshot`\n- **Snapshot suite expected duration**: ~7 min baseline (measured at 423s). Anything longer than ~10 min should be treated as a likely hang, not a slow run.\n - Do NOT just kill the run — first inspect the process tree (`ps -ef | grep -E \"vitest|xcodebuild|simctl|devicectl\"`) to identify what's stuck.\n - Common hang causes: locked physical device, stale simulator state, `devicectl diagnose` waiting for password, orphaned daemon process.\n - Capture what you find before killing, so the root cause can be fixed rather than papered over.\n- If physical-device snapshot tests hang after the final test summary, the likely cause is Apple post-failure diagnostics invoking `devicectl diagnose`, which may prompt for a macOS password and wedge in automated runs.\n- When asked to review changes or test failures, focus on regressions: behavior changes caused by the branch. Do not treat known/acceptable test flakes, environment setup issues, or nondeterministic tool output churn as regressions unless explicitly asked to investigate them.\n\n## **CRITICAL** Tool Usage Rules **CRITICAL**\n- NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.\n- You MUST read every file you modify in full before editing.\n","CLAUDE.md":"# Development Rules\n\n## Code Quality\n- No `any` types unless absolutely necessary\n- Check node_modules for external API type definitions instead of guessing\n- **NEVER use inline imports** - no `await import(\"./foo.js\")`, no `import(\"pkg\").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.\n- NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead\n- Always ask before removing functionality or code that appears to be intentional\n- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.\n- Review the complete merge-base diff and trace changed or reused helper contracts, including error and sentinel returns, through callers, consumers, tests, and operational configuration.\n- Verify standard quality commands include every changed path and exercise exact entry points and argument variants; validate explicitly when they do not.\n- For asynchronous, workflow, or process-boundary changes, enumerate lifecycle states, retries, supersession, and race transitions; test terminal outcomes and missing or optional metadata.\n\n## Test Conventions\n- Snapshot tests (`*.snapshot.test.ts`) must only assert generated tool output against fixtures. Move helper, parser, schema, setup, or behavior assertions to non-snapshot unit/integration tests.\n\n## Commands\n- NEVER commit unless user asks\n\n## GitHub\nWhen reading issues:\n- Always read all comments on the issue\n-\n## Tools\n- GitHub CLI for issues/PRs\n- MCP `readOnlyHint` describes whether a tool mutates host/project state such as files, build artifacts, configuration, or external services. Simulator HID/UI actions that only tap, type, press, or gesture inside the simulator may remain `readOnlyHint: true`; do not flip them to `false` merely because app UI state changes.\n- CLI design note: do not rely on CLI session-default writes. CLI is intentionally deterministic for CI/scripting and should use explicit command arguments as the primary input surface.\n- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.\n- After modifying any skill source, run `npx skill-check ` and address all errors/warnings before handoff.\n- Before handoff, run the matching manual Warden review for high-risk changes: runtime/CLI/daemon boundaries → `mobilebuildmcp-runtime-boundary-review`; test infrastructure or harnesses → `mobilebuildmcp-test-boundary-review`; tool manifests, schemas, or contracts → `mobilebuildmcp-tool-contract-review`. Invoke only applicable skills with `warden --skill `.\n-\n## Multi-process filesystem state\n- MobileBuildMCP explicitly supports multiple concurrent MCP server, daemon, CLI, test, and helper processes for the same or different workspaces.\n- Shared filesystem state under `~/Library/Developer/MobileBuildMCP` must be multi-process safe.\n- Use workspace-key scoped directories for workspace-owned state.\n- Do not store runtime state under `~/.mobilebuildmcp`; `.mobilebuildmcp/config.yaml` is only project configuration.\n- Use shared lock and atomic-write helpers for mutable shared files.\n- Prefer one-record-per-file registries over shared aggregate files.\n- Cleanup must verify ownership before deleting shared artifacts.\n- User-facing artifact/log paths in final text or structured output must use `displayPath()` from `src/utils/build-preflight.ts`, so paths are cwd-relative when possible or `~/...` instead of absolute home paths. Keep stored files at their real absolute paths; only normalize response/display values.\n\n## Style\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n\n## Docs\n- Do not commit transient investigation notes, prompt exports, or scratch analysis docs after the work is complete.\n- If an investigation leaves unresolved follow-up work, move it to a GitHub issue instead of preserving the transient doc in the branch.\n- Structured output JSON schemas are auto-published to the website/public schema mirror when merged; do not manually update public schema copies unless explicitly asked.\n\n### Changelog\nLocation: `CHANGELOG.md`\n\n#### Format\nUse these sections under `## [Unreleased]`:\n- `### Added` - New features\n- `### Changed` - Changes to existing functionality\n- `### Fixed` - Bug fixes\n- `### Removed` - Removed features\n-\n#### Rules\n- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist\n- New entries ALWAYS go under `## [Unreleased]` section\n- Append to existing subsections (e.g., `### Fixed`), do not create duplicates\n- NEVER modify already-released version sections (e.g., `## [0.12.2]`)\n- Each version section is immutable once released\n- NEVER update snapshot fixtures unless asked to do so, these are integration tests, on failure assume code is wrong before questioning the fixture\n-\n#### Attribution\n- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/MobileBuildMCP/issues/123))`\n- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/MobileBuildMCP/pull/456) by [@username](https://github.com/username))`\n\n\n## Rendering and Streaming Contract\n- Streaming fragments are transient live-progress output only. They may be displayed while a tool is running, but MUST NOT provide final settled MCP/JSON/CLI text.\n- Final settled output MUST render from the final structured/domain result and next-step metadata. If final output needs data, add it to the final result type instead of reading it from fragments.\n- Streaming-capable renderers may observe fragment callbacks only for live progress. Fragment handling must not affect final structured output or final settled text.\n\n## Error Handling\n- Structured errors (domain results with `didError`) are for domain errors only: failures in the user's build/test/device/simulator workflow (compile errors, test failures, missing destinations, etc.).\n- System errors with the MCP server or CLI itself (invalid internal state, unresolvable configuration, infrastructure failures) must NOT be wrapped in structured domain results — let them surface as runtime tool errors so they are clearly distinguishable from workflow outcomes.\n\n## Test Execution Rules\n- **NEVER run the snapshot or smoke test suites without explicit user permission.** They are expensive (~7 min baseline, spawn real `xcodebuild`/`simctl`/`devicectl` processes and can wedge). This covers `npm run test:snapshot`, `npm run test:smoke`, and any direct `vitest run --config vitest.snapshot.config.ts` / `vitest.smoke.config.ts` invocation. Ask first, then run only if the user agrees.\n- The default unit suite (`npm test` / `vitest run`), `npm run typecheck`, `npm run lint`, and `npm run build` are cheap and may be run freely without asking.\n- When running long test suites (snapshot tests, smoke tests), ALWAYS write full output to a log file and read it afterwards. NEVER pipe through `tail` or `grep` directly — that loses output you may need to debug failures.\n- Pattern: `DEVICE_ID=... npm run test:snapshot 2>&1 | tee /tmp/snapshot-results.txt` then read `/tmp/snapshot-results.txt` with the native read tool.\n- If you need a summary, read the log file and grep/filter it — the full output is always preserved.\n- Snapshot test command: `DEVICE_ID= npm run test:snapshot`\n- **Snapshot suite expected duration**: ~7 min baseline (measured at 423s). Anything longer than ~10 min should be treated as a likely hang, not a slow run.\n - Do NOT just kill the run — first inspect the process tree (`ps -ef | grep -E \"vitest|xcodebuild|simctl|devicectl\"`) to identify what's stuck.\n - Common hang causes: locked physical device, stale simulator state, `devicectl diagnose` waiting for password, orphaned daemon process.\n - Capture what you find before killing, so the root cause can be fixed rather than papered over.\n- When asked to review changes or test failures, focus on regressions: behavior changes caused by the branch. Do not treat known/acceptable test flakes, environment setup issues, or nondeterministic tool output churn as regressions unless explicitly asked to investigate them.\n\n## **CRITICAL** Tool Usage Rules **CRITICAL**\n- NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.\n- You MUST read every file you modify in full before editing.\n","example_projects/iOS/.cursor/rules/errors.mdc":"---\ndescription: \nglobs: \nalwaysApply: true\n---\nPlease don't fix any code errors unless reported by MobileBuildMCP server tool responses.","skills/mobilebuildmcp-cli/SKILL.md":"---\nname: mobilebuildmcp-cli\ndescription: Official skill for the MobileBuildMCP CLI. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).\n---\n\n# MobileBuildMCP CLI\n\nUse MobileBuildMCP tools via the `mobilebuildmcp` executable instead of raw `xcodebuild`, `xcrun`, or `simctl`.\n\n## Step 1: Ensure the CLI Exists\n\nCheck availability:\n```bash\nmobilebuildmcp --help\n```\n\nIf missing, install with one of:\n```bash\nbrew tap getsentry/xcodebuildmcp\nbrew install mobilebuildmcp\n```\n\n```bash\nnpm install -g mobilebuildmcp@latest\n```\n\nRe-check after install:\n```bash\nmobilebuildmcp --help\n```\n\n## Step 2: Use Help-First Discovery\n\nDiscover workflows and arguments from the CLI itself:\n```bash\nmobilebuildmcp --help\nmobilebuildmcp tools\nmobilebuildmcp --help\nmobilebuildmcp --help\n```\n\nUse this discovery path instead of memorizing static tool lists.\n\n## Step 3: Keep Execution Minimal\n\n- Choose the smallest command sequence that satisfies the request.\n- Prefer direct workflow commands over manual multi-step chains unless explicitly requested.\n- For simulator run intent, prefer the combined `build-and-run` command.\n- Do not chain `build` then `build-and-run` unless explicitly requested.\n\n## Capability Overview\n\n`mobilebuildmcp` supports:\n- simulator and device build/test/run\n- debugging and log capture\n- UI automation\n- project discovery and scaffolding\n- session defaults and workflow configuration\n\n## Exit Criteria\n\n- CLI presence is verified or installation steps are provided.\n- Commands are discovered via `--help` / `tools`.\n- Session defaults are checked before first build/run/test action.\n","skills/mobilebuildmcp/SKILL.md":"---\nname: mobilebuildmcp\ndescription: Official skill for MobileBuildMCP. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).\n---\n\n# MobileBuildMCP\n\nUse MobileBuildMCP tools instead of raw `xcodebuild`, `xcrun`, or `simctl`.\n\nCapabilities:\n- Session defaults: Configure project, scheme, simulator, and device defaults to avoid repetitive parameters\n- Project discovery: Find Xcode projects/workspaces, list schemes, inspect build settings\n- Simulator workflows: Build, run, test, install, and launch apps on iOS simulators; manage simulator state (boot, erase, location, appearance)\n- Device workflows: Build, test, install, and launch apps on physical devices with code signing\n- macOS workflows: Build, run, and test macOS applications\n- Log capture: Stream and capture logs from simulators and devices\n- LLDB debugging: Attach debugger, set breakpoints, inspect stack traces and variables, execute LLDB commands\n- UI automation: Capture screenshots, inspect view hierarchy with coordinates, perform taps/swipes/gestures, type text, press hardware buttons\n- SwiftPM: Build, run, test, and manage Swift Package Manager projects\n- Project scaffolding: Generate new iOS/macOS project templates\n\nOnly simulator workflow tools are enabled by default. If capabilities like device, macOS, debugging, or UI automation are not available, the user must configure MobileBuildMCP to enable them. See https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/configuration.mdx for workflow configuration.\n\n## Step 1: Establish Session Context\n\n- Call `session_show_defaults` before the first build/run/test action in a session.\n- Use `discover_projs` only when defaults show missing or incorrect project/workspace context.\n- Do not run discovery speculatively or in parallel with `session_show_defaults`.\n- For simulator run intent, prefer the combined build-and-run tool instead of separate build then run calls.\n- Do not chain build-only then build-and-run unless the user explicitly requests both.\n\n## Step 2: Understand Workflow-Scoped Tool Availability\n\n- Not all tools are enabled by default; tool availability depends on enabled workflows.\n- If a tool is expected but missing, check enabled workflows first.\n- Update enabled workflows in `.mobilebuildmcp/config.yaml`, then ask user to reload/restart the session to surface refreshes.\n\n## Step 3: Report Context Clearly\n\n- Return the active defaults context used for execution (project/workspace, scheme, simulator/device).\n- For failures, include the exact failing step and the next actionable command/tool call.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Development Rules\n\n## Build & Test\n- `npm run build` - Build (wireit + tsup, ESM)\n- `npm run test` - Unit/integration tests (Vitest)\n- `npm run test:smoke` - Smoke tests (builds first, serial execution)\n- `npm run lint` / `npm run lint:fix` - ESLint\n- `npm run format` / `npm run format:check` - Prettier\n- `npm run typecheck` - TypeScript type checking (src + test config)\n\n## Architecture\nESM TypeScript project (`type: module`). Key layers:\n\n- `src/cli/` - CLI entrypoint, yargs wiring, daemon routing\n- `src/server/` - MCP stdio server, lifecycle, workflow/resource registration\n- `src/runtime/` - Config bootstrap, session state, tool catalog assembly\n- `src/core/manifest/` - YAML manifest loading, validation, tool module imports\n- `src/mcp/tools/` - Tool implementations grouped by workflow (mirrors `manifests/workflows/`)\n- `src/mcp/resources/` - MCP resource implementations\n- `src/integrations/` - External integrations (Xcode tools bridge)\n- `src/utils/` - Shared helpers (execution, logging, validation, responses)\n- `src/visibility/` - Tool/workflow exposure predicates\n- `src/daemon/` - Background daemon for persistent sessions\n- `src/rendering/` - Output rendering and formatting\n- `src/types/` - Shared type definitions\n\n## Contributing Workflow\n1. Create a branch from `main`\n2. Make changes following the conventions in this file\n3. Run the pre-commit checklist before committing:\n ```bash\n npm run lint:fix\n npm run typecheck\n npm run format\n npm run build\n npm test\n ```\n4. Update `CHANGELOG.md` under `## [Unreleased]`\n5. Update documentation if adding or modifying features\n6. Clone and test against example projects (e.g., `XcodeBuildMCP-iOS-Template`) when changes affect runtime behavior\n7. Push and create a pull request with a clear description\n8. Link any related issues\n\n## Code Quality\n- No `any` types unless absolutely necessary\n- Check node_modules for external API type definitions instead of guessing\n- **NEVER use inline imports** - no `await import(\"./foo.js\")`, no `import(\"pkg\").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.\n- NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead\n- Always ask before removing functionality or code that appears to be intentional\n- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.\n- Review the complete merge-base diff and trace changed or reused helper contracts, including error and sentinel returns, through callers, consumers, tests, and operational configuration.\n- Verify standard quality commands include every changed path and exercise exact entry points and argument variants; validate explicitly when they do not.\n- For asynchronous, workflow, or process-boundary changes, enumerate lifecycle states, retries, supersession, and race transitions; test terminal outcomes and missing or optional metadata.\n\n## Import Conventions\n- ESM with explicit `.ts` extensions in `src/` (tsup rewrites to `.js` at build)\n- No `.js` imports in `src/` (enforced by ESLint)\n- No barrel imports from `utils/index` - import from specific submodules (e.g., `src/utils/execution/index.ts`, `src/utils/logging/index.ts`)\n\n\n## Rendering and Streaming Contract\n- Streaming fragments are transient live-progress output only. They may be displayed while a tool is running, but MUST NOT provide final settled MCP/JSON/CLI text.\n- Final settled output MUST render from the final structured/domain result and next-step metadata. If final output needs data, add it to the final result type instead of reading it from fragments.\n- Streaming-capable renderers may observe fragment callbacks only for live progress. Fragment handling must not affect final structured output or final settled text.\n\n## Error Handling\n- Structured errors (domain results with `didError`) are for domain errors only: failures in the user's build/test/device/simulator workflow (compile errors, test failures, missing destinations, etc.).\n- System errors with the MCP server or CLI itself (invalid internal state, unresolvable configuration, infrastructure failures) must NOT be wrapped in structured domain results — let them surface as runtime tool errors so they are clearly distinguishable from workflow outcomes.\n\n## Test Conventions\n- Vitest with colocated `__tests__/` directories using `*.test.ts`\n- Snapshot tests (`*.snapshot.test.ts`) must only assert generated tool output against fixtures. Move helper, parser, schema, setup, or behavior assertions to non-snapshot unit/integration tests.\n- Smoke tests in `src/smoke-tests/__tests__/` (separate Vitest config, serial execution)\n- Use `vi.mock`/`vi.hoisted` for isolation; inject executors and mock file systems\n- MCP integration tests use `McpServer`, `InMemoryTransport`, and `Client`\n- External dependencies (command execution, file system) must use dependency injection via `createMockExecutor()` / `createMockFileSystemExecutor()` from `src/test-utils/`\n\n## Tool Development\n- Tool manifests in `manifests/tools/*.yaml` define `id`, `module`, `names.mcp` (snake_case), optional `names.cli` (kebab-case), predicates, and annotations\n- MCP `readOnlyHint` describes whether a tool mutates host/project state such as files, build artifacts, configuration, or external services. Simulator HID/UI actions that only tap, type, press, or gesture inside the simulator may remain `readOnlyHint: true`; do not flip them to `false` merely because app UI state changes.\n- Workflow manifests in `manifests/workflows/*.yaml` group tools and define exposure rules\n- Tool modules export a Zod `schema`, a pure `*Logic` function, and a `handler` built with `createTypedTool` or `createSessionAwareTool`\n- Resource modules export a `handler` (and a pure `*Logic` function); `uri`, `name`, `description`, and `mimeType` are declared in `manifests/resources/*.yaml`\n\n## Commands\n- NEVER commit unless user asks\n\n## GitHub\nWhen reading issues:\n- Always read all comments on the issue\n-\n## Tools\n- GitHub CLI for issues/PRs\n- CLI design note: do not rely on CLI session-default writes. CLI is intentionally deterministic for CI/scripting and should use explicit command arguments as the primary input surface.\n- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.\n- After modifying any skill source, run `npx skill-check ` and address all errors/warnings before handoff.\n- Before handoff, run the matching manual Warden review for high-risk changes: runtime/CLI/daemon boundaries → `mobilebuildmcp-runtime-boundary-review`; test infrastructure or harnesses → `mobilebuildmcp-test-boundary-review`; tool manifests, schemas, or contracts → `mobilebuildmcp-tool-contract-review`. Invoke only applicable skills with `warden --skill `.\n-\n## Multi-process filesystem state\n- MobileBuildMCP explicitly supports multiple concurrent MCP server, daemon, CLI, test, and helper processes for the same or different workspaces.\n- Shared filesystem state under `~/Library/Developer/MobileBuildMCP` must be multi-process safe.\n- Use workspace-key scoped directories for workspace-owned state.\n- Do not store runtime state under `~/.mobilebuildmcp`; `.mobilebuildmcp/config.yaml` is only project configuration.\n- Use shared lock and atomic-write helpers for mutable shared files.\n- Prefer one-record-per-file registries over shared aggregate files.\n- Cleanup must verify ownership before deleting shared artifacts.\n- Multi-process safety means concurrent processes must not corrupt or delete each other's state.\n It does not mean ephemeral runtime handles should become portable between invocation surfaces.\n- Keep runtime/session-scoped handles isolated unless the product explicitly defines a cross-process\n contract. For example, UI automation `elementRef` values from runtime snapshots are handles for\n the runtime/session that produced them, not durable IDs to share between separate MCP and CLI\n invocations.\n- User-facing artifact/log paths in final text or structured output must use `displayPath()` from `src/utils/build-preflight.ts`, so paths are cwd-relative when possible or `~/...` instead of absolute home paths. Keep stored files at their real absolute paths; only normalize response/display values.\n\n## Style\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n\n## Docs\n- Do not commit transient investigation notes, prompt exports, or scratch analysis docs after the work is complete.\n- If an investigation leaves unresolved follow-up work, move it to a GitHub issue instead of preserving the transient doc in the branch.\n- Structured output JSON schemas are auto-published to the website/public schema mirror when merged; do not manually update public schema copies unless explicitly asked.\n\n### Changelog\nLocation: `CHANGELOG.md`\n\n#### Format\nUse these sections under `## [Unreleased]`:\n- `### Added` - New features\n- `### Changed` - Changes to existing functionality\n- `### Fixed` - Bug fixes\n- `### Removed` - Removed features\n-\n#### Rules\n- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist\n- New entries ALWAYS go under `## [Unreleased]` section\n- Append to existing subsections (e.g., `### Fixed`), do not create duplicates\n- NEVER modify already-released version sections (e.g., `## [0.12.2]`)\n- Each version section is immutable once released\n- NEVER update snapshot fixtures unless asked to do so, these are integration tests, on failure assume code is wrong before questioning the fixture\n-\n#### Attribution\n- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/MobileBuildMCP/issues/123))`\n- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/MobileBuildMCP/pull/456) by [@username](https://github.com/username))`\n\n## Test Execution Rules\n- **NEVER run the snapshot or smoke test suites without explicit user permission.** They are expensive (~7 min baseline, spawn real `xcodebuild`/`simctl`/`devicectl` processes and can wedge). This covers `npm run test:snapshot`, `npm run test:smoke`, and any direct `vitest run --config vitest.snapshot.config.ts` / `vitest.smoke.config.ts` invocation. Ask first, then run only if the user agrees.\n- The default unit suite (`npm test` / `vitest run`), `npm run typecheck`, `npm run lint`, and `npm run build` are cheap and may be run freely without asking.\n- When running long test suites (snapshot tests, smoke tests), ALWAYS write full output to a log file and read it afterwards. NEVER pipe through `tail` or `grep` directly — that loses output you may need to debug failures.\n- Pattern: `DEVICE_ID=... npm run test:snapshot 2>&1 | tee /tmp/snapshot-results.txt` then read `/tmp/snapshot-results.txt` with the native read tool.\n- If you need a summary, read the log file and grep/filter it — the full output is always preserved.\n- Snapshot test command: `DEVICE_ID= npm run test:snapshot`\n- **Snapshot suite expected duration**: ~7 min baseline (measured at 423s). Anything longer than ~10 min should be treated as a likely hang, not a slow run.\n - Do NOT just kill the run — first inspect the process tree (`ps -ef | grep -E \"vitest|xcodebuild|simctl|devicectl\"`) to identify what's stuck.\n - Common hang causes: locked physical device, stale simulator state, `devicectl diagnose` waiting for password, orphaned daemon process.\n - Capture what you find before killing, so the root cause can be fixed rather than papered over.\n- If physical-device snapshot tests hang after the final test summary, the likely cause is Apple post-failure diagnostics invoking `devicectl diagnose`, which may prompt for a macOS password and wedge in automated runs.\n- When asked to review changes or test failures, focus on regressions: behavior changes caused by the branch. Do not treat known/acceptable test flakes, environment setup issues, or nondeterministic tool output churn as regressions unless explicitly asked to investigate them.\n\n## **CRITICAL** Tool Usage Rules **CRITICAL**\n- NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.\n- You MUST read every file you modify in full before editing.\n","isInternal":false,"tokens":2824,"sizeBytes":12598},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# Development Rules\n\n## Code Quality\n- No `any` types unless absolutely necessary\n- Check node_modules for external API type definitions instead of guessing\n- **NEVER use inline imports** - no `await import(\"./foo.js\")`, no `import(\"pkg\").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.\n- NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead\n- Always ask before removing functionality or code that appears to be intentional\n- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.\n- Review the complete merge-base diff and trace changed or reused helper contracts, including error and sentinel returns, through callers, consumers, tests, and operational configuration.\n- Verify standard quality commands include every changed path and exercise exact entry points and argument variants; validate explicitly when they do not.\n- For asynchronous, workflow, or process-boundary changes, enumerate lifecycle states, retries, supersession, and race transitions; test terminal outcomes and missing or optional metadata.\n\n## Test Conventions\n- Snapshot tests (`*.snapshot.test.ts`) must only assert generated tool output against fixtures. Move helper, parser, schema, setup, or behavior assertions to non-snapshot unit/integration tests.\n\n## Commands\n- NEVER commit unless user asks\n\n## GitHub\nWhen reading issues:\n- Always read all comments on the issue\n-\n## Tools\n- GitHub CLI for issues/PRs\n- MCP `readOnlyHint` describes whether a tool mutates host/project state such as files, build artifacts, configuration, or external services. Simulator HID/UI actions that only tap, type, press, or gesture inside the simulator may remain `readOnlyHint: true`; do not flip them to `false` merely because app UI state changes.\n- CLI design note: do not rely on CLI session-default writes. CLI is intentionally deterministic for CI/scripting and should use explicit command arguments as the primary input surface.\n- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.\n- After modifying any skill source, run `npx skill-check ` and address all errors/warnings before handoff.\n- Before handoff, run the matching manual Warden review for high-risk changes: runtime/CLI/daemon boundaries → `mobilebuildmcp-runtime-boundary-review`; test infrastructure or harnesses → `mobilebuildmcp-test-boundary-review`; tool manifests, schemas, or contracts → `mobilebuildmcp-tool-contract-review`. Invoke only applicable skills with `warden --skill `.\n-\n## Multi-process filesystem state\n- MobileBuildMCP explicitly supports multiple concurrent MCP server, daemon, CLI, test, and helper processes for the same or different workspaces.\n- Shared filesystem state under `~/Library/Developer/MobileBuildMCP` must be multi-process safe.\n- Use workspace-key scoped directories for workspace-owned state.\n- Do not store runtime state under `~/.mobilebuildmcp`; `.mobilebuildmcp/config.yaml` is only project configuration.\n- Use shared lock and atomic-write helpers for mutable shared files.\n- Prefer one-record-per-file registries over shared aggregate files.\n- Cleanup must verify ownership before deleting shared artifacts.\n- User-facing artifact/log paths in final text or structured output must use `displayPath()` from `src/utils/build-preflight.ts`, so paths are cwd-relative when possible or `~/...` instead of absolute home paths. Keep stored files at their real absolute paths; only normalize response/display values.\n\n## Style\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n\n## Docs\n- Do not commit transient investigation notes, prompt exports, or scratch analysis docs after the work is complete.\n- If an investigation leaves unresolved follow-up work, move it to a GitHub issue instead of preserving the transient doc in the branch.\n- Structured output JSON schemas are auto-published to the website/public schema mirror when merged; do not manually update public schema copies unless explicitly asked.\n\n### Changelog\nLocation: `CHANGELOG.md`\n\n#### Format\nUse these sections under `## [Unreleased]`:\n- `### Added` - New features\n- `### Changed` - Changes to existing functionality\n- `### Fixed` - Bug fixes\n- `### Removed` - Removed features\n-\n#### Rules\n- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist\n- New entries ALWAYS go under `## [Unreleased]` section\n- Append to existing subsections (e.g., `### Fixed`), do not create duplicates\n- NEVER modify already-released version sections (e.g., `## [0.12.2]`)\n- Each version section is immutable once released\n- NEVER update snapshot fixtures unless asked to do so, these are integration tests, on failure assume code is wrong before questioning the fixture\n-\n#### Attribution\n- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/MobileBuildMCP/issues/123))`\n- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/MobileBuildMCP/pull/456) by [@username](https://github.com/username))`\n\n\n## Rendering and Streaming Contract\n- Streaming fragments are transient live-progress output only. They may be displayed while a tool is running, but MUST NOT provide final settled MCP/JSON/CLI text.\n- Final settled output MUST render from the final structured/domain result and next-step metadata. If final output needs data, add it to the final result type instead of reading it from fragments.\n- Streaming-capable renderers may observe fragment callbacks only for live progress. Fragment handling must not affect final structured output or final settled text.\n\n## Error Handling\n- Structured errors (domain results with `didError`) are for domain errors only: failures in the user's build/test/device/simulator workflow (compile errors, test failures, missing destinations, etc.).\n- System errors with the MCP server or CLI itself (invalid internal state, unresolvable configuration, infrastructure failures) must NOT be wrapped in structured domain results — let them surface as runtime tool errors so they are clearly distinguishable from workflow outcomes.\n\n## Test Execution Rules\n- **NEVER run the snapshot or smoke test suites without explicit user permission.** They are expensive (~7 min baseline, spawn real `xcodebuild`/`simctl`/`devicectl` processes and can wedge). This covers `npm run test:snapshot`, `npm run test:smoke`, and any direct `vitest run --config vitest.snapshot.config.ts` / `vitest.smoke.config.ts` invocation. Ask first, then run only if the user agrees.\n- The default unit suite (`npm test` / `vitest run`), `npm run typecheck`, `npm run lint`, and `npm run build` are cheap and may be run freely without asking.\n- When running long test suites (snapshot tests, smoke tests), ALWAYS write full output to a log file and read it afterwards. NEVER pipe through `tail` or `grep` directly — that loses output you may need to debug failures.\n- Pattern: `DEVICE_ID=... npm run test:snapshot 2>&1 | tee /tmp/snapshot-results.txt` then read `/tmp/snapshot-results.txt` with the native read tool.\n- If you need a summary, read the log file and grep/filter it — the full output is always preserved.\n- Snapshot test command: `DEVICE_ID= npm run test:snapshot`\n- **Snapshot suite expected duration**: ~7 min baseline (measured at 423s). Anything longer than ~10 min should be treated as a likely hang, not a slow run.\n - Do NOT just kill the run — first inspect the process tree (`ps -ef | grep -E \"vitest|xcodebuild|simctl|devicectl\"`) to identify what's stuck.\n - Common hang causes: locked physical device, stale simulator state, `devicectl diagnose` waiting for password, orphaned daemon process.\n - Capture what you find before killing, so the root cause can be fixed rather than papered over.\n- When asked to review changes or test failures, focus on regressions: behavior changes caused by the branch. Do not treat known/acceptable test flakes, environment setup issues, or nondeterministic tool output churn as regressions unless explicitly asked to investigate them.\n\n## **CRITICAL** Tool Usage Rules **CRITICAL**\n- NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.\n- You MUST read every file you modify in full before editing.\n","isInternal":false,"tokens":1877,"sizeBytes":8728},{"name":"errors.mdc","path":"example_projects/iOS/.cursor/rules/errors.mdc","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/example_projects/iOS/.cursor/rules/errors.mdc","title":"Cursor Rule: errors","category":"cursor-rule","format":"mdc","content":"---\ndescription: \nglobs: \nalwaysApply: true\n---\nPlease don't fix any code errors unless reported by MobileBuildMCP server tool responses.","frontmatter":{"description":null,"globs":null,"alwaysApply":true},"isInternal":false,"tokens":32,"sizeBytes":137},{"name":"SKILL.md","path":".agents/skills/mobilebuildmcp-docs-command-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/mobilebuildmcp-docs-command-review/SKILL.md","title":"mobilebuildmcp-docs-command-review","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp-docs-command-review\ndescription: Use when reviewing MobileBuildMCP changelog CLI command references for invalid current guidance while allowing historical migration examples.\nallowed-tools: Read Grep Glob\n---\n\n# MobileBuildMCP Docs Command Review\n\nReview changed changelog entries for CLI command references that would mislead users or agents.\n\n## What to inspect\n\n- `CHANGELOG.md`\n- `manifests/tools/*.yaml` and `manifests/workflows/*.yaml` when you need to verify current CLI workflow/tool names\n- `src/cli/**` only when command wiring is unclear from manifests\n\n## Issue criteria\n\nReport a finding only when a command reference is presented as current guidance and appears invalid for the current CLI surface.\n\n### High severity\n\n- A changelog bullet, example, or migration instruction tells users to run a removed or invalid `mobilebuildmcp` command as the current path.\n- A Breaking change mentions a removed command but does not give a valid replacement.\n- A command reference uses the wrong workflow/tool pairing in a way a user or agent would likely copy.\n\n### Medium severity\n\n- A command reference is ambiguous enough that users may not know whether it is historical or current.\n- A migration example gives the right replacement but does not clearly label the old command as \"Before\", \"old\", \"removed\", or equivalent.\n\n## Explicitly allowed\n\nDo not report removed commands when they are clearly historical context, especially in:\n\n- Breaking-change migration sections\n- \"Before\" examples paired with valid \"After\" examples\n- Already-released changelog sections describing past behavior\n\nExample that should not be reported:\n\n```markdown\nBefore:\nmobilebuildmcp logging start-sim-log-cap\n\nAfter:\nmobilebuildmcp simulator build-and-run\n```\n\n## Output\n\nFor each finding, include:\n\n- Severity\n- File and line\n- The command reference\n- Why it reads as current guidance\n- Suggested replacement wording or command\n\nIf all command references are historical or valid, report no findings.\n","frontmatter":{"name":"mobilebuildmcp-docs-command-review","description":"Use when reviewing MobileBuildMCP changelog CLI command references for invalid current guidance while allowing historical migration examples.","allowed-tools":"Read Grep Glob","allowedTools":["Read","Grep","Glob"]},"allowedTools":["Read","Grep","Glob"],"isInternal":false,"tokens":412,"sizeBytes":2013},{"name":"SKILL.md","path":".agents/skills/mobilebuildmcp-docs-release-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/mobilebuildmcp-docs-release-review/SKILL.md","title":"mobilebuildmcp-docs-release-review","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp-docs-release-review\ndescription: Use when reviewing MobileBuildMCP documentation, CLI command references, website manifest generation, changelog, release notes, and release script changes.\n---\n\n# MobileBuildMCP Docs and Release Review\n\nReview guardrails for documentation, generated references, and release flow consistency.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `README.md`\n- `CHANGELOG.md` when present\n- `scripts/build-website-manifest.mjs`\n- `scripts/generate-github-release-notes.mjs`\n- `scripts/release.sh`\n- `package.json`\n- `xcodebuildmcp.com/app/docs/_content/**`\n\n## Guardrails\n\n- CLI examples match generated CLI catalog/commands.\n- Docs do not reference unavailable tools or workflows.\n- User-facing behavior changes include changelog updates.\n- Release notes derive from a valid changelog section.\n- README install snippets align with release script tag replacement.\n- Website manifest generation preserves expected normalized fields.\n- Docs explain runtime/contracts without deprecated patterns.\n- Keep docs-only work from introducing product behavior changes.\n- CLI command references in changelog entries are reviewed by `mobilebuildmcp-docs-command-review`.\n\n## Validation\n\n- `npm run build`\n- Release notes check when touched:\n - `node scripts/generate-github-release-notes.mjs --version --changelog CHANGELOG.md`\n- `npx skill-check .agents/skills/mobilebuildmcp-docs-release-review`\n","frontmatter":{"name":"mobilebuildmcp-docs-release-review","description":"Use when reviewing MobileBuildMCP documentation, CLI command references, website manifest generation, changelog, release notes, and release script changes."},"isInternal":false,"tokens":325,"sizeBytes":1555},{"name":"SKILL.md","path":".agents/skills/mobilebuildmcp-packaging-resource-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/mobilebuildmcp-packaging-resource-review/SKILL.md","title":"mobilebuildmcp-packaging-resource-review","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp-packaging-resource-review\ndescription: Use when reviewing MobileBuildMCP packaging, resource-root, build artifact, bundled AXe, schema, manifest, and portable macOS distribution changes.\n---\n\n# MobileBuildMCP Packaging and Resource Review\n\nReview guardrails for package/build/resource integrity and portable distribution.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `package.json`\n- `scripts/copy-build-assets.js`\n- `scripts/package-macos-portable.sh`\n- `scripts/build-website-manifest.mjs`\n- `schemas/**`\n- `manifests/**`\n- `skills/**`\n- `bundled/**` when present\n- Resource-root utilities when touched\n\n## Guardrails\n\n- Published package `files` includes required runtime resources.\n- Portable package includes `build`, `manifests`, `bundled`, `skills`, `package.json`, and production dependencies.\n- AXe binary/framework expectations remain verified.\n- Wrapper scripts preserve `MOBILEBUILDMCP_RESOURCE_ROOT` and `DYLD_FRAMEWORK_PATH`.\n- Schemas and manifests stay available in installed and portable layouts.\n- Do not assume build outputs exist before `npm run build`.\n- Avoid network-dependent packaging behavior without verification/checksums.\n\n## Validation\n\n- `npm run build`\n- Packaging-specific when touched:\n - `npm run package:macos -- --help` (if supported)\n - `npm run verify:portable` after artifact creation\n- `npx skill-check .agents/skills/mobilebuildmcp-packaging-resource-review`\n","frontmatter":{"name":"mobilebuildmcp-packaging-resource-review","description":"Use when reviewing MobileBuildMCP packaging, resource-root, build artifact, bundled AXe, schema, manifest, and portable macOS distribution changes."},"isInternal":false,"tokens":339,"sizeBytes":1538},{"name":"SKILL.md","path":".agents/skills/mobilebuildmcp-rendering-streaming-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/mobilebuildmcp-rendering-streaming-review/SKILL.md","title":"mobilebuildmcp-rendering-streaming-review","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp-rendering-streaming-review\ndescription: Use when reviewing MobileBuildMCP rendering, streaming fragment, next-step, and CLI output mode changes for boundary violations.\n---\n\n# MobileBuildMCP Rendering and Streaming Review\n\nReview guardrails for rendering boundaries, streaming fragments, and output modes.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/rendering/**`\n- `src/types/domain-fragments.ts`\n- `src/types/runtime-status.ts`\n- `src/runtime/tool-invoker.ts`\n- `src/runtime/__tests__/tool-invoker.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/architecture-rendering-output.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-tool-lifecycle.mdx`\n- `xcodebuildmcp.com/app/docs/_content/output-formats.mdx`\n\n## Guardrails\n\n- Tool handlers do not branch on CLI vs MCP output mode.\n- Fragments represent progress, not final contract data.\n- Final structured output remains canonical.\n- Do not invent `json`/`jsonl` render strategies.\n- Streaming tools emit typed fragments and one final structured result.\n- Non-streaming tools do not emit unnecessary fragments.\n- Keep `ctx.emit` and xcodebuild pipeline `emitFragment` contexts separate.\n- Keep next-step rendering in runtime/rendering boundary.\n\n## Validation\n\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npm run test:snapshots`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-rendering-streaming-review`\n","frontmatter":{"name":"mobilebuildmcp-rendering-streaming-review","description":"Use when reviewing MobileBuildMCP rendering, streaming fragment, next-step, and CLI output mode changes for boundary violations."},"isInternal":false,"tokens":355,"sizeBytes":1544},{"name":"SKILL.md","path":".agents/skills/mobilebuildmcp-runtime-boundary-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/mobilebuildmcp-runtime-boundary-review/SKILL.md","title":"mobilebuildmcp-runtime-boundary-review","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp-runtime-boundary-review\ndescription: Use when reviewing MobileBuildMCP runtime boundary changes across MCP, direct CLI invocation, daemon-routed tools, and Xcode IDE bridge routing.\n---\n\n# MobileBuildMCP Runtime Boundary Review\n\nReview guardrails for runtime routing and invocation boundaries.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/runtime/tool-catalog.ts`\n- `src/runtime/tool-invoker.ts`\n- `src/runtime/types.ts`\n- `src/cli/**`\n- `src/daemon/**`\n- `manifests/tools/*.yaml`\n- `manifests/workflows/*.yaml`\n- `xcodebuildmcp.com/app/docs/_content/architecture-runtime-boundaries.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-manifest-visibility.mdx`\n\n## Guardrails\n\n- MCP, CLI, and daemon paths use shared handlers.\n- Stateful CLI tools route through daemon only when `routing.stateful` requires it.\n- Do not treat daemon as a third manifest availability mode.\n- Dynamic Xcode IDE tools keep daemon routing semantics.\n- Catalog filtering respects availability, workflow selection, and predicates.\n- Runtime failures surface via runtime/rendering status and fragments.\n- Avoid silent fallbacks and parallel invocation paths.\n\n## Validation\n\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-runtime-boundary-review`\n","frontmatter":{"name":"mobilebuildmcp-runtime-boundary-review","description":"Use when reviewing MobileBuildMCP runtime boundary changes across MCP, direct CLI invocation, daemon-routed tools, and Xcode IDE bridge routing."},"isInternal":false,"tokens":324,"sizeBytes":1450},{"name":"SKILL.md","path":".agents/skills/mobilebuildmcp-snapshot-fixture-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/mobilebuildmcp-snapshot-fixture-review/SKILL.md","title":"mobilebuildmcp-snapshot-fixture-review","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp-snapshot-fixture-review\ndescription: Use when reviewing MobileBuildMCP snapshot fixture changes for MCP, CLI, and JSON output contract integrity.\n---\n\n# MobileBuildMCP Snapshot Fixture Review\n\nReview guardrails for fixture and snapshot contract integrity.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/snapshot-tests/__fixtures__/**`\n- `src/snapshot-tests/contracts.ts`\n- `src/snapshot-tests/fixture-io.ts`\n- `src/snapshot-tests/__tests__/fixture-io.test.ts`\n- `src/snapshot-tests/__tests__/json-normalize.test.ts`\n- `src/snapshot-tests/__tests__/json-fixture-schema.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/testing.mdx`\n\n## Guardrails\n\n- Fixture updates map to intentional behavior changes.\n- Do not update fixtures only to make tests pass.\n- MCP, CLI, and JSON fixture updates stay aligned.\n- JSON fixtures preserve stable structured output envelopes.\n- Volatile values are normalized in code, not patched ad hoc in fixtures.\n- Missing fixtures are generated through the snapshot update flow.\n- Verify project-defined normalization sentinels in normalization code and tests before reporting\n them as implausible fixture values. In particular, `99999` is an intentional sentinel for\n volatile UI capture counts.\n- Group every occurrence of the same root cause into one finding and list the affected fixtures.\n Do not emit separate findings for equivalent CLI, MCP, text, or JSON drift.\n- Do not repeat a finding that is already resolved by the current diff.\n\n## Review limits\n\n- Review the changed fixtures and the directly relevant normalization or contract code only.\n- Do not run snapshot or smoke suites as part of an automated PR review.\n- Prefer one high-confidence cross-fixture finding over multiple speculative discrepancies.\n","frontmatter":{"name":"mobilebuildmcp-snapshot-fixture-review","description":"Use when reviewing MobileBuildMCP snapshot fixture changes for MCP, CLI, and JSON output contract integrity."},"isInternal":false,"tokens":393,"sizeBytes":1885},{"name":"SKILL.md","path":".agents/skills/mobilebuildmcp-structured-output-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/mobilebuildmcp-structured-output-review/SKILL.md","title":"mobilebuildmcp-structured-output-review","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp-structured-output-review\ndescription: Use when reviewing MobileBuildMCP structured output schema changes, schema versioning, manifest outputSchema metadata, and JSON fixture compatibility.\n---\n\n# MobileBuildMCP Structured Output Review\n\nReview guardrails for structured output schema correctness and compatibility.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `schemas/structured-output/**`\n- `src/core/structured-output-schema.ts`\n- `src/core/__tests__/structured-output-schema.test.ts`\n- `src/snapshot-tests/__fixtures__/json/**`\n- `src/snapshot-tests/__tests__/json-fixture-schema.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/schema-versioning.mdx`\n- `xcodebuildmcp.com/app/docs/_content/output-formats.mdx`\n\n## Guardrails\n\n- `schema` uses `mobilebuildmcp.output.` format.\n- `schemaVersion` uses integer strings only.\n- Breaking schema changes create a new versioned schema file.\n- Published schema versions are not removed or mutated incompatibly.\n- Manifest `outputSchema` matches emitted `ctx.structuredOutput` payload.\n- JSON fixtures validate against current schema contracts.\n- `$ref` usage remains compatible with bundling in `structured-output-schema.ts`.\n\n## Validation\n\n- `npm run test:schema-fixtures`\n- `npm test -- src/core/__tests__/structured-output-schema.test.ts`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-structured-output-review`\n","frontmatter":{"name":"mobilebuildmcp-structured-output-review","description":"Use when reviewing MobileBuildMCP structured output schema changes, schema versioning, manifest outputSchema metadata, and JSON fixture compatibility."},"isInternal":false,"tokens":338,"sizeBytes":1525},{"name":"SKILL.md","path":".agents/skills/mobilebuildmcp-test-boundary-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/mobilebuildmcp-test-boundary-review/SKILL.md","title":"mobilebuildmcp-test-boundary-review","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp-test-boundary-review\ndescription: Use when reviewing MobileBuildMCP tests for correct unit, snapshot, schema, smoke, and external process boundaries.\n---\n\n# MobileBuildMCP Test Boundary Review\n\nReview guardrails for test isolation, scope, and contract validation.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/**/__tests__/**`\n- `src/test-utils/**`\n- `src/snapshot-tests/**`\n- `scripts/**/__tests__/**`\n- `package.json`\n- `xcodebuildmcp.com/app/docs/_content/testing.mdx`\n- `xcodebuildmcp.com/app/docs/_content/contributing.mdx`\n\n## Guardrails\n\n- Unit tests inject command/filesystem/external dependencies.\n- Unit tests do not call real `xcodebuild`, `xcrun`, AXe, devices, or simulators.\n- Prefer testing logic/executor functions over handler wrappers unless testing runtime integration.\n- Use existing mock executor helpers.\n- Treat snapshot updates as contract changes requiring review.\n- Do not add fake e2e/snapshot state to force test success.\n- Avoid unsafe TypeScript suppressions.\n\n## Validation\n\n- Run targeted Vitest command for touched tests.\n- `npm test`\n- `npm run typecheck`\n- If fixtures/schemas changed: `npm run test:snapshots` and `npm run test:schema-fixtures`\n- `npx skill-check .agents/skills/mobilebuildmcp-test-boundary-review`\n","frontmatter":{"name":"mobilebuildmcp-test-boundary-review","description":"Use when reviewing MobileBuildMCP tests for correct unit, snapshot, schema, smoke, and external process boundaries."},"isInternal":false,"tokens":326,"sizeBytes":1391},{"name":"SKILL.md","path":".agents/skills/mobilebuildmcp-tool-contract-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/mobilebuildmcp-tool-contract-review/SKILL.md","title":"mobilebuildmcp-tool-contract-review","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp-tool-contract-review\ndescription: Use when reviewing MobileBuildMCP tool contract changes across implementation, manifests, workflow membership, output schema metadata, and next-step templates.\n---\n\n# MobileBuildMCP Tool Contract Review\n\nReview guardrails for tool contract changes across implementation, manifests, and workflow exposure.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/mcp/tools/**`\n- `manifests/tools/*.yaml`\n- `manifests/workflows/*.yaml`\n- `src/core/manifest/schema.ts`\n- `src/runtime/tool-catalog.ts`\n- `src/runtime/types.ts`\n- `xcodebuildmcp.com/app/docs/_content/tool-authoring.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-manifest-visibility.mdx`\n\n## Guardrails\n\n- Manifest `id` matches filename.\n- Manifest `module` points to implementation path without extension.\n- Tool module exports named `schema` and `handler`.\n- `names.mcp` remains globally unique.\n- `names.cli` stays workflow-local and consistent with CLI docs/fixtures.\n- Tool appears in at least one workflow unless intentionally hidden by availability.\n- `outputSchema` is present for tools that set `ctx.structuredOutput`.\n- `nextSteps.toolId` references existing manifest tool IDs.\n- Avoid parallel legacy paths or duplicate implementation paths.\n\n## Validation\n\n- `npm run typecheck`\n- `npm test -- src/core/manifest/__tests__/schema.test.ts`\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npx skill-check .agents/skills/mobilebuildmcp-tool-contract-review`\n","frontmatter":{"name":"mobilebuildmcp-tool-contract-review","description":"Use when reviewing MobileBuildMCP tool contract changes across implementation, manifests, workflow membership, output schema metadata, and next-step templates."},"isInternal":false,"tokens":361,"sizeBytes":1613},{"name":"patch-prompt.md","path":".agents/skills/warden-sweep/references/patch-prompt.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/warden-sweep/references/patch-prompt.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"Fix a verified code issue. You are working in a git worktree at: ${WORKTREE}\n\n## Finding\n- Title: ${TITLE}\n- File: ${FILE_PATH}:${START_LINE}\n- Description: ${DESCRIPTION}\n- Verification: ${REASONING}\n- Suggested Fix: ${FIX_DESCRIPTION}\n```diff\n${FIX_DIFF}\n```\n\n## Instructions\n\n### Step 1: Understand the code\nRead the file at ${WORKTREE}/${FILE_PATH}. Read at least 50 lines above and below the reported location. Trace callers and callees of the affected code using Grep/Glob to understand how it is used. Do NOT skip this step.\n\n### Step 2: Apply a minimal fix\nApply the smallest change that addresses the finding. If the suggested diff doesn't apply cleanly, adapt it while preserving intent. Do NOT refactor surrounding code, rename variables, add comments, or make any change beyond what the finding requires.\n\n### Step 3: Write tests\nWrite or update tests that verify the fix:\n- Follow existing test patterns (co-located files, same framework)\n- At minimum, write a test that would have caught the original bug\n- Test the specific edge case, not just the happy path\n\nOnly modify the fix target and its test file.\n\n### Step 4: Self-review\nBefore staging, run `git diff` in the worktree and review every changed line. Verify:\n1. The change addresses the specific finding described, not something else\n2. No unrelated code was modified (no drive-by cleanups, no formatting changes)\n3. Trace through changed code paths: does the fix introduce any new bug, null reference, type error, or broken import?\n4. Tests exercise the fix (the failure case), not just that the code runs\n\nIf ANY check fails, fix the problem before proceeding. If the suggested fix is wrong or would introduce a regression you cannot resolve, do NOT commit. Instead, skip to the output step and report why.\n\n### Step 5: Commit\nDo NOT run tests locally. CI will validate the changes.\n\nStage and commit with this exact message:\n\nfix: ${TITLE}\n\nWarden finding ${FINDING_ID}\nSeverity: ${SEVERITY}\n\nCo-Authored-By: Warden \n\n### Step 6: Output\nReturn ONLY valid JSON (no surrounding text). Use `\"status\": \"applied\"` if you committed a fix, or `\"status\": \"skipped\"` if you did not.\n\n```json\n{\n \"status\": \"applied\",\n \"filesChanged\": [\"src/example.ts\"],\n \"testFilesChanged\": [\"src/example.test.ts\"],\n \"selfReview\": \"Verified the fix addresses the null check and test covers the failure case\",\n \"skipReason\": null\n}\n```\n\nWhen skipping:\n```json\n{\n \"status\": \"skipped\",\n \"filesChanged\": [],\n \"testFilesChanged\": [],\n \"selfReview\": null,\n \"skipReason\": \"The suggested fix would introduce a regression in the error handling path\"\n}\n```\n","isInternal":false,"tokens":633,"sizeBytes":2630},{"name":"verify-prompt.md","path":".agents/skills/warden-sweep/references/verify-prompt.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/warden-sweep/references/verify-prompt.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"Verify a code analysis finding. Determine if this is a TRUE issue or a FALSE POSITIVE.\nDo NOT write or edit any files. Research only.\n\n## Finding\n- Title: ${TITLE}\n- Severity: ${SEVERITY} | Confidence: ${CONFIDENCE}\n- Skill: ${SKILL}\n- Location: ${FILE_PATH}:${START_LINE}-${END_LINE}\n- Description: ${DESCRIPTION}\n- Verification hint: ${VERIFICATION}\n\n## Instructions\n1. Read the file at the reported location. Examine at least 50 lines of surrounding context.\n2. Trace data flow to/from the flagged code using Grep/Glob.\n3. Check if the issue is mitigated elsewhere (guards, validation, try/catch upstream).\n4. Check if the issue is actually reachable in practice.\n\nReturn your verdict as JSON:\n{\n \"findingId\": \"${FINDING_ID}\",\n \"verdict\": \"verified\" or \"rejected\",\n \"confidence\": \"high\" or \"medium\" or \"low\",\n \"reasoning\": \"2-3 sentence explanation\",\n \"traceNotes\": \"What code paths you examined\"\n}\n","isInternal":false,"tokens":231,"sizeBytes":907},{"name":"SKILL.md","path":".agents/skills/warden-sweep/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/warden-sweep/SKILL.md","title":"warden-sweep","category":"anthropic-skill","format":"markdown","content":"---\nname: warden-sweep\ndescription: Full-repository code sweep. Scans every file with warden, verifies findings via deep tracing, creates draft PRs for validated issues. Use when asked to \"sweep the repo\", \"scan everything\", \"find all bugs\", \"full codebase review\", \"batch code analysis\", or run warden across the entire repository.\ndisable-model-invocation: true\n---\n\n# Warden Sweep\n\nFull-repository code sweep: scan every file, verify findings with deep tracing, create draft PRs for validated issues.\n\n**Requires**: `warden`, `gh`, `git`, `jq`, `uv`\n\n**Important**: Run all scripts from the repository root using `${CLAUDE_SKILL_ROOT}`. Output goes to `.warden/sweeps//`.\n\n## Bundled Scripts\n\n### `scripts/scan.py`\n\nRuns setup and scan in one call: generates run ID, creates sweep dir, checks deps, creates `warden` label, enumerates files, runs warden per file, extracts findings.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py [file ...]\n --sweep-dir DIR # Resume into existing sweep dir\n```\n\n### `scripts/index_prs.py`\n\nFetches open warden-labeled PRs, builds file-to-PR dedup index, caches diffs for overlapping PRs.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/index_prs.py \n```\n\n### `scripts/create_issue.py`\n\nCreates a GitHub tracking issue summarizing sweep results. Run after verification, before patching.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/create_issue.py \n```\n\n### `scripts/organize.py`\n\nTags security findings, labels security PRs, updates finding reports with PR links, posts final results to tracking issue, generates summary report, finalizes manifest.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/organize.py \n```\n\n### `scripts/extract_findings.py`\n\nParses warden JSONL log files and extracts normalized findings. Called automatically by `scan.py`.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/extract_findings.py -o \n```\n\n### `scripts/generate_report.py`\n\nBuilds `summary.md` and `report.json` from sweep data. Called automatically by `organize.py`.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/generate_report.py \n```\n\n### `scripts/find_reviewers.py`\n\nFinds top 2 git contributors for a file (last 12 months).\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/find_reviewers.py \n```\n\nReturns JSON: `{\"reviewers\": [\"user1\", \"user2\"]}`\n\n---\n\n## Phase 1: Scan\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py\n```\n\nTo resume a partial scan:\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py --sweep-dir .warden/sweeps/\n```\n\nParse the JSON stdout. Save `runId` and `sweepDir` for subsequent phases.\n\n**Report** to user:\n\n```\n## Scan Complete\n\nScanned **{filesScanned}** files, **{filesTimedOut}** timed out, **{filesErrored}** errors.\n\n### Findings ({totalFindings} total)\n\n| # | Severity | Skill | File | Title |\n|---|----------|-------|------|-------|\n| 1 | **HIGH** | security-review | `src/db/query.ts:42` | SQL injection in query builder |\n...\n```\n\nRender every finding from the `findings` array. Bold severity for high and above.\n\n**On failure**: If exit code 1, show the error JSON and stop. If exit code 2, show the partial results. List timed-out files separately from errored files so users know which can be retried.\n\n---\n\n## Phase 2: Verify\n\nDeep-trace each finding using Task subagents to qualify or disqualify.\n\n**For each finding in `data/all-findings.jsonl`:**\n\nCheck if `data/verify/.json` already exists (incrementality). If it does, skip.\n\nLaunch a Task subagent (`subagent_type: \"general-purpose\"`) for each finding. Process findings in parallel batches of up to 8 to improve throughput.\n\n**Task prompt for each finding:**\n\nRead `${CLAUDE_SKILL_ROOT}/references/verify-prompt.md` for the prompt template. Substitute the finding's values into the `${...}` placeholders.\n\n**Process results:**\n\nParse the JSON from the subagent response and:\n- Write result to `data/verify/.json`\n- Append to `data/verified.jsonl` or `data/rejected.jsonl`\n- For verified findings, generate `findings/.md`:\n\n```markdown\n# ${TITLE}\n\n**ID**: ${FINDING_ID} | **Severity**: ${SEVERITY} | **Confidence**: ${CONFIDENCE}\n**Skill**: ${SKILL} | **File**: ${FILE_PATH}:${START_LINE}\n\n## Description\n${DESCRIPTION}\n\n## Verification\n**Verdict**: Verified (${VERIFICATION_CONFIDENCE})\n**Reasoning**: ${REASONING}\n**Code trace**: ${TRACE_NOTES}\n\n## Suggested Fix\n${FIX_DESCRIPTION}\n```diff\n${FIX_DIFF}\n```\n```\n\nUpdate manifest: set `phases.verify` to `\"complete\"`.\n\n**Report** to user after all verifications:\n\n```\n## Verification Complete\n\n**{verified}** verified, **{rejected}** rejected.\n\n### Verified Findings\n\n| # | Severity | Confidence | File | Title | Reasoning |\n|---|----------|------------|------|-------|-----------|\n| 1 | **HIGH** | high | `src/db/query.ts:42` | SQL injection in query builder | User input flows directly into... |\n...\n\n### Rejected ({rejected_count})\n\n- `{findingId}` {file}: {reasoning}\n...\n```\n\n---\n\n## Phase 3: Issue\n\nCreate a tracking issue that ties all PRs together and gives reviewers a single overview.\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/create_issue.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout. Save `issueUrl` and `issueNumber` for Phase 4.\n\n**Report** to user:\n\n```\n## Tracking Issue Created\n\n{issueUrl}\n```\n\n**On failure**: Show the error. Continue to Phase 4 (PRs can still be created without a tracking issue).\n\n---\n\n## Phase 4: Patch\n\nFor each verified finding, create a worktree, fix the code, and open a draft PR. Process findings **sequentially** (one at a time) since parallel subagents cross-contaminate worktrees.\n\n**Severity triage**: Patch HIGH and above. For MEDIUM, only patch findings from bug-detection skills (e.g., `code-review`, `security-review`). Skip LOW and INFO findings.\n\n**Step 0: Setup** (run once before the loop):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/index_prs.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout. Use `fileIndex` for dedup checks.\n\nDetermine the default branch and fetch latest so worktrees branch from current upstream:\n\n```bash\nDEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')\ngit fetch origin \"${DEFAULT_BRANCH}\"\n```\n\n**For each finding in `data/verified.jsonl`:**\n\nCheck if finding ID already exists in `data/patches.jsonl` (incrementality). If it does, skip.\n\n**Dedup check**: Use the file index from `index_prs.py` output to determine if an existing open PR already addresses the same issue.\n\n1. **File match**: Look up the finding's file path in the `fileIndex`. If no PR touches that file, no conflict; proceed to Step 1.\n2. **Chunk overlap**: If a PR does touch the same file, read its cached diff from `data/pr-diffs/.diff` and check whether the PR's changed hunks overlap with the finding's line range (startLine-endLine). Overlapping or adjacent hunks (within ~10 lines) indicate the same code region.\n3. **Same concern**: If the hunks overlap, compare the PR title and the finding title/description. Are they fixing the same kind of defect? A PR fixing an off-by-one error and a finding about a null check in the same function are different issues; both should proceed.\n\nSkip the finding only when there is both chunk overlap AND the PR addresses the same concern. Record it in `data/patches.jsonl` with `\"status\": \"existing\"` and `\"prUrl\"` pointing to the matching PR, then continue to the next finding.\n\n**Step 1: Create worktree**\n\n```bash\nBRANCH=\"warden-sweep/${RUN_ID}/${FINDING_ID}\"\nWORKTREE=\"${SWEEP_DIR}/worktrees/${FINDING_ID}\"\ngit worktree add \"${WORKTREE}\" -b \"${BRANCH}\" \"origin/${DEFAULT_BRANCH}\"\n```\n\nEach finding branches from the repo's default branch so PRs contain only the fix commit.\n\n**Step 2: Generate fix**\n\nLaunch a Task subagent (`subagent_type: \"general-purpose\"`) to apply the fix in the worktree. Read `${CLAUDE_SKILL_ROOT}/references/patch-prompt.md` for the prompt template. Substitute the finding's values and worktree path into the `${...}` placeholders.\n\n**Step 2b: Handle skipped findings**\n\nIf the subagent returned `\"status\": \"skipped\"` (not `\"applied\"`), do NOT proceed to Steps 3-4. Instead:\n1. Record the finding in `data/patches.jsonl` with `\"status\": \"error\"` and `\"error\": \"Subagent skipped: ${skipReason}\"`\n2. Clean up the worktree\n3. Continue to the next finding\n\n**Step 3: Find reviewers**\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/find_reviewers.py \"${FILE_PATH}\"\n```\n\n**Step 4: Create draft PR**\n\n```bash\ncd \"${WORKTREE}\" && git push -u origin HEAD:\"${BRANCH}\"\n```\n\nCreate the PR with a 1-2 sentence \"What\" summary based on the finding and fix, followed by the finding description and verification reasoning:\n\n```bash\nREVIEWERS=\"\"\n# If find_reviewers.py returned reviewers, build the flags\n# e.g., REVIEWERS=\"--reviewer user1 --reviewer user2\"\n\ngh pr create --draft \\\n --label \"warden\" \\\n --title \"fix: ${TITLE}\" \\\n --body \"$(cat <<'EOF'\n${FIX_WHAT_DESCRIPTION}\n\n${DESCRIPTION}\n\n${REASONING}\n\nAutomated fix for Warden finding ${FINDING_ID} (${SEVERITY}, detected by ${SKILL}).\n\n\nRef #${ISSUE_NUMBER}\n\n> This PR was auto-generated by a Warden Sweep (run ${RUN_ID}).\n> The finding has been validated through automated deep tracing,\n> but human confirmation is requested as this is batch work.\nEOF\n)\" ${REVIEWERS}\n```\n\nSave the PR URL.\n\n**Step 5: Record and cleanup**\n\nAppend to `data/patches.jsonl` (use `\"created\"` as status for successful PRs, not the subagent's `\"applied\"`):\n```json\n{\"findingId\": \"...\", \"prUrl\": \"https://...\", \"branch\": \"...\", \"reviewers\": [\"user1\", \"user2\"], \"filesChanged\": [\"...\"], \"status\": \"created|existing|error\"}\n```\n\nRemove the worktree:\n```bash\ncd \"$(git rev-parse --show-toplevel)\"\ngit worktree remove \"${WORKTREE}\" --force\n```\n\n**Error handling**: On failure at any step, write to `data/patches.jsonl` with `\"status\": \"error\"` and `\"error\": \"...\"`, clean up the worktree, and continue to the next finding.\n\nUpdate manifest: set `phases.patch` to `\"complete\"`.\n\n**Report** to user after all patches:\n\n```\n## PRs Created\n\n**{created}** created, **{skipped}** skipped (existing), **{failed}** failed.\n\n| # | Finding | PR | Status |\n|---|---------|-----|--------|\n| 1 | `security-review-a1b2c3d4` SQL injection in query builder | #142 | created |\n| 2 | `code-review-e5f6g7h8` Null pointer in handler | - | existing (#138) |\n...\n```\n\n---\n\n## Phase 5: Organize\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/organize.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout.\n\n**Report** to user:\n\n```\n## Sweep Complete\n\n| Metric | Count |\n|--------|-------|\n| Files scanned | {filesScanned} |\n| Findings verified | {verified} |\n| PRs created | {prsCreated} |\n| Security findings | {securityFindings} |\n\nFull report: `{summaryPath}`\n```\n\n**On failure**: Show the error and note which steps completed.\n\n---\n\n## Resuming a Sweep\n\nEach phase is incremental. To resume from where you left off:\n\n1. Check `data/manifest.json` to see which phases are complete\n2. For scan: pass `--sweep-dir` to `scan.py`\n3. For verify: existing `data/verify/.json` files are skipped\n4. For issue: `create_issue.py` is idempotent (skips if `issueUrl` in manifest)\n5. For patch: existing entries in `data/patches.jsonl` are skipped\n6. For organize: safe to re-run (idempotent)\n\n## Output Directory Structure\n\n```\n.warden/sweeps//\n summary.md # Stats, key findings, PR links\n findings/ # One markdown per verified finding\n .md\n security/ # Security-specific view\n index.jsonl # Security findings index\n .md # Copies of security findings\n data/ # Structured data for tooling\n manifest.json # Run metadata, phase state\n scan-index.jsonl # Per-file scan tracking\n all-findings.jsonl # Every finding from scan\n verified.jsonl # Findings that passed verification\n rejected.jsonl # Findings that failed verification\n patches.jsonl # Finding -> PR URL -> reviewers\n existing-prs.json # Cached open warden PRs\n report.json # Machine-readable summary\n verify/ # Individual verification results\n .json\n logs/ # Warden JSONL logs per file\n .jsonl\n pr-diffs/ # Cached PR diffs for dedup\n .diff\n```\n","frontmatter":{"name":"warden-sweep","description":"Full-repository code sweep. Scans every file with warden, verifies findings via deep tracing, creates draft PRs for validated issues. Use when asked to \"sweep the repo\", \"scan everything\", \"find all bugs\", \"full codebase review\", \"batch code analysis\", or run warden across the entire repository.","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":3246,"sizeBytes":12666},{"name":"cli-reference.md","path":".agents/skills/warden/references/cli-reference.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/warden/references/cli-reference.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# CLI Reference\n\n## Usage\n\n```\nwarden [command] [targets...] [options]\n```\n\nAnalyze code for security issues and code quality.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `(default)` | Run analysis on targets or using warden.toml skills |\n| `init` | Initialize warden.toml and GitHub workflow |\n| `add [skill]` | Add a skill to warden.toml |\n| `sync [remote]` | Update cached remote skills to latest |\n| `setup-app` | Create a GitHub App for Warden via manifest flow |\n\n## Targets\n\n| Target | Description |\n|--------|-------------|\n| `` | Analyze specific files (e.g., `src/auth.ts`) |\n| `` | Analyze files matching pattern (e.g., `\"src/**/*.ts\"`) |\n| `` | Analyze changes from git ref (e.g., `HEAD~3`, `main..feature`) |\n| `(none)` | Analyze uncommitted changes using warden.toml skills |\n\nAmbiguous targets (no path separator, no extension) are resolved by checking if a file exists at the path. Use `--git` to force git ref interpretation.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--skill ` | Run only this skill (default: run all built-in skills) |\n| `--config ` | Path to warden.toml (default: `./warden.toml`) |\n| `-m, --model ` | Model to use (fallback when not set in config) |\n| `--json` | Output results as JSON |\n| `-o, --output ` | Write full run output to a JSONL file |\n| `--fail-on ` | Exit with code 1 if findings >= severity |\n| `--report-on ` | Only show findings >= severity in output |\n| `--fix` | Automatically apply all suggested fixes |\n| `--parallel ` | Max concurrent skill executions (default: 4) |\n| `--git` | Force ambiguous targets to be treated as git refs |\n| `--offline` | Use cached remote skills without network access |\n| `-q, --quiet` | Errors and final summary only |\n| `-v, --verbose` | Show real-time findings and hunk details |\n| `-vv` | Show debug info (token counts, latencies) |\n| `--debug` | Enable debug output (equivalent to `-vv`) |\n| `--log` | Use log output (no animations, timestamped) |\n| `--color / --no-color` | Override color detection |\n| `-h, --help` | Show help message |\n| `-V, --version` | Show version number |\n\n## Per-Command Options\n\n**Init:**\n| Option | Description |\n|--------|-------------|\n| `-f, --force` | Overwrite existing files |\n\n**Add:**\n| Option | Description |\n|--------|-------------|\n| `--list` | List available skills |\n| `--remote ` | Remote repository (`owner/repo`, URL, or with `@sha`) |\n| `--force` | Bypass skill cache and fetch latest |\n\n**Sync:**\n| Option | Description |\n|--------|-------------|\n| `--remote ` | Specific remote to sync (default: all) |\n\n**Setup-app:**\n| Option | Description |\n|--------|-------------|\n| `--org ` | Create under organization (default: personal) |\n| `--port ` | Local server port (default: 3000) |\n| `--timeout ` | Callback timeout in seconds (default: 300) |\n| `--name ` | Custom app name (default: Warden) |\n| `--no-open` | Print URL instead of opening browser |\n\n## Severity Levels\n\nUsed in `--fail-on` and `--report-on`:\n\n| Level | Meaning |\n|-------|---------|\n| `high` | Must fix before merge |\n| `medium` | Worth reviewing |\n| `low` | Minor improvement |\n| `off` | Disable the threshold |\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | No findings at or above `--fail-on` threshold |\n| `1` | Findings at or above `--fail-on` threshold |\n\n## Examples\n\n```bash\n# Initialize\nwarden init\n\n# Interactive skill selection\nwarden add\nwarden add \nwarden add --list\n\n# Remote skills\nwarden add --remote / --skill \nwarden add --remote https://github.com// --skill \nwarden add --remote /@ --skill \n\n# Run analysis\nwarden # Skills from warden.toml\nwarden src/auth.ts # Specific file\nwarden src/auth.ts --skill \nwarden \"src/**/*.ts\" # Glob pattern\nwarden HEAD~3 # Git changes\nwarden HEAD~3 --skill \nwarden main..HEAD # Branch diff\n\n# Output control\nwarden --json\nwarden --fail-on high\nwarden -o results.jsonl\n\n# Fix mode\nwarden --fix\n\n# Cached skills only\nwarden --offline\nwarden sync # Update all unpinned remote skills\n\n# GitHub App setup\nwarden setup-app\nwarden setup-app --org myorg\n```\n","isInternal":false,"tokens":1174,"sizeBytes":4433},{"name":"config-schema.md","path":".agents/skills/warden/references/config-schema.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/warden/references/config-schema.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# warden.toml Configuration Schema\n\n## Top-Level Structure\n\n```toml\nversion = 1 # Required, must be 1\n\n[defaults] # Optional, inherited by all skills\n[[skills]] # Required, array of skill configs\n```\n\n## Defaults Section\n\n```toml\n[defaults]\nmodel = \"claude-sonnet-4-20250514\" # Default model\nmaxTurns = 50 # Max agentic turns per hunk\ndefaultBranch = \"main\" # Base branch for comparisons\nfailOn = \"high\" # Exit 1 if findings >= this severity\nreportOn = \"medium\" # Show findings >= this severity\nmaxFindings = 50 # Max findings to report (0 = unlimited)\nreportOnSuccess = false # Post report even with no findings\npaths = [\"src/**/*.ts\"] # Include only matching files\nignorePaths = [\"*.test.ts\"] # Exclude matching files\n\n[defaults.chunking]\nenabled = true # Enable hunk-based chunking\n\n[defaults.chunking.coalesce]\nenabled = true # Merge nearby hunks\nmaxGapLines = 30 # Lines between hunks to merge\nmaxChunkSize = 8000 # Max chars per chunk\n\n[[defaults.chunking.filePatterns]]\npattern = \"*.config.*\" # Glob pattern\nmode = \"whole-file\" # per-hunk | whole-file | skip\n```\n\n## Skills Section\n\n```toml\n[[skills]]\nname = \"skill-name\" # Required, unique identifier\nremote = \"owner/repo@sha\" # Optional, fetch skill from GitHub repo\npaths = [\"src/**\"] # Include only matching files\nignorePaths = [\"**/*.test.ts\"] # Exclude matching files\n\n# Optional overrides (inherit from defaults if not set)\nmodel = \"claude-opus-4-20250514\"\nmaxTurns = 100\nfailOn = \"high\"\nreportOn = \"medium\"\nmaxFindings = 20\nreportOnSuccess = true\n\n[[skills.triggers]]\ntype = \"pull_request\" # Required: pull_request | local | schedule\nactions = [\"opened\", \"synchronize\"] # Required for pull_request\n\n# Schedule-specific (only for type = \"schedule\")\n[[skills.triggers]]\ntype = \"schedule\"\n\n[skills.triggers.schedule]\nissueTitle = \"Daily Security Review\" # GitHub issue title for tracking\ncreateFixPR = true # Create PR with fixes\nfixBranchPrefix = \"security-fix\" # Branch name prefix\n```\n\n**Trigger types:**\n- `pull_request` - Triggers on PR events\n- `local` - Local CLI only (will not run in CI)\n- `schedule` - Cron schedule (GitHub Action only)\n\nAll skills run locally regardless of trigger type. Skills with no triggers run everywhere (wildcard). Use `type = \"local\"` for skills that should *only* run locally.\n\n**Actions (for pull_request):**\n- `opened`, `synchronize`, `reopened`, `closed`\n\n## Severity Values\n\nUsed in `failOn` and `reportOn`:\n- `high` - Must fix before merge\n- `medium` - Worth reviewing\n- `low` - Minor improvement\n- `off` - Disable threshold\n\n## Built-in Skip Patterns\n\nAlways skipped (cannot be overridden):\n- Package locks: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `Cargo.lock`, etc.\n- Minified files: `**/*.min.js`, `**/*.min.css`\n- Build artifacts: `dist/`, `build/`, `node_modules/`, `.next/`, `__pycache__/`\n- Generated code: `*.generated.*`, `*.g.ts`, `__generated__/`\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required) |\n| `WARDEN_MODEL` | Default model (lowest priority) |\n| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |\n| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |\n\n## Model Precedence (highest to lowest)\n\n1. Skill-level `model`\n2. `[defaults]` `model`\n3. CLI `--model` flag\n4. `WARDEN_MODEL` env var\n5. SDK default\n","isInternal":false,"tokens":945,"sizeBytes":3679},{"name":"configuration.md","path":".agents/skills/warden/references/configuration.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/warden/references/configuration.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Configuration (warden.toml)\n\nSee [config-schema.md](config-schema.md) for the complete schema reference.\n\n## Minimal Example\n\nThe `name` field references a skill you've created (via `warden add`) or defined in `.agents/skills//SKILL.md`. Use that same name everywhere — in config, CLI flags, and triggers.\n\n```toml\nversion = 1\n\n[defaults]\nmodel = \"claude-sonnet-4-20250514\"\n\n[[skills]]\nname = \"my-skill\" # matches .agents/skills/my-skill/SKILL.md\npaths = [\"src/**/*.ts\"]\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n## Skill Configuration\n\nSkills define what to analyze and when. Each skill requires a name. Triggers are optional — skills with no triggers run everywhere (PR, local, schedule). All skills run locally regardless of trigger type.\n\n```toml\n[[skills]]\nname = \"my-skill\"\npaths = [\"src/auth/**\", \"src/payments/**\"]\nfailOn = \"high\"\nreportOn = \"medium\"\nmaxFindings = 20\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Trigger types:** `pull_request`, `local` (local-only), `schedule` (CI-only)\n\n**Actions (pull_request):** `opened`, `synchronize`, `reopened`, `closed`\n\n## Common Patterns\n\n**Strict checks on critical files:**\n```toml\n[[skills]]\nname = \"my-skill\"\nmodel = \"claude-opus-4-20250514\"\nmaxTurns = 100\npaths = [\"src/auth/**\", \"src/payments/**\"]\nfailOn = \"high\"\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Skip test files:**\n```toml\n[[skills]]\nname = \"my-skill\"\npaths = [\"src/**/*.ts\"]\nignorePaths = [\"**/*.test.ts\", \"**/*.spec.ts\"]\n```\n\n**Whole-file analysis for configs:**\n```toml\n[defaults.chunking.filePatterns]\npattern = \"*.config.*\"\nmode = \"whole-file\"\n```\n\n## Model Precedence\n\nFrom highest to lowest priority:\n\n1. Skill-level `model`\n2. `[defaults]` `model`\n3. CLI `--model` flag\n4. `WARDEN_MODEL` env var\n5. SDK default\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required unless using Claude Code subscription) |\n| `WARDEN_MODEL` | Default model (lowest priority) |\n| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |\n| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |\n\n## Troubleshooting\n\n**No findings reported:**\n- Check `--report-on` threshold (default shows all)\n- Verify skill matches file types in `paths`\n- Use `-v` to see which files are being analyzed\n\n**Files being skipped:**\n- Built-in skip patterns: lock files, minified, `node_modules/`, `dist/`\n- Check `ignorePaths` in config\n- Use `-vv` to see skip reasons\n\n**Token/cost issues:**\n- Reduce `maxTurns` (default: 50)\n- Use chunking settings to control chunk size\n- Filter to relevant files with `paths`\n","isInternal":false,"tokens":763,"sizeBytes":2779},{"name":"creating-skills.md","path":".agents/skills/warden/references/creating-skills.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/warden/references/creating-skills.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Creating Skills\n\nSkills are markdown files that tell Warden what to look for. They follow the [agentskills.io](https://agentskills.io) specification.\n\n## Skill Discovery\n\nWarden searches these directories in order (first match wins):\n\n```\n.agents/skills/{name}/SKILL.md # Primary (recommended)\n.claude/skills/{name}/SKILL.md # Backup (Claude Code convention)\n```\n\n## SKILL.md Format\n\n```markdown\n---\nname: my-skill\ndescription: What this skill analyzes\nallowed-tools: Read Grep Glob\n---\n\n[Analysis instructions for the agent]\n\n## What to Look For\n- Specific issue type 1\n- Specific issue type 2\n\n## Output Format\nReport findings with severity, location, and suggested fix.\n```\n\n## Available Tools\n\n`Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Bash`, `Write`, `Edit`\n\nMost review skills only need `Read`, `Grep`, and `Glob` for exploring context.\n\n## Writing Checklist\n\n- One skill, one concern (\"security review\" not \"code quality\")\n- Clear criteria for what counts as an issue and at what severity\n- Actionable findings that include how to fix\n- Examples of good and bad code where helpful\n\n## Remote Skills\n\nSkills can be fetched from GitHub repositories:\n\n```bash\n# Add a remote skill\nwarden add --remote / --skill \n\n# Add with version pinning (recommended for reproducibility)\nwarden add --remote /@ --skill \n\n# List skills in a remote repo\nwarden add --remote / --list\n\n# Update all unpinned remote skills\nwarden sync\n\n# Update specific repo\nwarden sync /\n\n# Run with cached skills only (no network)\nwarden --offline\n```\n\n**Remote skill in warden.toml:**\n\n```toml\n[[skills]]\nname = \"my-skill\"\nremote = \"/@\"\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Cache location:** `~/.local/warden/skills/` (override with `WARDEN_STATE_DIR`)\n\n**Cache TTL:** 24 hours for unpinned refs (override with `WARDEN_SKILL_CACHE_TTL` in seconds)\n","isInternal":false,"tokens":512,"sizeBytes":1972},{"name":"SKILL.md","path":".agents/skills/warden/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/.agents/skills/warden/SKILL.md","title":"warden","category":"anthropic-skill","format":"markdown","content":"---\nname: warden\ndescription: Run Warden to analyze code changes before committing. Use when asked to \"run warden\", \"check my changes\", \"review before commit\", \"warden config\", \"warden.toml\", \"create a warden skill\", \"add trigger\", or any Warden-related local development task.\n---\n\nRun Warden to analyze code changes before committing.\n\n## References\n\nRead the relevant reference when the task requires deeper detail:\n\n| Document | Read When |\n|----------|-----------|\n| `${CLAUDE_SKILL_ROOT}/references/cli-reference.md` | Full option details, per-command flags, examples |\n| `${CLAUDE_SKILL_ROOT}/references/configuration.md` | Editing warden.toml, triggers, patterns, troubleshooting |\n| `${CLAUDE_SKILL_ROOT}/references/config-schema.md` | Exact field names, types, and defaults |\n| `${CLAUDE_SKILL_ROOT}/references/creating-skills.md` | Writing custom skills, remote skills, skill discovery |\n\n## Running Warden\n\n```bash\n# Analyze uncommitted changes (uses warden.toml triggers)\nwarden\n\n# Run a specific skill\nwarden --skill \n\n# Analyze specific files\nwarden src/auth.ts src/database.ts\n\n# Analyze changes from a git ref\nwarden main..HEAD\nwarden HEAD~3\n\n# Auto-apply suggested fixes\nwarden --fix\n\n# Fail on high-severity findings\nwarden --fail-on high\n```\n\nSet `WARDEN_ANTHROPIC_API_KEY` or log in via `claude login` before running.\n\n## Pre-Commit Workflow\n\nAfter making code changes and before committing:\n\n1. Run `warden` to analyze uncommitted changes\n2. Review the findings\n3. Fix issues Warden reports (or use `warden --fix` to auto-apply)\n4. Commit the changes\n\nRun Warden once to validate work. Do not loop re-running Warden on the same changes.\n\n## Reading Output\n\n**Severity levels:**\n- `high` - Must fix before merge\n- `medium` - Worth reviewing\n- `low` - Minor improvement\n\n**Exit codes:** `0` = no findings at or above fail threshold. `1` = findings at or above fail threshold.\n\n**Verbosity:** `-v` shows real-time findings. `-vv` shows debug info (tokens, latency). `-q` shows errors and summary only.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `warden` | Run analysis (default) |\n| `warden init` | Initialize warden.toml and GitHub workflow |\n| `warden add [skill]` | Add skill trigger to warden.toml |\n| `warden sync [remote]` | Update cached remote skills |\n| `warden setup-app` | Create GitHub App via manifest flow |\n\nFor full options and flags, read `${CLAUDE_SKILL_ROOT}/references/cli-reference.md`.\n","frontmatter":{"name":"warden","description":"Run Warden to analyze code changes before committing. Use when asked to \"run warden\", \"check my changes\", \"review before commit\", \"warden config\", \"warden.toml\", \"create a warden skill\", \"add trigger\", or any Warden-related local development task."},"isInternal":false,"tokens":617,"sizeBytes":2464},{"name":"SKILL.md","path":"skills/mobilebuildmcp-cli/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/skills/mobilebuildmcp-cli/SKILL.md","title":"mobilebuildmcp-cli","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp-cli\ndescription: Official skill for the MobileBuildMCP CLI. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).\n---\n\n# MobileBuildMCP CLI\n\nUse MobileBuildMCP tools via the `mobilebuildmcp` executable instead of raw `xcodebuild`, `xcrun`, or `simctl`.\n\n## Step 1: Ensure the CLI Exists\n\nCheck availability:\n```bash\nmobilebuildmcp --help\n```\n\nIf missing, install with one of:\n```bash\nbrew tap getsentry/xcodebuildmcp\nbrew install mobilebuildmcp\n```\n\n```bash\nnpm install -g mobilebuildmcp@latest\n```\n\nRe-check after install:\n```bash\nmobilebuildmcp --help\n```\n\n## Step 2: Use Help-First Discovery\n\nDiscover workflows and arguments from the CLI itself:\n```bash\nmobilebuildmcp --help\nmobilebuildmcp tools\nmobilebuildmcp --help\nmobilebuildmcp --help\n```\n\nUse this discovery path instead of memorizing static tool lists.\n\n## Step 3: Keep Execution Minimal\n\n- Choose the smallest command sequence that satisfies the request.\n- Prefer direct workflow commands over manual multi-step chains unless explicitly requested.\n- For simulator run intent, prefer the combined `build-and-run` command.\n- Do not chain `build` then `build-and-run` unless explicitly requested.\n\n## Capability Overview\n\n`mobilebuildmcp` supports:\n- simulator and device build/test/run\n- debugging and log capture\n- UI automation\n- project discovery and scaffolding\n- session defaults and workflow configuration\n\n## Exit Criteria\n\n- CLI presence is verified or installation steps are provided.\n- Commands are discovered via `--help` / `tools`.\n- Session defaults are checked before first build/run/test action.\n","frontmatter":{"name":"mobilebuildmcp-cli","description":"Official skill for the MobileBuildMCP CLI. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation)."},"isInternal":false,"tokens":403,"sizeBytes":1671},{"name":"SKILL.md","path":"skills/mobilebuildmcp/SKILL.md","rawUrl":"https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/HEAD/skills/mobilebuildmcp/SKILL.md","title":"mobilebuildmcp","category":"anthropic-skill","format":"markdown","content":"---\nname: mobilebuildmcp\ndescription: Official skill for MobileBuildMCP. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).\n---\n\n# MobileBuildMCP\n\nUse MobileBuildMCP tools instead of raw `xcodebuild`, `xcrun`, or `simctl`.\n\nCapabilities:\n- Session defaults: Configure project, scheme, simulator, and device defaults to avoid repetitive parameters\n- Project discovery: Find Xcode projects/workspaces, list schemes, inspect build settings\n- Simulator workflows: Build, run, test, install, and launch apps on iOS simulators; manage simulator state (boot, erase, location, appearance)\n- Device workflows: Build, test, install, and launch apps on physical devices with code signing\n- macOS workflows: Build, run, and test macOS applications\n- Log capture: Stream and capture logs from simulators and devices\n- LLDB debugging: Attach debugger, set breakpoints, inspect stack traces and variables, execute LLDB commands\n- UI automation: Capture screenshots, inspect view hierarchy with coordinates, perform taps/swipes/gestures, type text, press hardware buttons\n- SwiftPM: Build, run, test, and manage Swift Package Manager projects\n- Project scaffolding: Generate new iOS/macOS project templates\n\nOnly simulator workflow tools are enabled by default. If capabilities like device, macOS, debugging, or UI automation are not available, the user must configure MobileBuildMCP to enable them. See https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/configuration.mdx for workflow configuration.\n\n## Step 1: Establish Session Context\n\n- Call `session_show_defaults` before the first build/run/test action in a session.\n- Use `discover_projs` only when defaults show missing or incorrect project/workspace context.\n- Do not run discovery speculatively or in parallel with `session_show_defaults`.\n- For simulator run intent, prefer the combined build-and-run tool instead of separate build then run calls.\n- Do not chain build-only then build-and-run unless the user explicitly requests both.\n\n## Step 2: Understand Workflow-Scoped Tool Availability\n\n- Not all tools are enabled by default; tool availability depends on enabled workflows.\n- If a tool is expected but missing, check enabled workflows first.\n- Update enabled workflows in `.mobilebuildmcp/config.yaml`, then ask user to reload/restart the session to surface refreshes.\n\n## Step 3: Report Context Clearly\n\n- Return the active defaults context used for execution (project/workspace, scheme, simulator/device).\n- For failures, include the exact failing step and the next actionable command/tool call.\n","frontmatter":{"name":"mobilebuildmcp","description":"Official skill for MobileBuildMCP. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation)."},"isInternal":false,"tokens":553,"sizeBytes":2623}],"systemPromptSnippet":"\n\n# Development Rules\n\n## Build & Test\n- `npm run build` - Build (wireit + tsup, ESM)\n- `npm run test` - Unit/integration tests (Vitest)\n- `npm run test:smoke` - Smoke tests (builds first, serial execution)\n- `npm run lint` / `npm run lint:fix` - ESLint\n- `npm run format` / `npm run format:check` - Prettier\n- `npm run typecheck` - TypeScript type checking (src + test config)\n\n## Architecture\nESM TypeScript project (`type: module`). Key layers:\n\n- `src/cli/` - CLI entrypoint, yargs wiring, daemon routing\n- `src/server/` - MCP stdio server, lifecycle, workflow/resource registration\n- `src/runtime/` - Config bootstrap, session state, tool catalog assembly\n- `src/core/manifest/` - YAML manifest loading, validation, tool module imports\n- `src/mcp/tools/` - Tool implementations grouped by workflow (mirrors `manifests/workflows/`)\n- `src/mcp/resources/` - MCP resource implementations\n- `src/integrations/` - External integrations (Xcode tools bridge)\n- `src/utils/` - Shared helpers (execution, logging, validation, responses)\n- `src/visibility/` - Tool/workflow exposure predicates\n- `src/daemon/` - Background daemon for persistent sessions\n- `src/rendering/` - Output rendering and formatting\n- `src/types/` - Shared type definitions\n\n## Contributing Workflow\n1. Create a branch from `main`\n2. Make changes following the conventions in this file\n3. Run the pre-commit checklist before committing:\n ```bash\n npm run lint:fix\n npm run typecheck\n npm run format\n npm run build\n npm test\n ```\n4. Update `CHANGELOG.md` under `## [Unreleased]`\n5. Update documentation if adding or modifying features\n6. Clone and test against example projects (e.g., `XcodeBuildMCP-iOS-Template`) when changes affect runtime behavior\n7. Push and create a pull request with a clear description\n8. Link any related issues\n\n## Code Quality\n- No `any` types unless absolutely necessary\n- Check node_modules for external API type definitions instead of guessing\n- **NEVER use inline imports** - no `await import(\"./foo.js\")`, no `import(\"pkg\").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.\n- NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead\n- Always ask before removing functionality or code that appears to be intentional\n- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.\n- Review the complete merge-base diff and trace changed or reused helper contracts, including error and sentinel returns, through callers, consumers, tests, and operational configuration.\n- Verify standard quality commands include every changed path and exercise exact entry points and argument variants; validate explicitly when they do not.\n- For asynchronous, workflow, or process-boundary changes, enumerate lifecycle states, retries, supersession, and race transitions; test terminal outcomes and missing or optional metadata.\n\n## Import Conventions\n- ESM with explicit `.ts` extensions in `src/` (tsup rewrites to `.js` at build)\n- No `.js` imports in `src/` (enforced by ESLint)\n- No barrel imports from `utils/index` - import from specific submodules (e.g., `src/utils/execution/index.ts`, `src/utils/logging/index.ts`)\n\n\n## Rendering and Streaming Contract\n- Streaming fragments are transient live-progress output only. They may be displayed while a tool is running, but MUST NOT provide final settled MCP/JSON/CLI text.\n- Final settled output MUST render from the final structured/domain result and next-step metadata. If final output needs data, add it to the final result type instead of reading it from fragments.\n- Streaming-capable renderers may observe fragment callbacks only for live progress. Fragment handling must not affect final structured output or final settled text.\n\n## Error Handling\n- Structured errors (domain results with `didError`) are for domain errors only: failures in the user's build/test/device/simulator workflow (compile errors, test failures, missing destinations, etc.).\n- System errors with the MCP server or CLI itself (invalid internal state, unresolvable configuration, infrastructure failures) must NOT be wrapped in structured domain results — let them surface as runtime tool errors so they are clearly distinguishable from workflow outcomes.\n\n## Test Conventions\n- Vitest with colocated `__tests__/` directories using `*.test.ts`\n- Snapshot tests (`*.snapshot.test.ts`) must only assert generated tool output against fixtures. Move helper, parser, schema, setup, or behavior assertions to non-snapshot unit/integration tests.\n- Smoke tests in `src/smoke-tests/__tests__/` (separate Vitest config, serial execution)\n- Use `vi.mock`/`vi.hoisted` for isolation; inject executors and mock file systems\n- MCP integration tests use `McpServer`, `InMemoryTransport`, and `Client`\n- External dependencies (command execution, file system) must use dependency injection via `createMockExecutor()` / `createMockFileSystemExecutor()` from `src/test-utils/`\n\n## Tool Development\n- Tool manifests in `manifests/tools/*.yaml` define `id`, `module`, `names.mcp` (snake_case), optional `names.cli` (kebab-case), predicates, and annotations\n- MCP `readOnlyHint` describes whether a tool mutates host/project state such as files, build artifacts, configuration, or external services. Simulator HID/UI actions that only tap, type, press, or gesture inside the simulator may remain `readOnlyHint: true`; do not flip them to `false` merely because app UI state changes.\n- Workflow manifests in `manifests/workflows/*.yaml` group tools and define exposure rules\n- Tool modules export a Zod `schema`, a pure `*Logic` function, and a `handler` built with `createTypedTool` or `createSessionAwareTool`\n- Resource modules export a `handler` (and a pure `*Logic` function); `uri`, `name`, `description`, and `mimeType` are declared in `manifests/resources/*.yaml`\n\n## Commands\n- NEVER commit unless user asks\n\n## GitHub\nWhen reading issues:\n- Always read all comments on the issue\n-\n## Tools\n- GitHub CLI for issues/PRs\n- CLI design note: do not rely on CLI session-default writes. CLI is intentionally deterministic for CI/scripting and should use explicit command arguments as the primary input surface.\n- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.\n- After modifying any skill source, run `npx skill-check ` and address all errors/warnings before handoff.\n- Before handoff, run the matching manual Warden review for high-risk changes: runtime/CLI/daemon boundaries → `mobilebuildmcp-runtime-boundary-review`; test infrastructure or harnesses → `mobilebuildmcp-test-boundary-review`; tool manifests, schemas, or contracts → `mobilebuildmcp-tool-contract-review`. Invoke only applicable skills with `warden --skill `.\n-\n## Multi-process filesystem state\n- MobileBuildMCP explicitly supports multiple concurrent MCP server, daemon, CLI, test, and helper processes for the same or different workspaces.\n- Shared filesystem state under `~/Library/Developer/MobileBuildMCP` must be multi-process safe.\n- Use workspace-key scoped directories for workspace-owned state.\n- Do not store runtime state under `~/.mobilebuildmcp`; `.mobilebuildmcp/config.yaml` is only project configuration.\n- Use shared lock and atomic-write helpers for mutable shared files.\n- Prefer one-record-per-file registries over shared aggregate files.\n- Cleanup must verify ownership before deleting shared artifacts.\n- Multi-process safety means concurrent processes must not corrupt or delete each other's state.\n It does not mean ephemeral runtime handles should become portable between invocation surfaces.\n- Keep runtime/session-scoped handles isolated unless the product explicitly defines a cross-process\n contract. For example, UI automation `elementRef` values from runtime snapshots are handles for\n the runtime/session that produced them, not durable IDs to share between separate MCP and CLI\n invocations.\n- User-facing artifact/log paths in final text or structured output must use `displayPath()` from `src/utils/build-preflight.ts`, so paths are cwd-relative when possible or `~/...` instead of absolute home paths. Keep stored files at their real absolute paths; only normalize response/display values.\n\n## Style\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n\n## Docs\n- Do not commit transient investigation notes, prompt exports, or scratch analysis docs after the work is complete.\n- If an investigation leaves unresolved follow-up work, move it to a GitHub issue instead of preserving the transient doc in the branch.\n- Structured output JSON schemas are auto-published to the website/public schema mirror when merged; do not manually update public schema copies unless explicitly asked.\n\n### Changelog\nLocation: `CHANGELOG.md`\n\n#### Format\nUse these sections under `## [Unreleased]`:\n- `### Added` - New features\n- `### Changed` - Changes to existing functionality\n- `### Fixed` - Bug fixes\n- `### Removed` - Removed features\n-\n#### Rules\n- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist\n- New entries ALWAYS go under `## [Unreleased]` section\n- Append to existing subsections (e.g., `### Fixed`), do not create duplicates\n- NEVER modify already-released version sections (e.g., `## [0.12.2]`)\n- Each version section is immutable once released\n- NEVER update snapshot fixtures unless asked to do so, these are integration tests, on failure assume code is wrong before questioning the fixture\n-\n#### Attribution\n- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/MobileBuildMCP/issues/123))`\n- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/MobileBuildMCP/pull/456) by [@username](https://github.com/username))`\n\n## Test Execution Rules\n- **NEVER run the snapshot or smoke test suites without explicit user permission.** They are expensive (~7 min baseline, spawn real `xcodebuild`/`simctl`/`devicectl` processes and can wedge). This covers `npm run test:snapshot`, `npm run test:smoke`, and any direct `vitest run --config vitest.snapshot.config.ts` / `vitest.smoke.config.ts` invocation. Ask first, then run only if the user agrees.\n- The default unit suite (`npm test` / `vitest run`), `npm run typecheck`, `npm run lint`, and `npm run build` are cheap and may be run freely without asking.\n- When running long test suites (snapshot tests, smoke tests), ALWAYS write full output to a log file and read it afterwards. NEVER pipe through `tail` or `grep` directly — that loses output you may need to debug failures.\n- Pattern: `DEVICE_ID=... npm run test:snapshot 2>&1 | tee /tmp/snapshot-results.txt` then read `/tmp/snapshot-results.txt` with the native read tool.\n- If you need a summary, read the log file and grep/filter it — the full output is always preserved.\n- Snapshot test command: `DEVICE_ID= npm run test:snapshot`\n- **Snapshot suite expected duration**: ~7 min baseline (measured at 423s). Anything longer than ~10 min should be treated as a likely hang, not a slow run.\n - Do NOT just kill the run — first inspect the process tree (`ps -ef | grep -E \"vitest|xcodebuild|simctl|devicectl\"`) to identify what's stuck.\n - Common hang causes: locked physical device, stale simulator state, `devicectl diagnose` waiting for password, orphaned daemon process.\n - Capture what you find before killing, so the root cause can be fixed rather than papered over.\n- If physical-device snapshot tests hang after the final test summary, the likely cause is Apple post-failure diagnostics invoking `devicectl diagnose`, which may prompt for a macOS password and wedge in automated runs.\n- When asked to review changes or test failures, focus on regressions: behavior changes caused by the branch. Do not treat known/acceptable test flakes, environment setup issues, or nondeterministic tool output churn as regressions unless explicitly asked to investigate them.\n\n## **CRITICAL** Tool Usage Rules **CRITICAL**\n- NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.\n- You MUST read every file you modify in full before editing.\n\n\n# Development Rules\n\n## Code Quality\n- No `any` types unless absolutely necessary\n- Check node_modules for external API type definitions instead of guessing\n- **NEVER use inline imports** - no `await import(\"./foo.js\")`, no `import(\"pkg\").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.\n- NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead\n- Always ask before removing functionality or code that appears to be intentional\n- Do not add fallback behavior by default. If required context, configuration, runtime state, or dependencies are missing, fail loudly and fix the caller/setup instead of silently switching to an alternate path. Add a fallback only when explicitly requested or when it is a documented product requirement.\n- Review the complete merge-base diff and trace changed or reused helper contracts, including error and sentinel returns, through callers, consumers, tests, and operational configuration.\n- Verify standard quality commands include every changed path and exercise exact entry points and argument variants; validate explicitly when they do not.\n- For asynchronous, workflow, or process-boundary changes, enumerate lifecycle states, retries, supersession, and race transitions; test terminal outcomes and missing or optional metadata.\n\n## Test Conventions\n- Snapshot tests (`*.snapshot.test.ts`) must only assert generated tool output against fixtures. Move helper, parser, schema, setup, or behavior assertions to non-snapshot unit/integration tests.\n\n## Commands\n- NEVER commit unless user asks\n\n## GitHub\nWhen reading issues:\n- Always read all comments on the issue\n-\n## Tools\n- GitHub CLI for issues/PRs\n- MCP `readOnlyHint` describes whether a tool mutates host/project state such as files, build artifacts, configuration, or external services. Simulator HID/UI actions that only tap, type, press, or gesture inside the simulator may remain `readOnlyHint: true`; do not flip them to `false` merely because app UI state changes.\n- CLI design note: do not rely on CLI session-default writes. CLI is intentionally deterministic for CI/scripting and should use explicit command arguments as the primary input surface.\n- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.\n- After modifying any skill source, run `npx skill-check ` and address all errors/warnings before handoff.\n- Before handoff, run the matching manual Warden review for high-risk changes: runtime/CLI/daemon boundaries → `mobilebuildmcp-runtime-boundary-review`; test infrastructure or harnesses → `mobilebuildmcp-test-boundary-review`; tool manifests, schemas, or contracts → `mobilebuildmcp-tool-contract-review`. Invoke only applicable skills with `warden --skill `.\n-\n## Multi-process filesystem state\n- MobileBuildMCP explicitly supports multiple concurrent MCP server, daemon, CLI, test, and helper processes for the same or different workspaces.\n- Shared filesystem state under `~/Library/Developer/MobileBuildMCP` must be multi-process safe.\n- Use workspace-key scoped directories for workspace-owned state.\n- Do not store runtime state under `~/.mobilebuildmcp`; `.mobilebuildmcp/config.yaml` is only project configuration.\n- Use shared lock and atomic-write helpers for mutable shared files.\n- Prefer one-record-per-file registries over shared aggregate files.\n- Cleanup must verify ownership before deleting shared artifacts.\n- User-facing artifact/log paths in final text or structured output must use `displayPath()` from `src/utils/build-preflight.ts`, so paths are cwd-relative when possible or `~/...` instead of absolute home paths. Keep stored files at their real absolute paths; only normalize response/display values.\n\n## Style\n- Keep answers short and concise\n- No emojis in commits, issues, PR comments, or code\n- No fluff or cheerful filler text\n- Technical prose only, be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\")\n\n## Docs\n- Do not commit transient investigation notes, prompt exports, or scratch analysis docs after the work is complete.\n- If an investigation leaves unresolved follow-up work, move it to a GitHub issue instead of preserving the transient doc in the branch.\n- Structured output JSON schemas are auto-published to the website/public schema mirror when merged; do not manually update public schema copies unless explicitly asked.\n\n### Changelog\nLocation: `CHANGELOG.md`\n\n#### Format\nUse these sections under `## [Unreleased]`:\n- `### Added` - New features\n- `### Changed` - Changes to existing functionality\n- `### Fixed` - Bug fixes\n- `### Removed` - Removed features\n-\n#### Rules\n- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist\n- New entries ALWAYS go under `## [Unreleased]` section\n- Append to existing subsections (e.g., `### Fixed`), do not create duplicates\n- NEVER modify already-released version sections (e.g., `## [0.12.2]`)\n- Each version section is immutable once released\n- NEVER update snapshot fixtures unless asked to do so, these are integration tests, on failure assume code is wrong before questioning the fixture\n-\n#### Attribution\n- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/MobileBuildMCP/issues/123))`\n- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/MobileBuildMCP/pull/456) by [@username](https://github.com/username))`\n\n\n## Rendering and Streaming Contract\n- Streaming fragments are transient live-progress output only. They may be displayed while a tool is running, but MUST NOT provide final settled MCP/JSON/CLI text.\n- Final settled output MUST render from the final structured/domain result and next-step metadata. If final output needs data, add it to the final result type instead of reading it from fragments.\n- Streaming-capable renderers may observe fragment callbacks only for live progress. Fragment handling must not affect final structured output or final settled text.\n\n## Error Handling\n- Structured errors (domain results with `didError`) are for domain errors only: failures in the user's build/test/device/simulator workflow (compile errors, test failures, missing destinations, etc.).\n- System errors with the MCP server or CLI itself (invalid internal state, unresolvable configuration, infrastructure failures) must NOT be wrapped in structured domain results — let them surface as runtime tool errors so they are clearly distinguishable from workflow outcomes.\n\n## Test Execution Rules\n- **NEVER run the snapshot or smoke test suites without explicit user permission.** They are expensive (~7 min baseline, spawn real `xcodebuild`/`simctl`/`devicectl` processes and can wedge). This covers `npm run test:snapshot`, `npm run test:smoke`, and any direct `vitest run --config vitest.snapshot.config.ts` / `vitest.smoke.config.ts` invocation. Ask first, then run only if the user agrees.\n- The default unit suite (`npm test` / `vitest run`), `npm run typecheck`, `npm run lint`, and `npm run build` are cheap and may be run freely without asking.\n- When running long test suites (snapshot tests, smoke tests), ALWAYS write full output to a log file and read it afterwards. NEVER pipe through `tail` or `grep` directly — that loses output you may need to debug failures.\n- Pattern: `DEVICE_ID=... npm run test:snapshot 2>&1 | tee /tmp/snapshot-results.txt` then read `/tmp/snapshot-results.txt` with the native read tool.\n- If you need a summary, read the log file and grep/filter it — the full output is always preserved.\n- Snapshot test command: `DEVICE_ID= npm run test:snapshot`\n- **Snapshot suite expected duration**: ~7 min baseline (measured at 423s). Anything longer than ~10 min should be treated as a likely hang, not a slow run.\n - Do NOT just kill the run — first inspect the process tree (`ps -ef | grep -E \"vitest|xcodebuild|simctl|devicectl\"`) to identify what's stuck.\n - Common hang causes: locked physical device, stale simulator state, `devicectl diagnose` waiting for password, orphaned daemon process.\n - Capture what you find before killing, so the root cause can be fixed rather than papered over.\n- When asked to review changes or test failures, focus on regressions: behavior changes caused by the branch. Do not treat known/acceptable test flakes, environment setup issues, or nondeterministic tool output churn as regressions unless explicitly asked to investigate them.\n\n## **CRITICAL** Tool Usage Rules **CRITICAL**\n- NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.\n- You MUST read every file you modify in full before editing.\n\n\n---\ndescription: \nglobs: \nalwaysApply: true\n---\nPlease don't fix any code errors unless reported by MobileBuildMCP server tool responses.\n\n\n---\nname: mobilebuildmcp-docs-command-review\ndescription: Use when reviewing MobileBuildMCP changelog CLI command references for invalid current guidance while allowing historical migration examples.\nallowed-tools: Read Grep Glob\n---\n\n# MobileBuildMCP Docs Command Review\n\nReview changed changelog entries for CLI command references that would mislead users or agents.\n\n## What to inspect\n\n- `CHANGELOG.md`\n- `manifests/tools/*.yaml` and `manifests/workflows/*.yaml` when you need to verify current CLI workflow/tool names\n- `src/cli/**` only when command wiring is unclear from manifests\n\n## Issue criteria\n\nReport a finding only when a command reference is presented as current guidance and appears invalid for the current CLI surface.\n\n### High severity\n\n- A changelog bullet, example, or migration instruction tells users to run a removed or invalid `mobilebuildmcp` command as the current path.\n- A Breaking change mentions a removed command but does not give a valid replacement.\n- A command reference uses the wrong workflow/tool pairing in a way a user or agent would likely copy.\n\n### Medium severity\n\n- A command reference is ambiguous enough that users may not know whether it is historical or current.\n- A migration example gives the right replacement but does not clearly label the old command as \"Before\", \"old\", \"removed\", or equivalent.\n\n## Explicitly allowed\n\nDo not report removed commands when they are clearly historical context, especially in:\n\n- Breaking-change migration sections\n- \"Before\" examples paired with valid \"After\" examples\n- Already-released changelog sections describing past behavior\n\nExample that should not be reported:\n\n```markdown\nBefore:\nmobilebuildmcp logging start-sim-log-cap\n\nAfter:\nmobilebuildmcp simulator build-and-run\n```\n\n## Output\n\nFor each finding, include:\n\n- Severity\n- File and line\n- The command reference\n- Why it reads as current guidance\n- Suggested replacement wording or command\n\nIf all command references are historical or valid, report no findings.\n\n\n---\nname: mobilebuildmcp-docs-release-review\ndescription: Use when reviewing MobileBuildMCP documentation, CLI command references, website manifest generation, changelog, release notes, and release script changes.\n---\n\n# MobileBuildMCP Docs and Release Review\n\nReview guardrails for documentation, generated references, and release flow consistency.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `README.md`\n- `CHANGELOG.md` when present\n- `scripts/build-website-manifest.mjs`\n- `scripts/generate-github-release-notes.mjs`\n- `scripts/release.sh`\n- `package.json`\n- `xcodebuildmcp.com/app/docs/_content/**`\n\n## Guardrails\n\n- CLI examples match generated CLI catalog/commands.\n- Docs do not reference unavailable tools or workflows.\n- User-facing behavior changes include changelog updates.\n- Release notes derive from a valid changelog section.\n- README install snippets align with release script tag replacement.\n- Website manifest generation preserves expected normalized fields.\n- Docs explain runtime/contracts without deprecated patterns.\n- Keep docs-only work from introducing product behavior changes.\n- CLI command references in changelog entries are reviewed by `mobilebuildmcp-docs-command-review`.\n\n## Validation\n\n- `npm run build`\n- Release notes check when touched:\n - `node scripts/generate-github-release-notes.mjs --version --changelog CHANGELOG.md`\n- `npx skill-check .agents/skills/mobilebuildmcp-docs-release-review`\n\n\n---\nname: mobilebuildmcp-packaging-resource-review\ndescription: Use when reviewing MobileBuildMCP packaging, resource-root, build artifact, bundled AXe, schema, manifest, and portable macOS distribution changes.\n---\n\n# MobileBuildMCP Packaging and Resource Review\n\nReview guardrails for package/build/resource integrity and portable distribution.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `package.json`\n- `scripts/copy-build-assets.js`\n- `scripts/package-macos-portable.sh`\n- `scripts/build-website-manifest.mjs`\n- `schemas/**`\n- `manifests/**`\n- `skills/**`\n- `bundled/**` when present\n- Resource-root utilities when touched\n\n## Guardrails\n\n- Published package `files` includes required runtime resources.\n- Portable package includes `build`, `manifests`, `bundled`, `skills`, `package.json`, and production dependencies.\n- AXe binary/framework expectations remain verified.\n- Wrapper scripts preserve `MOBILEBUILDMCP_RESOURCE_ROOT` and `DYLD_FRAMEWORK_PATH`.\n- Schemas and manifests stay available in installed and portable layouts.\n- Do not assume build outputs exist before `npm run build`.\n- Avoid network-dependent packaging behavior without verification/checksums.\n\n## Validation\n\n- `npm run build`\n- Packaging-specific when touched:\n - `npm run package:macos -- --help` (if supported)\n - `npm run verify:portable` after artifact creation\n- `npx skill-check .agents/skills/mobilebuildmcp-packaging-resource-review`\n\n\n---\nname: mobilebuildmcp-rendering-streaming-review\ndescription: Use when reviewing MobileBuildMCP rendering, streaming fragment, next-step, and CLI output mode changes for boundary violations.\n---\n\n# MobileBuildMCP Rendering and Streaming Review\n\nReview guardrails for rendering boundaries, streaming fragments, and output modes.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/rendering/**`\n- `src/types/domain-fragments.ts`\n- `src/types/runtime-status.ts`\n- `src/runtime/tool-invoker.ts`\n- `src/runtime/__tests__/tool-invoker.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/architecture-rendering-output.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-tool-lifecycle.mdx`\n- `xcodebuildmcp.com/app/docs/_content/output-formats.mdx`\n\n## Guardrails\n\n- Tool handlers do not branch on CLI vs MCP output mode.\n- Fragments represent progress, not final contract data.\n- Final structured output remains canonical.\n- Do not invent `json`/`jsonl` render strategies.\n- Streaming tools emit typed fragments and one final structured result.\n- Non-streaming tools do not emit unnecessary fragments.\n- Keep `ctx.emit` and xcodebuild pipeline `emitFragment` contexts separate.\n- Keep next-step rendering in runtime/rendering boundary.\n\n## Validation\n\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npm run test:snapshots`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-rendering-streaming-review`\n\n\n---\nname: mobilebuildmcp-runtime-boundary-review\ndescription: Use when reviewing MobileBuildMCP runtime boundary changes across MCP, direct CLI invocation, daemon-routed tools, and Xcode IDE bridge routing.\n---\n\n# MobileBuildMCP Runtime Boundary Review\n\nReview guardrails for runtime routing and invocation boundaries.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/runtime/tool-catalog.ts`\n- `src/runtime/tool-invoker.ts`\n- `src/runtime/types.ts`\n- `src/cli/**`\n- `src/daemon/**`\n- `manifests/tools/*.yaml`\n- `manifests/workflows/*.yaml`\n- `xcodebuildmcp.com/app/docs/_content/architecture-runtime-boundaries.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-manifest-visibility.mdx`\n\n## Guardrails\n\n- MCP, CLI, and daemon paths use shared handlers.\n- Stateful CLI tools route through daemon only when `routing.stateful` requires it.\n- Do not treat daemon as a third manifest availability mode.\n- Dynamic Xcode IDE tools keep daemon routing semantics.\n- Catalog filtering respects availability, workflow selection, and predicates.\n- Runtime failures surface via runtime/rendering status and fragments.\n- Avoid silent fallbacks and parallel invocation paths.\n\n## Validation\n\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-runtime-boundary-review`\n\n\n---\nname: mobilebuildmcp-snapshot-fixture-review\ndescription: Use when reviewing MobileBuildMCP snapshot fixture changes for MCP, CLI, and JSON output contract integrity.\n---\n\n# MobileBuildMCP Snapshot Fixture Review\n\nReview guardrails for fixture and snapshot contract integrity.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/snapshot-tests/__fixtures__/**`\n- `src/snapshot-tests/contracts.ts`\n- `src/snapshot-tests/fixture-io.ts`\n- `src/snapshot-tests/__tests__/fixture-io.test.ts`\n- `src/snapshot-tests/__tests__/json-normalize.test.ts`\n- `src/snapshot-tests/__tests__/json-fixture-schema.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/testing.mdx`\n\n## Guardrails\n\n- Fixture updates map to intentional behavior changes.\n- Do not update fixtures only to make tests pass.\n- MCP, CLI, and JSON fixture updates stay aligned.\n- JSON fixtures preserve stable structured output envelopes.\n- Volatile values are normalized in code, not patched ad hoc in fixtures.\n- Missing fixtures are generated through the snapshot update flow.\n- Verify project-defined normalization sentinels in normalization code and tests before reporting\n them as implausible fixture values. In particular, `99999` is an intentional sentinel for\n volatile UI capture counts.\n- Group every occurrence of the same root cause into one finding and list the affected fixtures.\n Do not emit separate findings for equivalent CLI, MCP, text, or JSON drift.\n- Do not repeat a finding that is already resolved by the current diff.\n\n## Review limits\n\n- Review the changed fixtures and the directly relevant normalization or contract code only.\n- Do not run snapshot or smoke suites as part of an automated PR review.\n- Prefer one high-confidence cross-fixture finding over multiple speculative discrepancies.\n\n\n---\nname: mobilebuildmcp-structured-output-review\ndescription: Use when reviewing MobileBuildMCP structured output schema changes, schema versioning, manifest outputSchema metadata, and JSON fixture compatibility.\n---\n\n# MobileBuildMCP Structured Output Review\n\nReview guardrails for structured output schema correctness and compatibility.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `schemas/structured-output/**`\n- `src/core/structured-output-schema.ts`\n- `src/core/__tests__/structured-output-schema.test.ts`\n- `src/snapshot-tests/__fixtures__/json/**`\n- `src/snapshot-tests/__tests__/json-fixture-schema.test.ts`\n- `xcodebuildmcp.com/app/docs/_content/schema-versioning.mdx`\n- `xcodebuildmcp.com/app/docs/_content/output-formats.mdx`\n\n## Guardrails\n\n- `schema` uses `mobilebuildmcp.output.` format.\n- `schemaVersion` uses integer strings only.\n- Breaking schema changes create a new versioned schema file.\n- Published schema versions are not removed or mutated incompatibly.\n- Manifest `outputSchema` matches emitted `ctx.structuredOutput` payload.\n- JSON fixtures validate against current schema contracts.\n- `$ref` usage remains compatible with bundling in `structured-output-schema.ts`.\n\n## Validation\n\n- `npm run test:schema-fixtures`\n- `npm test -- src/core/__tests__/structured-output-schema.test.ts`\n- `npm run typecheck`\n- `npx skill-check .agents/skills/mobilebuildmcp-structured-output-review`\n\n\n---\nname: mobilebuildmcp-test-boundary-review\ndescription: Use when reviewing MobileBuildMCP tests for correct unit, snapshot, schema, smoke, and external process boundaries.\n---\n\n# MobileBuildMCP Test Boundary Review\n\nReview guardrails for test isolation, scope, and contract validation.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/**/__tests__/**`\n- `src/test-utils/**`\n- `src/snapshot-tests/**`\n- `scripts/**/__tests__/**`\n- `package.json`\n- `xcodebuildmcp.com/app/docs/_content/testing.mdx`\n- `xcodebuildmcp.com/app/docs/_content/contributing.mdx`\n\n## Guardrails\n\n- Unit tests inject command/filesystem/external dependencies.\n- Unit tests do not call real `xcodebuild`, `xcrun`, AXe, devices, or simulators.\n- Prefer testing logic/executor functions over handler wrappers unless testing runtime integration.\n- Use existing mock executor helpers.\n- Treat snapshot updates as contract changes requiring review.\n- Do not add fake e2e/snapshot state to force test success.\n- Avoid unsafe TypeScript suppressions.\n\n## Validation\n\n- Run targeted Vitest command for touched tests.\n- `npm test`\n- `npm run typecheck`\n- If fixtures/schemas changed: `npm run test:snapshots` and `npm run test:schema-fixtures`\n- `npx skill-check .agents/skills/mobilebuildmcp-test-boundary-review`\n\n\n---\nname: mobilebuildmcp-tool-contract-review\ndescription: Use when reviewing MobileBuildMCP tool contract changes across implementation, manifests, workflow membership, output schema metadata, and next-step templates.\n---\n\n# MobileBuildMCP Tool Contract Review\n\nReview guardrails for tool contract changes across implementation, manifests, and workflow exposure.\n\n## Review scope\n\n- Review-only by default.\n- Do not edit product code unless the user explicitly requests implementation changes.\n\n## Files to inspect\n\n- `src/mcp/tools/**`\n- `manifests/tools/*.yaml`\n- `manifests/workflows/*.yaml`\n- `src/core/manifest/schema.ts`\n- `src/runtime/tool-catalog.ts`\n- `src/runtime/types.ts`\n- `xcodebuildmcp.com/app/docs/_content/tool-authoring.mdx`\n- `xcodebuildmcp.com/app/docs/_content/architecture-manifest-visibility.mdx`\n\n## Guardrails\n\n- Manifest `id` matches filename.\n- Manifest `module` points to implementation path without extension.\n- Tool module exports named `schema` and `handler`.\n- `names.mcp` remains globally unique.\n- `names.cli` stays workflow-local and consistent with CLI docs/fixtures.\n- Tool appears in at least one workflow unless intentionally hidden by availability.\n- `outputSchema` is present for tools that set `ctx.structuredOutput`.\n- `nextSteps.toolId` references existing manifest tool IDs.\n- Avoid parallel legacy paths or duplicate implementation paths.\n\n## Validation\n\n- `npm run typecheck`\n- `npm test -- src/core/manifest/__tests__/schema.test.ts`\n- `npm test -- src/runtime/__tests__/tool-invoker.test.ts`\n- `npx skill-check .agents/skills/mobilebuildmcp-tool-contract-review`\n\n\nFix a verified code issue. You are working in a git worktree at: ${WORKTREE}\n\n## Finding\n- Title: ${TITLE}\n- File: ${FILE_PATH}:${START_LINE}\n- Description: ${DESCRIPTION}\n- Verification: ${REASONING}\n- Suggested Fix: ${FIX_DESCRIPTION}\n```diff\n${FIX_DIFF}\n```\n\n## Instructions\n\n### Step 1: Understand the code\nRead the file at ${WORKTREE}/${FILE_PATH}. Read at least 50 lines above and below the reported location. Trace callers and callees of the affected code using Grep/Glob to understand how it is used. Do NOT skip this step.\n\n### Step 2: Apply a minimal fix\nApply the smallest change that addresses the finding. If the suggested diff doesn't apply cleanly, adapt it while preserving intent. Do NOT refactor surrounding code, rename variables, add comments, or make any change beyond what the finding requires.\n\n### Step 3: Write tests\nWrite or update tests that verify the fix:\n- Follow existing test patterns (co-located files, same framework)\n- At minimum, write a test that would have caught the original bug\n- Test the specific edge case, not just the happy path\n\nOnly modify the fix target and its test file.\n\n### Step 4: Self-review\nBefore staging, run `git diff` in the worktree and review every changed line. Verify:\n1. The change addresses the specific finding described, not something else\n2. No unrelated code was modified (no drive-by cleanups, no formatting changes)\n3. Trace through changed code paths: does the fix introduce any new bug, null reference, type error, or broken import?\n4. Tests exercise the fix (the failure case), not just that the code runs\n\nIf ANY check fails, fix the problem before proceeding. If the suggested fix is wrong or would introduce a regression you cannot resolve, do NOT commit. Instead, skip to the output step and report why.\n\n### Step 5: Commit\nDo NOT run tests locally. CI will validate the changes.\n\nStage and commit with this exact message:\n\nfix: ${TITLE}\n\nWarden finding ${FINDING_ID}\nSeverity: ${SEVERITY}\n\nCo-Authored-By: Warden \n\n### Step 6: Output\nReturn ONLY valid JSON (no surrounding text). Use `\"status\": \"applied\"` if you committed a fix, or `\"status\": \"skipped\"` if you did not.\n\n```json\n{\n \"status\": \"applied\",\n \"filesChanged\": [\"src/example.ts\"],\n \"testFilesChanged\": [\"src/example.test.ts\"],\n \"selfReview\": \"Verified the fix addresses the null check and test covers the failure case\",\n \"skipReason\": null\n}\n```\n\nWhen skipping:\n```json\n{\n \"status\": \"skipped\",\n \"filesChanged\": [],\n \"testFilesChanged\": [],\n \"selfReview\": null,\n \"skipReason\": \"The suggested fix would introduce a regression in the error handling path\"\n}\n```\n\n\nVerify a code analysis finding. Determine if this is a TRUE issue or a FALSE POSITIVE.\nDo NOT write or edit any files. Research only.\n\n## Finding\n- Title: ${TITLE}\n- Severity: ${SEVERITY} | Confidence: ${CONFIDENCE}\n- Skill: ${SKILL}\n- Location: ${FILE_PATH}:${START_LINE}-${END_LINE}\n- Description: ${DESCRIPTION}\n- Verification hint: ${VERIFICATION}\n\n## Instructions\n1. Read the file at the reported location. Examine at least 50 lines of surrounding context.\n2. Trace data flow to/from the flagged code using Grep/Glob.\n3. Check if the issue is mitigated elsewhere (guards, validation, try/catch upstream).\n4. Check if the issue is actually reachable in practice.\n\nReturn your verdict as JSON:\n{\n \"findingId\": \"${FINDING_ID}\",\n \"verdict\": \"verified\" or \"rejected\",\n \"confidence\": \"high\" or \"medium\" or \"low\",\n \"reasoning\": \"2-3 sentence explanation\",\n \"traceNotes\": \"What code paths you examined\"\n}\n\n\n---\nname: warden-sweep\ndescription: Full-repository code sweep. Scans every file with warden, verifies findings via deep tracing, creates draft PRs for validated issues. Use when asked to \"sweep the repo\", \"scan everything\", \"find all bugs\", \"full codebase review\", \"batch code analysis\", or run warden across the entire repository.\ndisable-model-invocation: true\n---\n\n# Warden Sweep\n\nFull-repository code sweep: scan every file, verify findings with deep tracing, create draft PRs for validated issues.\n\n**Requires**: `warden`, `gh`, `git`, `jq`, `uv`\n\n**Important**: Run all scripts from the repository root using `${CLAUDE_SKILL_ROOT}`. Output goes to `.warden/sweeps//`.\n\n## Bundled Scripts\n\n### `scripts/scan.py`\n\nRuns setup and scan in one call: generates run ID, creates sweep dir, checks deps, creates `warden` label, enumerates files, runs warden per file, extracts findings.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py [file ...]\n --sweep-dir DIR # Resume into existing sweep dir\n```\n\n### `scripts/index_prs.py`\n\nFetches open warden-labeled PRs, builds file-to-PR dedup index, caches diffs for overlapping PRs.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/index_prs.py \n```\n\n### `scripts/create_issue.py`\n\nCreates a GitHub tracking issue summarizing sweep results. Run after verification, before patching.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/create_issue.py \n```\n\n### `scripts/organize.py`\n\nTags security findings, labels security PRs, updates finding reports with PR links, posts final results to tracking issue, generates summary report, finalizes manifest.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/organize.py \n```\n\n### `scripts/extract_findings.py`\n\nParses warden JSONL log files and extracts normalized findings. Called automatically by `scan.py`.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/extract_findings.py -o \n```\n\n### `scripts/generate_report.py`\n\nBuilds `summary.md` and `report.json` from sweep data. Called automatically by `organize.py`.\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/generate_report.py \n```\n\n### `scripts/find_reviewers.py`\n\nFinds top 2 git contributors for a file (last 12 months).\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/find_reviewers.py \n```\n\nReturns JSON: `{\"reviewers\": [\"user1\", \"user2\"]}`\n\n---\n\n## Phase 1: Scan\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py\n```\n\nTo resume a partial scan:\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/scan.py --sweep-dir .warden/sweeps/\n```\n\nParse the JSON stdout. Save `runId` and `sweepDir` for subsequent phases.\n\n**Report** to user:\n\n```\n## Scan Complete\n\nScanned **{filesScanned}** files, **{filesTimedOut}** timed out, **{filesErrored}** errors.\n\n### Findings ({totalFindings} total)\n\n| # | Severity | Skill | File | Title |\n|---|----------|-------|------|-------|\n| 1 | **HIGH** | security-review | `src/db/query.ts:42` | SQL injection in query builder |\n...\n```\n\nRender every finding from the `findings` array. Bold severity for high and above.\n\n**On failure**: If exit code 1, show the error JSON and stop. If exit code 2, show the partial results. List timed-out files separately from errored files so users know which can be retried.\n\n---\n\n## Phase 2: Verify\n\nDeep-trace each finding using Task subagents to qualify or disqualify.\n\n**For each finding in `data/all-findings.jsonl`:**\n\nCheck if `data/verify/.json` already exists (incrementality). If it does, skip.\n\nLaunch a Task subagent (`subagent_type: \"general-purpose\"`) for each finding. Process findings in parallel batches of up to 8 to improve throughput.\n\n**Task prompt for each finding:**\n\nRead `${CLAUDE_SKILL_ROOT}/references/verify-prompt.md` for the prompt template. Substitute the finding's values into the `${...}` placeholders.\n\n**Process results:**\n\nParse the JSON from the subagent response and:\n- Write result to `data/verify/.json`\n- Append to `data/verified.jsonl` or `data/rejected.jsonl`\n- For verified findings, generate `findings/.md`:\n\n```markdown\n# ${TITLE}\n\n**ID**: ${FINDING_ID} | **Severity**: ${SEVERITY} | **Confidence**: ${CONFIDENCE}\n**Skill**: ${SKILL} | **File**: ${FILE_PATH}:${START_LINE}\n\n## Description\n${DESCRIPTION}\n\n## Verification\n**Verdict**: Verified (${VERIFICATION_CONFIDENCE})\n**Reasoning**: ${REASONING}\n**Code trace**: ${TRACE_NOTES}\n\n## Suggested Fix\n${FIX_DESCRIPTION}\n```diff\n${FIX_DIFF}\n```\n```\n\nUpdate manifest: set `phases.verify` to `\"complete\"`.\n\n**Report** to user after all verifications:\n\n```\n## Verification Complete\n\n**{verified}** verified, **{rejected}** rejected.\n\n### Verified Findings\n\n| # | Severity | Confidence | File | Title | Reasoning |\n|---|----------|------------|------|-------|-----------|\n| 1 | **HIGH** | high | `src/db/query.ts:42` | SQL injection in query builder | User input flows directly into... |\n...\n\n### Rejected ({rejected_count})\n\n- `{findingId}` {file}: {reasoning}\n...\n```\n\n---\n\n## Phase 3: Issue\n\nCreate a tracking issue that ties all PRs together and gives reviewers a single overview.\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/create_issue.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout. Save `issueUrl` and `issueNumber` for Phase 4.\n\n**Report** to user:\n\n```\n## Tracking Issue Created\n\n{issueUrl}\n```\n\n**On failure**: Show the error. Continue to Phase 4 (PRs can still be created without a tracking issue).\n\n---\n\n## Phase 4: Patch\n\nFor each verified finding, create a worktree, fix the code, and open a draft PR. Process findings **sequentially** (one at a time) since parallel subagents cross-contaminate worktrees.\n\n**Severity triage**: Patch HIGH and above. For MEDIUM, only patch findings from bug-detection skills (e.g., `code-review`, `security-review`). Skip LOW and INFO findings.\n\n**Step 0: Setup** (run once before the loop):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/index_prs.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout. Use `fileIndex` for dedup checks.\n\nDetermine the default branch and fetch latest so worktrees branch from current upstream:\n\n```bash\nDEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')\ngit fetch origin \"${DEFAULT_BRANCH}\"\n```\n\n**For each finding in `data/verified.jsonl`:**\n\nCheck if finding ID already exists in `data/patches.jsonl` (incrementality). If it does, skip.\n\n**Dedup check**: Use the file index from `index_prs.py` output to determine if an existing open PR already addresses the same issue.\n\n1. **File match**: Look up the finding's file path in the `fileIndex`. If no PR touches that file, no conflict; proceed to Step 1.\n2. **Chunk overlap**: If a PR does touch the same file, read its cached diff from `data/pr-diffs/.diff` and check whether the PR's changed hunks overlap with the finding's line range (startLine-endLine). Overlapping or adjacent hunks (within ~10 lines) indicate the same code region.\n3. **Same concern**: If the hunks overlap, compare the PR title and the finding title/description. Are they fixing the same kind of defect? A PR fixing an off-by-one error and a finding about a null check in the same function are different issues; both should proceed.\n\nSkip the finding only when there is both chunk overlap AND the PR addresses the same concern. Record it in `data/patches.jsonl` with `\"status\": \"existing\"` and `\"prUrl\"` pointing to the matching PR, then continue to the next finding.\n\n**Step 1: Create worktree**\n\n```bash\nBRANCH=\"warden-sweep/${RUN_ID}/${FINDING_ID}\"\nWORKTREE=\"${SWEEP_DIR}/worktrees/${FINDING_ID}\"\ngit worktree add \"${WORKTREE}\" -b \"${BRANCH}\" \"origin/${DEFAULT_BRANCH}\"\n```\n\nEach finding branches from the repo's default branch so PRs contain only the fix commit.\n\n**Step 2: Generate fix**\n\nLaunch a Task subagent (`subagent_type: \"general-purpose\"`) to apply the fix in the worktree. Read `${CLAUDE_SKILL_ROOT}/references/patch-prompt.md` for the prompt template. Substitute the finding's values and worktree path into the `${...}` placeholders.\n\n**Step 2b: Handle skipped findings**\n\nIf the subagent returned `\"status\": \"skipped\"` (not `\"applied\"`), do NOT proceed to Steps 3-4. Instead:\n1. Record the finding in `data/patches.jsonl` with `\"status\": \"error\"` and `\"error\": \"Subagent skipped: ${skipReason}\"`\n2. Clean up the worktree\n3. Continue to the next finding\n\n**Step 3: Find reviewers**\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/find_reviewers.py \"${FILE_PATH}\"\n```\n\n**Step 4: Create draft PR**\n\n```bash\ncd \"${WORKTREE}\" && git push -u origin HEAD:\"${BRANCH}\"\n```\n\nCreate the PR with a 1-2 sentence \"What\" summary based on the finding and fix, followed by the finding description and verification reasoning:\n\n```bash\nREVIEWERS=\"\"\n# If find_reviewers.py returned reviewers, build the flags\n# e.g., REVIEWERS=\"--reviewer user1 --reviewer user2\"\n\ngh pr create --draft \\\n --label \"warden\" \\\n --title \"fix: ${TITLE}\" \\\n --body \"$(cat <<'EOF'\n${FIX_WHAT_DESCRIPTION}\n\n${DESCRIPTION}\n\n${REASONING}\n\nAutomated fix for Warden finding ${FINDING_ID} (${SEVERITY}, detected by ${SKILL}).\n\n\nRef #${ISSUE_NUMBER}\n\n> This PR was auto-generated by a Warden Sweep (run ${RUN_ID}).\n> The finding has been validated through automated deep tracing,\n> but human confirmation is requested as this is batch work.\nEOF\n)\" ${REVIEWERS}\n```\n\nSave the PR URL.\n\n**Step 5: Record and cleanup**\n\nAppend to `data/patches.jsonl` (use `\"created\"` as status for successful PRs, not the subagent's `\"applied\"`):\n```json\n{\"findingId\": \"...\", \"prUrl\": \"https://...\", \"branch\": \"...\", \"reviewers\": [\"user1\", \"user2\"], \"filesChanged\": [\"...\"], \"status\": \"created|existing|error\"}\n```\n\nRemove the worktree:\n```bash\ncd \"$(git rev-parse --show-toplevel)\"\ngit worktree remove \"${WORKTREE}\" --force\n```\n\n**Error handling**: On failure at any step, write to `data/patches.jsonl` with `\"status\": \"error\"` and `\"error\": \"...\"`, clean up the worktree, and continue to the next finding.\n\nUpdate manifest: set `phases.patch` to `\"complete\"`.\n\n**Report** to user after all patches:\n\n```\n## PRs Created\n\n**{created}** created, **{skipped}** skipped (existing), **{failed}** failed.\n\n| # | Finding | PR | Status |\n|---|---------|-----|--------|\n| 1 | `security-review-a1b2c3d4` SQL injection in query builder | #142 | created |\n| 2 | `code-review-e5f6g7h8` Null pointer in handler | - | existing (#138) |\n...\n```\n\n---\n\n## Phase 5: Organize\n\n**Run** (1 tool call):\n\n```bash\nuv run ${CLAUDE_SKILL_ROOT}/scripts/organize.py ${SWEEP_DIR}\n```\n\nParse the JSON stdout.\n\n**Report** to user:\n\n```\n## Sweep Complete\n\n| Metric | Count |\n|--------|-------|\n| Files scanned | {filesScanned} |\n| Findings verified | {verified} |\n| PRs created | {prsCreated} |\n| Security findings | {securityFindings} |\n\nFull report: `{summaryPath}`\n```\n\n**On failure**: Show the error and note which steps completed.\n\n---\n\n## Resuming a Sweep\n\nEach phase is incremental. To resume from where you left off:\n\n1. Check `data/manifest.json` to see which phases are complete\n2. For scan: pass `--sweep-dir` to `scan.py`\n3. For verify: existing `data/verify/.json` files are skipped\n4. For issue: `create_issue.py` is idempotent (skips if `issueUrl` in manifest)\n5. For patch: existing entries in `data/patches.jsonl` are skipped\n6. For organize: safe to re-run (idempotent)\n\n## Output Directory Structure\n\n```\n.warden/sweeps//\n summary.md # Stats, key findings, PR links\n findings/ # One markdown per verified finding\n .md\n security/ # Security-specific view\n index.jsonl # Security findings index\n .md # Copies of security findings\n data/ # Structured data for tooling\n manifest.json # Run metadata, phase state\n scan-index.jsonl # Per-file scan tracking\n all-findings.jsonl # Every finding from scan\n verified.jsonl # Findings that passed verification\n rejected.jsonl # Findings that failed verification\n patches.jsonl # Finding -> PR URL -> reviewers\n existing-prs.json # Cached open warden PRs\n report.json # Machine-readable summary\n verify/ # Individual verification results\n .json\n logs/ # Warden JSONL logs per file\n .jsonl\n pr-diffs/ # Cached PR diffs for dedup\n .diff\n```\n\n\n# CLI Reference\n\n## Usage\n\n```\nwarden [command] [targets...] [options]\n```\n\nAnalyze code for security issues and code quality.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `(default)` | Run analysis on targets or using warden.toml skills |\n| `init` | Initialize warden.toml and GitHub workflow |\n| `add [skill]` | Add a skill to warden.toml |\n| `sync [remote]` | Update cached remote skills to latest |\n| `setup-app` | Create a GitHub App for Warden via manifest flow |\n\n## Targets\n\n| Target | Description |\n|--------|-------------|\n| `` | Analyze specific files (e.g., `src/auth.ts`) |\n| `` | Analyze files matching pattern (e.g., `\"src/**/*.ts\"`) |\n| `` | Analyze changes from git ref (e.g., `HEAD~3`, `main..feature`) |\n| `(none)` | Analyze uncommitted changes using warden.toml skills |\n\nAmbiguous targets (no path separator, no extension) are resolved by checking if a file exists at the path. Use `--git` to force git ref interpretation.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--skill ` | Run only this skill (default: run all built-in skills) |\n| `--config ` | Path to warden.toml (default: `./warden.toml`) |\n| `-m, --model ` | Model to use (fallback when not set in config) |\n| `--json` | Output results as JSON |\n| `-o, --output ` | Write full run output to a JSONL file |\n| `--fail-on ` | Exit with code 1 if findings >= severity |\n| `--report-on ` | Only show findings >= severity in output |\n| `--fix` | Automatically apply all suggested fixes |\n| `--parallel ` | Max concurrent skill executions (default: 4) |\n| `--git` | Force ambiguous targets to be treated as git refs |\n| `--offline` | Use cached remote skills without network access |\n| `-q, --quiet` | Errors and final summary only |\n| `-v, --verbose` | Show real-time findings and hunk details |\n| `-vv` | Show debug info (token counts, latencies) |\n| `--debug` | Enable debug output (equivalent to `-vv`) |\n| `--log` | Use log output (no animations, timestamped) |\n| `--color / --no-color` | Override color detection |\n| `-h, --help` | Show help message |\n| `-V, --version` | Show version number |\n\n## Per-Command Options\n\n**Init:**\n| Option | Description |\n|--------|-------------|\n| `-f, --force` | Overwrite existing files |\n\n**Add:**\n| Option | Description |\n|--------|-------------|\n| `--list` | List available skills |\n| `--remote ` | Remote repository (`owner/repo`, URL, or with `@sha`) |\n| `--force` | Bypass skill cache and fetch latest |\n\n**Sync:**\n| Option | Description |\n|--------|-------------|\n| `--remote ` | Specific remote to sync (default: all) |\n\n**Setup-app:**\n| Option | Description |\n|--------|-------------|\n| `--org ` | Create under organization (default: personal) |\n| `--port ` | Local server port (default: 3000) |\n| `--timeout ` | Callback timeout in seconds (default: 300) |\n| `--name ` | Custom app name (default: Warden) |\n| `--no-open` | Print URL instead of opening browser |\n\n## Severity Levels\n\nUsed in `--fail-on` and `--report-on`:\n\n| Level | Meaning |\n|-------|---------|\n| `high` | Must fix before merge |\n| `medium` | Worth reviewing |\n| `low` | Minor improvement |\n| `off` | Disable the threshold |\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | No findings at or above `--fail-on` threshold |\n| `1` | Findings at or above `--fail-on` threshold |\n\n## Examples\n\n```bash\n# Initialize\nwarden init\n\n# Interactive skill selection\nwarden add\nwarden add \nwarden add --list\n\n# Remote skills\nwarden add --remote / --skill \nwarden add --remote https://github.com// --skill \nwarden add --remote /@ --skill \n\n# Run analysis\nwarden # Skills from warden.toml\nwarden src/auth.ts # Specific file\nwarden src/auth.ts --skill \nwarden \"src/**/*.ts\" # Glob pattern\nwarden HEAD~3 # Git changes\nwarden HEAD~3 --skill \nwarden main..HEAD # Branch diff\n\n# Output control\nwarden --json\nwarden --fail-on high\nwarden -o results.jsonl\n\n# Fix mode\nwarden --fix\n\n# Cached skills only\nwarden --offline\nwarden sync # Update all unpinned remote skills\n\n# GitHub App setup\nwarden setup-app\nwarden setup-app --org myorg\n```\n\n\n# warden.toml Configuration Schema\n\n## Top-Level Structure\n\n```toml\nversion = 1 # Required, must be 1\n\n[defaults] # Optional, inherited by all skills\n[[skills]] # Required, array of skill configs\n```\n\n## Defaults Section\n\n```toml\n[defaults]\nmodel = \"claude-sonnet-4-20250514\" # Default model\nmaxTurns = 50 # Max agentic turns per hunk\ndefaultBranch = \"main\" # Base branch for comparisons\nfailOn = \"high\" # Exit 1 if findings >= this severity\nreportOn = \"medium\" # Show findings >= this severity\nmaxFindings = 50 # Max findings to report (0 = unlimited)\nreportOnSuccess = false # Post report even with no findings\npaths = [\"src/**/*.ts\"] # Include only matching files\nignorePaths = [\"*.test.ts\"] # Exclude matching files\n\n[defaults.chunking]\nenabled = true # Enable hunk-based chunking\n\n[defaults.chunking.coalesce]\nenabled = true # Merge nearby hunks\nmaxGapLines = 30 # Lines between hunks to merge\nmaxChunkSize = 8000 # Max chars per chunk\n\n[[defaults.chunking.filePatterns]]\npattern = \"*.config.*\" # Glob pattern\nmode = \"whole-file\" # per-hunk | whole-file | skip\n```\n\n## Skills Section\n\n```toml\n[[skills]]\nname = \"skill-name\" # Required, unique identifier\nremote = \"owner/repo@sha\" # Optional, fetch skill from GitHub repo\npaths = [\"src/**\"] # Include only matching files\nignorePaths = [\"**/*.test.ts\"] # Exclude matching files\n\n# Optional overrides (inherit from defaults if not set)\nmodel = \"claude-opus-4-20250514\"\nmaxTurns = 100\nfailOn = \"high\"\nreportOn = \"medium\"\nmaxFindings = 20\nreportOnSuccess = true\n\n[[skills.triggers]]\ntype = \"pull_request\" # Required: pull_request | local | schedule\nactions = [\"opened\", \"synchronize\"] # Required for pull_request\n\n# Schedule-specific (only for type = \"schedule\")\n[[skills.triggers]]\ntype = \"schedule\"\n\n[skills.triggers.schedule]\nissueTitle = \"Daily Security Review\" # GitHub issue title for tracking\ncreateFixPR = true # Create PR with fixes\nfixBranchPrefix = \"security-fix\" # Branch name prefix\n```\n\n**Trigger types:**\n- `pull_request` - Triggers on PR events\n- `local` - Local CLI only (will not run in CI)\n- `schedule` - Cron schedule (GitHub Action only)\n\nAll skills run locally regardless of trigger type. Skills with no triggers run everywhere (wildcard). Use `type = \"local\"` for skills that should *only* run locally.\n\n**Actions (for pull_request):**\n- `opened`, `synchronize`, `reopened`, `closed`\n\n## Severity Values\n\nUsed in `failOn` and `reportOn`:\n- `high` - Must fix before merge\n- `medium` - Worth reviewing\n- `low` - Minor improvement\n- `off` - Disable threshold\n\n## Built-in Skip Patterns\n\nAlways skipped (cannot be overridden):\n- Package locks: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `Cargo.lock`, etc.\n- Minified files: `**/*.min.js`, `**/*.min.css`\n- Build artifacts: `dist/`, `build/`, `node_modules/`, `.next/`, `__pycache__/`\n- Generated code: `*.generated.*`, `*.g.ts`, `__generated__/`\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required) |\n| `WARDEN_MODEL` | Default model (lowest priority) |\n| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |\n| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |\n\n## Model Precedence (highest to lowest)\n\n1. Skill-level `model`\n2. `[defaults]` `model`\n3. CLI `--model` flag\n4. `WARDEN_MODEL` env var\n5. SDK default\n\n\n# Configuration (warden.toml)\n\nSee [config-schema.md](config-schema.md) for the complete schema reference.\n\n## Minimal Example\n\nThe `name` field references a skill you've created (via `warden add`) or defined in `.agents/skills//SKILL.md`. Use that same name everywhere — in config, CLI flags, and triggers.\n\n```toml\nversion = 1\n\n[defaults]\nmodel = \"claude-sonnet-4-20250514\"\n\n[[skills]]\nname = \"my-skill\" # matches .agents/skills/my-skill/SKILL.md\npaths = [\"src/**/*.ts\"]\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n## Skill Configuration\n\nSkills define what to analyze and when. Each skill requires a name. Triggers are optional — skills with no triggers run everywhere (PR, local, schedule). All skills run locally regardless of trigger type.\n\n```toml\n[[skills]]\nname = \"my-skill\"\npaths = [\"src/auth/**\", \"src/payments/**\"]\nfailOn = \"high\"\nreportOn = \"medium\"\nmaxFindings = 20\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Trigger types:** `pull_request`, `local` (local-only), `schedule` (CI-only)\n\n**Actions (pull_request):** `opened`, `synchronize`, `reopened`, `closed`\n\n## Common Patterns\n\n**Strict checks on critical files:**\n```toml\n[[skills]]\nname = \"my-skill\"\nmodel = \"claude-opus-4-20250514\"\nmaxTurns = 100\npaths = [\"src/auth/**\", \"src/payments/**\"]\nfailOn = \"high\"\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Skip test files:**\n```toml\n[[skills]]\nname = \"my-skill\"\npaths = [\"src/**/*.ts\"]\nignorePaths = [\"**/*.test.ts\", \"**/*.spec.ts\"]\n```\n\n**Whole-file analysis for configs:**\n```toml\n[defaults.chunking.filePatterns]\npattern = \"*.config.*\"\nmode = \"whole-file\"\n```\n\n## Model Precedence\n\nFrom highest to lowest priority:\n\n1. Skill-level `model`\n2. `[defaults]` `model`\n3. CLI `--model` flag\n4. `WARDEN_MODEL` env var\n5. SDK default\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required unless using Claude Code subscription) |\n| `WARDEN_MODEL` | Default model (lowest priority) |\n| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |\n| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |\n\n## Troubleshooting\n\n**No findings reported:**\n- Check `--report-on` threshold (default shows all)\n- Verify skill matches file types in `paths`\n- Use `-v` to see which files are being analyzed\n\n**Files being skipped:**\n- Built-in skip patterns: lock files, minified, `node_modules/`, `dist/`\n- Check `ignorePaths` in config\n- Use `-vv` to see skip reasons\n\n**Token/cost issues:**\n- Reduce `maxTurns` (default: 50)\n- Use chunking settings to control chunk size\n- Filter to relevant files with `paths`\n\n\n# Creating Skills\n\nSkills are markdown files that tell Warden what to look for. They follow the [agentskills.io](https://agentskills.io) specification.\n\n## Skill Discovery\n\nWarden searches these directories in order (first match wins):\n\n```\n.agents/skills/{name}/SKILL.md # Primary (recommended)\n.claude/skills/{name}/SKILL.md # Backup (Claude Code convention)\n```\n\n## SKILL.md Format\n\n```markdown\n---\nname: my-skill\ndescription: What this skill analyzes\nallowed-tools: Read Grep Glob\n---\n\n[Analysis instructions for the agent]\n\n## What to Look For\n- Specific issue type 1\n- Specific issue type 2\n\n## Output Format\nReport findings with severity, location, and suggested fix.\n```\n\n## Available Tools\n\n`Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Bash`, `Write`, `Edit`\n\nMost review skills only need `Read`, `Grep`, and `Glob` for exploring context.\n\n## Writing Checklist\n\n- One skill, one concern (\"security review\" not \"code quality\")\n- Clear criteria for what counts as an issue and at what severity\n- Actionable findings that include how to fix\n- Examples of good and bad code where helpful\n\n## Remote Skills\n\nSkills can be fetched from GitHub repositories:\n\n```bash\n# Add a remote skill\nwarden add --remote / --skill \n\n# Add with version pinning (recommended for reproducibility)\nwarden add --remote /@ --skill \n\n# List skills in a remote repo\nwarden add --remote / --list\n\n# Update all unpinned remote skills\nwarden sync\n\n# Update specific repo\nwarden sync /\n\n# Run with cached skills only (no network)\nwarden --offline\n```\n\n**Remote skill in warden.toml:**\n\n```toml\n[[skills]]\nname = \"my-skill\"\nremote = \"/@\"\n\n[[skills.triggers]]\ntype = \"pull_request\"\nactions = [\"opened\", \"synchronize\"]\n```\n\n**Cache location:** `~/.local/warden/skills/` (override with `WARDEN_STATE_DIR`)\n\n**Cache TTL:** 24 hours for unpinned refs (override with `WARDEN_SKILL_CACHE_TTL` in seconds)\n\n\n---\nname: warden\ndescription: Run Warden to analyze code changes before committing. Use when asked to \"run warden\", \"check my changes\", \"review before commit\", \"warden config\", \"warden.toml\", \"create a warden skill\", \"add trigger\", or any Warden-related local development task.\n---\n\nRun Warden to analyze code changes before committing.\n\n## References\n\nRead the relevant reference when the task requires deeper detail:\n\n| Document | Read When |\n|----------|-----------|\n| `${CLAUDE_SKILL_ROOT}/references/cli-reference.md` | Full option details, per-command flags, examples |\n| `${CLAUDE_SKILL_ROOT}/references/configuration.md` | Editing warden.toml, triggers, patterns, troubleshooting |\n| `${CLAUDE_SKILL_ROOT}/references/config-schema.md` | Exact field names, types, and defaults |\n| `${CLAUDE_SKILL_ROOT}/references/creating-skills.md` | Writing custom skills, remote skills, skill discovery |\n\n## Running Warden\n\n```bash\n# Analyze uncommitted changes (uses warden.toml triggers)\nwarden\n\n# Run a specific skill\nwarden --skill \n\n# Analyze specific files\nwarden src/auth.ts src/database.ts\n\n# Analyze changes from a git ref\nwarden main..HEAD\nwarden HEAD~3\n\n# Auto-apply suggested fixes\nwarden --fix\n\n# Fail on high-severity findings\nwarden --fail-on high\n```\n\nSet `WARDEN_ANTHROPIC_API_KEY` or log in via `claude login` before running.\n\n## Pre-Commit Workflow\n\nAfter making code changes and before committing:\n\n1. Run `warden` to analyze uncommitted changes\n2. Review the findings\n3. Fix issues Warden reports (or use `warden --fix` to auto-apply)\n4. Commit the changes\n\nRun Warden once to validate work. Do not loop re-running Warden on the same changes.\n\n## Reading Output\n\n**Severity levels:**\n- `high` - Must fix before merge\n- `medium` - Worth reviewing\n- `low` - Minor improvement\n\n**Exit codes:** `0` = no findings at or above fail threshold. `1` = findings at or above fail threshold.\n\n**Verbosity:** `-v` shows real-time findings. `-vv` shows debug info (tokens, latency). `-q` shows errors and summary only.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `warden` | Run analysis (default) |\n| `warden init` | Initialize warden.toml and GitHub workflow |\n| `warden add [skill]` | Add skill trigger to warden.toml |\n| `warden sync [remote]` | Update cached remote skills |\n| `warden setup-app` | Create GitHub App via manifest flow |\n\nFor full options and flags, read `${CLAUDE_SKILL_ROOT}/references/cli-reference.md`.\n\n\n---\nname: mobilebuildmcp-cli\ndescription: Official skill for the MobileBuildMCP CLI. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).\n---\n\n# MobileBuildMCP CLI\n\nUse MobileBuildMCP tools via the `mobilebuildmcp` executable instead of raw `xcodebuild`, `xcrun`, or `simctl`.\n\n## Step 1: Ensure the CLI Exists\n\nCheck availability:\n```bash\nmobilebuildmcp --help\n```\n\nIf missing, install with one of:\n```bash\nbrew tap getsentry/xcodebuildmcp\nbrew install mobilebuildmcp\n```\n\n```bash\nnpm install -g mobilebuildmcp@latest\n```\n\nRe-check after install:\n```bash\nmobilebuildmcp --help\n```\n\n## Step 2: Use Help-First Discovery\n\nDiscover workflows and arguments from the CLI itself:\n```bash\nmobilebuildmcp --help\nmobilebuildmcp tools\nmobilebuildmcp --help\nmobilebuildmcp --help\n```\n\nUse this discovery path instead of memorizing static tool lists.\n\n## Step 3: Keep Execution Minimal\n\n- Choose the smallest command sequence that satisfies the request.\n- Prefer direct workflow commands over manual multi-step chains unless explicitly requested.\n- For simulator run intent, prefer the combined `build-and-run` command.\n- Do not chain `build` then `build-and-run` unless explicitly requested.\n\n## Capability Overview\n\n`mobilebuildmcp` supports:\n- simulator and device build/test/run\n- debugging and log capture\n- UI automation\n- project discovery and scaffolding\n- session defaults and workflow configuration\n\n## Exit Criteria\n\n- CLI presence is verified or installation steps are provided.\n- Commands are discovered via `--help` / `tools`.\n- Session defaults are checked before first build/run/test action.\n\n\n---\nname: mobilebuildmcp\ndescription: Official skill for MobileBuildMCP. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).\n---\n\n# MobileBuildMCP\n\nUse MobileBuildMCP tools instead of raw `xcodebuild`, `xcrun`, or `simctl`.\n\nCapabilities:\n- Session defaults: Configure project, scheme, simulator, and device defaults to avoid repetitive parameters\n- Project discovery: Find Xcode projects/workspaces, list schemes, inspect build settings\n- Simulator workflows: Build, run, test, install, and launch apps on iOS simulators; manage simulator state (boot, erase, location, appearance)\n- Device workflows: Build, test, install, and launch apps on physical devices with code signing\n- macOS workflows: Build, run, and test macOS applications\n- Log capture: Stream and capture logs from simulators and devices\n- LLDB debugging: Attach debugger, set breakpoints, inspect stack traces and variables, execute LLDB commands\n- UI automation: Capture screenshots, inspect view hierarchy with coordinates, perform taps/swipes/gestures, type text, press hardware buttons\n- SwiftPM: Build, run, test, and manage Swift Package Manager projects\n- Project scaffolding: Generate new iOS/macOS project templates\n\nOnly simulator workflow tools are enabled by default. If capabilities like device, macOS, debugging, or UI automation are not available, the user must configure MobileBuildMCP to enable them. See https://github.com/getsentry/xcodebuildmcp.com/blob/main/app/docs/_content/configuration.mdx for workflow configuration.\n\n## Step 1: Establish Session Context\n\n- Call `session_show_defaults` before the first build/run/test action in a session.\n- Use `discover_projs` only when defaults show missing or incorrect project/workspace context.\n- Do not run discovery speculatively or in parallel with `session_show_defaults`.\n- For simulator run intent, prefer the combined build-and-run tool instead of separate build then run calls.\n- Do not chain build-only then build-and-run unless the user explicitly requests both.\n\n## Step 2: Understand Workflow-Scoped Tool Availability\n\n- Not all tools are enabled by default; tool availability depends on enabled workflows.\n- If a tool is expected but missing, check enabled workflows first.\n- Update enabled workflows in `.mobilebuildmcp/config.yaml`, then ask user to reload/restart the session to surface refreshes.\n\n## Step 3: Report Context Clearly\n\n- Return the active defaults context used for execution (project/workspace, scheme, simulator/device).\n- For failures, include the exact failing step and the next actionable command/tool call.\n"}