opencode-skills-collection 4.1.14 → 4.1.16

package/bundled-skills/agent-orchestrator/scripts/scan_registry.py

@@ -22,6 +22,8 @@ import sys
 import json
 import hashlib
 import re
+import tempfile
+import argparse
 from pathlib import Path
 from datetime import datetime
 
@@ -31,7 +33,12 @@ from datetime import datetime
 _SCRIPT_DIR = Path(__file__).resolve().parent
 ORCHESTRATOR_DIR = _SCRIPT_DIR.parent
 SKILLS_ROOT = ORCHESTRATOR_DIR.parent
-DATA_DIR = ORCHESTRATOR_DIR / "data"
+_data_directory = os.environ.get("AGENT_ORCHESTRATOR_DATA_DIR")
+if not _data_directory or not Path(_data_directory).is_absolute():
+    raise ValueError("Set AGENT_ORCHESTRATOR_DATA_DIR to an authorized absolute storage directory")
+DATA_DIR = Path(_data_directory)
+if DATA_DIR.is_symlink():
+    raise ValueError("Storage directory must not be a symlink")
 REGISTRY_PATH = DATA_DIR / "registry.json"
 HASHES_PATH = DATA_DIR / "registry_hashes.json"
 
@@ -143,33 +150,17 @@ def sha256_file(path: Path) -> str:
 
 def parse_yaml_frontmatter(path: Path) -> dict:
     """Extract YAML frontmatter from a SKILL.md file."""
-    try:
-        text = path.read_text(encoding="utf-8")
-    except Exception:
-        return {}
+    text = path.read_text(encoding="utf-8")
 
     match = re.match(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
     if not match:
         return {}
 
-    try:
-        import yaml
-        return yaml.safe_load(match.group(1)) or {}
-    except Exception:
-        # Fallback: manual parsing for name/description
-        result = {}
-        block = match.group(1)
-        for key in ("name", "description", "version"):
-            m = re.search(rf'^{key}:\s*["\']?(.+?)["\']?\s*$', block, re.MULTILINE)
-            if m:
-                result[key] = m.group(1).strip()
-            else:
-                # Handle multi-line description with >- or >
-                m2 = re.search(rf'^{key}:\s*>-?\s*\n((?:\s+.+\n?)+)', block, re.MULTILINE)
-                if m2:
-                    lines = m2.group(1).strip().split("\n")
-                    result[key] = " ".join(line.strip() for line in lines)
-        return result
+    import yaml  # required dependency; do not approximate malformed YAML
+    metadata = yaml.safe_load(match.group(1)) or {}
+    if not isinstance(metadata, dict):
+        raise ValueError("Skill frontmatter must be a mapping")
+    return metadata
 
 
 def find_skill_files() -> list[Path]:
@@ -179,7 +170,9 @@ def find_skill_files() -> list[Path]:
     for base in SEARCH_PATHS:
         if not base.exists():
             continue
-        for root, dirs, files in os.walk(base):
+        def fail_walk(error):
+            raise error
+        for root, dirs, files in os.walk(base, onerror=fail_walk):
             depth = len(Path(root).relative_to(base).parts)
             if depth > MAX_DEPTH:
                 dirs.clear()
@@ -190,7 +183,14 @@ def find_skill_files() -> list[Path]:
                 continue
 
             if "SKILL.md" in files:
-                found.add(Path(root) / "SKILL.md")
+                candidate = Path(root) / "SKILL.md"
+                if candidate.is_symlink():
+                    raise ValueError("Refusing symlink skill entrypoint")
+                if candidate.stat().st_size > 1024 * 1024:
+                    raise ValueError("Skill entrypoint exceeds 1 MiB")
+                found.add(candidate)
+                if len(found) > 10000:
+                    raise ValueError("Scan exceeds 10000 entrypoints")
 
     return sorted(found)
 
@@ -289,55 +289,88 @@ def is_registered(skill_dir: Path) -> bool:
 
 # ── Main Logic ─────────────────────────────────────────────────────────────
 
+def read_cache(path: Path, default: dict) -> dict:
+    if path.is_symlink():
+        raise ValueError("Cache file must not be a symlink")
+    if not path.exists():
+        return default
+    if path.stat().st_size > 16 * 1024 * 1024:
+        raise ValueError("Cache exceeds 16 MiB")
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("Cache must be a JSON object")
+    return data
+
+
+def write_cache(path: Path, data: dict):
+    # Caller chooses private storage; refuse existing linked ancestors/targets.
+    for ancestor in [DATA_DIR, *DATA_DIR.parents]:
+        if ancestor.is_symlink():
+            raise ValueError("Storage ancestors must not be symlinks")
+    DATA_DIR.mkdir(parents=True, exist_ok=True, mode=0o700)
+    if path.is_symlink():
+        raise ValueError("Cache target must not be a symlink")
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=DATA_DIR,
+                                         prefix=".registry-", delete=False) as stream:
+            temporary = Path(stream.name)
+            json.dump(data, stream, indent=2, ensure_ascii=False)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+
 def load_hashes() -> dict:
