v0.7.0 to v1.0.0

- version: "0.7.0"

- description: Verify code against organizational policies, security requirements, and framework best practices. Use when asked to "verify", "review", "audit", "check compliance", or "validate" code.

- Verify code against business rules, security policies, and framework best practices. All analysis happens locally—code never leaves your machine.

- - "verify my code/agent"

- - "review code"

- - "audit my code"

- - "check against rules"

- - "validate implementation"

- ## Process

-

- ### Step 1: Detect Mode and Load Context

-

- **Check for Kahuna integration** (`.kahuna/` directory exists):

-

- If `.kahuna/` directory exists:

- - Context is pre-loaded from `kahuna_prepare_context`

- - Use `kahuna_ask` for additional queries

- - Read `.kahuna/context-guide.md` for organizational rules and framework patterns

-

- If `.kahuna/` directory does NOT exist (standalone mode):

- - Scan for project configuration files

- - Apply built-in best practices (see Step 1b)

-

- ### Step 1b: Standalone Context Discovery

-

- When running without Kahuna, gather context from the project itself:

-

- **Project configuration files:**

- - `package.json`, `pyproject.toml`, `Cargo.toml` - Dependencies and project type

- - `tsconfig.json`, `biome.json`, `.eslintrc*` - Linting/formatting rules

- - `.env.example` - Expected environment variables

-

- **Documentation:**

- - `README.md` - Project overview

- - `docs/`, `CONTRIBUTING.md`, `.github/CONTRIBUTING.md` - Guidelines

- - `ARCHITECTURE.md`, `DESIGN.md` - Design decisions

-

- **Detect language/framework from:**

- - File extensions (`.py`, `.ts`, `.js`, `.go`, `.rs`)

- - Dependencies in manifest files

- - Directory structure patterns

-

- ### Step 2: Discover Files to Analyze

-

- Locate implementation files in the project. Check these common locations:

-

- **Directories:**

- - `src/agent/`, `agent/`, `src/`, project root

- - `lib/`, `app/`, `packages/`

-

- **Key files to analyze:**

- - `graph.py` - Workflow/graph definition (LangGraph)

- - `tools.py` - Tool implementations

- - `state.py` - State schema definitions

- - `prompts.py` - Prompt templates

- - `nodes.py` - Node function implementations

- - `config.py`, `settings.py` - Configuration

- - `*.ts`, `*.js` - TypeScript/JavaScript sources

- - `*.go`, `*.rs` - Go/Rust sources

-

- **AI Agent files to prioritize (when agent patterns detected):**

- - `graph.py`, `graph.ts` - Agent workflow definitions

- - `tools.py`, `tools.ts`, `tools/*.py`, `tools/*.ts` - Tool implementations

- - `state.py`, `state.ts` - State schemas

- - `prompts.py`, `prompts/*.md`, `system.md` - Prompt templates

- - `agent.py`, `agent.ts` - Main agent logic

- - `langgraph.json`, `crew.yaml` - Framework configurations

-

- **Exclude from prompt size analysis:**

- - `skills/` directory and all subdirectories — these are skill definition files (e.g. `SKILL.md`) loaded on demand by the coding agent, not static system prompts embedded in every LLM call. Flagging them for size would be a false positive.

-

- Use `list_files` or equivalent to discover the actual structure, then read relevant files.

-

- ### Step 3: Verify Code Against Rules

-

- #### Check Tiers

-

- Every check in this skill is classified as one of two tiers. Apply them differently:

-

- - **`[PATTERN]`** — Mechanical. The answer is objectively correct or incorrect based on code structure. Apply the rule exactly as written. Do not use judgment to soften or skip. A missing `stop=` parameter on `@retry` is always an ❌ Issue, regardless of context. Report these with high confidence.

-

- - **`[HEURISTIC]`** — Judgment required. The rule describes a quality signal that requires interpretation. Apply it as a best-effort assessment. Mark these findings clearly so the reader knows they reflect analysis, not a deterministic check.

-

- In the report, tag every finding with its tier: `[P]` for pattern, `[H]` for heuristic.

-

- #### Fallback Rule

-

- Every `[PATTERN]` check has a paired `[HEURISTIC]` fallback. After running the pattern table for a given category, also scan for behavior that *resembles* the anti-pattern but doesn't match any specific table entry. This catches novel libraries, custom implementations, and pattern drift that rigid tables cannot anticipate.

