solidity-argus 0.5.10 → 0.6.1

package/AGENTS.md

@@ -11,7 +11,7 @@ CLI: `argus doctor`, `argus init`, `argus install`.
 ## argus
 
 **Role**: Primary security audit orchestrator
-**Description**: Argus Panoptes, the All-Seeing Guardian. Coordinates full Solidity security audits by dispatching Sentinel (analysis), Pythia (research), Scribe (reporting), and Themis (validation). Follows a rigorous 7-step methodology: Reconnaissance, Automated Scanning, Manual Review, Attack Surface Mapping, Vulnerability Research, Testing & Verification, and Reporting.
+**Description**: Argus Panoptes, the All-Seeing Guardian. Coordinates full Solidity security audits by dispatching Sentinel (analysis), Pythia (research), Audit Specialist (deep/adversarial profiles), Scribe (reporting), and Themis (validation). Follows a rigorous 7-step methodology: Reconnaissance, Automated Scanning, Manual Review, Attack Surface Mapping, Vulnerability Research, Testing & Verification, and Reporting.
 **Model**: anthropic/claude-opus-4-7
 **Tools**: 15 orchestrator-accessible argus_* tools (argus_slither_analyze, argus_analyze_contract, argus_check_patterns, argus_proxy_detection, argus_solodit_search, argus_forge_test, argus_gas_analysis, argus_forge_fuzz, argus_forge_coverage, argus_skill_load, argus_generate_report, argus_record_finding, argus_read_findings, argus_sync_knowledge, argus_themis_disposition). `argus_persist_deduped` is reserved for Scribe.
 
@@ -29,6 +29,13 @@ CLI: `argus doctor`, `argus init`, `argus install`.
 **Model**: anthropic/claude-sonnet-4-6
 **Tools**: argus_solodit_search, argus_check_patterns, argus_record_finding, skill
 
+## audit-specialist
+
+**Role**: Profile-driven adversarial specialist auditor
+**Description**: Runs focused deep/adversarial passes under profiles such as vector-scan, access-control, math-precision, invariant, economic-security, execution-trace, periphery, and first-principles. Combines Sentinel-style analysis and verification tools with Pythia-style historical research. Records only confirmed findings; returns unproven trails as LEAD blocks.
+**Model**: anthropic/claude-sonnet-4-6
+**Tools**: argus_skill_load, argus_check_patterns, argus_solodit_search, argus_analyze_contract, argus_slither_analyze, argus_proxy_detection, argus_forge_test, argus_forge_fuzz, argus_forge_coverage, argus_gas_analysis, argus_record_finding, skill
+
 ## scribe
 
 **Role**: Audit report writer

package/README.md