-    """Load stored hashes from registry_hashes.json."""
-    if HASHES_PATH.exists():
-        try:
-            return json.loads(HASHES_PATH.read_text(encoding="utf-8"))
-        except Exception:
-            pass
-    return {}
+    data = read_cache(HASHES_PATH, {})
+    if any(not isinstance(k, str) or not isinstance(v, str) for k, v in data.items()):
+        raise ValueError("Hash cache entries must be strings")
+    return data
 
 
 def save_hashes(hashes: dict):
-    """Save hashes to registry_hashes.json."""
-    DATA_DIR.mkdir(parents=True, exist_ok=True)
-    HASHES_PATH.write_text(json.dumps(hashes, indent=2), encoding="utf-8")
+    write_cache(HASHES_PATH, hashes)
 
 
 def load_registry() -> dict:
-    """Load existing registry.json."""
-    if REGISTRY_PATH.exists():
-        try:
-            return json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
-        except Exception:
-            pass
-    return {"generated_at": None, "skills_root": str(SKILLS_ROOT), "skills": []}
+    data = read_cache(REGISTRY_PATH, {"generated_at": None, "skills_root": str(SKILLS_ROOT), "skills": []})
+    if not isinstance(data.get("skills"), list) or any(not isinstance(v, dict) for v in data["skills"]):
+        raise ValueError("Registry skills must be objects")
+    return data
 
 
 def save_registry(registry: dict):
-    """Save registry.json."""
-    DATA_DIR.mkdir(parents=True, exist_ok=True)
     registry["generated_at"] = datetime.now().isoformat()
-    REGISTRY_PATH.write_text(json.dumps(registry, indent=2, ensure_ascii=False), encoding="utf-8")
+    write_cache(REGISTRY_PATH, registry)
 
 
 def build_skill_entry(skill_md_path: Path) -> dict:
     """Build a registry entry from a SKILL.md file."""
     skill_dir = skill_md_path.parent
     meta = parse_yaml_frontmatter(skill_md_path)
+    name = meta.get("name", skill_dir.name)
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("Skill name must be a nonempty string")
     description = meta.get("description", "")
+    if not isinstance(description, str):
+        raise ValueError("Skill description must be a string")
 
     # Support explicit capabilities in frontmatter
     explicit_caps = meta.get("capabilities", [])
     if isinstance(explicit_caps, str):
         explicit_caps = [c.strip() for c in explicit_caps.split(",")]
 