-

- Heuristic fallback findings are always:

- - Tagged `[H]` in the report

- - Reported as ⚠️ Warning (never ❌ Issue) — they reflect judgment, not a definitive match

- - Accompanied by a note explaining why a manual review is recommended

-

- The pattern check is the **primary** detector (high confidence, low false positives). The heuristic fallback is the **safety net** (lower confidence, catches what patterns miss).

-

- ---

-

- Analyze code against all available rules:

-

- **With Kahuna (enhanced mode):**

- 1. **Organizational rules** - Company policies from `.kahuna/context-guide.md`

- 2. **IT/Security rules** - Security requirements from knowledge base

- 3. **Framework best practices** - Patterns from surfaced context

-

- **Standalone (built-in rules):**

-

- 1. **`[HEURISTIC]` General code quality**

- - Clear naming conventions (descriptive, consistent)

- - Appropriate code organization and structure

- - Error handling patterns

- - No magic numbers/strings without constants

-

- 2. **Security basics** — mixed tier (see per-item labels below:)

- - `[PATTERN]` No hardcoded secrets — scan for assignments matching `API_KEY`, `SECRET`, `PASSWORD`, `TOKEN`, `PRIVATE_KEY` (case-insensitive) assigned to string literals. Flag any match as ❌ Issue.

- - `[HEURISTIC]` Input validation on external data

- - `[HEURISTIC]` Proper error messages (no stack traces in production)

- - `[HEURISTIC]` Secure defaults

-

- 3. **Language-specific (auto-detected):**

-

- *TypeScript/JavaScript:*

- - `[PATTERN]` Type safety — flag if `tsconfig.json` does not have `"strict": true`

- - `[HEURISTIC]` Async/await error handling

- - `[PATTERN]` No `any` types — flag unqualified `: any` annotations as ⚠️ Warning

- - `[HEURISTIC]` Dependency security (outdated/vulnerable packages)

-

- *Python:*

- - `[PATTERN]` Type hints — flag any `def` function in public scope (no leading `_`) that has parameters without type annotations, as ⚠️ Warning

- - `[HEURISTIC]` Docstrings for modules, classes, functions

- - `[PATTERN]` Requirements pinning — flag any line in `requirements.txt` / `pyproject.toml` dependencies using `>=`, `>`, or no version specifier (should use `==`), as ❌ Issue

-

- *Go:*

- - `[PATTERN]` No ignored errors — flag any `_ = ` assignments where the right-hand side is a function call returning `error`, as ❌ Issue

- - `[HEURISTIC]` Context propagation

- - `[HEURISTIC]` Proper package structure

-

- 4. **AI Agent-specific (if detected):**

- - `[HEURISTIC]` State schema validation

- - `[HEURISTIC]` Tool error handling

- - `[HEURISTIC]` Prompt injection considerations

- - `[HEURISTIC]` Rate limiting awareness

-

- **Agent Observability Patterns:**

-

- 5. **`[PATTERN]` Loop Safety**

-

- Apply mechanically. Do not pass a loop because it "looks like it might terminate."

-

- | Pattern to find | Pass condition | Severity |

- |-----------------|----------------|----------|

- | `while True:` in Python | A `break` statement exists within the same block scope | ⚠️ Warning if absent |

- | `for { }` in Go | A `break` or `return` exists within the block | ⚠️ Warning if absent |

- | `while (true)` in TS/JS | A `break` or `return` exists within the block | ⚠️ Warning if absent |

- | Function calls itself recursively | A non-recursive return path exists (base case), OR a depth/counter parameter is present | ⚠️ Warning if absent |

-

- **`[HEURISTIC]` Fallback: Unrecognized Loop Patterns**

-

- After applying the pattern table above, also scan for loop-like behavior that may run indefinitely but doesn't match any specific pattern above:

- - Any loop where the termination condition depends entirely on external/runtime state with no timeout or max-iteration guard

- - Generator functions that `yield` indefinitely without a documented exit condition

- - Event loops or polling loops (e.g. `while not done:`, `while queue:`) without timeout parameters

- - Recursive call chains across multiple functions (A calls B, B calls A) without depth tracking

-

