act101

Audit whether an AI agent edit to a file is safe — composes secret-surface, taint-flow, change-impact, and API-surface analysis into an agent-edit safety report. Use before letting an agent modify a sensitive or high-blast-radius file.

Execute structural decompositions based on an architectural analysis report. Use when breaking circular dependencies, splitting god classes, reducing coupling between modules, extracting interfaces at seam boundaries, or executing any large-scale structural change identified in an architectural analysis. Requires a prior architecture audit (the architecture-audit skill) that produced project-map.md and a run report.

Use when asked to audit architecture, produce a comprehensive architectural overview, get the full structural picture of a codebase, assess overall health and porting readiness, find module boundaries, circular dependencies, coupling hotspots, dead code, or code patterns. Depth 3 — full audit with hypothesis-driven investigation. Optionally enriches the structural audit with runtime and git evidence (coverage, churn, co-change coupling, ownership) when those overlays are available. Replaces the architectural-analysis and architecture-audit-plus skills.

Use when looking for extraction candidates, planning a module split, analyzing module boundaries, or before decomposing a large component. Also use when asked "where should I split this?" or "find natural module boundaries". Depth 2 — investigate. Produces extraction candidates with cut costs, layer violations, interface width assessment, orphan types, and a recommended decomposition sequence.

Use before modifying a file or symbol, or when asked "what breaks if I change X?". Depth 0 — fast, no follow-up queries, returns immediately. Two modes: inline (no artifacts, default for agent-initiated use) and artifact (writes to docs/act/, triggered for human-initiated requests or Critical risk verdicts).

Traverse large repositories efficiently using act's query tools. Use when exploring unfamiliar code, mapping dependencies, understanding API surfaces, analyzing side effects before modifying functions, or following call chains across files. Avoids reading entire files by querying only the structure needed.

Review code for bugs, complexity, unused symbols, and structural issues using AST-aware analysis. Use when reviewing PRs, checking code quality, finding dead code, analyzing function complexity, auditing a codebase, or checking for type errors. Each call reports the kinds it modeled in `modeled_kinds` — that is the honest coverage signal; the supported-language list is whatever act ships.

Generate a robust, idempotent work-loop tracker — the single resumable state file that drives a large implementation program through plan → implement → review cycles with self-tracking, found-issue capture, and remediation discipline. Use whenever the user wants to execute a large or multi-item implementation systematically; triggers include "create a work loop", "set up a tracker", "make this resumable", "execution harness", "work through this spec item by item", or any time one or more approved specs need to be implemented across many sessions or by many agents and progress must survive context loss. Also drives and resumes the **quality loop** — a.k.a. "continuous quality", "the quality ratchet", "the architecture ratchet" — which maps to the architecture-audit → architectural-refactoring → verify-refactor skill cycle; triggers include "run the quality loop", "set up a quality ratchet", "keep auditing and refactoring", "continuously improve architecture".

Use when you want to safely remove code — finds symbols that are statically unreferenced, never covered by tests, and never executed in production, by intersecting dead-code, coverage, and trace evidence.

Use when asked about code health, quality trends, what's getting worse, or for a periodic quality check. Depth 1 — fast, trend-aware. Produces a health snapshot with hotspots, cohesion issues, test gaps (evidence-labeled: lcov or convention), and trend comparison if prior runs exist. Replaces the codebase-analysis skill.

Use when deciding what to optimize or refactor for performance — ranks code by combining runtime profile hotness with static complexity and coupling, so effort lands where it is both expensive at runtime and hard to change.

Use when assessing migration readiness, planning a port to another language, understanding what makes this codebase hard to rewrite, or requesting "how ready is this for porting?". Depth 2 — investigate. Produces per-module readiness cards, recommended migration order, hard/soft blocker list, and platform dependency assessment. Optionally enriches the plan with security and history evidence (taint flow, secret surface, unsafe constructs, coverage, churn, ownership) so blockers reflect real porting risk, not structure alone. Replaces the migration-readiness-plus skill.

Use when onboarding to an unfamiliar codebase — produces a guided reading order (entry points first, then high-traffic and load-bearing code) annotated with ownership and risk flags.

Gate a cross-language port for correctness — composes port-scoped behavioral equivalence, contract parity, and port-manifest drift into a port-correctness verdict. Use to verify that a ported function matches its source before marking the port done.

Emit durable refactor receipts — content-addressed JSON artifacts proving a refactor was verified. Delegates to the shipped gate machinery (act gate --receipts / MCP gate with receipts:true) rather than re-running verification ops manually.

Perform semantic code refactoring using AST-aware tools. Use when renaming symbols, extracting functions or variables, inlining code, moving symbols between files, organizing imports, or any code transformation that must update all references. Supports preview mode and undo. Each call reports the kinds it modeled in `modeled_kinds`; the supported-language list is whatever act ships.

Decide whether a change is safe to merge — runs `act gate`, the deterministic verdict (MERGE / REVIEW / BLOCK / UNKNOWN) over every changed function. Use before merging a branch or approving a PR.

Use to produce an application-security surface report for a file or module — dangerous constructs, secret-touching code, and source→sink taint flows. Composes unsafe_surface + secret_surface + taint_flow + analyze_surface. Architecture tier (taint_flow is Architecture). Inline by default; artifact mode for human-initiated audits or High/Critical verdicts.

Verify a refactor preserved behavior — composes contract, side-effect, and CFG-equivalence checks across two versions of a function. Use after editing a function to confirm the change is safe.

Use when you need to find the riskiest code in a repository — where bugs are most likely to live — by combining git churn, complexity, co-change coupling, and ownership concentration into one ranked, explained list.

Generate boilerplate code from existing types using AST-aware code generation. Use when creating constructors, getters/setters, builders, equals/hash methods, JSON serialization, toString, interface implementations, test stubs, or any repetitive code derived from existing class/struct definitions. Supports batch generation for maximum efficiency.