Architecture Review Skill: Audit Before Refactor

Where this fits

Your team uses /squid-implement-task and /squid-implement-night daily, so each feature lands cleanly. But no one looks at the architecture as a whole until the monolith starts hurting. You need a periodic audit that reads ADRs, maps dependencies, and produces a prioritized list of refactor proposals—before coupling becomes unmanageable.

Why agents benefit

• Delegates exploration to sub-agents, so the main agent keeps context small while the audit explores wide.
• Reads docs/adr/ first, preventing proposals that reopen settled decisions.
• Reports up to 10 findings shaped as refactor proposals, so /squid-refactor can consume them directly into a Tasks Plan.
• Explicitly does not write code or start refactors, keeping the auditor role clean and safe in CI.
• Scope can be limited with an argument, making audits faster for targeted components.

Practical scenarios

Monthly repo health sweep

Run the skill on the whole repository every sprint boundary. The output becomes the team's architecture backlog.

Pre-refactor investigation

Before a large refactor, run it on the affected module to surface coupling and dead code that a task-grain workflow would miss.

Onboarding a legacy codebase

New team members can run an audit to learn actual layering and dependency flows instead of guessing from outdated docs.

Add it to your agent workflow

Install the skill:

npx skills add iusztinpaul/squid --skill squid-architecture-review

Then invoke it on a scope:

Run squid-architecture-review on services/payment

The skill returns a written report with prioritized refactor proposals. Hand one proposal to /squid-refactor to generate a Tasks Plan—no manual translation needed.

Compare before adopting

Before adopting, compare quality signals: does the skill actually read ADRs and produce findings that survive a human review? Check maintenance freshness—recent commits, open issues, and whether the author uses it in production. Alternatives include rolling your own prompt for "audit this repo" or using general code-analysis agents; compare them for workflow fit. Finally, verify the skill's output format matches your existing /squid-refactor setup, since the value is in the direct handoff.

Why it is worth tracking

The skill is young at 184 stars but fills a real gap: long-horizon architecture upkeep in agentic pipelines. Its strong constraint—propose, don't implement—keeps the audit trustworthy. Track it as the ecosystem moves from single-task agents to multi-step planning systems. You can follow its OpenAgentSkill listing at https://www.openagentskill.com/skills/iusztinpaul-squid-architecture-review to see updated signals and community feedback.