- If found, flag as ⚠️ Warning: *"Potential unbounded loop not matching known patterns — verify termination condition manually"*

-

- 6. **`[PATTERN]` Retry Limit Enforcement**

-

- Apply mechanically. Check each decorator or call against the table below. If the required parameter is absent, flag as ❌ Issue regardless of other parameters present.

-

- **Decorator-based (Python):**

-

- | Library/Pattern | Required parameter | Fail condition |

- |-----------------|-------------------|----------------|

- | `@retry` (tenacity) | `stop=stop_after_attempt(n)` or `stop=stop_after_delay(n)` | `stop=` absent |

- | `@backoff.on_exception` | `max_tries=n` | `max_tries=` absent |

-

- **HTTP client retry configuration (Python):**

-

- | Library/Pattern | Required parameter | Fail condition |

- |-----------------|-------------------|----------------|

- | `urllib3.Retry(...)` | `total=n` where n > 0 | `total=` absent or `total=0` |

- | `HTTPAdapter(max_retries=Retry(...))` | The `Retry` object must have `total=n` | `total=` absent in the `Retry` object passed to `max_retries=` |

- | `httpx.HTTPTransport(retries=n)` | `retries=n` where n > 0 | `retries=` absent or `retries=0` |

-

- **AWS SDK (Python/boto3):**

-

- | Library/Pattern | Required parameter | Fail condition |

- |-----------------|-------------------|----------------|

- | `Config(retries={...})` (botocore) | `max_attempts` key with value > 1 | `max_attempts` absent, or `max_attempts: 0` or `max_attempts: 1` (no retries) |

-

- > Note: boto3 clients without any explicit `Config(retries=...)` use the SDK default (3 attempts, standard mode) — do **not** flag the absence of retry config as an issue. Only flag when retry config is present but disables retries.

-

- **JavaScript/TypeScript:**

-

- | Library/Pattern | Required parameter | Fail condition |

- |-----------------|-------------------|----------------|

- | `retry(...)` (async-retry) | `retries: n` in options object | `retries:` absent |

- | `pRetry(...)` (p-retry) | `retries: n` in options object | `retries:` absent |

-

- **Custom retry loops (all languages):**

-

- A `while True:` / `while (true)` / `for {}` block that contains a `try/except` (or `try/catch`) with a `continue` or a re-invocation of the same call is a manual retry loop. Apply the same rule as Loop Safety: a bounded counter must be present.

-

- | Pattern to find | Pass condition | Fail condition |

- |-----------------|----------------|----------------|

- | Loop + `try/except` + `continue` | An integer counter is declared before the loop and incremented inside it, with a conditional check against a max | No counter present → ❌ Issue |

-

- **`[HEURISTIC]` Fallback: Unrecognized Retry Patterns**

-

- After applying the pattern tables above, also scan for retry-like behavior that doesn't match any known library or pattern:

- - Any function or decorator containing "retry" in its name not covered by the tables above

- - Any imported module with "retry" in its package name not listed in the tables (e.g. `stamina`, `retry`, `aiohttp_retry`)

- - A loop containing: sleep/delay + exception handling + re-invocation of the same external call, where no counter or max-attempt mechanism is visible

- - Configuration objects with keys like `max_retries`, `retry_count`, `attempts` that may belong to unlisted libraries

-

- If found, flag as ⚠️ Warning: *"Potential retry pattern not matching known libraries — verify retry bounds manually"*

-

- 7. **`[PATTERN]` Tool Registry Consistency**

-

- Apply mechanically:

- 1. Collect all tool names from definition files. A tool name is defined by:

- - `@tool` or `@function_tool` decorator on a function → the function name

- - A dict/object with a `"name":` or `name:` key at the top level of a tools file

- 2. Collect all tool name references from prompt files (`.md`, `.txt`, `prompts.py`). A reference is any backtick-quoted identifier or string that names a capability the agent is told it can use.

- 3. Flag every reference not in the definition list as ❌ Issue (hallucinated tool).

- 4. Flag every defined tool not mentioned in any prompt as ⚠️ Warning (undocumented tool).

