agent-loom

Review code changes for correctness, completeness, bugs, edge cases, and quality. Load when the user explicitly asks to review code, check a PR, review a diff, audit recent changes, or verify an implementation matches requirements. Also triggers on "review this code", "check this PR", "review my changes", "code review", "did this implement correctly", "audit this diff", or any explicit request for a formal code review. Do NOT load for "review changes for context" or "review what happened" — those are requests to read code, not to perform a formal review.

Fix broken or failing functionality through structured reproduction, root-cause analysis, minimal fix, and verification. Load when the user asks to fix a bug, debug an error, resolve an issue, or work on a Linear ticket. Also triggers on "this is broken", "fix this bug", "why is this failing", "debug this", "resolve this error", "what went wrong", or any request to diagnose and fix a problem.

Structure git work with atomic commits, conventional messages, short-lived branches, and pre-commit hygiene. Load when committing, branching, resolving merge conflicts, organizing parallel work, or reviewing git history. Also triggers on "git workflow", "commit message", "conventional commits", "atomic commit", "branch strategy", "git worktree", "how should I commit this". Does not replace project-specific hook policies — complements them.

Create a detailed, step-by-step implementation plan for a feature or project. Load when the user asks to plan a feature, create a technical roadmap, break down a PRD into tasks, design an implementation strategy, or sequence engineering work. Also triggers on "how should we build this", "implementation plan for", "technical breakdown", "task list for", or any request to turn a high-level requirement into a concrete execution plan. Supports phased rollouts, architecture-first, and MVP-focused planning.

Deliver multi-file changes in thin vertical slices — implement, test, verify, commit, repeat. Load when implementing a feature from a plan, building across more than one file, refactoring, or when tempted to land a large change in one pass. Also triggers on "incremental implementation", "vertical slice", "thin slice", "one slice at a time", "don't do it all at once". Routes single-file fixes to direct execution. Pairs with test-driven-development and git-workflow-and-versioning.

Apply the Red-Green-Refactor cycle to software development. Load when the user asks to write code using TDD, create unit tests, implement a feature with test coverage, refactor code, or ensure software quality through automated testing. Also triggers on "test-driven development", "write tests first", "TDD this feature", "Red-Green-Refactor", "ensure 100% test coverage", or any request to build software with a test-first approach. Supports unit, integration, and end-to-end testing strategies.

Select alternative execution paths when a plan step fails — branch on outcomes instead of blind retry. Load when a structured plan step fails, an unexpected observation arrives, or the user asks what to try next after an error. Also triggers on "try another approach", "route around this failure", "replan on failure", "if X fails try Y", or outcome-based branching during multi-step work. Pairs with structured-planning and debug-and-fix. Does not replace root-cause debugging — adds plan-level path selection.

Score LLM and agent outputs using LLM-as-judge techniques — direct scoring against rubrics or pairwise comparison between two outputs. Includes built-in bias mitigation for position bias, length bias, and self-enhancement bias. Load when the user asks to score an output, judge a response, evaluate against a rubric, compare two outputs, do direct scoring, run pairwise comparison, or says "rate this", "which response is better", "score this against the rubric", "judge this output", "LLM as judge this". Sub-skill of eval-output orchestrator.

Orchestrator for the eval-output skill suite — evaluate LLM and agent outputs for quality, accuracy, helpfulness, and safety using structured rubrics and LLM-as-judge techniques. Load when the user says "evaluate this output", "score this response", "run an eval", "LLM as judge", "evaluate agent output", "how good is this response", "rate this answer", "eval this", or provides an LLM output that should be assessed for quality. Single entry point for all output evaluation workflows.

Design automated evaluation pipelines for LLM and agent systems — combining deterministic checks, statistical metrics, and LLM-as-judge scoring into repeatable, CI-integrated eval suites. Load when the user asks to set up automated evals, design an eval pipeline, integrate evals into CI/CD, create an eval suite, do eval-driven development, or says "automate my evals", "CI eval integration", "evaluation pipeline", "continuous evaluation", "monitoring eval quality", "set up regression testing for my agent". Sub-skill of eval-output orchestrator.

Design structured evaluation rubrics for scoring LLM and agent outputs — defining quality dimensions, scoring scales, hard gates, score descriptions, and edge cases. Load when the user asks to create an eval rubric, define evaluation criteria, design scoring dimensions, write an eval spec, or says "what should I evaluate", "design a rubric", "create eval criteria", "define quality dimensions", "evaluation rubric for", "how do I measure quality of". Sub-skill of eval-output orchestrator.

