SoMi AI

Targeted architectural review of a change, plan, or ADR. Evaluates boundaries, contracts, dependency direction, and reversibility on a years-long horizon. Output lands under .somi/reviews/<slug>/ when scoped to a work item.

Bounded code → review → fix loop on a single iteration. Exits on approve, on Blocker/Major-free verdict, on iteration cap, on diff cap, or on a recurring finding (coder/reviewer disagree → human).

Fan out provably-independent iterations into isolated git worktrees, run each under /code-loop concurrently, then integrate them one at a time behind a gate (re-test + review per merge). Conservative by construction — only iterations the plan marks Parallelizable with disjoint file sets are eligible.

Execute against an approved plan in .somi/plans/<slug>/ with senior-level design judgment. Updates progress.md and diary.md as it goes. Specify which work item and phase/iteration to run.

Pre-development discovery & requirements engineering. Researches the competition and common failure modes, then authors the .somi/rd/<slug>/ document set (research report, BRD, SRS, FRD, SDD, TDD) with inline user verification. Feeds the planning workflow.

Reviews architectural decisions, ADRs, new modules/services, dependency direction changes, and contract changes. Use before introducing a new service, splitting/merging modules, or changing a published interface. Optimizes for long-term maintainability, clear boundaries, and reversibility of decisions.

Elite implementation agent. Use to execute against an approved plan in .somi/plans/<slug>/, or for constrained, well-scoped implementation tasks. Writes maintainable, secure, well-tested code with senior-level design judgment. Keeps the plan in sync — when implementation reveals the plan needs to change, updates spec/decisions/phases in place and appends a diary entry. Detects bad abstractions, tight coupling, and accidental complexity while implementing.

Pre-development discovery & requirements-engineering agent. Use BEFORE any planning or coding, when a new software idea / product concept needs to be turned into a defensible requirements + high-level-design foundation. Performs extensive competitive and complaint research, then authors the .somi/rd/<slug>/ document set (research report, BRD, SRS, FRD, SDD, TDD) with inline user verification at every crossroads. Its output is the cornerstone that the planner consumes.

Staff-engineer-grade planning agent. Use BEFORE writing non-trivial code, when scoping a feature, decomposing an ambiguous request, or when the user asks "how should we approach X". Produces the .somi/plans/<slug>/ artifact set (context, spec, decisions, phases, progress, diary) with inline user verification on architectural choices. Always invoke for changes that cross modules, touch security/auth, or require migrations.

Surgical refactoring agent. Use when the right next move is "untangle this first" rather than "patch around it." Operates under green tests, behavior-preserving by default, with explicit before/after structure. Never combines refactoring with feature work in the same iteration.

Use when adding or changing an HTTP/gRPC/library API. Covers resource modeling, error shapes, versioning, idempotency, pagination, and backward compatibility. Optimizes for callers, not implementers.

Use when naming things, structuring functions, deciding whether to add a comment, or cleaning up code mid-implementation. Pragmatic clean-code rules with explicit anti-patterns and when-not-to-apply guidance.

Use when researching a software idea before specifying it — scanning competitors, mining real user complaints and churn reasons, finding recurring failure modes to design away from, and turning that evidence into requirements, non-goals, and risks. Covers where to look, signal-vs-noise, citation discipline, and how to avoid fabrication and confirmation bias.

Use when adding logs, metrics, or traces — or when reviewing whether code can be debugged in production at 3am. Covers structured logging, the three signals, correlation, cardinality, and alerting philosophy.

Use when the work touches authentication, authorization, cryptography, secret handling, input validation, deserialization, file uploads, template rendering, outbound HTTP triggered by user input, or any sensitive sink. Provides concrete defenses for the OWASP Top 10 mapped to actionable code-level checks.

7 hooks across 3 events