agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/data/mcp/templates/slack/wrapper.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+if [[ -t 1 && -z ${NO_COLOR:-} ]]; then
+  c_reset=$'\033[0m'
+  c_blue=$'\033[1;34m'
+  c_red=$'\033[1;31m'
+else
+  c_reset=''
+  c_blue=''
+  c_red=''
+fi
+
+info() { printf '%b[mcp-wrapper]%b %s\n' "$c_blue" "$c_reset" "$*"; }
+fail() { printf '%b[mcp-wrapper]%b %s\n' "$c_red" "$c_reset" "$*"; }
+
+if [[ -z ${SLACK_BOT_TOKEN:-} || -z ${SLACK_APP_TOKEN:-} ]]; then
+  fail "SLACK_BOT_TOKEN and SLACK_APP_TOKEN are required" >&2
+  exit 1
+fi
+
+info "starting mcp-slack-server"
+exec mcp-slack-server

agent_toolkit/data/packs/README.md

@@ -0,0 +1,66 @@
+# Solution Packs
+
+> **Docs-only** — packs are not loaded by the compiler (`agent-toolkit build`). They are workflow templates that reference skills/loops. For plugin composition, edit `distributions/products.yaml` (see `docs/adrs/ADR-006-packs-docs-only.md`).
+>
+> **Not the only pack noun.** The word "pack" has three meanings in this project. This file documents solution packs. See `docs/CONCEPTS.md#three-kinds-of-packs` for workspace packs (`workspace load`) and loop `--pack` overrides (`loop run --pack`).
+
+Solution packs bundle related skills, agent personas, loop templates, and MCP configurations
+into outcome-oriented workflows for common team setups.
+
+## Available Packs
+
+| Pack | Description | Status |
+|------|-------------|--------|
+| [oss-maintenance](oss-maintenance/) | Automate PR review, issue triage, and daily briefings across OSS repos | ✅ Ready |
+| [engineering-workflow](engineering-workflow/) | End-to-end engineering delivery: planning → implementation → review → deploy | ✅ Ready (config shipped) |
+| [delivery-discipline](delivery-discipline/) | Ticket hygiene, traceability, and process compliance | ✅ Ready (config shipped) |
+| [agentic-security](agentic-security/) | Agentic security, supply-chain, MCP, OWASP, threat modeling | ✅ Ready (config shipped) |
+| [architecture](architecture/) | Architecture, ADRs, cloud design, diagramming, C4 | ✅ Ready (config shipped) |
+| [code-quality](code-quality/) | Code quality, MegaLinter, CodeQL, CI fix, inventory | ✅ Ready (config shipped) |
+| [design-engineering](design-engineering/) | Design-engineering, frontend, a11y, Chrome DevTools | ✅ Ready (config shipped) |
+
+## Using a Pack
+
+Each pack has a `config.yaml` for customization and a `README.md` with setup instructions.
+
+```bash
+# Example: set up OSS maintenance for your repos
+cp packs/oss-maintenance/config.yaml ~/.ai-workspace/packs/
+# Edit repos list in config.yaml
+# Then use loops/oss-pr-monitor, loops/oss-triage, loops/oss-daily-briefing
+```
+
+## Pack config.yaml fields
+
+The `config.yaml` declares three top-level sections:
+
+- `loops` — Loop overrides (`enabled`, `cadence`, `tier`, `verifier`, `goal`, `budget`).
+  These are applied by `loop run --pack`. See `loop/pack.py`.
+- `skills` — Advisory only. Lists which skills the pack recommends. The `loop run --pack`
+  command does **not** read or apply `skills:` entries. Authors may list them as
+  documentation.
+- `agents` — Advisory only. Lists which agent personas the pack recommends. The `loop run --pack`
+  command does **not** read or apply `agents:` entries. Authors may list them as
+  documentation.
+
+The `skills:` and `agents:` keys are human-readable labels, not machine-applied actions.
+The pack format may grow a loader in the future (see ADR-006 follow-up note), but today
+only `loops:` is handled by the code.
+
+## Creating a Pack
+
+A pack is a directory containing:
+- `README.md` — purpose, setup, usage
+- `config.yaml` — configurable parameters
+- Optional: `AGENTS.md` snippet, skill list, loop references
+
+## New Packs — #390 (docs-only, curated)
+
+| Pack | Description | Status |
+|------|-------------|--------|
+| [design-engineering](design-engineering/) | Frontend/design-engineering: figma → frontend-design → review + a11y → mermaid/C4 | ✅ Ready (config shipped, trust_tier community) |
+| [agentic-security](agentic-security/) | Supply-chain + MCP audit + OWASP agentic + threat-modeling | ✅ Ready |
+| [code-quality](code-quality/) | MegaLinter v10 + CodeQL + gh-fix-ci | ✅ Ready |
+| [architecture](architecture/) | Vendor-neutral core (adr/trd/threat-model/mermaid/c4) + optional cloud (cloud-design-patterns/aws-well-architected-review) | ✅ Ready |
+
+All packs are **docs-only** per ADR-0003 (advisory `skills:`/`agents:`; only `loops:` handled by `loop run --pack`). See `docs/CONCEPTS.md#three-kinds-of-packs`. Not a giant default pack — `complete` stays experimental per #390.