- 5. **`[HEURISTIC]` Tools never bound to LLM** — Find where tools are defined (any list, registry, or decorated set of functions intended as agent tools). Then find where the LLM is invoked (the call that sends messages to the model). Check whether the tools are passed to that invocation point. If a tools collection exists but is never connected to the LLM call, flag as ❌ Issue: the LLM has no knowledge of these tools and cannot invoke them — the tool-calling architecture is broken or incomplete.

-

- The connection can take many forms depending on the framework (e.g. a `tools=` argument, a bind method, a plugin registration API, an agent constructor parameter). Do not look for any specific method name — reason about whether the defined tools actually reach the LLM invocation. Example of the broken pattern: tools decorated with `@tool` and collected in `ALL_TOOLS`, but the LLM call never receives `ALL_TOOLS` in any form.

-

- **`[HEURISTIC]` Fallback: Unrecognized Tool Definitions**

-

- After applying the known tool definition patterns above, also scan for tool-like structures that don't match any known format:

- - Any dict/object with both `"description"` and `"parameters"` keys that resembles a tool schema but doesn't match the specific patterns listed

- - Functions with structured docstrings that look like tool descriptions (name, parameter list, return description) but lack a `@tool` decorator

- - Any variable named `tools`, `tool_list`, `available_tools`, `functions`, or similar containing callable references or schema objects

- - Class-based tool patterns (classes with `run()`, `execute()`, or `__call__()` methods that appear to wrap external capabilities)

-

- If found, include in the tool registry count and note: *"Tool detected via heuristic — format not in known pattern table. Verify this is an intended agent tool."*

-

- 8. **`[PATTERN]` Context Size Awareness**

-

- Apply mechanically using the formula: `token_estimate = len(file_content_chars) / 4`

-

- | Content | ⚠️ Warning threshold | ❌ Issue threshold |

- |---------|----------------------|-------------------|

- | System prompt file | > 4,000 tokens | > 8,000 tokens |

- | Single tool description block | > 500 tokens | > 1,000 tokens |

- | All tool descriptions combined | > 2,000 tokens | > 4,000 tokens |

-

- Exclude `skills/` directories from this check (see Step 2).

-

- **`[HEURISTIC]` Fallback: Borderline and Non-Standard Context Sizes**

-

- After applying the mechanical threshold check above, also apply judgment in these cases:

- - When a token estimate falls within 20% of any threshold, flag as ⚠️ Warning: *"Token estimate is approximate (chars/4). Actual token count may differ — consider measuring with a tokenizer if close to limit."*

- - Dynamically assembled prompts (e.g. f-strings, `.format()`, template concatenation) where the final size depends on runtime data — flag as ⚠️ Warning if the static template alone is large, since runtime content will add to it

- - Multiple prompt files that are concatenated or chained together — estimate the combined size, not just individual files

- - Prompt files that include or import other files (e.g. `{% include %}`, `{read_file(...)}`) — note that the effective size may be larger than the single file

-

- If found, flag as ⚠️ Warning with an explanation of why the actual context size may differ from the static estimate.

-

- 9. **`[HEURISTIC]` Explicit Tool Listing**

- - System prompts should list available tools

- - Tool capabilities should be clearly described

-

- *Detection:* Check for tool listing sections (headers like "Available Tools", "You have access to")

-

- For each check, determine:

- - ✅ **Pass** - Code complies with the rule

- - ⚠️ **Warning** - Potential concern worth reviewing

- - ❌ **Issue** - Clear violation that needs fixing

-

- ### Step 3b: Agent Pattern Analysis (if AI agent detected)

-

- If the project appears to be an AI agent (LangGraph, CrewAI, AutoGen, LangChain, or custom), perform additional analysis:

-

- **Framework Detection:**

- - `langgraph` in imports → LangGraph agent

- - `crewai` in imports → CrewAI agent

- - `autogen` in imports → AutoGen agent

- - `langchain` in imports → LangChain agent

- - Custom patterns → Custom agent framework

-

- **Analysis Steps:**

-

- 1. **Build tool registry**

-

- Scan all tool definition files: `tools.py`, `tools.ts`, `tools/*.py`, `tools/*.ts`, and any file whose name or content suggests it defines agent tools. Extract tool names using the patterns below. A name found by **any** pattern counts as a registered tool.

-

- **Python — decorator patterns:**

-

- | Pattern | How to extract name |

- |---------|---------------------|

- | `@tool` (LangChain) on a `def` | Function name immediately below the decorator |