Build, update, and query a persistent project knowledge graph from skills, memory, docs, and code structure — stdlib Python only, no external tools. Dual-mode: skill-library (agent-loom) or application (any consumer repo). Load when the user asks for a knowledge graph, project map, skill relationships, query the graph, update the graph, or trace how components connect. Auto-runs on memory-handoff and project-setup bootstrap. Also triggers on "build the graph", "what connects to X", "map this project".

Plan which model tier handles which work BEFORE execution begins — a high-cognition model deeply understands the problem, lays the foundations, then emits a modular plan assigning each module the cheapest tier that can safely execute it, with escalation tripwires and one-way-door protection. Advisory only: it announces "next module → tier X / model Y" at each boundary and the HUMAN switches models — harnesses like Cursor cannot switch mid-run. Load when the user asks which model to use, wants a model plan, model tiers, model-tier routing, assign models to tasks or modules, says "cheap model got stuck", "which model for this task", "cost-efficient model choice", or when implementation-plan / problem-to-plan need a model: tier column. NOT dynamic-routing (plan-path selection after failure) — this skill assigns cognition tiers to work.

Tactical fast path: turn a small problem, bug report, edit request, or narrow refactor into three deliverables — a brief change-spec (docs/specs/), a detailed implementation-ready plan (docs/plans/), and a TODO.md with agent-pickable tasks and milestones. Load when the user describes a tactical problem and wants quick planning artifacts, says "plan this change", "create a TODO", "write a plan for this", "problem to plan", "break this into tasks for agents", "I want to change X — plan it", or when process-decomposer routes here after determining the user needs lightweight planning deliverables. Also triggers on "create tasks from this problem", "make this actionable", or "turn this into a plan agents can execute". For feature-sized work that needs an executable spec + constitution + cross-check gate, route to `spec-driven-development` (or `feature-spec`) instead.

Design, build, validate, and ship cross-platform agent skills. Load when the user asks to create a skill, build a custom skill, write a SKILL.md, package a workflow as reusable agent capability, improve or audit a skill, publish a skill, or build a planned skill suite.

Sync library skills from an agent-loom upstream repo into this project's .agents/skills while preserving project-local and forked skills. Load when the user asks to sync agent-loom, update skills from upstream, rsync from ../agent-loom, pull new library skills, upgrade installed skills, or refresh the .agents folder without losing custom project skills. Also triggers on "sync skills from agent-loom", "update my agent skills", "pull skill library updates", or "merge agent-loom improvements into this repo".

Instrument a shipped product's AI agents with tracing and observability so you can see what they did, why outputs happened, and what each run cost. Plain-language primer plus free-tier-first backend selection (Langfuse, Phoenix, LangSmith, Braintrust) and OpenTelemetry/OpenInference instrumentation. Load when the user asks to add observability, add tracing, instrument my agents, see what my agent is doing in production, set up Langfuse or Phoenix or LangSmith, debug why my agent gave a bad answer, or track LLM cost per request. Also fires when agent-system-architecture or setup-evaluation requires an observability plan for an agent-chain product. NOT for tracing the coding agent itself — that is run-trace. Precondition for runtime-learning-loop.

Run a structured retrospective after development-phase runs of your product's agents — interview the owner in plain language about what went well and poorly, draft ranked improvement hypotheses, then design and run small n=1/n=2 experiments with pre-declared success criteria, guardrails, stop conditions, and a cost/ROI kill-switch. Load when the user says how did that run go, retro this run, the agent output was bad, what should we improve, draft hypotheses, run a small experiment, or after repeated dev runs of an agentic system produce uneven quality. Priority: output quality over performance over cost, each with diminishing-returns stops. NOT a product A/B test (experimentation), NOT coding-agent harness repair (harness-evolution), NOT production-scale learning (runtime-learning-loop).

Design state-of-the-art multi-agent systems, orchestration patterns, and wiring from scratch. Load when the user asks to build an agent system from scratch, design agent orchestration patterns, choose between sequential/parallel/hierarchical workflows, or define how multiple agents should collaborate. Also triggers on "agent architecture", "multi-agent wiring", "agent orchestration pattern", "how to connect these agents", "design the communication structure". Called by agent-builder for complex topologies (>4 agents or hierarchical). For process-driven agent design, use agent-builder instead.

Generate a tailored AGENTS.md for any new project by interviewing the user about their skill gaps, project goals, and tech context. Load when the user asks to set up a project, initialize agents, create an AGENTS.md, bootstrap a repo, onboard agents to a codebase, or says "set up this project for agents". Also triggers on "write an AGENTS.md for this project", "configure agents for my repo", "project bootstrap", "agent onboarding", or when the user starts a new project and needs agent-ready configuration. Re-run when new context arrives (PRD written, stack changes, team changes) to update the AGENTS.md.