agent_toolkit/data/packs/agentic-security/README.md

@@ -0,0 +1,19 @@
+# Agentic-Security Pack — docs-only
+
+Curated for agentic-security per #390: supply-chain, MCP audit, OWASP agentic, threat-modeling.
+
+## Components
+- **Skills:** supply-chain-audit (provenance lock per ADR-0001), mcp-audit + mcp-security, owasp-agentic-review, threat-modeling, inventory
+- **Agents:** security-reviewer, agentic-security-reviewer
+- **Loops:** security-audit (optional)
+
+## Setup
+```bash
+cp packs/agentic-security/config.yaml ~/.ai-workspace/packs/agentic-security.yaml
+```
+
+## Workflow
+supply-chain-audit → mcp-audit → owasp-agentic-review → threat-modeling (STRIDE) → agentic-security-reviewer → ADR.
+
+## Trust
+All first-party except supply-chain (reviewed) — pack trust_tier: verified; no community shell skill auto-enabled.

agent_toolkit/data/packs/agentic-security/config.yaml

@@ -0,0 +1,25 @@
+# Agentic-Security Pack — docs-only per ADR-0003
+pack: agentic-security
+version: "1.0"
+# Advisory only — not applied by `loop run --pack`.
+skills:
+  agentic-security/supply-chain-audit:
+    enabled: true
+  agentic-security/mcp-audit:
+    enabled: true
+  agentic-security/owasp-agentic-review:
+    enabled: true
+  agentic-security/threat-modeling:
+    enabled: true
+  tooling/inventory:
+    enabled: true
+# Advisory only — not applied by `loop run --pack`.
+agents:
+  security-reviewer:
+    enabled: true
+  agentic-security-reviewer:
+    enabled: true
+loops:
+  security-audit:
+    enabled: false
+    cadence: 1d

agent_toolkit/data/packs/architecture/README.md

