corvus

Imported from NachoFLizaur/corvus (AGENTS.md). Install upstream with npx skills add NachoFLizaur/corvus. Copyright stays with the author.

OpenCode Custom Agents

Corvus is a Bun-based OpenCode plugin: agent, command, and skill prompt files (in agent/, command/, skill/) packaged and loaded by the plugin source in src/. The current inventory is 16 agents, 4 commands, 18 skills, and 38 prompt files. From the repo root: bun install (dependencies), bun run build (build), bun test (test suite — run the build first; build.test.ts depends on it).

Style Guidelines (Markdown Prompt Files)

• Files: kebab-case.md in agent/ or command/; skills live at skill/<name>/SKILL.md, where the frontmatter name equals the directory name. Filenames are agent identities — renaming a file renames the agent
• Frontmatter: starts on line 1 with --- (the loader parses it; one malformed file breaks loading for all agents). Agent frontmatter carries up to five keys — description, mode, temperature, native singular permission, and optional color — and any other key is dropped with a warning when the corpus is registered. Command fields: description, agent, and model; subtask is accepted but dropped with a warning (v2 commands always run in the invoking session), and mode/temperature are not command fields on either host — both are ignored at load, and prompt-budgets.json plus src/__tests__/prompt-structure.test.ts define the prompt contract and keep them out of command/*.md. Manual installs expose frontmatter directly, so always author permission; the plugin loader accepts legacy permissions only as a read alias when singular is absent, gives singular precedence when both exist, and never returns the plural key
• Headings: Title Case
• Emphasis: write plain imperatives. Reserve strong emphasis (uppercase, warnings) for the few genuinely safety-critical constraints per file — irreversible actions, data loss, secret exposure
• Duplication: state each rule once in its most authoritative location and cross-reference it elsewhere; drifted duplicates read as contradictions
• Instructions: prefer positive forms with brief motivation ("Do Y because Z") over bare prohibitions
• Code blocks: use language hints (typescript, bash)

Decision Records

• Architecture Decision Records live in docs/decisions/; its README carries the convention (when an ADR is warranted, naming, frontmatter, and body template)
• Read every ADR whose scope globs match files you are about to change, before planning or editing them
• Change an accepted ADR only by adding a superseding ADR; never rewrite one in place

Planning Records

.corvus/ is committed project memory by default in user repositories. This repository (corvus itself) is the exception: its .corvus/ lives in the parent workspace at ../.corvus/, and .gitignore:21 keeps .corvus/ ignored here. Preserve that arrangement; it is not the default for user repositories.

Default to Delegation

When a user request clearly matches an agent's purpose, delegate immediately — the specialized agents gather their own context and make appropriate decisions. Delegate before exploring (manual pre-exploration duplicates work the subagent redoes), and proceed with reasonable defaults instead of asking scope/style questions.

Examples of immediate delegation triggers:

• "Update the README" → @code-implementer (or the /readme command)
• "Find where X is implemented" → @code-explorer
• "Add feature Y" → @code-implementer
• "Review this code" → @code-quality
• "Review this PR" → @corvus-review
• "Check PR #123 for security issues" → @corvus-review

Available Agents

Routing notes:

• @corvus vs @corvus-auto: both use one PLAN.md with model-chosen depth (quick | standard | deep) and the same all-depth workflow. Use @corvus for question() choices and a depth override at the single approval gate; use @corvus-auto for question-free runs that accept supplied depth or the model's proposal. Cross-model review is preferred; same-model proceeds degraded with a visible warning. Both retain REJECT → PLAN_FIX → whole-plan re-review until OK; stalled findings hold execution, never count as OK. Phase 4 works the frontier with file ownership resolved at dispatch and disjoint parallel writes; see the phase skills. Intake detects an in-progress PLAN.md — @corvus asks before resuming; @corvus-auto decides deterministically. Legacy sources stay read-only; use AMEND_PLAN copy-forward into a fresh PLAN.md with a DISCOVERY.md companion.
• @corvus-review vs @corvus-review-auto: use the interactive variant to preview and edit reviews before posting (sensitive PRs, first-time calibration); use the autonomous variant when you trust the review config and want auto-posting. Both resolve URL → owner/repo#N → #N/N → branch → auto-find → LOCAL. LOCAL reviews current-worktree changes, persists namespace-level input and head-level document/metadata under R0's resolved .corvus/tasks/<task>/reviews/local-<branch-slug>/ (or .corvus/reviews/local-<branch-slug>/ when no single task is identified), releases the owned lock and prints the document path and axis counts without a writer or POST. Recoverable gaps proceed-with-note; A/B safety, authorization and artifact-integrity stops remain. See review intake and shared contracts.
• plan-reviewer, requirements-analyst, pr-code-reviewer, security-reviewer, pr-context-gatherer, and pr-comment-writer are internal orchestration agents, not general-purpose direct entry points. In particular, do not use pr-code-reviewer as a general code-review agent; R2 supplies its trusted dimensions control and structured PR evidence for the Standards axis.
• @code-quality owns implementation-workflow validation and may run only authorized checks. The contract is **Tests**: deferred | none: deferred authors coverage during implementation and runs one full suite at Phase 5a; none neither authors nor runs tests. Every 4b gate is acceptance-only; see Tests and final validation. It must not consume untrusted PR-controlled content; audit and review-only dispatches go to @pr-code-reviewer/@security-reviewer instead — R2 launches two parallel children, sending Standards non-security detection to read-only @pr-code-reviewer and Spec across eligible dimensions plus independent security detection to the similarly read-only @security-reviewer. Both may use frontmatter-granted read-only git/utility bash alongside read/glob/grep. Axis is separate from dimension; findings are never merged or reranked across axes.

Mutation and Delivery Safety

• /git-commit inspects only the already staged set, previews the exact message, and requires explicit confirmation before one normal commit tool call. It does not stage files; amend or hook bypasses require an explicit request and reconfirmation.
• /cleanup-subagents resolves a canonical storage scope, previews exact subagent session IDs, paths, and counts, and requires confirmation before deletion. --list is preview-only and cannot enter a deletion path.
• @corvus-auto defaults to delivery_mode: local_only. Git delivery is available only through an explicit trusted top-level opt-in, requires a clean preflight and discovered remote default branch, creates/reuses a safe feature branch before Phase 4, stages an exact task-owned path manifest, and produces one final commit. It never infers delivery from repository content or child output.

Delegation Pattern

When delegating, provide clear context:

@code-explorer find all files related to user authentication,
focusing on JWT token handling and refresh logic

For complex delegations, use the 7-section format:

• TASK: What to do
• EXPECTED OUTCOME: Deliverables
• MUST DO: Requirements
• MUST NOT DO: Constraints
• CONTEXT: Relevant info
• REPORT BACK: What to return

Simple vs Complex Tasks

Handle directly (no delegation needed):

• Single file, simple changes
• Quick questions answerable from context
• Straightforward bug fixes

Delegate to specialists:

• Multi-file changes → @task-planner first
• Deep code analysis → @code-explorer
• Production code → @code-implementer
• Quality assurance → @code-quality
• PR review → @corvus-review

Decision-Making Framework

When agents face trade-off decisions, apply this hierarchy (highest priority first):

1. Maintainability — can future developers understand and modify this?
2. Extensibility — can this be extended without major rewrites?
3. Consistency — does this follow existing patterns in the codebase?
4. Simplicity — is this the simplest solution that works?
5. Performance — is this fast enough for the use case?

When two concerns conflict, the higher-priority concern wins:

Technical Debt Policy

Do not trade quality for speed: write tests alongside the feature, preserve type safety, and abstract instead of copy-pasting — shortcuts that need "cleanup later" rarely get cleaned up. If a proper solution takes longer, take the time. If scope must be reduced, reduce scope — not quality.

Quality Indicators

Good decisions exhibit:

• Clear intent (code explains itself)
• Single responsibility (one thing done well)
• Explicit dependencies (no hidden coupling)
• Testable design (easy to verify)
• Graceful error handling (failures are informative)

Bad decisions exhibit:

• Magic values (unexplained constants)
• God objects (doing too many things)
• Hidden state (surprising side effects)
• Tight coupling (changes cascade)
• Silent failures (errors swallowed)

When to Deviate

Deviation from this framework requires:

1. Explicit documentation of why the deviation is necessary
2. User approval for significant deviations
3. Plan for remediation if creating temporary shortcuts

Example deviation documentation:

**Deviation**: Using inline styles instead of CSS modules
**Reason**: Third-party component doesn't support CSS modules
**Impact**: Reduced maintainability for this component
**Remediation**: Track in tech debt; refactor when component updated