@@ -10,12 +10,12 @@
 
 **solidity-argus** is a security auditing plugin for [OpenCode](https://opencode.ai) that brings professional-grade Solidity smart contract auditing directly into your AI coding workflow.
 
-Argus Panoptes — the mythological all-seeing giant — orchestrates a team of 5 specialized AI agents to conduct comprehensive security audits: static analysis, vulnerability research, dynamic testing, professional report generation, and independent validation.
+Argus Panoptes — the mythological all-seeing giant — orchestrates a team of 6 specialized AI agents to conduct comprehensive security audits: static analysis, vulnerability research, deep adversarial specialist review, dynamic testing, professional report generation, and independent validation.
 
 **What it does:**
 - Runs Slither static analysis and Foundry tests automatically
 - Searches 7,769+ real-world audit findings via SCVD and Solodit
-- Matches code against 82 curated SKILL.md knowledge files
+- Matches code against 91 curated SKILL.md knowledge files
 - Generates professional markdown audit reports with severity classifications
 - Follows a rigorous 7-step audit methodology (Reconnaissance → Report)
 
@@ -68,11 +68,12 @@ Argus will automatically:
 | `@argus` | Orchestrator — coordinates the full audit | claude-opus-4-7 |
 | `@sentinel` | Static analysis & testing specialist | claude-sonnet-4-6 |
 | `@pythia` | Vulnerability researcher | claude-sonnet-4-6 |
+| `@audit-specialist` | Profile-driven adversarial specialist | claude-sonnet-4-6 |
 | `@scribe` | Audit report writer | claude-sonnet-4-6 |
 | `@themis` | Independent audit quality gate | gpt-5.5 |
 
 ### @argus — The Orchestrator
-Argus Panoptes is the lead auditor. It follows a 7-step methodology (Reconnaissance, Automated Scanning, Manual Review, Attack Surface Mapping, Vulnerability Research, Testing & Verification, Reporting) and delegates to Sentinel, Pythia, Scribe, and Themis as needed.
+Argus Panoptes is the lead auditor. It follows a 7-step methodology (Reconnaissance, Automated Scanning, Manual Review, Attack Surface Mapping, Vulnerability Research, Testing & Verification, Reporting) and delegates to Sentinel, Pythia, Audit Specialist, Scribe, and Themis as needed.
 
 ### @sentinel — The Executor
 Runs Slither, writes and executes Foundry tests, performs fuzz testing. Your tactical executor for all dynamic and static analysis tasks.
@@ -80,6 +81,9 @@ Runs Slither, writes and executes Foundry tests, performs fuzz testing. Your tac
 ### @pythia — The Researcher
 Searches Solodit and SCVD for historical exploits, checks vulnerability pattern databases, and provides research context for similar protocols and known attack vectors.
 
+### @audit-specialist — The Adversarial Specialist
+Runs focused deep/adversarial passes under profiles such as `vector-scan`, `access-control`, `math-precision`, `invariant`, `economic-security`, `execution-trace`, `periphery`, and `first-principles`. It records only confirmed findings and returns unproven trails as leads.
+
 ### @scribe — The Reporter
 Transforms raw findings into professional, structured markdown audit reports with severity classifications, impact assessments, and actionable recommendations.
 
@@ -92,17 +96,17 @@ Validates the completed audit by comparing raw findings, deduped findings, and t
 
 | Tool | Agent | Description |
 |------|-------|-------------|
-| `argus_slither_analyze` | Sentinel | Runs Slither static analysis on Solidity contracts; detects reentrancy, uninitialized variables, unchecked returns, and more |
-| `argus_analyze_contract` | Sentinel | Generates a deep structural profile of a contract: functions, state variables, modifiers, inheritance tree |
-| `argus_check_patterns` | Sentinel, Pythia | Scans code against a library of complex vulnerability patterns (regex/AST-based) covering 50+ vulnerability classes across 14 pattern categories |
-| `argus_proxy_detection` | Sentinel | Detects proxy patterns in Solidity contracts (ERC1967, UUPS, transparent, beacon, diamond) with confidence scoring |
-| `argus_solodit_search` | Pythia | Searches Solodit's database of real-world audit reports for similar protocols and historical findings |
-| `argus_forge_test` | Sentinel | Runs existing or newly written Foundry/Forge tests; essential for PoC verification |
-| `argus_gas_analysis` | Sentinel | Runs forge gas report analysis, parses per-function gas metrics, and identifies high-gas hotspots above configurable threshold |
-| `argus_forge_fuzz` | Sentinel | Fuzzes specific functions with random inputs to find edge cases and invariant violations |
-| `argus_forge_coverage` | Sentinel | Runs forge coverage analysis and returns structured per-file coverage metrics (lines, statements, branches, functions) |
-| `argus_skill_load` | Pythia, Themis | Loads curated SKILL.md knowledge files on demand for vulnerability patterns, protocol guidance, methodology, and case studies |
-| `argus_record_finding` | Sentinel, Pythia | Records verified manual, static-analysis, research, or testing findings into durable audit state |
+| `argus_slither_analyze` | Sentinel, Audit Specialist | Runs Slither static analysis on Solidity contracts; detects reentrancy, uninitialized variables, unchecked returns, and more |
+| `argus_analyze_contract` | Sentinel, Audit Specialist | Generates a deep structural profile of a contract: functions, state variables, modifiers, inheritance tree |
+| `argus_check_patterns` | Sentinel, Pythia, Audit Specialist | Scans code against a library of complex vulnerability patterns (regex/AST-based) covering 50+ vulnerability classes across 14 pattern categories |
+| `argus_proxy_detection` | Sentinel, Audit Specialist | Detects proxy patterns in Solidity contracts (ERC1967, UUPS, transparent, beacon, diamond) with confidence scoring |
+| `argus_solodit_search` | Pythia, Audit Specialist | Searches Solodit's database of real-world audit reports for similar protocols and historical findings |
+| `argus_forge_test` | Sentinel, Audit Specialist | Runs existing or newly written Foundry/Forge tests; essential for PoC verification |
+| `argus_gas_analysis` | Sentinel, Audit Specialist | Runs forge gas report analysis, parses per-function gas metrics, and identifies high-gas hotspots above configurable threshold |
+| `argus_forge_fuzz` | Sentinel, Audit Specialist | Fuzzes specific functions with random inputs to find edge cases and invariant violations |
+| `argus_forge_coverage` | Sentinel, Audit Specialist | Runs forge coverage analysis and returns structured per-file coverage metrics (lines, statements, branches, functions) |
+| `argus_skill_load` | Pythia, Audit Specialist, Themis | Loads curated SKILL.md knowledge files on demand for vulnerability patterns, protocol guidance, methodology, and case studies |
+| `argus_record_finding` | Sentinel, Pythia, Audit Specialist | Records verified manual, static-analysis, research, or testing findings into durable audit state |
 | `argus_read_findings` | Scribe, Themis | Reads persisted findings and audit artifacts for report generation and validation |
 | `argus_persist_deduped` | Scribe | Persists deduplicated findings before final report generation and validation |
 | `argus_generate_report` | Scribe | Generates the final structured audit report in professional markdown format |
@@ -113,15 +117,15 @@ Validates the completed audit by comparing raw findings, deduped findings, and t
 
 ## Knowledge Base
 
-The plugin ships with **82 curated SKILL.md files** organized into 6 categories:
+The plugin ships with **91 curated SKILL.md files** organized into 7 categories:
 
 | Category | Files | Description |
 |----------|-------|-------------|
 | Vulnerability Patterns | 51 | Reentrancy, oracle manipulation, flash loans, access control, ERC4626, governance, front-running, and 44 more |
-| Methodology | 3 | Audit workflow, report templates, severity classification |
+| Methodology | 11 | Audit workflow, report templates, severity classification, and 8 audit-specialist profiles |
 | Protocol Patterns | 5 | AMM/DEX, bridges, governance, lending, staking security guides |
 | Checklists | 6 | Cyfrin audit checklists (DeFi core, integrations, upgrades, gas, best practices) |
-| References | 2 | DeFi exploit reference index, SmartBugs vulnerable contract examples |
+| References | 3 | DeFi exploit reference index, SmartBugs vulnerable contract examples, and the attack-vector deck |
 | Case Studies | 15 | Major DeFi exploit analyses (Euler, Nomad Bridge, Ronin, Cream Finance, etc.) |
 
 **Sources:** Trail of Bits, Cyfrin, DeFiFoFum, kadenzipfel, SunWeb3Sec, smartbugs, BailSec, Argus
@@ -288,6 +292,7 @@ Create `.argus/solidity-argus.jsonc` in your project root. `.opencode/solidity-a
     "argus": { "model": "anthropic/claude-opus-4-7" },
     "sentinel": { "model": "anthropic/claude-sonnet-4-6" },
     "pythia": { "model": "anthropic/claude-sonnet-4-6" },
+    "auditSpecialist": { "model": "anthropic/claude-sonnet-4-6" },
     "scribe": { "model": "anthropic/claude-sonnet-4-6" },
     "themis": { "model": "openai/gpt-5.5" }
   },
@@ -339,11 +344,12 @@ Argus uses a **three-channel context delivery system** to inject dynamic audit s
 
 ### Prompt Channel (Static Identity)
 
-Each of the 5 Argus agents has a static prompt file defining its role, methodology, and tool instructions:
+Each of the 6 Argus agents has a static prompt file defining its role, methodology, and tool instructions:
 
 - `src/agents/argus-prompt.ts` — Orchestrator methodology (7-step audit framework)
 - `src/agents/sentinel-prompt.ts` — Static analysis & testing instructions
 - `src/agents/pythia-prompt.ts` — Vulnerability research methodology
+- `src/agents/audit-specialist-prompt.ts` — Profile-driven adversarial review methodology
 - `src/agents/scribe-prompt.ts` — Report generation format and structure
 - `src/agents/themis-prompt.ts` — Independent validation and quality gate logic
 
@@ -358,7 +364,7 @@ The `experimental.chat.system.transform` hook injects dynamic audit state into t
 - Tools executed and their results
 - Session-specific audit state (contract under review, scope, etc.)
 
-**Critical Rule:** This hook is **Argus-family gated**. Only agents in `{argus, sentinel, pythia, scribe, themis}` receive injected context. All other agents receive `undefined` (no injection).
+**Critical Rule:** This hook is **Argus-family gated**. Only agents in `{argus, sentinel, pythia, audit-specialist, scribe, themis}` receive injected context. All other agents receive `undefined` (no injection).
 
 **Session→Agent Mapping Pattern:**
 1. `chat.params` hook captures `(sessionID, agentName)` pairs during each turn
@@ -373,9 +379,9 @@ Agents load specialized knowledge on-demand via the `argus_skill_load` tool:
 
 - **Vulnerability Patterns** — 51 SKILL.md files covering reentrancy, oracle manipulation, flash loans, etc.
 - **Protocol Patterns** — 5 files for AMM/DEX, bridges, governance, lending, staking
-- **Methodology** — 3 files for audit workflow, report templates, severity classification
+- **Methodology** — 11 files for audit workflow, report templates, severity classification, and specialist profiles
 - **Checklists** — 6 Cyfrin audit checklists
-- **References** — 2 files for exploit index and vulnerable contract examples
+- **References** — 3 files for exploit index, vulnerable contract examples, and attack-vector deck
 
 This channel is **lazy-loaded** — agents request skills only when needed, reducing context overhead.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "solidity-argus",
-  "version": "0.5.10",
-  "description": "Solidity smart contract security auditing plugin for OpenCode — 5 specialized agents, 16 tools (15 core + optional Solodit), and a curated vulnerability knowledge base",
+  "version": "0.6.1",
+  "description": "Solidity smart contract security auditing plugin for OpenCode — 6 specialized agents, 16 tools (15 core + optional Solodit), and a curated vulnerability knowledge base",
   "keywords": [
     "solidity",
     "security",

package/skills/INVENTORY.md

@@ -1,7 +1,7 @@
 # Argus Knowledge Base Inventory
 
 Generated: 2026-02-20
-Total SKILL.md files: 82
+Total SKILL.md files: 91
 
 ## Vulnerability Patterns
 | File | Source(s) | Topic | Word Count |
@@ -65,6 +65,18 @@ Total SKILL.md files: 82
 | methodology/report-template/SKILL.md | DeFiFoFum | Audit Report Template | 585 |
 | methodology/severity-classification/SKILL.md | DeFiFoFum | Severity Classification Guide | 603 |
 
+## Specialist Profiles
+| File | Source(s) | Topic | Word Count |
+|------|-----------|-------|------------|
+| specialist-profiles/access-control-specialist/SKILL.md | Argus | Access Control Specialist Profile | 190 |
+| specialist-profiles/economic-security/SKILL.md | Argus | Economic Security Profile | 190 |
+| specialist-profiles/execution-trace/SKILL.md | Argus | Execution Trace Profile | 180 |
+| specialist-profiles/first-principles/SKILL.md | Argus | First Principles Profile | 170 |
+| specialist-profiles/invariant/SKILL.md | Argus | Invariant Profile | 170 |
+| specialist-profiles/math-precision/SKILL.md | Argus | Math Precision Profile | 190 |
+| specialist-profiles/periphery/SKILL.md | Argus | Periphery Profile | 175 |
+| specialist-profiles/vector-scan/SKILL.md | Argus | Vector Scan Profile | 150 |
+
 ## Protocol Patterns
 | File | Source(s) | Topic | Word Count |
 |------|-----------|-------|------------|
@@ -89,6 +101,7 @@ Total SKILL.md files: 82
 |------|-----------|-------|------------|
 | references/exploit-reference/SKILL.md | SunWeb3Sec | DeFi Exploit Reference Index | 1125 |
 | references/smartbugs-examples/SKILL.md | smartbugs | SmartBugs Curated Dataset — Vulnerable Contract Examples | 1677 |
+| references/attack-vector-deck/SKILL.md | Argus | Attack-Vector Deck | 520 |
 
 ## Case Studies
 | File | Source(s) | Topic | Word Count |

package/skills/README.md

@@ -9,9 +9,10 @@ OpenCode Skills System
 ├── skills/ (bundled with plugin)
 │   ├── vulnerability-patterns/ (51 patterns from kadenzipfel + DeFiFoFum + BailSec + Argus)
 │   ├── methodology/ (3 files from DeFiFoFum)
+│   ├── specialist-profiles/ (8 profile skills for audit-specialist)
 │   ├── protocol-patterns/ (5 files from DeFiFoFum)
 │   ├── checklists/ (6 files from DeFiFoFum + Cyfrin)
-│   ├── references/ (2 files: SmartBugs + DeFiHackLabs)
+│   ├── references/ (3 files: SmartBugs + DeFiHackLabs + attack-vector deck)
 │   └── case-studies/ (15 case studies from DeFiFoFum)
 ├── SCVD Local Index (~/.cache/solidity-argus/scvd-index.json)
 │   └── 7,769+ findings, auto-synced from api.scvd.dev
@@ -37,6 +38,7 @@ All sources in the table below must include the following metadata in their SKIL
 | SunWeb3Sec/DeFiHackLabs | Reference only | https://github.com/SunWeb3Sec/DeFiHackLabs | 15 exploit PoC GitHub URL references |
 | BailSec | CC0 | https://github.com/bailsec/BailSec | Vulnerability patterns extracted from professional audit PDFs |
 | SCVD (api.scvd.dev) | CC0 | https://api.scvd.dev | 7,769+ findings via local index (auto-synced) |
+| Argus specialist profiles | MIT | https://github.com/Apegurus/solidity-argus | 8 profile skills and one attack-vector deck for deep/adversarial audit passes |
 
 ## SKILL.md Format Specification
 
@@ -119,4 +121,4 @@ detection_rules:
 
 ## Inventory
 
-See [INVENTORY.md](./INVENTORY.md) for a complete listing of all 82 SKILL.md files currently bundled with Argus.
+See [INVENTORY.md](./INVENTORY.md) for a complete listing of all 91 SKILL.md files currently bundled with Argus.

package/skills/references/attack-vector-deck/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: attack-vector-deck
+description: Compact catalogue of concrete Solidity vulnerability vectors with detection cues and false-positive guards.
+category: reference
+source_url: https://github.com/Apegurus/solidity-argus
+source_license: MIT
+imported_at: "2026-05-18T00:00:00Z"
+---
+
+# Attack-Vector Deck
+
+Use this as a review catalogue, not as an automatic finding source. A vector becomes a finding only after proving reachability, missing guard or broken accounting, and impact in the reviewed code.
+
+## Vectors
+
+**1. Unprotected Privileged State Change**
+- **D:** External/public function mutates admin-controlled state without a role, owner, governance, or contract-only guard.
+- **FP:** The function is reachable only during construction/initialization or guarded by an equivalent custom authorization check.
+
+**2. Initializer or Upgrade Authority Takeover**
+- **D:** Proxy implementation, initializer, upgrade function, or ownership transfer can be called by an unintended account or more than once.
+- **FP:** Initializer is disabled on the implementation and proxy initialization is atomic with deployment.
+
+**3. Share or Reward Accumulator Drift**
+- **D:** Deposits, withdrawals, reward-rate changes, or supply changes occur without settling global/user accumulators first.
+- **FP:** Every state-changing path checkpoints both global and user state before mutating rates, balances, or supply.
+
+**4. Decimal or Scale Mismatch**
+- **D:** Assets, oracle prices, shares, or rewards with different decimals are multiplied/divided without explicit normalization.
+- **FP:** Code normalizes all operands to a documented common scale before arithmetic.
+
+**5. Rounding Direction Value Leak**
+- **D:** Mint/redeem/borrow/liquidate paths round in the user's favor across repeatable operations.
+- **FP:** Rounding direction is explicit, bounded, and unfavorable to the caller where value can be extracted.
+
+**6. Callback or Reentrancy State Desynchronization**
+- **D:** External calls, token hooks, receiver callbacks, or low-level calls occur before all dependent state is finalized.
+- **FP:** Reentrancy guard plus checks-effects-interactions cover every callable path sharing the same state.
+
+**7. Oracle or Spot Price Manipulation**
+- **D:** Critical mint/borrow/liquidation/swap logic uses spot AMM reserves or a manipulable single-source price.
+- **FP:** Price source is TWAP/medianized/bounded and stale/manipulated values are rejected.
+
+**8. Fee-On-Transfer or Rebasing Token Desync**
+- **D:** Protocol credits requested transfer amounts instead of observed balance deltas for arbitrary ERC20s.
+- **FP:** Accounting uses pre/post balance deltas or the token set is strictly allowlisted to standard behavior.
+
+**9. Cross-Chain Message Spoofing or Replay**
+- **D:** Receiver accepts messages without validating endpoint, chain/domain, registered peer, nonce, or replay status.
+- **FP:** Endpoint, origin, chain/domain, and replay protection are all enforced before effects.
+
+**10. Queue or Async Flow Parameter Divergence**
+- **D:** Request parameters are stored, transformed, or fulfilled later with mutable global parameters that can drift unfairly.
+- **FP:** The request snapshots all price/rate/limit parameters needed for fair fulfillment.
+
+**11. Periphery Encoder or Adapter Semantic Mismatch**
+- **D:** Helper, router, adapter, or library changes calldata/order/units/trust assumptions relative to the core contract.
+- **FP:** Adapter invariants are documented and tested against the core contract's expected semantics.
+
+**12. Invariant Broken by Donation or Direct Transfer**
+- **D:** Accounting assumes token balance equals internal tracked balance, but anyone can transfer assets directly.
+- **FP:** Conversions use internal accounting or explicitly handle unsolicited balance changes.

package/skills/specialist-profiles/access-control-specialist/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: access-control-specialist
+description: Specialist profile for roles, modifiers, initialization, upgrade authority, and guard consistency review.
+category: methodology
+source_url: https://github.com/Apegurus/solidity-argus
+source_license: MIT
+imported_at: "2026-05-18T00:00:00Z"
+---
+
+# Access Control Specialist Profile
+
+## Objective
+Find authorization gaps, inconsistent guards, initialization takeovers, upgrade authority mistakes, and privileged flows that can be abused.
+
+## Attack Surfaces
+Owners, roles, multisigs, governance executors, keepers, pausers, upgraders, initializers, factories, delegates, and adapter-only entry points.
+
+## Reading Pattern
+1. List every external/public state-changing function.
+2. Map each function to its intended actor and actual guard.
+3. Trace initialization and upgrade paths separately.
+4. Compare similar functions for missing or weaker modifiers.
+
+## Recommended Skills
+Load `access-control`, `proxy-vulnerabilities`, `cyfrin-best-practices-upgrades`, and `governance-attacks` when relevant.
+
+## Proof Fields
+Include caller identity, target function, missing/incorrect guard, state change reached, and security impact.
+
+## False-Positive Cautions
+Public functions are not bugs if intentionally permissionless and bounded by economic or state constraints.

package/skills/specialist-profiles/economic-security/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: economic-security
+description: Specialist profile for external dependencies, token behavior, incentives, oracle assumptions, and value-flow attacks.
+category: methodology
+source_url: https://github.com/Apegurus/solidity-argus
+source_license: MIT
+imported_at: "2026-05-18T00:00:00Z"
+---
+
+# Economic Security Profile
+
+## Objective
+Find attacks where the code is locally correct but economically exploitable through prices, incentives, liquidity, token behavior, governance, or integration assumptions.
+
+## Attack Surfaces
+AMM reserves, oracle feeds, collateral values, liquidation incentives, reward emissions, fee paths, arbitrary ERC20 integrations, governance power, and flash-loan-amplified flows.
+
+## Reading Pattern
+1. Trace all value flows into and out of the protocol.
+2. Identify assumptions about price, liquidity, token behavior, and participant incentives.
+3. Ask whether capital, same-block execution, or governance power can bend those assumptions.
+4. Search historical precedents when the shape matches known DeFi exploits.
+
+## Recommended Skills
+Load `oracle-manipulation`, `flash-loan-attacks`, `weird-tokens`, `unsafe-erc20-transfers`, `amm-dex`, and `lending-borrowing` as needed.
+
+## Proof Fields
+Include dependency manipulated, attack capital/sequence, resulting mispricing or incentive break, and value impact.
+
+## False-Positive Cautions
+Do not report generic centralization or market risk unless a code path makes the risk exploitable or materially worse.

package/skills/specialist-profiles/execution-trace/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: execution-trace
+description: Specialist profile for stale reads, parameter divergence, branch ordering, callbacks, and cross-transaction interleavings.
+category: methodology
+source_url: https://github.com/Apegurus/solidity-argus
+source_license: MIT
+imported_at: "2026-05-18T00:00:00Z"
+---
+
+# Execution Trace Profile
+
+## Objective
+Find bugs that appear only when execution order, callbacks, stale reads, queued requests, or multi-transaction interleavings are traced precisely.
+
+## Attack Surfaces
+External calls, token hooks, receiver callbacks, routers, queues, delayed settlement, permit/signature flows, and multi-step lifecycle functions.
+
+## Reading Pattern
+1. Trace each critical function as ordered reads, checks, effects, and interactions.
+2. Mark every value read before an external call and used after it.
+3. Identify stored request parameters and mutable globals used during later fulfillment.
+4. Consider same-block and cross-transaction ordering attacks.
+
+## Recommended Skills
+Load `reentrancy`, `front-running-attacks`, `dos-revert`, `missing-protection-signature-replay`, and `unbounded-return-data` when relevant.
+
+## Proof Fields
+Include ordered trace, stale/divergent value, attacker-controlled step, and state/asset impact.
+
+## False-Positive Cautions
+Callbacks are not vulnerabilities by themselves; show the callback can observe or mutate shared state in a harmful way.

package/skills/specialist-profiles/first-principles/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: first-principles
+description: Specialist profile for line-by-line assumption extraction without relying on named bug classes.
+category: methodology
+source_url: https://github.com/Apegurus/solidity-argus
+source_license: MIT
+imported_at: "2026-05-18T00:00:00Z"
+---
+
+# First Principles Profile
+
+## Objective
+Ignore vulnerability taxonomies at first. Extract what the code assumes must be true, then search for any caller, state, or dependency that makes an assumption false.
+
+## Attack Surfaces
+Any high-value, unfamiliar, or highly coupled code path; especially systems where named bug patterns do not fully describe the risk.
+
+## Reading Pattern
+1. For each critical function, list assumptions about caller, state, timing, external contracts, balances, prices, and previous calls.
+2. For each assumption, ask who can falsify it and at what cost.
+3. Build minimal violating sequences.
+4. Only map the result back to a named bug class after proof exists.
+
+## Recommended Skills
+Load `audit-context-building`, `logic-errors`, `general-audit`, and `attack-vector-deck` when broad context is needed.
+
+## Proof Fields
+Include assumption, falsification path, code location, state transition, and impact.
+
+## False-Positive Cautions
+Do not record philosophical concerns. Convert assumptions into concrete reachable failures.

package/skills/specialist-profiles/invariant/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: invariant
+description: Specialist profile for extracting conservation laws and state couplings, then searching for violating paths.
+category: methodology
+source_url: https://github.com/Apegurus/solidity-argus
+source_license: MIT
+imported_at: "2026-05-18T00:00:00Z"
+---
+
+# Invariant Profile
+
+## Objective
+Derive the protocol's core invariants and find reachable sequences that violate them.
+
+## Attack Surfaces
+Mint/burn symmetry, total assets versus shares, collateral versus debt, reward accumulators, escrow balances, queued requests, and role lifecycle state.
+
+## Reading Pattern
+1. State each invariant in plain language and as an equation when possible.
+2. Map every function that mutates each variable in the invariant.
+3. Search for paths that update only one side of the coupling.
+4. Use tests or fuzzing when a violation can be encoded cheaply.
+
+## Recommended Skills
+Load `property-based-testing`, `share-accounting-desynchronization`, and protocol-specific skills such as `lending-borrowing` or `staking-vesting`.
+
+## Proof Fields
+Include invariant statement, violating path, concrete state before and after, and impact.
+
+## False-Positive Cautions
+An invariant must reflect intended protocol behavior, not an assumption imposed by the reviewer.

package/skills/specialist-profiles/math-precision/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: math-precision
+description: Specialist profile for rounding, scale, decimal, downcast, and arithmetic accounting edge cases.
+category: methodology
+source_url: https://github.com/Apegurus/solidity-argus
+source_license: MIT
+imported_at: "2026-05-18T00:00:00Z"
+---
+
+# Math Precision Profile
+
+## Objective
+Find arithmetic bugs that leak value, distort accounting, or break protocol invariants through rounding, scale mismatch, decimal mismatch, downcasts, and stale accumulators.
+
+## Attack Surfaces
+Share conversions, reward math, fee math, collateral factors, liquidation discounts, oracle scaling, vesting schedules, and accumulator updates.
+
+## Reading Pattern
+1. Write the unit/scale next to every value in each formula.
+2. Identify every division and rounding direction.
+3. Check whether the caller can repeat a favorable rounding path.
+4. Compare internal accounting against actual token balances.
+
+## Recommended Skills
+Load `lack-of-precision`, `share-accounting-desynchronization`, `erc4626-exchange-rate-manipulation`, and `stateful-parameter-update-drift` when applicable.
+
+## Proof Fields
+Include concrete numbers, before/after balances, rounding direction, repeatability, and value impact.
+
+## False-Positive Cautions
+Dust-level loss is not a security finding unless repeatable, griefable, or able to accumulate into material loss.

package/skills/specialist-profiles/periphery/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: periphery
+description: Specialist profile for libraries, helpers, base contracts, adapters, encoders, wrappers, and integration glue.
+category: methodology
+source_url: https://github.com/Apegurus/solidity-argus
+source_license: MIT
+imported_at: "2026-05-18T00:00:00Z"
+---
+
+# Periphery Profile
+
+## Objective
+Find bugs hidden in supporting code that changes semantics before calls reach core contracts.
+
+## Attack Surfaces
+Libraries, inherited base contracts, routers, adapters, wrappers, encoders, factories, deployment scripts, allowlists, and helper math.
+
+## Reading Pattern
+1. Identify all code that prepares, wraps, routes, or translates calls to core contracts.
+2. Compare units, address assumptions, calldata layout, and access checks between periphery and core.
+3. Search for differences between direct core calls and periphery-mediated calls.
+4. Check inherited hooks and overridden functions for unexpected side effects.
+
+## Recommended Skills
+Load `logic-errors`, `unsafe-erc20-transfers`, `incorrect-inheritance-order`, and protocol integration skills as needed.
+
+## Proof Fields
+Include periphery path, semantic mismatch, affected core call, and exploit impact.
+
+## False-Positive Cautions
+Periphery bugs matter when users, integrations, or privileged flows actually rely on the periphery path.

package/skills/specialist-profiles/vector-scan/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: vector-scan
+description: Specialist profile for mechanically applying the attack-vector deck and classifying vectors as skip, drop, or investigate.
+category: methodology
+source_url: https://github.com/Apegurus/solidity-argus
+source_license: MIT
+imported_at: "2026-05-18T00:00:00Z"
+---
+
+# Vector Scan Profile
+
+## Objective
+Apply `attack-vector-deck` across the scoped code and force every relevant vector into `skip`, `drop`, or `investigate`.
+
+## Reading Pattern
+1. Load `attack-vector-deck`.
+2. Map contracts by asset custody, privileged controls, external calls, oracle use, and async flows.
+3. For each vector, cite the concrete functions reviewed.
+4. Promote only proven `investigate` items to `FINDING`; return incomplete trails as `LEAD`.
+
+## Recommended Skills
+Load `general-audit`, `access-control`, `reentrancy`, `oracle-manipulation`, or protocol-specific skills only when the vector points at that domain.
+
+## Proof Fields
+Include vector number, path, missing guard or broken invariant, concrete exploit sequence, and impact.
+
+## False-Positive Cautions
+Do not record a finding from vector similarity alone. Prove the vector applies to reachable production code.