Bootstrap full agent infrastructure for an existing, already-coded project without modifying a single line of source code. Surveys the repo, infers conventions from manifests, README, git history, and source samples, then generates the missing AGENTS.md, docs/architecture.md, docs/product-soul.md, ADR backfill, and seeded docs/memory/ files. Asks the user only about gaps the repo cannot reveal. Load when the user asks to "retroactive project setup", "backfill agent infrastructure", "bootstrap agents for this existing repo", "onboard agents to a legacy codebase", "set up agents without touching code", or "fill in missing agent context for this project".

Design a self-improvement loop for a shipped product's AI agents — production traces feed evals, evals feed improvement proposals (prompts, playbooks, retrieval configs), and a human approval gate promotes changes with rollback. Technique-agnostic: chooses per project between ACE-style evolving playbooks, GEPA/MIPROv2 offline optimization, or simple eval-driven iteration via references/techniques.md. Load when the user asks to make my product's agents self-improving, learn from production traces, add a learning loop, evolve prompts or playbooks safely, promote agent improvements, or GEPA-style optimization. NOT harness-evolution (that improves the coding agent), NOT experimentation (product A/B tests), NOT agent-run-retro (dev-phase manual retros — this skill is the production-scale continuation).

Validate process decomposition and architecture design quality before execution begins. Load when the setup-evaluator agent fires (automatic for agent-chain tasks), or when user says "evaluate this setup", "check the decomposition", "validate the architecture", "is this plan sound", "review the agent design". Catches structural errors, missing knowledge, unrealistic step ordering, and topology mismatches. Does NOT modify — only evaluates.

Guided first-run that produces a real verified win in under five minutes using the skill library on a seeded offline fixture. Load when a new user asks how to start, run the demo, try agent-loom, or get a quick win. Also triggers on "quickstart", "first run", "demo agent-loom", "try the skills", or onboarding to the library. Zero external credentials required. Idempotent — safe to run multiple times.

Apply one logical code change with mandatory impact mapping, git snapshot, verification, and automatic revert on failure. Load when the user asks for a safe edit, verified change, one change at a time with rollback, or codespine-style edit loop. Also triggers on "safe change", "edit with verification", "don't break the build", "revert if tests fail", or any non-trivial code edit where blast radius matters. Always runs dependency-mapping first. Pairs with incremental-implementation for multi-slice work; this skill is one atomic verify cycle per invocation.

Map symbol dependencies, callers, and blast radius before editing code. Load when the user asks what depends on a symbol, what breaks if they change something, blast radius of a change, reverse dependencies, or which tests cover a function. Also triggers on "who calls this", "impact of changing", "dependency map", "what uses this", "find callers", or before any non-trivial edit when safe-change is not yet active. Pairs with codebase-understanding for broad architecture; this skill is symbol-scoped and edit-gated.

Deploy with unified build/test/deploy intent across providers using .agent-loom/deploy.yml and per-provider adapters. Load when the user asks to deploy, ship to preview, release to production, or run a provider-agnostic deploy flow. Also triggers on "deploy anywhere", "deploy to Vercel", "deploy with GitHub Actions", "preview deploy", or "ship this". Runs preflight before any deploy — stops on missing secrets. Pairs with ci-cd-and-automation for pipeline design. Ships vercel and github-actions adapters; extensible adapter interface.

Find the earliest decisive failure in an agent run trace and propose an evidence-backed targeted repair. Load when a run failed, results are wrong, or the user asks what went wrong in an agent session. Also triggers on "localize the fault", "first incorrect step", "debug this run", "trace attribution", "why did the agent fail", or after run-trace captures errors. Pairs with debug-and-fix for code defects and dynamic-routing for plan faults.

Mirror issues and status across issue trackers with stable external-ID mapping to avoid duplicates. Load when syncing GitHub and Linear issues, mirroring ticket status, or keeping two trackers in sync. Also triggers on "issue sync", "sync issues", "mirror issues to", "keep Linear and GitHub in sync", or bidirectional issue tracker updates. Requires API access on both sides — stops if credentials missing.

Author pull requests with intent-separated commits, blast-radius disclosure, and verification evidence. Load when opening a PR, writing a PR description, separating refactor from feature commits, or summarizing a change set for review. Also triggers on "write the PR", "PR body", "intent-separated commits", "split refactor from feature", "pr summary", or after safe-change cycles complete. Extends git-workflow-and-versioning — does not replace it.

Append structured execution traces across operational, cognitive, and contextual surfaces with minimal overhead. Load when inspecting agent runs, logging tool calls and observations, enabling post-run debugging, or pairing with structured-planning step IDs. Also triggers on "trace this run", "log execution", "agent observability", "run log", or when fault-localize needs evidence. Default-on during multi-step plans. Traces live at .agent-loom/traces/ — git-ignored by default.