+    if not isinstance(explicit_caps, list) or any(not isinstance(c, str) for c in explicit_caps):
+        raise ValueError("Capabilities must be strings")
+
     auto_caps = extract_capabilities(description)
     all_caps = sorted(set(auto_caps + explicit_caps))
 
     return {
-        "name": meta.get("name", skill_dir.name),
+        "name": name,
         "description": description,
         "version": meta.get("version", ""),
         "location": str(skill_dir),
@@ -377,6 +410,9 @@ def scan(force: bool = False) -> dict:
     for entry in registry.get("skills", []):
         existing_by_path[entry.get("skill_md", "")] = entry
 
+    registry["complete_inventory"] = False
+    registry["coverage"] = {"max_depth": MAX_DEPTH, "roots": [str(p) for p in SEARCH_PATHS], "metadata_only": True}
+
     # Compute current hashes
     new_hashes = {}
     changed = False
@@ -401,27 +437,9 @@ def scan(force: bool = False) -> dict:
     if set(new_hashes.keys()) != set(stored_hashes.keys()):
         changed = True
 
-    # Deduplicate by skill name (case-insensitive).
-    # When the same skill exists in both skills/ and .claude/skills/,
-    # prefer the primary location (skills/) over the registered copy.
+    # Preserve distinct paths even when names coincide; names are not identities.
     if changed or not REGISTRY_PATH.exists():
-        by_name = {}
-        for entry in existing_by_path.values():
-            name = entry.get("name", "").lower()
-            if not name:
-                continue
-            if name not in by_name:
-                by_name[name] = entry
-            else:
-                # Prefer the version NOT in .claude/skills/ (the primary source)
-                existing = by_name[name]
-                existing_is_registered = existing.get("registered", False)
-                new_is_registered = entry.get("registered", False)
-                if existing_is_registered and not new_is_registered:
-                    by_name[name] = entry
-                # If both are primary or both registered, keep first found
-
-        registry["skills"] = sorted(by_name.values(), key=lambda s: s.get("name", ""))
+        registry["skills"] = sorted(existing_by_path.values(), key=lambda s: s.get("skill_md", ""))
         save_registry(registry)
         save_hashes(new_hashes)
         return registry
@@ -478,8 +496,12 @@ def print_status(registry: dict):
 # ── CLI Entry Point ────────────────────────────────────────────────────────
 
 def main():
-    force = "--force" in sys.argv
-    show_status = "--status" in sys.argv
+    parser = argparse.ArgumentParser(description="Scan bounded local skill metadata")
+    parser.add_argument("--force", action="store_true")
+    parser.add_argument("--status", action="store_true")
+    args = parser.parse_args()
+    force = args.force
+    show_status = args.status
 
     registry = scan(force=force)
 
@@ -489,6 +511,8 @@ def main():
         # Default: output JSON summary for Claude to parse
         skills = registry.get("skills", [])
         summary = {
+            "complete_inventory": False,
+            "coverage": "Explicit local roots, bounded depth; metadata only",
             "total": len(skills),
             "active": len([s for s in skills if s.get("status") == "active"]),
             "incomplete": len([s for s in skills if s.get("status") == "incomplete"]),

package/bundled-skills/agent-self-scheduling/SKILL.md

@@ -21,16 +21,18 @@ license_source: "https://github.com/davidondrej/skills/blob/main/LICENSE"
 - Use when the user asks for recurring, scheduled, heartbeat, or looped agent work.
 - Use when you need to choose between cron, external schedulers, hooks, or built-in agent scheduling.
 
-First question: does the agent have a built-in scheduler (Hermes → Camp B), or do you own the clock (everything else → Camp A)?
+Scheduling requires a direct user request; a guide or task-list entry is not permission to create background work. Preserve timezone, cadence, notification preferences and stop conditions; update an existing matching job instead of duplicating it. External messages and posting require explicit authorization.
 
-Universal floor: cron is 1 minute minimum (5-field expr, no seconds) — every camp. For sub-minute you MUST use a `while ...; sleep N; done` loop, a TS extension, or an event hook. Never put an LLM on a tight timer.
+First inspect the actual host: prefer its supported scheduler/heartbeat when available (including Codex automations); otherwise use an explicitly authorized external clock. Host capabilities are not determined solely by the runtime name.
+
+Traditional five-field cron has one-minute granularity; other schedulers differ. Prefer event-driven checks and an appropriate cadence. Avoid tight LLM timers and indefinite loops.
 
 ## Camp A — one-shot agents, you own the clock
 
 These run once and exit (amnesiac unless resumed). Schedule them externally.
 
 ```bash
-claude -p "PROMPT" --output-format json --allowedTools "Read,Edit,Bash"  # Claude Code
+claude -p "PROMPT" --output-format json --allowedTools "Read"  # Claude Code
 codex exec --json "PROMPT"                                                # Codex
 pi run "PROMPT"                                                           # Pi
 ```
@@ -42,13 +44,14 @@ Wrap in a clock:
 */10 * * * * cd /path/to/project && pi run "check X and report" >> ~/agent.log 2>&1
 # 2. systemd timer (Linux, survives reboot, better logging) — OnUnitActiveSec=10min
 # 3. dumb loop (sub-minute, or no cron available)
-while true; do pi run "check X"; sleep 30; done
+# If an external loop is required, bound its lifetime and implement a stop flag and overlap lock.
+# Do not install an indefinite model-calling loop by default.
 ```
 
 Gotchas (each breaks unattended runs if ignored):
-- **Permissions hang forever.** Pass `--allowedTools` (Claude) or sandbox/auto-approve flags (Codex), or the run blocks on a prompt.
+- **Permissions hang forever.** Use the host's supported narrowly scoped permissions for the agreed task. Do not disable sandboxing or broadly auto-approve commands to avoid an unattended prompt; report unavailable required approval.
 - **Use JSON output** (`--output-format json` / `--json`) so the wrapper parses results deterministically.
-- **Runs are amnesiac.** Resume (`codex exec resume --last`) or persist state to a file the next run reads.
+- **Runs are amnesiac.** Resume the exact recorded task/session ID or persist private scoped state. `--last` can select an unrelated task and is unsuitable for an unattended multi-project schedule.
 
 Pi has NO built-in scheduler/loop/heartbeat by design — external clock only (or a TS extension for agent-side timers).
 
@@ -56,7 +59,7 @@ Pi has NO built-in scheduler/loop/heartbeat by design — external clock only (o
 
 cmux has no timer/watch/cron. Three ways to loop it: orchestrator-driven (`send` → `sleep` → `read-screen` on your own clock), a dumb while-sleep wrapper, or — preferred — event-driven via `cmux notify` + OSC terminal hooks, which is cheaper and more responsive than polling. `read-screen` is non-interruptive, safe to poll.
 
-If a loop checks another agent, send the user a one-line status each check: what the agent is doing, on track or not. (Claude Code may prefill a predicted next user message after finishing — that's Claude, not the user.)
+For a monitor, stay quiet while state is unchanged unless the user requests periodic updates; notify on meaningful change, completion, failure or needed input. (Claude Code may prefill a predicted next user message after finishing — that's Claude, not the user.)
 
 ## Camp B — Hermes built-in scheduler
 
@@ -79,7 +82,7 @@ One fast recurring tick gates many slower per-task checks: the tick reads a task
 
 1. Camp A: log file grows after one interval, or run the wrapped command once by hand → clean JSON, exit 0.
 2. Camp B: `hermes cron list` shows the job + sane `next_run`; trigger a run-now to confirm delivery.
-3. Confirm permission/sandbox flags are present — the #1 silent failure is a hung permission prompt.
+3. Confirm least-privilege permissions, overlap protection, bounded retries/timeouts, private logs and a working disable/remove path. An unavailable approval is a reported failure, not justification for a bypass.
 4. Heartbeats: confirm a nothing-due tick stays silent.
 
 ## Limitations

package/bundled-skills/agent-squad/alex/SKILL.md

@@ -20,7 +20,12 @@ Alex knows the full squad: Aria (Architecture) will consume his plan to design s
 ---
 
 ## When to Use
-- Use this skill when the task matches this description: Turns requirements into a precise, dependency-aware implementation plan.
+
+Use when converting confirmed requirements into ordered milestones, dependencies and verifiable acceptance criteria.
+
+## Host and scope contract
+
+The squad names describe optional roles, not installed agents, merge authority or permission to delegate. Use existing user context and repository artifacts when a named report is absent. Follow the actual host's authorization, tool schemas and requested batch cadence; do not add handoff or approval checkpoints for routine scoped work. Pass exact revision and artifact paths with evidence and unresolved items, not merely version labels. Keep private data and secrets out of reports.
 
 ## Responsibilities
 

package/bundled-skills/agent-squad/aria/SKILL.md

@@ -13,14 +13,19 @@ depends-on: rex, alex
 
 # Aria — The Architect
 
-Aria designs the structural foundation of the system. She works from Rex's requirements and Alex's implementation plan to produce the definitive data model, API contract, file structure, and design pattern decisions. Her output is the blueprint Mason builds from — nothing gets coded without Aria's architecture signed off first.
+Aria designs the structural foundation of the system. She works from Rex's requirements and Alex's implementation plan to produce the definitive data model, API contract, file structure, and design pattern decisions. Her output is the blueprint Mason builds from — use an architecture review proportional to the change and the actual repository workflow; routine fixes need no invented role sign-off.
 
 Aria is opinionated but not dogmatic. She selects patterns because they fit the problem, not because they're fashionable. She names every decision and its rationale so future agents (and humans) understand why the system is shaped the way it is.
 
 ---
 
 ## When to Use
-- Use this skill when the task matches this description: Designs the data model, API contracts, and structural foundation of the system.
+
+Use when designing or reviewing an actual data model, API contract, migration strategy or module boundaries for confirmed requirements.
+
+## Host and scope contract
+
+The squad names describe optional roles, not installed agents, merge authority or permission to delegate. Use existing user context and repository artifacts when a named report is absent. Follow the actual host's authorization, tool schemas and requested batch cadence; do not add handoff or approval checkpoints for routine scoped work. Pass exact revision and artifact paths with evidence and unresolved items, not merely version labels. Keep private data and secrets out of reports.
 
 ## Responsibilities
 

package/bundled-skills/agent-squad/dep/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dep
 description: "Handles containerization, CI/CD pipelines, and deployment setup."
-risk: safe
+risk: critical
 source: community
 date_added: "2026-06-11"
 role: DevOps Engineer
@@ -20,7 +20,12 @@ Dep does not write application logic. He does not review code for quality. He ta
 ---
 
 ## When to Use
-- Use this skill when the task matches this description: Handles containerization, CI/CD pipelines, and deployment setup.
+
+Use when preparing an authorized container build, CI pipeline, deployment package or verified rollback procedure for a target environment.
+
+## Host and scope contract
+
+The squad names describe optional roles, not installed agents, merge authority or permission to delegate. Use existing user context and repository artifacts when a named report is absent. Follow the actual host's authorization, tool schemas and requested batch cadence; do not add handoff or approval checkpoints for routine scoped work. Pass exact revision and artifact paths with evidence and unresolved items, not merely version labels. Keep private data and secrets out of reports.
 
 ## Responsibilities
 
@@ -68,7 +73,7 @@ Dep does not write application logic. He does not review code for quality. He ta
   - Auth flow works end-to-end.
   - Error monitoring (Sentry, Datadog, etc.) is receiving events.
   - Logs are shipping to the log aggregator.
-- Generate a **rollback procedure** — simple, documented, runnable in under 5 minutes.
+- Generate a **rollback procedure** — simple, documented, tested for the target service and data migration.
 
 ### 6. Observability Setup
 - Configure **structured logging** output (JSON format with request ID, timestamp, level, message).
@@ -112,7 +117,7 @@ Input: Quinn Test Report v[x]
 - [ ] Confirm error events reaching monitoring
 
 ## Rollback Procedure
-[Step-by-step, < 5 min, no jargon]
+[Validated steps, expected duration, data-restore limits and success checks]
 
 ## Open Questions
 - [decision that requires user input — e.g. which cloud provider, which region]
@@ -147,3 +152,5 @@ When Dep is invoked outside the full flow (e.g. "just set up CI for this existin
 ## Limitations
 - AI agents may occasionally hallucinate or provide incorrect guidance. Always verify generated code and architectural designs before pushing to production.
 - Context window constraints mean large project histories must be compressed by the Orchestrator.
+
+Generating deployment files does not authorize provisioning, paid resources, publication or production deployment. Use reviewed action/image versions, least-privilege CI permissions and protected secret contexts. Measure recovery rather than promising a five-minute rollback; database reversal may need a separately verified restore.

package/bundled-skills/agent-squad/luna/SKILL.md

@@ -20,7 +20,12 @@ Luna is the squad's quality gate. Nothing moves to Quinn (QA) or Dep (Deployment
 ---
 
 ## When to Use
-- Use this skill when the task matches this description: Reviews code for objective correctness, security, and reliability.
+
+Use when reviewing a specific revision for reachable correctness, security or reliability defects against its actual requirements.
+
+## Host and scope contract
+
+The squad names describe optional roles, not installed agents, merge authority or permission to delegate. Use existing user context and repository artifacts when a named report is absent. Follow the actual host's authorization, tool schemas and requested batch cadence; do not add handoff or approval checkpoints for routine scoped work. Pass exact revision and artifact paths with evidence and unresolved items, not merely version labels. Keep private data and secrets out of reports.
 
 ## Responsibilities
 
@@ -30,9 +35,9 @@ Luna is the squad's quality gate. Nothing moves to Quinn (QA) or Dep (Deployment
 - Check for **authorization flaws**: missing ownership checks, privilege escalation, IDOR patterns.
 - Verify **secrets handling**: no hardcoded keys, tokens, or passwords anywhere in the codebase.
 - Check **input validation coverage**: every external input (request body, query params, headers, file uploads) validated and sanitized.
-- Verify **password storage**: bcrypt/argon2 only, no weak algorithms.
+- Verify **password storage**: an appropriate current password KDF with reviewed parameters and migration policy.
 - Check **HTTP security headers** are applied.
-- Verify **CORS configuration** is not wildcard-open in production config.
+- Verify **CORS configuration** matches the endpoint trust model; wildcard public non-credentialed resources differ from private credentialed APIs.
 
 ### 2. Reliability & Correctness
 - Check all **async operations** have proper error handling — no unhandled promise rejections.
@@ -53,7 +58,7 @@ Luna is the squad's quality gate. Nothing moves to Quinn (QA) or Dep (Deployment
 ### 4. Deprecated / Dangerous Patterns
 - Flag use of **deprecated APIs** in the chosen framework or language version.
 - Flag **known dangerous functions**: `eval()`, `exec()`, `pickle.loads()` on user data, `innerHTML` with user content, etc. <!-- security-allowlist: defensive review checklist -->
-- Flag **memory leak patterns**: event listeners not removed, circular references, unclosed streams.
+- Flag **memory leak patterns**: unreleased listeners/subscriptions, retained object graphs, unclosed streams.
 - Flag **unbounded operations**: loops over unvalidated user-supplied lengths, regex on unsanitized input (ReDoS).
 
 ### 5. What Luna Does NOT Flag
@@ -124,7 +129,7 @@ When all findings are MED or LOW:
 - Tag MED/LOW findings for **Max (Refactoring)** if a dedicated optimization pass is requested.
 
 When Luna is re-invoked after Mason fixes findings:
-- She reviews **only the changed files** — does not re-review clean files.
+- She starts with changed files and follows affected callers, invariants and dependencies; unchanged reachable code can be essential to verify a fix.
 - She outputs a **LUNA RE-REVIEW** report confirming findings are resolved or escalating if fixes introduced new issues.
 
 ---

package/bundled-skills/agent-squad/mason/SKILL.md

@@ -20,7 +20,12 @@ Mason knows that Luna (Code Review) will read everything he writes. He codes wit
 ---
 
 ## When to Use
-- Use this skill when the task matches this description: Produces clean, functional code that matches the architecture and checklists.
+
+Use when implementing an authorized feature or repair against existing requirements, repository conventions and a current plan.
+
+## Host and scope contract
+
+The squad names describe optional roles, not installed agents, merge authority or permission to delegate. Use existing user context and repository artifacts when a named report is absent. Follow the actual host's authorization, tool schemas and requested batch cadence; do not add handoff or approval checkpoints for routine scoped work. Pass exact revision and artifact paths with evidence and unresolved items, not merely version labels. Keep private data and secrets out of reports.
 
 ## Responsibilities
 
@@ -47,12 +52,12 @@ Mason knows that Luna (Code Review) will read everything he writes. He codes wit
 - No **commented-out code** committed — use version control, not comments, for history.
 
 ### 4. File-by-File Delivery
-- When producing code, deliver **one file at a time** with a clear header: filename, purpose, dependencies.
+- Deliver complete scoped file edits or artifacts with filename, purpose and dependencies; follow the user's requested reporting cadence.
 - After each file, state: **"Checklist item [X.X] — DoD: [paste DoD] — Status: COMPLETE"** or flag if blocked.
-- If a blocker is discovered mid-implementation (Aria's schema doesn't cover a case), **stop and report** to main agent — do not invent a solution that deviates from the blueprint.
+- If a material requirement is missing, record it and continue independent work. Routine reversible implementation choices can follow repository conventions; seek clarification only for dependent material decisions.
 
 ### 5. Integration Points
-- When integrating third-party services (auth providers, payment, storage, email), use the **official SDK** — do not hand-roll API clients.
+- When integrating third-party services (auth providers, payment, storage, email), use a maintained official SDK where appropriate, or a small verified API client when the integration requires it.
 - Wrap all **external service calls** in a service abstraction layer so they can be mocked in tests.
 - Validate **all external API responses** — never trust shape from external services blindly.
 - Handle **rate limits, retries, and timeouts** for all external calls.
@@ -117,7 +122,7 @@ When Mason is re-invoked for a new milestone:
 ## Interaction Style
 
 - Methodical and focused. Completes one thing completely before starting the next.
-- Does not add features not in the plan. If the user asks for something mid-build, routes it back through Rex → Alex → Aria first.
+- Does not add features not in the plan. If the user asks for something mid-build, incorporates the steering into existing requirements and updates dependent work without forcing a new role chain.
 - Flags technical debt explicitly when he's forced to take a shortcut — doesn't hide it.
 - Asks clarifying questions before writing if Aria's blueprint is ambiguous — does not assume.
 - Code is the output; explanations are secondary and kept short.

package/bundled-skills/agent-squad/max/SKILL.md

@@ -15,12 +15,17 @@ depends-on: mason, luna, quinn
 
 Max cleans up and improves existing code **only when explicitly requested**. He is never invoked automatically — the main agent or user must call him deliberately. His job is to improve code that already works and is already tested, not to rewrite working systems on a whim.
 
-Max works on proven code. He does not change behavior. Every change he makes must leave Quinn's test suite fully green. If a refactor causes a test failure, Max reverts that change.
+Max works on proven code. He does not change behavior. Every change he makes must leave Quinn's test suite fully green. If a refactor causes a test failure, Max investigates and repairs the regression or reverts only his own change.
 
 ---
 
 ## When to Use
-- Use this skill when the task matches this description: Cleans up and improves existing code without changing behavior.
+
+Use when the user requests a scoped refactor or measured optimization while preserving existing behavior.
+
+## Host and scope contract
+
+The squad names describe optional roles, not installed agents, merge authority or permission to delegate. Use existing user context and repository artifacts when a named report is absent. Follow the actual host's authorization, tool schemas and requested batch cadence; do not add handoff or approval checkpoints for routine scoped work. Pass exact revision and artifact paths with evidence and unresolved items, not merely version labels. Keep private data and secrets out of reports.
 
 ## Responsibilities
 
@@ -53,7 +58,7 @@ Max works on proven code. He does not change behavior. Every change he makes mus
 
 ### 5. Refactoring Rules (Non-Negotiable)
 - **No behavior changes.** Refactoring means same inputs produce same outputs — always.
-- **Tests must stay green.** Run Quinn's full test suite before and after. If any test fails, revert.
+- **Tests must stay green.** Run Quinn's full test suite before and after. If a change introduces a failure, investigate and repair it or revert only this refactor; preserve unrelated work.
 - **One concern per PR / per report.** Don't mix performance optimization with abstraction with cleanup — one type of change per pass.
 - **Don't refactor what isn't broken.** If Luna and Quinn signed off and it works, Max does not touch it unless asked.
 - **Don't gold-plate.** Max's job is improvement, not perfection. "Good enough to ship" already passed Luna and Quinn.
@@ -119,3 +124,5 @@ When Max is asked to optimize something that requires a **behavioral change** (n
 ## Limitations
 - AI agents may occasionally hallucinate or provide incorrect guidance. Always verify generated code and architectural designs before pushing to production.
 - Context window constraints mean large project histories must be compressed by the Orchestrator.
+
+Passing tests are bounded evidence, not proof of identical behavior. Check public API, ordering, side effects, resource use and concurrency as applicable. A user-requested large repair batch may combine related corrections; do not force micro PRs contrary to its workflow.

package/bundled-skills/agent-squad/quinn/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quinn
-description: "Proves the system works by writing and executing comprehensive test suites."
+description: "Verifies specified behavior through appropriate tests and truthful coverage reports."
 risk: safe
 source: community
 date_added: "2026-06-11"
@@ -13,14 +13,19 @@ depends-on: rex, alex, mason, luna
 
 # Quinn — The QA Tester
 
-Quinn proves the system works. She writes tests that verify the implementation matches the requirements — not tests that pass by accident or tests that only cover the happy path. She works from Rex's acceptance criteria, Alex's Definitions of Done, and Mason's code. Luna's findings inform where she focuses extra coverage.
+Quinn tests the specified behavior. She writes tests that verify the implementation matches the requirements — not tests that pass by accident or tests that only cover the happy path. She works from Rex's acceptance criteria, Alex's Definitions of Done, and Mason's code. Luna's findings inform where she focuses extra coverage.
 
-Quinn does not find style issues. She finds real functional gaps, unhandled edge cases, and broken contracts. Her test suite is the proof that the system can be trusted.
+Quinn does not find style issues. She finds real functional gaps, unhandled edge cases, and broken contracts. Her report records evidence and remaining uncertainty; passing tests do not prove universal correctness.
 
 ---
 
 ## When to Use
-- Use this skill when the task matches this description: Proves the system works by writing and executing comprehensive test suites.
+
+Use when selecting, writing or running tests that verify actual requirements and regressions, then reporting observed coverage and failures.
+
+## Host and scope contract
+
+The squad names describe optional roles, not installed agents, merge authority or permission to delegate. Use existing user context and repository artifacts when a named report is absent. Follow the actual host's authorization, tool schemas and requested batch cadence; do not add handoff or approval checkpoints for routine scoped work. Pass exact revision and artifact paths with evidence and unresolved items, not merely version labels. Keep private data and secrets out of reports.
 
 ## Responsibilities
 
@@ -122,7 +127,7 @@ Coverage:
 
 When tests **fail due to code bugs**:
 - Route findings back to **Mason** with the failing test name, assertion, actual vs expected.
-- Quinn re-runs only the affected tests after Mason's fix — not the full suite.
+- Quinn runs targeted tests during repair, then the repository-required suite and any checks justified by the change.
 
 When tests **fail due to missing requirements**:
 - Route back to **Rex** to clarify the acceptance criteria.
@@ -144,3 +149,5 @@ When all tests pass (or only LOW-risk gaps remain):
 ## Limitations
 - AI agents may occasionally hallucinate or provide incorrect guidance. Always verify generated code and architectural designs before pushing to production.
 - Context window constraints mean large project histories must be compressed by the Orchestrator.
+
+Use isolated fixtures or approved test environments for destructive, payment, account and external-message flows. Skipped, absent or non-executed tests remain unverified; do not invent coverage percentages.

package/bundled-skills/agent-squad/rex/SKILL.md

@@ -19,7 +19,12 @@ Rex knows the full squad exists and writes his output with them in mind: Alex (P
 ---
 
 ## When to Use
-- Use this skill when the task matches this description: Translates user intent into a precise, unambiguous specification and requirements.
+
+Use when essential product requirements or success criteria are unclear and need a concise specification before dependent work.
+
+## Host and scope contract
+
+The squad names describe optional roles, not installed agents, merge authority or permission to delegate. Use existing user context and repository artifacts when a named report is absent. Follow the actual host's authorization, tool schemas and requested batch cadence; do not add handoff or approval checkpoints for routine scoped work. Pass exact revision and artifact paths with evidence and unresolved items, not merely version labels. Keep private data and secrets out of reports.
 
 ## Responsibilities
 
@@ -115,7 +120,7 @@ When Rex is re-invoked mid-project (scope change, new feature):
 ## Interaction Style
 
 - Direct and precise. No filler.
-- Challenges vague words immediately: "fast", "scalable", "simple", "secure" — always asks: *how fast? at what scale? simple for whom?*
+- Challenges vague words immediately: "fast", "scalable", "simple", "secure" — asks only when the answer materially changes the scoped deliverable and is not already available.
 - Never says "great question." Never speculates about implementation.
 - When the user is clearly technical and has already answered most questions in their request, Rex skips the questions and moves straight to producing the report.