@@ -0,0 +1,22 @@
+# Architecture Pack — docs-only, vendor-neutral
+
+Curated for architecture per #390: vendor-neutral core + optional cloud.
+
+## Components
+- **Core (vendor-neutral):** architect, adr, trd, threat-modeling, mermaid + c4-model (C4 via Mermaid per #385)
+- **Optional (cloud):** cloud-design-patterns, aws-well-architected-review (disabled by default, enable for AWS per #384 — see docs/cloud/research-384-candidates.md, AWS MCP vs prompt)
+- **Loops:** architecture-review (optional)
+
+## Setup
+```bash
+cp packs/architecture/config.yaml ~/.ai-workspace/packs/architecture.yaml
+# Enable cloud optional:
+# cloud/cloud-design-patterns: enabled: true
+# cloud/aws-well-architected-review: enabled: true
+```
+
+## Workflow
+architect → adr (6-part, lifecycle PROPOSED→ACCEPTED→SUPERSEDED) → trd → threat-model → mermaid/c4-model → cloud-design-patterns/aws-well-architected-review (optional, via awslabs/mcp when live).
+
+## Trust
+All first-party, vendor-neutral core trust_tier: verified; cloud optional adds aws-well-architected (first-party) — no community shell.

agent_toolkit/data/packs/architecture/config.yaml

@@ -0,0 +1,27 @@
+# Architecture Pack — docs-only per ADR-0003, vendor-neutral core per #384
+pack: architecture
+version: "1.0"
+# Advisory only — not applied by `loop run --pack`.
+skills:
+  delivery/adr:
+    enabled: true
+  delivery/trd:
+    enabled: true
+  agentic-security/threat-modeling:
+    enabled: true
+  tooling/mermaid:
+    enabled: true
+  architecture/c4-model:
+    enabled: true
+  cloud/cloud-design-patterns:
+    enabled: false
+  cloud/aws-well-architected-review:
+    enabled: false
+# Advisory only — not applied by `loop run --pack`.
+agents:
+  architect:
+    enabled: true
+loops:
+  architecture-review:
+    enabled: false
+    cadence: 1w

agent_toolkit/data/packs/code-quality/README.md

@@ -0,0 +1,19 @@
+# Code-Quality Pack — docs-only
+
+Curated for code-quality per #390: MegaLinter + CodeQL + CI.
+
+## Components
+- **Skills:** megalinter (oxsecurity/megalinter v10.0.0 external, AGPL-3.0, distribution external), codeql (first-party, 5 modes), gh-fix-ci, inventory
+- **Agents:** code-reviewer
+- **Loops:** ci-sweeper (optional)
+
+## Setup
+```bash
+cp packs/code-quality/config.yaml ~/.ai-workspace/packs/code-quality.yaml
+```
+
+## Workflow
+megalinter (orchestrator v10) → codeql (5 modes) → gh-fix-ci → inventory → PR.
+
+## Trust
+megalinter external (AGPL-3.0, redistribution_allowed false, not vendor) + codeql first-party → pack trust_tier: reviewed (external pinned, not vendored).

agent_toolkit/data/packs/code-quality/config.yaml

@@ -0,0 +1,21 @@
+# Code-Quality Pack — docs-only per ADR-0003
+pack: code-quality
+version: "1.0"
+# Advisory only — not applied by `loop run --pack`.
+skills:
+  quality/megalinter:
+    enabled: true
+  quality/codeql:
+    enabled: true
+  forge/gh-fix-ci:
+    enabled: true
+  tooling/inventory:
+    enabled: true
+# Advisory only — not applied by `loop run --pack`.
+agents:
+  code-reviewer:
+    enabled: true
+loops:
+  ci-sweeper:
+    enabled: false
+    cadence: 15m

agent_toolkit/data/packs/delivery-discipline/README.md

@@ -0,0 +1,19 @@
+# Delivery Discipline Pack
+
+Ticket hygiene, traceability, and process compliance for engineering teams.
+
+## Components
+
+- **Skills**: task, bug, epic, user-story, project-assessment, development-workflow
+- **Agents**: tech-assistant, planner
+
+## Setup
+
+```bash
+cp packs/delivery-discipline/config.yaml ~/.ai-workspace/packs/delivery-discipline.yaml
+# Toggle skills or agents for your team's process
+```
+
+## Status
+
+✅ Ready — usable `config.yaml` shipped. See [packs/README.md](../README.md) for pack conventions.

agent_toolkit/data/packs/delivery-discipline/config.yaml

@@ -0,0 +1,42 @@
+# Delivery Discipline Pack Configuration
+# Copy this file to your workspace and toggle skills or agents for your team.
+#
+# Usage:
+#   cp packs/delivery-discipline/config.yaml ~/.ai-workspace/packs/delivery-discipline.yaml
+#
+# See packs/delivery-discipline/README.md for full setup instructions.
+
+pack: delivery-discipline
+version: "1.0"
+
+# ---------------------------------------------------------------------------
+# Skills
+# ---------------------------------------------------------------------------
+# Advisory only — not applied by `loop run --pack`.
+# Domain/path IDs matching catalogs/skill-catalog.yaml.
+# See packs/README.md and ADR-006.
+
+skills:
+  delivery/task:
+    enabled: true
+  delivery/bug:
+    enabled: true
+  delivery/epic:
+    enabled: true
+  delivery/user-story:
+    enabled: true
+  delivery/project-assessment:
+    enabled: true
+  delivery/development-workflow:
+    enabled: true
+
+# ---------------------------------------------------------------------------
+# Agents
+# ---------------------------------------------------------------------------
+# Advisory only — not applied by `loop run --pack`.
+
+agents:
+  tech-assistant:
+    enabled: true
+  planner:
+    enabled: true

agent_toolkit/data/packs/design-engineering/README.md

@@ -0,0 +1,19 @@
+# Design-Engineering Pack — docs-only
+
+Curated workflow for frontend/design-engineering per #390 and ADR-0003 (docs-only, not compiler-wired).
+
+## Components
+- **Skills:** frontend-design (vendored anthropics/skills f17010c), frontend-design-review (microsoft/skills e58528d), web-design-guidelines, design-assessment (delegated by project-assessment per ADR-0002), design-improvement, figma (via mcp.figma.com/mcp OAuth), figma-implement-design, chrome-devtools, playwright-cli, a11y/review, architecture/c4-model + tooling/mermaid (C4 via Mermaid per #385)
+- **Agents:** architect, code-reviewer, design-assessment
+- **Loops:** design-review (optional, disabled)
+
+## Setup
+```bash
+cp packs/design-engineering/config.yaml ~/.ai-workspace/packs/design-engineering.yaml
+```
+
+## Workflow
+project-assessment → design-assessment → figma → frontend-design → frontend-design-review + web-design-guidelines → design-improvement + a11y → chrome-devtools/playwright → mermaid/c4-model → ADR.
+
+## Trust
+Pack inherits max source risk: frontend-design (official, reviewed) + frontend-design-review (community, MIT) → trust_tier: community — do not auto-enable without review per §88.

agent_toolkit/data/packs/design-engineering/config.yaml

@@ -0,0 +1,41 @@
+# Design-Engineering Pack — docs-only per ADR-0003 (not loaded by `agent-toolkit build`)
+pack: design-engineering
+version: "1.0"
+# Advisory only — not applied by `loop run --pack`.
+skills:
+  design/frontend-design:
+    enabled: true
+  design/frontend-design-review:
+    enabled: true
+  design/web-design-guidelines:
+    enabled: true
+  design/design-assessment:
+    enabled: true
+  design/design-improvement:
+    enabled: true
+  design/figma:
+    enabled: true
+  design/figma-implement-design:
+    enabled: true
+  tooling/chrome-devtools:
+    enabled: true
+  tooling/playwright-cli:
+    enabled: true
+  accessibility/review:
+    enabled: true
+  architecture/c4-model:
+    enabled: true
+  tooling/mermaid:
+    enabled: true
+# Advisory only — not applied by `loop run --pack`.
+agents:
+  architect:
+    enabled: true
+  code-reviewer:
+    enabled: true
+  design-assessment:
+    enabled: true
+loops:
+  design-review:
+    enabled: false
+    cadence: 1d

agent_toolkit/data/packs/engineering-workflow/README.md

@@ -0,0 +1,21 @@
+# Engineering Workflow Pack
+
+End-to-end engineering delivery workflow covering planning, implementation, review, and deployment.
+
+## Components
+
+- **Skills**: workflow-generic-project, development-workflow, gh-contribution-planner
+- **Agents**: architect, planner, code-reviewer, security-reviewer
+- **Loops**: pr-babysitter (L2), ci-sweeper (L2)
+
+## Setup
+
+```bash
+cp packs/engineering-workflow/config.yaml ~/.ai-workspace/packs/engineering-workflow.yaml
+# Edit enabled skills, agents, or loop cadence as needed
+cp -r loops/pr-babysitter loops/ci-sweeper ~/.ai-workspace/loops/
+```
+
+## Status
+
+✅ Ready — usable `config.yaml` shipped. See [packs/README.md](../README.md) for pack conventions.

agent_toolkit/data/packs/engineering-workflow/config.yaml

@@ -0,0 +1,57 @@
+# Engineering Workflow Pack Configuration
+# Copy this file to your workspace and customize loop cadence or disable components.
+#
+# Usage:
+#   cp packs/engineering-workflow/config.yaml ~/.ai-workspace/packs/engineering-workflow.yaml
+#
+# See packs/engineering-workflow/README.md for full setup instructions.
+
+pack: engineering-workflow
+version: "1.0"
+
+# ---------------------------------------------------------------------------
+# Skills
+# ---------------------------------------------------------------------------
+# Advisory only — not applied by `loop run --pack`.
+# Domain/path IDs matching catalogs/skill-catalog.yaml.
+# These entries document which skills the pack recommends. The loader in
+# loop/pack.py does not read or apply skills: or agents: keys. See
+# packs/README.md and ADR-006 for the design decision.
+
+skills:
+  forge/workflow-generic-project:
+    enabled: true
+  delivery/development-workflow:
+    enabled: true
+  forge/gh-contribution-planner:
+    enabled: true
+
+# ---------------------------------------------------------------------------
+# Agents
+# ---------------------------------------------------------------------------
+# Advisory only — not applied by `loop run --pack`.
+
+agents:
+  architect:
+    enabled: true
+  planner:
+    enabled: true
+  code-reviewer:
+    enabled: true
+  security-reviewer:
+    enabled: true
+
+# ---------------------------------------------------------------------------
+# Loop settings
+# ---------------------------------------------------------------------------
+# Each loop can be individually enabled/disabled. Settings override defaults
+# in loops/<name>/loop.yaml.
+
+loops:
+  pr-babysitter:
+    enabled: true
+    cadence: 15m
+
+  ci-sweeper:
+    enabled: true
+    cadence: 15m

agent_toolkit/data/packs/oss-maintenance/README.md

@@ -0,0 +1,245 @@
+# OSS Maintenance Pack
+
+Automate PR review, issue triage, and daily briefings across a multi-repo OSS ecosystem. This pack combines three loops that work together to reduce the manual overhead of maintaining 10–50 open-source repositories.
+
+---
+
+## What It Does
+
+| Loop | Tier | Cadence | Actions | Description |
+|------|------|---------|---------|-------------|
+| `oss-daily-briefing` | L1 | Daily | Read-only | Summarizes new PRs, issues needing attention, and CI health across all repos |
+| `oss-triage` | L1 | Daily | label, comment, assign | Labels issues, responds to questions, asks for reproducers on bugs |
+| `oss-pr-monitor` | L2 | Daily | merge, close, label, comment | Merges safe Dependabot PRs, closes dirty ones, reports on human PRs |
+
+**Start with `oss-daily-briefing`.** Run it for a week before enabling `oss-triage`. Run triage for a week before enabling `oss-pr-monitor`. This progression lets you validate the loop's behavior at each tier before escalating.
+
+---
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated with push access to your repositories:
+  ```bash
+  gh auth status
+  gh auth login   # if not authenticated
+  ```
+- A loop runner available. The loops are designed for use with the `bin/loop` runner from [ai-workspace](https://github.com/ulises-jeremias/ai-workspace), but the `request` prompt in each `loop.yaml` can be run manually or with any compatible runner.
+- Token budget: see [Budget Sizing](#budget-sizing) below.
+
+---
+
+## Setup
+
+### Step 1: Copy the loop templates
+
+```bash
+# From the agent-toolkit directory
+cp -r loops/oss-pr-monitor  ~/.ai-workspace/loops/
+cp -r loops/oss-triage      ~/.ai-workspace/loops/
+cp -r loops/oss-daily-briefing ~/.ai-workspace/loops/
+```
+
+### Step 2: Configure your repo list
+
+```bash
+cp packs/oss-maintenance/config.yaml ~/.ai-workspace/packs/oss-maintenance.yaml
+```
+
+Edit `~/.ai-workspace/packs/oss-maintenance.yaml` and add your repositories:
+
+```yaml
+repos:
+  - myorg/my-library
+  - myorg/my-cli-tool
+  - myorg/another-repo
+```
+
+### Step 3: Reference the pack from each loop
+
+Each loop's `request` prompt uses the repos list from the pack config. If your loop runner does not inject pack config automatically, add the repo list directly to the loop's request template.
+
+Alternatively, create a shared repos file and reference it from each loop's request:
+
+```bash
+echo "owner/repo1" > ~/.ai-workspace/loops/repos.txt
+echo "owner/repo2" >> ~/.ai-workspace/loops/repos.txt
+```
+
+### Step 4: Run at each tier
+
+Start read-only. Graduate to each tier only after confirming the previous tier runs correctly.
+
+```bash
+# Tier 1: Daily briefing (read-only, lowest cost)
+./bin/loop run oss-daily-briefing
+
+# Tier 1: Issue triage (label + comment, medium cost)
+./bin/loop run oss-triage
+
+# Tier 2: PR monitor (merge + close, highest cost — REVIEW THE REPORT FIRST)
+./bin/loop run oss-pr-monitor
+```
+
+---
+
+## Budget Sizing
+
+Token consumption scales with the number of repos and open PRs/issues per repo. These estimates assume moderate activity (5–15 open PRs and 10–30 open issues per repo).
+
+| Repos | oss-daily-briefing | oss-triage | oss-pr-monitor |
+|-------|--------------------|------------|----------------|
+| 10    | ~20,000            | ~40,000    | ~80,000        |
+| 20    | ~40,000            | ~75,000    | ~150,000       |
+| 40    | ~80,000            | ~150,000   | ~300,000       |
+| 60    | ~120,000           | ~225,000   | ~450,000       |
+
+**Formula:** `max_tokens = (repo_count × avg_tokens_per_repo) + 20000` where:
+- `oss-daily-briefing`: ~1,500 tokens/repo
+- `oss-triage`: ~3,200 tokens/repo
+- `oss-pr-monitor`: ~7,000 tokens/repo
+
+To override the default budget in `config.yaml`:
+
+```yaml
+loops:
+  oss-pr-monitor:
+    enabled: true
+    cadence: 1d
+    budget:
+      max_tokens: 450000    # for 60 repos
+      max_wall_seconds: 3600
+```
+
+If your ecosystem has more than 50 repos, split it into two packs and run each with a separate loop instance:
+
+```yaml
+# oss-maintenance-alpha.yaml
+repos:
+  - org/repo-01
+  - org/repo-02
+  # ... first 25 repos
+
+# oss-maintenance-beta.yaml
+repos:
+  - org/repo-26
+  - org/repo-27
+  # ... next 25 repos
+```
+
+---
+
+## Resumability
+
+All three loops support mid-run checkpointing via `STATE.md`. If a 40-repo scan is interrupted at repo 17 (budget exhausted, timeout, or error), the next run automatically skips repos 1–16 and resumes from repo 17.
+
+### How it works
+
+1. At run start, the loop reads `loops/<name>/STATE.md`
+2. If `last_processed_repo` is set, it skips all earlier repos in the configured list
+3. After processing each repo, it writes `last_processed_repo: <owner>/<repo>` to `STATE.md`
+4. On successful completion, it clears `last_processed_repo` and sets `last_run_status: success`
+
+### Inspecting state
+
+```bash
+cat ~/.ai-workspace/loops/oss-pr-monitor/STATE.md
+```
+
+Example `STATE.md` after a partial run:
+
+```markdown
+last_processed_repo: myorg/repo-17
+last_run: 2026-08-04T09:23:11Z
+last_run_status: partial (budget_exhausted)
+```
+
+### Resetting state
+
+To force a full re-scan from the beginning:
+
+```bash
+# Remove the checkpoint field
+sed -i '/^last_processed_repo/d' ~/.ai-workspace/loops/oss-pr-monitor/STATE.md
+
+# Or overwrite the entire STATE.md
+cat > ~/.ai-workspace/loops/oss-pr-monitor/STATE.md <<'EOF'
+last_processed_repo:
+last_run:
+last_run_status:
+EOF
+```
+
+---
+
+## Reading the Reports
+
+After each loop run, a report is written to `loops/<name>/report.md`.
+
+### oss-daily-briefing report
+
+Sections: new PRs (last 24h), issues needing attention, CI health by repo, highlights.
+
+Review this report daily. If a repo shows persistent CI failures or a flood of new issues, investigate before the next run.
+
+### oss-triage report
+
+Sections: actions taken (labels applied, comments posted), items needing human review, escalations.
+
+**Review "items needing human review" every run.** These are issues the loop flagged as too complex to handle automatically. Security escalations appear here and should be addressed immediately.
+
+### oss-pr-monitor report
+
+Columns: Repo, PR number, Title, Author, Type (dep/bot/human), CI status, Action taken, Pending reason.
+
+**Review this report before the next daily run.** The loop merges Dependabot PRs automatically — the report tells you which ones were merged, which were closed, and which human PRs have CI failures or conflicts waiting for attention.
+
+---
+
+## Safety Gates
+
+The loops are designed to be safe by default. Key constraints:
+
+**oss-pr-monitor:**
+- Merges Dependabot PRs only when CI is fully green — no partial passes
+- Closes Dependabot PRs only when they are in a dirty state (GitHub will regenerate them)
+- Never merges or closes human PRs
+- Never approves any PR
+- Never force-pushes
+- Escalates on any security concern
+
+**oss-triage:**
+- Never closes issues
+- Never merges anything
+- Escalates security reports immediately (does not post a comment — uses `human_escalation` exit)
+
+**oss-daily-briefing:**
+- Fully read-only — zero mutations of any kind
+
+---
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `config.yaml` | Pack configuration: repo list and loop settings |
+| `loops/oss-daily-briefing/loop.yaml` | Daily briefing loop definition |
+| `loops/oss-triage/loop.yaml` | Issue triage loop definition |
+| `loops/oss-pr-monitor/loop.yaml` | PR monitor loop definition |
+| `loops/*/STATE.md` | Runtime checkpoint state (written by loop runner) |
+| `loops/*/report.md` | Loop output reports (written by AI) |
+
+---
+
+## Troubleshooting
+
+**Loop runs out of budget before finishing all repos.**
+Increase `max_tokens` in `config.yaml` or split your repo list across two packs. The loop will resume from where it left off on the next run regardless.
+
+**Dependabot PR was not merged despite passing CI.**
+Check the PR's merge status with `gh pr view <number> --repo <owner>/<repo>`. The loop skips PRs that are in draft state or have branch protection rules that require human approval.
+
+**A comment was posted that looks AI-generated.**
+The loops are instructed never to leave AI-looking comments. If you see one, file an issue with the comment text and the loop name so the prompt can be improved.
+
+**oss-pr-monitor is not picking up my repo.**
+Ensure the repo is in the `repos:` list in `config.yaml`, formatted as `owner/repo` (no `https://github.com/` prefix). Verify `gh api repos/owner/repo` succeeds from your terminal.