Decompose multi-step work into a revisable subgoal plan with stable step IDs, checkpointing, and plan-ahead execution. Load when a task needs explicit planning before action, subgoal decomposition, plan checkpointing, or ReCAP-style plan-ahead execution. Also triggers on "structured plan", "plan with steps", "subgoal graph", "revise the plan", "checkpoint plan", or multi-step tasks where naive one-shot execution would be fragile. Skips trivial single-step tasks. Pairs with dynamic-routing on failure. Distinct from process-decomposer (registry/triage) and problem-to-plan (doc deliverables).

Load bounded working context at the start of a coding session. FIRES ON EVERY FIRST USER MESSAGE in a fresh session, regardless of content — including bare greetings ("hi", "hello", "hey"), task-only openers, or "let's start". Also triggers on: "fresh session", "session start", "first message in a new thread", "new chat", "cold start", "begin work in this repo", "starting work", "continue from prior session", "what were we working on", "resume", "what happened last time", "load memory", "recall context", "create a handoff", "prior session context", "latest handoff", "current state", "decision context". Skip ONLY if the user explicitly says "fresh start" or "ignore prior context". Self no-ops if invoked mid-session when context is already loaded.

Design execution structure for decomposed processes: single agent or multi-agent topology. Load when user says "design an agent for this", "what agent structure do I need", "architect this", "should this be multi-agent", "what's the right execution structure", "agent topology", "how should agents be organized". Takes process-decomposer output as primary input. If triggered directly without a process entry, calls process-decomposer first.

Orchestrator for agent harness work — the setup that makes AI agents follow project rules and improve when they fail. FIRES PROACTIVELY when agents misbehave, repeat mistakes, ignore instructions, skip skills, or when AGENTS.md exists but docs/harness/manifest.json is missing. Also triggers on: harness engineering, agent scaffold, agent keeps failing, agent not following instructions, make agents reliable, agents going off rails, agent forgot context, improve agent setup, self-improving agents, agents keep making mistakes, why is my agent bad, agent quality, agent setup broken, agents ignore skills, same mistake again, fix agent behavior, tune agent instructions, set up agent infrastructure, after project setup agents still bad. Routes bootstrap vs evolution. Not multi-agent topology — agent-builder.

Improve agent reliability over time — diagnose why agents fail and fix the setup. Triggers on: agent keeps failing, same mistake again, agent not improving, make agent smarter, agent quality plateau, agents ignore skills, agent skips tests, fix agent behavior, agent unreliable, improve agent setup, self-improving harness, agents worse over time, tune agent instructions, agent going in circles, agent ignores AGENTS.md, repeated agent errors. Requires harness v0 and eval harness. AUTO-ROUTED from harness-engineering on symptoms. Not first setup — harness-generation first.

Seed minimal agent harness v0 — manifest, eval checks stub, governance. AUTO-INVOKED after project-setup or retroactive-project-setup when docs/harness/manifest.json is missing. Also triggers on: generate harness, scaffold agents, agent bootstrap, first time agents in this repo, new project agent setup, set up agent harness, agent onboarding files, missing agent configuration, agent instructions setup, make agents read project rules, agent reliability setup, agents not configured. Pairs with project-setup. Evolution is harness-evolution.

Write concise next-agent handoff summaries across sessions, tools, and coding agents. Load when the user says handoff, next agent should know, save context, summarize where we are, switching agents, before ending a meaningful session, or when the user asks to commit, push, commit and push, create a git commit, push to origin, or publish commits — commit/push requests MUST run this skill first to prepare handoff docs, then proceed with git operations.

Route user requests to the right skill, decompose complex work into parallel subagents, and manage project phase transitions. Load when the user asks "what should I do next", "which skill should I use", "orchestrate this", "run the full workflow", "split this into parallel tasks", or when a complex request spans multiple skills. Also triggers on "coordinate agents", "parallel execution", "task decomposition", "agent workflow", "what phase am I in", or when the user gives a broad instruction that requires multiple skills in sequence. This is the project's brain — it decides what runs, when, and whether to parallelise.

Evaluate any project, product, or system's claims against its actual implementation — scoring each claim for truth, identifying architectural gaps, assessing competitive positioning, proposing creative solutions, and producing an actionable roadmap. Load when the user asks to evaluate claims, reality-check a project, assess what this project actually does vs what it says, validate product claims, or score a system's credibility. Also triggers on "is this real", "does this work as claimed", "evaluate this project", "assess the gap between claims and reality", "how credible is this", "investor assessment", "score these claims", or "what's real vs marketing".