- | `@function_tool` (OpenAI Agents SDK) on a `def` | Function name immediately below the decorator |

- | `@tool(name="...")` with explicit name arg | Use the `name=` argument value, not the function name |

-

- **Python — dict/list patterns:**

- | Pattern | How to extract name |

- |---------|---------------------|

- | `{"type": "function", "function": {"name": "..."}}` (OpenAI function calling) | Value of the `"name"` key inside `"function"` |

- | `{"name": "...", "input_schema": {...}}` (Anthropic tool use) | Value of the top-level `"name"` key |

- | `{"name": "...", "description": "...", "parameters": {...}}` (generic schema) | Value of the top-level `"name"` key |

- | `ToolNode([func1, func2, ...])` (LangGraph) | Each function name in the list — these must already be registered via decorator or schema above |

- | `tools = [func1, func2]` / `TOOLS = [...]` list assigned to a variable | Each identifier in the list — resolve to function names already found by other patterns |

- **TypeScript/JavaScript — patterns:**

- | Pattern | How to extract name |

- |---------|---------------------|

- | `{ type: "function", function: { name: "..." } }` (OpenAI) | Value of `name:` inside `function:` |

- | `tool({ description: "...", parameters: z.object({...}) })` assigned to a `const name =` (Vercel AI SDK) | The `const` variable name |

- | `new DynamicTool({ name: "...", ... })` (LangChain.js) | Value of `name:` |

- | `zodFunction({ name: "...", ... })` | Value of `name:` |

- After collecting all names, note the total count and source format for the report.

- 2. **Analyze agent loops**

- - Find main execution loops

- - Check for termination conditions (break, return, max iterations)

- - Verify retry limits on all retry mechanisms

- 3. **Analyze prompts**

- - Measure prompt sizes (estimate tokens)

- - Check for tool listings in system prompts

- - Verify tool references against registry

- - **Exclude `skills/` directories** — files under `skills/` (e.g. `SKILL.md`) are skill definitions loaded on demand, not static system prompts. Do not flag them for context size.

- 4. **Cross-reference**

- - Tools in prompts vs registry (flag mismatches)

- - State fields vs usage

- - Config vs implementation

- 5. **LangGraph graph cycle analysis** *(only when LangGraph is detected)*

- LangGraph agents define control flow as a directed graph of nodes and edges, not `while` loops. A cycle in the graph is intentional (the agent loops between "agent" and "tools" nodes), but **every cycle must have at least one conditional edge that can route to `END`**. A cycle with no reachable `END` is an infinite loop at the graph level.

- **Detection steps:**

- a. Find the graph file (`graph.py`, `graph.ts`, or file containing `StateGraph`/`MessageGraph`)

- b. Build an edge map by scanning for:

- - `workflow.add_edge(source, dest)` — unconditional edge

- - `workflow.add_conditional_edges(source, fn, mapping)` — conditional edges; extract all destination values from the mapping dict

- c. Identify cycles: find any node that is reachable from itself by following edges

- d. For each cycle, check if `END` (or `"__end__"`) is reachable from any node in the cycle via a conditional edge mapping

- e. Flag accordingly:

- | Condition | Severity |

- |-----------|----------|

- | Cycle exists, `END` reachable via conditional edge | ✅ Pass |

- | Cycle exists, no path to `END` from any node in cycle | ❌ Issue |

- | Graph has no `END` node at all | ❌ Issue |

- | Node has no outgoing edges and is not `END` | ⚠️ Warning (dead-end node) |

- **Example — infinite cycle (❌ Issue):**

- ```python

- workflow.add_edge("agent", "tools")

- workflow.add_edge("tools", "agent") # cycle, but no path to END

- ```

- **Example — cycle with exit (✅ Pass):**

- ```python

- workflow.add_conditional_edges("agent", should_continue, {

- "continue": "tools",

- "end": END # END is reachable → cycle is safe

- })

- workflow.add_edge("tools", "agent")

- ```

- **Note:** The check inspects the *static structure* of `add_edge` / `add_conditional_edges` calls. It does not evaluate the routing function itself (`should_continue`) — that is runtime behaviour. If the mapping dict contains `END` as a possible destination, the check passes.

- **`[HEURISTIC]` Fallback: Unrecognized Graph and State Machine Patterns**

