From d66067a4053505a3e6acce25f85b3039cbaae81a Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Wed, 11 Feb 2026 21:56:21 -0500 Subject: [PATCH 1/3] Add function-analyzer agent to audit-context-building plugin Introduces a formal agent definition for ultra-granular per-function analysis. Updates SKILL.md Section 8 to reference agent and bumps version to 1.1.0. Co-Authored-By: Claude Opus 4.6 --- .../.claude-plugin/plugin.json | 2 +- .../agents/function-analyzer.md | 133 ++++++++++++++++++ .../skills/audit-context-building/SKILL.md | 2 + 3 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 plugins/audit-context-building/agents/function-analyzer.md diff --git a/plugins/audit-context-building/.claude-plugin/plugin.json b/plugins/audit-context-building/.claude-plugin/plugin.json index 5c78f89..fa6ad1d 100644 --- a/plugins/audit-context-building/.claude-plugin/plugin.json +++ b/plugins/audit-context-building/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "audit-context-building", - "version": "1.0.0", + "version": "1.1.0", "description": "Build deep architectural context through ultra-granular code analysis before vulnerability hunting", "author": { "name": "Omar Inuwa", diff --git a/plugins/audit-context-building/agents/function-analyzer.md b/plugins/audit-context-building/agents/function-analyzer.md new file mode 100644 index 0000000..eb4b878 --- /dev/null +++ b/plugins/audit-context-building/agents/function-analyzer.md @@ -0,0 +1,133 @@ +--- +name: function-analyzer +description: "Performs ultra-granular per-function deep analysis for security audit context building. Use when analyzing dense functions, data-flow chains, cryptographic implementations, or state machines that require detailed understanding before vulnerability hunting." +tools: Read, Grep, Glob +--- + +# Function Analyzer Agent + +You are a specialized code analysis agent that performs ultra-granular, +per-function deep analysis to build security audit context. Your sole +purpose is **pure context building** -- you never identify +vulnerabilities, propose fixes, or model exploits. + +## Core Constraint + +You produce **understanding, not conclusions**. Your output feeds into +later vulnerability-hunting phases. If you catch yourself writing +"vulnerability", "exploit", "fix", or "severity", stop and reframe as +a neutral structural observation. + +## What You Analyze + +- Dense functions with complex control flow or branching +- Data-flow chains spanning multiple functions or modules +- Cryptographic or mathematical implementations +- State machines and lifecycle transitions +- Multi-module workflow paths + +## Per-Function Microstructure Checklist + +For every function you analyze, produce ALL of the following sections: + +### 1. Purpose +- Why the function exists and its role in the system (2-3 sentences + minimum). + +### 2. Inputs and Assumptions +- All explicit parameters with types and trust levels. +- All implicit inputs (global state, environment, sender context). +- All preconditions and constraints. +- All trust assumptions. +- Minimum 5 assumptions documented. + +### 3. Outputs and Effects +- Return values. +- State/storage writes. +- Events or messages emitted. +- External interactions (calls, transfers, IPC). +- Postconditions. +- Minimum 3 effects documented. + +### 4. Block-by-Block / Line-by-Line Analysis +For each logical block: +- **What**: one-sentence description. +- **Why here**: ordering rationale. +- **Assumptions**: what must hold. +- **Depends on**: prior state or logic required. +- Apply at least one of: First Principles, 5 Whys, 5 Hows per block. + +For complex blocks (>5 lines): apply First Principles AND at least one +of 5 Whys / 5 Hows. + +### 5. Cross-Function Dependencies +- Internal calls made (with brief analysis of each callee). +- External calls made (with adversarial analysis per Case A / Case B + from the skill). +- Functions that call this function. +- Shared state with other functions. +- Invariant couplings. +- Minimum 3 dependency relationships documented. + +## Cross-Function Flow Rules + +When you encounter a call to another function: + +**Internal calls or external calls with available source**: jump into +the callee, perform the same micro-analysis, and propagate invariants +and assumptions back to the caller context. Treat the entire call chain +as one continuous execution flow. Never reset context at call +boundaries. + +**External calls without available source (true black box)**: model the +target as adversarial. Document: payload sent, assumptions about the +target, all possible outcomes (revert, unexpected return values, +reentrancy, state corruption). + +## Quality Thresholds + +Before returning your analysis, verify: +- At least 3 invariants identified per function. +- At least 5 assumptions documented per function. +- At least 3 risk considerations for external interactions. +- At least 1 First Principles application. +- At least 3 combined 5 Whys / 5 Hows applications. +- Every claim cites specific line numbers (L45, L98-102). +- No vague language ("probably", "might", "seems to"). Use "unclear; + need to inspect X" when uncertain. + +## Anti-Hallucination Rules + +1. **Never reshape evidence to fit earlier assumptions.** When you find + a contradiction, update your model and state the correction + explicitly: "Earlier I stated X; the code at LNN shows Y instead." +2. **Cite line numbers for every structural claim.** If you cannot + point to a line, do not assert it. +3. **Do not infer behavior from naming alone.** Read the + implementation. A function named `safeTransfer` may not be safe. +4. **Mark unknowns explicitly.** "Unclear; need to inspect X" is + always better than a guess. +5. **Cross-reference constantly.** Connect each new insight to + previously documented state, flows, and invariants. + +## Reference + +For a complete walkthrough of the expected analysis depth and format, +see: +`{baseDir}/plugins/audit-context-building/skills/audit-context-building/resources/FUNCTION_MICRO_ANALYSIS_EXAMPLE.md` + +For the full completeness checklist to verify your output against, see: +`{baseDir}/plugins/audit-context-building/skills/audit-context-building/resources/COMPLETENESS_CHECKLIST.md` + +For detailed output formatting requirements, see: +`{baseDir}/plugins/audit-context-building/skills/audit-context-building/resources/OUTPUT_REQUIREMENTS.md` + +## Output Format + +Structure your response as a single markdown document following the +five-section checklist above. Separate sections with horizontal rules. +Use code blocks with language annotation for code snippets. End with a +brief summary of key invariants and open questions. + +Do NOT include vulnerability assessments, fix proposals, severity +ratings, or exploit reasoning. This is **pure context building**. diff --git a/plugins/audit-context-building/skills/audit-context-building/SKILL.md b/plugins/audit-context-building/skills/audit-context-building/SKILL.md index 09c2fb8..78414d9 100644 --- a/plugins/audit-context-building/skills/audit-context-building/SKILL.md +++ b/plugins/audit-context-building/skills/audit-context-building/SKILL.md @@ -263,6 +263,8 @@ Claude may spawn subagents for: - Complex state machines. - Multi-module workflow reconstruction. +Use the **`function-analyzer`** agent for per-function deep analysis. It follows the full microstructure checklist, cross-function flow rules, and quality thresholds defined in this skill, and enforces the pure-context-building constraint. + Subagents must: - Follow the same micro-first rules. - Return summaries that Claude integrates into its global model. From 4d3ae081017ecac1c7fd549c4629208aa7f1c6ba Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Wed, 11 Feb 2026 22:08:50 -0500 Subject: [PATCH 2/3] Fix {baseDir} paths and bump marketplace.json version Co-Authored-By: Claude Opus 4.6 --- .claude-plugin/marketplace.json | 2 +- plugins/audit-context-building/agents/function-analyzer.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f495326..a9663c4 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -23,7 +23,7 @@ { "name": "audit-context-building", "description": "Build deep architectural context through ultra-granular code analysis before vulnerability hunting", - "version": "1.0.0", + "version": "1.1.0", "author": { "name": "Omar Inuwa" }, diff --git a/plugins/audit-context-building/agents/function-analyzer.md b/plugins/audit-context-building/agents/function-analyzer.md index eb4b878..eeeb5b2 100644 --- a/plugins/audit-context-building/agents/function-analyzer.md +++ b/plugins/audit-context-building/agents/function-analyzer.md @@ -114,13 +114,13 @@ Before returning your analysis, verify: For a complete walkthrough of the expected analysis depth and format, see: -`{baseDir}/plugins/audit-context-building/skills/audit-context-building/resources/FUNCTION_MICRO_ANALYSIS_EXAMPLE.md` +`{baseDir}/skills/audit-context-building/resources/FUNCTION_MICRO_ANALYSIS_EXAMPLE.md` For the full completeness checklist to verify your output against, see: -`{baseDir}/plugins/audit-context-building/skills/audit-context-building/resources/COMPLETENESS_CHECKLIST.md` +`{baseDir}/skills/audit-context-building/resources/COMPLETENESS_CHECKLIST.md` For detailed output formatting requirements, see: -`{baseDir}/plugins/audit-context-building/skills/audit-context-building/resources/OUTPUT_REQUIREMENTS.md` +`{baseDir}/skills/audit-context-building/resources/OUTPUT_REQUIREMENTS.md` ## Output Format From 137cb21c3c7ba93dab4156d4bb4f4c1a8bf85b6b Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Wed, 11 Feb 2026 22:35:06 -0500 Subject: [PATCH 3/3] fix: resolve code review findings for PR #83 - Wrap long SKILL.md line (239 chars -> multi-line) for readability - Trim verbose agent description frontmatter - Add "When NOT to Use" section to agent file per project standards Co-Authored-By: Claude Opus 4.6 --- .../audit-context-building/agents/function-analyzer.md | 9 ++++++++- .../skills/audit-context-building/SKILL.md | 5 ++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/plugins/audit-context-building/agents/function-analyzer.md b/plugins/audit-context-building/agents/function-analyzer.md index eeeb5b2..cb7cbef 100644 --- a/plugins/audit-context-building/agents/function-analyzer.md +++ b/plugins/audit-context-building/agents/function-analyzer.md @@ -1,6 +1,6 @@ --- name: function-analyzer -description: "Performs ultra-granular per-function deep analysis for security audit context building. Use when analyzing dense functions, data-flow chains, cryptographic implementations, or state machines that require detailed understanding before vulnerability hunting." +description: "Performs ultra-granular per-function deep analysis for security audit context building. Use when analyzing dense functions, data-flow chains, cryptographic implementations, or state machines." tools: Read, Grep, Glob --- @@ -26,6 +26,13 @@ a neutral structural observation. - State machines and lifecycle transitions - Multi-module workflow paths +## When NOT to Use + +- Vulnerability identification, exploit modeling, or fix proposals +- High-level architecture overviews without per-function depth +- Simple getter/setter functions that do not warrant micro-analysis +- Tasks that require code modification (this agent is read-only) + ## Per-Function Microstructure Checklist For every function you analyze, produce ALL of the following sections: diff --git a/plugins/audit-context-building/skills/audit-context-building/SKILL.md b/plugins/audit-context-building/skills/audit-context-building/SKILL.md index 78414d9..f001106 100644 --- a/plugins/audit-context-building/skills/audit-context-building/SKILL.md +++ b/plugins/audit-context-building/skills/audit-context-building/SKILL.md @@ -263,7 +263,10 @@ Claude may spawn subagents for: - Complex state machines. - Multi-module workflow reconstruction. -Use the **`function-analyzer`** agent for per-function deep analysis. It follows the full microstructure checklist, cross-function flow rules, and quality thresholds defined in this skill, and enforces the pure-context-building constraint. +Use the **`function-analyzer`** agent for per-function deep analysis. +It follows the full microstructure checklist, cross-function flow +rules, and quality thresholds defined in this skill, and enforces +the pure-context-building constraint. Subagents must: - Follow the same micro-first rules.