- After applying LangGraph-specific edge parsing above, also scan for graph-like control flow structures in other frameworks or custom implementations:

- - State machine definitions with transition tables or dispatch dicts (e.g. `transitions` library, custom `state_map = {"state_a": handler_a, ...}`)

- - Custom routing logic where nodes call other nodes based on conditions, forming implicit cycles

- - LangGraph.js patterns using camelCase methods (`.addNode()`, `.addEdge()`, `.addConditionalEdges()`) — apply the same cycle analysis

- - CrewAI, AutoGen, or other multi-agent frameworks where agents hand off to each other in a potentially circular pattern

- - Any adjacency list, dict-of-lists, or graph object that defines node connections with no clear termination path

- If a cycle is detected with no visible termination condition, flag as ⚠️ Warning: *"Potential cyclic control flow detected in non-LangGraph graph structure — verify that a termination condition exists"*

- **Example findings:**

- ```markdown

- ### ⚠️ Warnings

- - Potential infinite loop: `agent/loop.py:45`

- - **Pattern:** `while True:` without visible break condition

- - **Suggestion:** Add explicit max iteration counter: `for i in range(MAX_ITERATIONS):`

- - Large system prompt: `prompts/system.md`

- - **Size:** ~6,200 tokens (estimated)

- - **Threshold:** 4,000 tokens (warning)

- - **Risk:** May cause context overflow with long conversations

- - **Suggestion:** Consider splitting into base prompt + dynamic sections

- ### ❌ Issues

- - Missing retry limit: `tools/api_client.py:23`

- - **Pattern:** `@retry` decorator without `stop` parameter

- - **Rule:** All retry mechanisms must have explicit bounds

- - **Fix:** Add `@retry(stop=stop_after_attempt(3))` or use `tenacity.stop_after_attempt(3)`

- - Hallucinated tool reference: `prompts/system.md:34`

- - **Reference:** `execute_sql_query`

- - **Available tools:** search_docs, write_file, run_tests

- - **Rule:** Tool references must match registered tools

- - **Fix:** Either add tool definition or remove reference from prompt

- ```

- ### Step 4: Generate Report

- Output a structured verification report with agent-specific sections when applicable:

- # Verification Report

- **Agent type detected:** [LangGraph | CrewAI | AutoGen | LangChain | Custom | None]

- | Code Quality | X | X | X |

- | Agent Patterns | X | X | X |

- ## Agent Pattern Analysis

- *(Include this section only when Agent type detected ≠ None)*

- - [x] All retry mechanisms have explicit limits

- - [ ] ❌ Y hallucinated tool references in prompts

- - [ ] ❌ `[H]` Tools defined but never connected to LLM invocation — LLM cannot invoke tools

- - [ ] ⚠️ Z tools not documented in system prompt

- ### Context Management

- - [ ] ⚠️ System prompt exceeds recommended size (~X tokens)

- - [x] Tool descriptions within limits

- ## Findings

- - `[P]` [Check name]: [Brief confirmation of compliance]

- - `[P|H]` [Check name]: [Description of concern]

- - **Location:** [file:line if applicable]

- - `[P|H]` [Check name]: [Description of violation]

- *(Generic recommendations for all projects)*

-

- 1. [Priority recommendation based on findings]

- 2. [Additional improvements]

-

- ## Agent-Specific Recommendations

- *(Include this section only when Agent type detected ≠ None)*

- 1. **Loop Safety:** [Add iteration limits / Add retry bounds]

- 2. **Tool Registry:** [Remove or define hallucinated tools]

- 3. **Context Management:** [Split large prompts / Add tool documentation]

- ### Step 5: Export Report (Optional)

- 2. Generate filename with **actual current timestamp** (not zeros):

- ```

- reports/verification/YYYY-MM-DD_HH-MM-SS.md

- ```

- **Example:** `reports/verification/2026-03-04_16-48-21.md`

- Use the current time from the system, not placeholder values.

- The format is: `{year}-{month}-{day}_{hour}-{minute}-{second}.md`

- - **Respect tier discipline:** `[PATTERN]` checks must be applied exactly as specified — do not use judgment to pass something the rule says should fail. `[HEURISTIC]` checks require judgment — apply them thoughtfully and mark findings clearly so the reader understands the confidence level.