@vigolium/piolium 0.0.1

package/skills/spec-to-code-compliance/resources/IR_EXAMPLES.md

@@ -0,0 +1,417 @@
+# Intermediate Representation Examples
+
+The following examples demonstrate the complete IR workflow using realistic DEX swap patterns.
+
+---
+
+## Example 1: Spec-IR Record
+
+**Scenario:** Extracting a security requirement from a DEX protocol whitepaper.
+
+```yaml
+id: SPEC-001
+spec_excerpt: "All swaps MUST enforce maximum slippage of 1% to protect users from sandwich attacks"
+source_section: "Whitepaper §4.1 - Trading Mechanism & User Protection"
+source_document: "dex-protocol-whitepaper-v3.pdf"
+semantic_type: invariant
+normalized_form:
+  type: constraint
+  entity: swap_transaction
+  operation: token_exchange
+  condition: "abs((actual_output - expected_output) / expected_output) <= 0.01"
+  enforcement: MUST (mandatory)
+  rationale: "sandwich_attack_prevention"
+confidence: 1.0
+notes: "Slippage measured as percentage deviation from expected output at transaction submission time"
+```
+
+**What this shows:**
+- Extraction of trading protection requirement with full traceability
+- Normalized form makes slippage calculation explicit and machine-verifiable
+- High confidence (1.0) because requirement is stated explicitly with specific percentage
+- Notes clarify measurement methodology
+
+---
+
+## Example 2: Code-IR Record
+
+**Scenario:** Analyzing the `swap()` function in a DEX router contract.
+
+```yaml
+id: CODE-001
+file: "contracts/Router.sol"
+function: "swap(address tokenIn, address tokenOut, uint256 amountIn, uint256 minAmountOut, uint256 deadline)"
+lines: 89-135
+visibility: external
+modifiers: [nonReentrant, ensure(deadline)]
+
+behavior:
+  preconditions:
+    - condition: "block.timestamp <= deadline"
+      line: 90
+      enforcement: modifier (ensure)
+      purpose: "prevent stale transactions"
+    - condition: "amountIn > 0"
+      line: 92
+      enforcement: require
+    - condition: "minAmountOut > 0"
+      line: 93
+      enforcement: require
+    - condition: "tokenIn != tokenOut"
+      line: 94
+      enforcement: require
+
+  state_reads:
+    - variable: "pairs[tokenIn][tokenOut]"
+      line: 98
+      purpose: "get liquidity pool address"
+    - variable: "reserves[pair]"
+      line: 102
+      purpose: "get current pool reserves"
+    - variable: "feeRate"
+      line: 108
+      purpose: "calculate trading fee"
+
+  state_writes:
+    - variable: "reserves[pair].reserve0"
+      line: 125
+      operation: "update after swap"
+    - variable: "reserves[pair].reserve1"
+      line: 126
+      operation: "update after swap"
+
+  computations:
+    - operation: "amountInWithFee = amountIn * 997"
+      line: 108
+      purpose: "apply 0.3% fee (997/1000)"
+    - operation: "amountOut = (amountInWithFee * reserveOut) / (reserveIn * 1000 + amountInWithFee)"
+      line: 110-111
+      purpose: "constant product formula (x * y = k)"
+    - operation: "slippageCheck = amountOut >= minAmountOut"
+      line: 115
+      purpose: "enforce user-specified minimum output"
+
+  external_calls:
+    - target: "IERC20(tokenIn).transferFrom(msg.sender, pair, amountIn)"
+      line: 118
+      type: "ERC20 transfer"
+      return_handling: "require success"
+    - target: "IERC20(tokenOut).transfer(msg.sender, amountOut)"
+      line: 122
+      type: "ERC20 transfer"
+      return_handling: "require success"
+
+  events:
+    - name: "Swap"
+      line: 130
+      parameters: "msg.sender, tokenIn, tokenOut, amountIn, amountOut"
+
+  postconditions:
+    - "amountOut >= minAmountOut (slippage protection enforced)"
+    - "reserves updated to maintain K=xy invariant"
+    - "tokenIn transferred from user to pool"
+    - "tokenOut transferred from pool to user"
+
+invariants_enforced:
+  - "slippage_protection: amountOut >= minAmountOut (line 115)"
+  - "constant_product: reserveIn * reserveOut >= k_before (line 125-126)"
+  - "fee_application: effective_rate = 0.3% (line 108)"
+```
+
+**What this shows:**
+- Complete DEX swap function analysis with line-level precision
+- Captures AMM constant product formula and fee mechanics
+- Documents slippage protection enforcement at line 115
+- Shows state transitions (reserve updates) and external interactions
+- All claims reference specific line numbers for traceability
+
+---
+
+## Example 3: Alignment Record (Positive Case)
+
+**Scenario:** Verifying that the swap function correctly implements the 0.3% fee requirement.
+
+```yaml
+id: ALIGN-001
+spec_ref: SPEC-002
+code_ref: CODE-001
+
+spec_claim: "Protocol MUST charge exactly 0.3% fee on all swaps"
+spec_source: "Whitepaper §4.2 - Fee Structure"
+
+code_behavior: "amountInWithFee = amountIn * 997 (line 108), effective fee = (1000-997)/1000 = 0.3%"
+code_location: "Router.sol:L108"
+
+match_type: full_match
+confidence: 1.0
+
+reasoning: |
+  Spec requires: 0.3% fee on all swaps
+  Code implements: amountIn * 997 / 1000
+
+  Mathematical verification:
+  - Fee deduction: 1000 - 997 = 3
+  - Fee percentage: 3 / 1000 = 0.003 = 0.3% ✓
+
+  The code uses numerator 997 instead of explicit fee subtraction,
+  but this is mathematically equivalent and gas-optimized.
+
+  Enforcement: Fee is applied before price calculation (line 108-111),
+  ensuring it affects the swap output. Cannot be bypassed.
+
+evidence:
+  spec_quote: "The protocol charges a fixed 0.3% fee on the input amount for every swap transaction"
+  spec_location: "Whitepaper §4.2, page 8, paragraph 1"
+  code_quote: "uint256 amountInWithFee = amountIn * 997; // 0.3% fee: (1000-997)/1000"
+  code_location: "Router.sol:L108"
+
+  verification_steps:
+    - "Checked numerator 997 is used consistently"
+    - "Verified denominator 1000 matches in formula at L110-111"
+    - "Confirmed fee applies to all swap paths (no conditional logic)"
+    - "Validated fee is not configurable (hardcoded = guaranteed)"
+
+ambiguity_notes: null
+```
+
+**What this shows:**
+- Successful alignment between spec requirement and code implementation
+- Mathematical proof that 997/1000 = 0.3% fee
+- Reasoning explains WHY implementation is correct (gas optimization via numerator)
+- Evidence provides exact quotes and line numbers
+- High confidence (1.0) due to clear mathematical equivalence
+
+---
+
+## Example 4: Divergence Finding (Critical Issue)
+
+**Scenario:** Identifying that the critical slippage protection requirement is completely missing.
+
+```yaml
+id: DIV-001
+severity: CRITICAL
+title: "Missing slippage protection enables unlimited sandwich attacks"
+
+spec_claim:
+  excerpt: "All swaps MUST enforce maximum slippage of 1% to protect users from sandwich attacks"
+  source: "Whitepaper §4.1 - Trading Mechanism & User Protection"
+  source_location: "Page 7, paragraph 3"
+  semantic_type: security_constraint
+  enforcement_level: MUST (mandatory)
+
+code_finding:
+  file: "contracts/RouterV1.sol"
+  function: "swap(address tokenIn, address tokenOut, uint256 amountIn)"
+  lines: 45-78
+  observation: "Function signature lacks minAmountOut parameter; no slippage validation exists"
+
+match_type: missing_in_code
+confidence: 1.0
+
+reasoning: |
+  Specification Analysis:
+  - Spec explicitly requires: "MUST enforce maximum slippage of 1%"
+  - Requirement scope: "All swaps" (no exceptions)
+  - Purpose stated: "protect users from sandwich attacks"
+
+  Code Analysis:
+  - Function signature: swap(tokenIn, tokenOut, amountIn)
+  - Missing parameter: minAmountOut (required for slippage check)
+  - Line-by-line review of function body (L45-L78):
+    * L50-55: Price calculation from reserves
+    * L58-60: Fee deduction (0.3%)
+    * L62-65: Output amount calculation
+    * L68: Transfer tokenIn from user
+    * L72: Transfer tokenOut to user
+    * L75: Emit Swap event
+  - NO slippage validation found anywhere in function
+
+  Gap: Spec requires slippage protection → Code provides zero protection
+
+  Additional verification:
+  - Searched entire RouterV1.sol for "slippage", "minAmount", "minOutput": 0 results
+  - Checked if validation exists in called functions: None found
+  - Verified no modifiers perform slippage check: Confirmed absent
+
+evidence:
+  spec_evidence:
+    quote: "To protect users from front-running and sandwich attacks, all swap operations MUST enforce a maximum slippage of 1% between the expected and actual output amounts"
+    location: "Whitepaper §4.1, page 7, paragraph 3"
+    emphasis: "MUST" indicates mandatory requirement
+
+  code_evidence:
+    function_signature: "function swap(address tokenIn, address tokenOut, uint256 amountIn) external"
+    signature_location: "RouterV1.sol:L45"
+    missing_parameter: "uint256 minAmountOut"
+
+    function_body_summary: |
+      L50: uint256 amountOut = calculateSwapOutput(tokenIn, tokenOut, amountIn);
+      L68: IERC20(tokenIn).transferFrom(msg.sender, pair, amountIn);
+      L72: IERC20(tokenOut).transfer(msg.sender, amountOut);
+
+      CRITICAL ISSUE: No validation that amountOut meets user expectations
+
+    search_results:
+      - pattern: "minAmountOut" → 0 occurrences in RouterV1.sol
+      - pattern: "slippage" → 0 occurrences in RouterV1.sol
+      - pattern: "require.*amountOut" → 0 occurrences in RouterV1.sol
+      - pattern: "amountOut >=" → 0 occurrences in RouterV1.sol
+
+exploitability: |
+  Attack Vector: Classic Sandwich Attack
+
+  Prerequisites:
+  - Attacker monitors public mempool for pending swap transactions
+  - Attacker has capital to move market price (typically 10-50x target trade size)
+  - Target trade is on-chain (not private mempool)
+
+  Attack Sequence:
+
+  1. Detection Phase
+     - Victim submits swap: 100 ETH → USDC
+     - Expected output at current price: 200,000 USDC (price = $2,000/ETH)
+     - Transaction appears in mempool with no slippage protection
+
+  2. Front-Run Transaction
+     - Attacker submits swap: 500 ETH → USDC (higher gas to execute first)
+     - Large buy moves price: $2,000 → $2,100 (+5%)
+     - Pool reserves now imbalanced
+
+  3. Victim Transaction Executes
+     - Victim's 100 ETH swap executes at manipulated price
+     - Actual output: 195,122 USDC (effective price $1,951/ETH)
+     - Victim loses: 4,878 USDC vs expected 200,000
+     - Loss percentage: 2.4% of trade value
+     - NO PROTECTION: Transaction succeeds despite 2.4% slippage (exceeds 1% spec limit)
+
+  4. Back-Run Transaction
+     - Attacker sells USDC → ETH at inflated price
+     - Profits from price impact: ~$4,500
+     - Price returns toward equilibrium
+
+  Economic Analysis:
+  - Victim trade size: $200,000
+  - Attacker cost: Gas fees (~$50-100)
+  - Attacker profit: ~$4,500 (net ~$4,400)
+  - Victim loss: $4,878 (2.4% slippage)
+  - Attack ROI: 4400% in single block
+
+  Impact Scale:
+  - Per transaction: $500 - $10,000 extractable (depending on trade size)
+  - Daily volume: $10M → potential $100K-500K daily extraction
+  - Unlimited because: No slippage check = no upper bound on extraction
+
+  Real-World Precedent:
+  - SushiSwap (2020): Suffered sandwich attacks before slippage protection
+  - Average loss per victim: 1-5% of trade value
+  - Specification exists specifically to prevent this attack class
+
+remediation:
+  immediate_fix: |
+    Add minAmountOut parameter and enforce slippage protection:
+
+    ```solidity
+    function swap(
+        address tokenIn,
+        address tokenOut,
+        uint256 amountIn,
+        uint256 minAmountOut,  // NEW: User-specified minimum output
+        uint256 deadline        // NEW: Prevent stale transactions
+    ) external ensure(deadline) nonReentrant {
+        require(amountIn > 0, "Invalid input amount");
+        require(minAmountOut > 0, "Invalid minimum output");  // NEW
+
+        // Existing price calculation
+        uint256 amountOut = calculateSwapOutput(tokenIn, tokenOut, amountIn);
+
+        // NEW: Enforce slippage protection
+        require(amountOut >= minAmountOut, "Slippage exceeded");
+
+        // Rest of swap logic...
+    }
+    ```
+
+    This allows users to specify maximum acceptable slippage:
+    - User calculates expected output: 200,000 USDC
+    - User sets minAmountOut: 198,000 USDC (1% slippage tolerance)
+    - Sandwich attack moves price 2.4% → transaction reverts
+    - User protected from excessive value extraction
+
+  long_term_improvements: |
+    1. Add helper function for slippage calculation:
+       ```solidity
+       function calculateMinOutput(
+           uint256 expectedOutput,
+           uint256 slippageBps  // basis points, e.g., 100 = 1%
+       ) public pure returns (uint256) {
+           return expectedOutput * (10000 - slippageBps) / 10000;
+       }
+       ```
+
+    2. Implement deadline parameter (as shown in immediate fix)
+       - Prevents stale transactions from executing at unexpected prices
+       - Standard in Uniswap V2/V3
+
+    3. Add price impact warnings in UI:
+       - Show estimated price impact before transaction
+       - Warn if impact exceeds 1% (spec threshold)
+       - Suggest splitting large trades
+
+    4. Consider TWAP (Time-Weighted Average Price) validation:
+       - Compare spot price vs 30-min TWAP
+       - Reject if deviation exceeds threshold
+       - Prevents oracle manipulation attacks
+
+    5. Add events for slippage monitoring:
+       ```solidity
+       event SlippageApplied(
+           address indexed user,
+           uint256 expectedOutput,
+           uint256 actualOutput,
+           uint256 slippageBps
+       );
+       ```
+
+  testing_requirements: |
+    1. Unit test: Swap with 0.5% slippage succeeds
+    2. Unit test: Swap with 1.5% slippage reverts
+    3. Integration test: Simulate sandwich attack, verify protection
+    4. Fuzz test: Random minAmountOut values, verify correct revert behavior
+    5. Mainnet fork test: Replay historical sandwich attacks, verify prevention
+
+  breaking_changes: |
+    YES - This is a breaking change to the swap() function signature.
+
+    Migration path:
+    1. Deploy RouterV2 with new signature
+    2. Update frontend to calculate and pass minAmountOut
+    3. Deprecate RouterV1 after 30-day migration period
+    4. Add wrapper function in RouterV1 for backward compatibility:
+       ```solidity
+       function swapLegacy(address tokenIn, address tokenOut, uint256 amountIn) external {
+           uint256 expectedOutput = getExpectedOutput(tokenIn, tokenOut, amountIn);
+           uint256 minOutput = expectedOutput * 99 / 100;  // 1% default slippage
+           swap(tokenIn, tokenOut, amountIn, minOutput, block.timestamp + 300);
+       }
+       ```
+
+  specification_update: |
+    If slippage protection is intentionally omitted (NOT recommended):
+
+    Update whitepaper §4.1 to:
+    "Swaps execute at current market price without slippage protection.
+    Users are responsible for sandwich attack mitigation via:
+    - Private transaction channels (Flashbots, MEV-Blocker)
+    - Off-chain price monitoring and transaction cancellation
+    - External slippage calculation and manual validation
+
+    WARNING: On-chain swaps are vulnerable to MEV extraction."
+```
+
+**What this shows:**
+- Complete divergence finding with CRITICAL severity
+- Evidence-based: Shows exhaustive search for slippage protection (0 results)
+- Detailed exploit scenario with concrete numbers ($200k trade → $4,878 loss)
+- Economic impact quantification (ROI, daily volume, extraction potential)
+- Comprehensive remediation with code examples, testing requirements, migration path
+- Distinguishes between fixing code vs updating spec (if intentional)

package/skills/spec-to-code-compliance/resources/OUTPUT_REQUIREMENTS.md

@@ -0,0 +1,105 @@
+# Output Requirements & Quality Thresholds
+
+When performing spec-to-code compliance analysis, Claude MUST produce structured IR following the formats demonstrated in [IR_EXAMPLES.md](IR_EXAMPLES.md).
+
+---
+
+## Required IR Production
+
+For EACH phase, output MUST include:
+
+### Phase 2 - Spec-IR (mandatory)
+- MUST extract ALL intended behavior into Spec-IR records
+- Each record MUST include: `id`, `spec_excerpt`, `source_section`, `source_document`, `semantic_type`, `normalized_form`, `confidence`
+- MUST use YAML format matching Example 1
+- MUST extract minimum 10 Spec-IR items for any non-trivial specification (5+ pages of documentation)
+- MUST include confidence scores (0-1) for all extractions
+- MUST document both explicit and implicit invariants
+
+### Phase 3 - Code-IR (mandatory)
+- MUST analyze EVERY function with structured extraction
+- Each record MUST include: `id`, `file`, `function`, `lines`, `visibility`, `modifiers`, `behavior` (preconditions, state_reads, state_writes, computations, external_calls, events, postconditions), `invariants_enforced`
+- MUST use YAML format matching Example 2
+- MUST document line numbers for ALL claims (every precondition, state read/write, computation, external call)
+- MUST capture full control flow (all conditional branches, revert paths)
+- MUST identify all external interactions with risk analysis
+
+### Phase 4 - Alignment-IR (mandatory)
+- MUST compare EVERY Spec-IR item against Code-IR
+- Each record MUST include: `id`, `spec_ref`, `code_ref`, `spec_claim`, `code_behavior`, `match_type`, `confidence`, `reasoning`, `evidence`
+- MUST classify using exactly one of: `full_match`, `partial_match`, `mismatch`, `missing_in_code`, `code_stronger_than_spec`, `code_weaker_than_spec`
+- MUST use YAML format matching Example 3
+- MUST provide reasoning trace explaining WHY classification was chosen
+- MUST include evidence with exact quotes and locations from both spec and code
+- Every Spec-IR item MUST have corresponding Alignment record (no gaps)
+
+### Phase 5 - Divergence Findings (when applicable)
+- MUST create detailed finding for EVERY `mismatch`, `missing_in_code`, or `code_weaker_than_spec`
+- Each finding MUST include: `id`, `severity`, `title`, `spec_claim`, `code_finding`, `match_type`, `confidence`, `reasoning`, `evidence`, `exploitability`, `remediation`
+- MUST use YAML format matching Example 4
+- MUST quantify impact with concrete numbers (not "could be exploited" but "attacker gains $X, victim loses $Y")
+- MUST provide exploitability analysis with attack scenarios (prerequisites, sequence, impact)
+- MUST include remediation with code examples and testing requirements
+
+### Phase 6 - Final Report (mandatory)
+- MUST produce structured report following 16-section format defined in Phase 6
+- MUST include all IR artifacts (Spec-IR, Code-IR, Alignment-IR, Divergence Findings)
+- MUST provide Full Alignment Matrix showing all spec→code mappings
+- MUST quantify risk and prioritize remediations
+
+---
+
+## Quality Thresholds
+
+A complete spec-to-code compliance analysis MUST achieve:
+
+### Spec-IR minimum standards:
+- Minimum 10 Spec-IR items for non-trivial specifications
+- At least 3 invariants extracted (explicit or implicit)
+- At least 2 security requirements identified (MUST/NEVER/ALWAYS keywords)
+- At least 1 math formula or economic assumption documented
+- Confidence scores for all extractions (no missing scores)
+
+### Code-IR minimum standards:
+- EVERY public/external function analyzed (no gaps in coverage)
+- Minimum 3 invariants documented per analyzed function
+- ALL external calls identified with return handling documented
+- ALL state modifications tracked (reads and writes)
+- Line number citations for ALL claims (100% traceability)
+
+### Alignment-IR minimum standards:
+- EVERY Spec-IR item has corresponding Alignment record (complete matrix)
+- Reasoning provided for all match_type classifications
+- Evidence includes exact quotes from both spec and code
+- Ambiguities explicitly flagged (never guessed or inferred)
+- Confidence scores reflect actual certainty (not placeholder 1.0 for everything)
+
+### Divergence Finding minimum standards:
+- EVERY CRITICAL/HIGH finding has exploit scenario with concrete attack sequence
+- Economic impact quantified with dollar amounts or percentages
+- Remediation includes code examples (not just "add validation")
+- Testing requirements specified (unit tests, integration tests, fuzz tests)
+- Breaking changes documented with migration path
+
+---
+
+## Format Consistency
+
+- MUST use YAML for all IR records (Spec-IR, Code-IR, Alignment-IR, Divergence)
+- MUST use consistent field names across all records (e.g., `spec_excerpt` not `specification_text`)
+- MUST reference line numbers in format: `L45`, `lines: 89-135`, `line 108`
+- MUST cite spec locations: `"Section §4.1"`, `"Page 7, paragraph 3"`, `"Whitepaper section 2.3"`
+- MUST use markdown code blocks with language tags: ` ```yaml `, ` ```solidity `
+- MUST separate major sections with `---` horizontal rules
+
+---
+
+## Anti-Hallucination Requirements
+
+- NEVER infer behavior not present in spec or code
+- ALWAYS quote exact text (spec_quote, code_quote in evidence)
+- ALWAYS provide line numbers for code claims
+- ALWAYS provide section/page for spec claims
+- If uncertain: Set confidence < 0.8 and document ambiguity
+- If spec is silent: Classify as `UNDOCUMENTED`, never guess
+- If code adds behavior: Classify as `code_stronger_than_spec`, document in Alignment-IR

package/skills/supply-chain-risk-auditor/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: supply-chain-risk-auditor
+description: "Identifies dependencies at heightened risk of exploitation or takeover. Use when assessing supply chain attack surface, evaluating dependency health, or scoping security engagements."
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+# Supply Chain Risk Auditor
+
+Activates when the user says "audit this project's dependencies".
+
+## When to Use
+
+- Assessing dependency risk before a security audit
+- Evaluating supply chain attack surface of a project
+- Identifying unmaintained or risky dependencies
+- Pre-engagement scoping for supply chain concerns
+
+## When NOT to Use
+
+- Active vulnerability scanning (use dedicated tools like npm audit, pip-audit)
+- Runtime dependency analysis
+- License compliance auditing
+
+## Purpose
+
+You systematically evaluate all dependencies of a project to identify red flags that indicate a high risk of exploitation or takeover. You generate a summary report noting these issues.
+
+### Risk Criteria
+
+A dependency is considered high-risk if it features any of the following risk factors:
+
+* **Single maintainer or team of individuals** - The project is primarily or solely maintained by a single individual, or a small number of individuals. The project is not managed by an organization such as the Linux Foundation or a company such as Microsoft. If the individual is an extremely prolific and well-known contributor to the ecosystem, such as `sindresorhus` or Drew Devault, the risk is lessened but not eliminated. Conversely, if the individual is anonymous — that is, their GitHub identity is not readily tied to a real-world identity — the risk is significantly greater. **Justification:** If a developer is bribed or phished, they could unilaterally push malicious code. Consider the left-pad incident.
+* **Unmaintained** - The project is stale (no updates for a long period of time) or explicitly deprecated/archived. The maintainer may have put a note in the README.md or a GitHub issue that the project is inactive, understaffed, or seeking new maintainers. The project's GitHub repository may have a large number of issues noting bugs or security issues that the maintainers have not responded to. Feature request issues do NOT count.  **Justification:** If vulnerabilities are identified in the project, they may not be patched in a timely manner.
+* **Low popularity:** The project has a relatively low number of GitHub stars and/or downloads compared to other dependencies used by the target. **Justification:** Fewer users means fewer eyes on the project. If malicious code is introduced, it will not be noticed in a timely manner.
+* **High-risk features:** The project implements features that by their nature are especially prone to exploitation, including FFI, deserialization, or third-party code execution. **Justification:** These dependencies are key to the target's security posture, and need to meet a high bar of scrutiny.
+* **Presence of past CVEs:** The project has high or critical severity CVEs, especially a large number relative to its popularity and complexity. **Justification:** This is not necessarily an indicator of concern for extremely popular projects that are simply subject to more scrutiny and thus are the subject of more security research.
+* **Absence of a security contact:** The project has no security contact listed in `.github/SECURITY.md`, `CONTRIBUTING.md`, `README.md`, etc., or separately on the project's website (if one exists). **Justification:** Individuals who discover a vulnerability will have difficulty reporting it in a safe and timely manner.
+
+## Prerequisites
+
+Ensure that the `gh` tool is available before continuing. Ask the user to install if it is not found.
+
+## Workflow (Initial Setup)
+
+You achieve your purpose by:
+
+1. Creating a `.supply-chain-risk-auditor` directory for your workspace
+	* Start a `results.md` report file based on `results-template.md` in this directory
+2. Finding all git repositories for direct dependencies.
+3. Normalizing the git repository entries to URLs, i.e., if they are just in name/project format, make sure to prepend the github URL.
+
+## Workflow (Dependency Audit)
+1. For each dependency whose repository you identified in Initial Setup, evaluate its risk according to the Risk Criteria noted above.
+	* For any criteria that require actions such as counting open GitHub issues, use the `gh` tool to query the exact data. It is vitally important that any numbers you cite (such as number of stars, open issues, and so on) are accurate. You may round numbers of issues and stars using ~ notation, e.g. "~4000 stars".
+2. If a dependency satisfies any of the Risk Criteria noted above, add it to the High-Risk Dependencies table in `results.md`, clearly noting your reason for flagging it as high-risk. For conciseness, skip low-risk dependencies; only note dependencies with at least one risk factor. Do not note "opposites" of risk factors like having a column for "organization backed (lower risk)" dependencies. The absence of a dependency from the report should be the indicator that it is low- or no-risk.
+
+## Workflow (Post-Audit)
+1. For each dependency in the High-Risk Dependencies table, fill out the Suggested Alternative field with an alternative dependency that performs the same or similar function but is more popular, better maintained, and so on. Prefer direct successors and drop-in replacements if available. Provide a short justification of your suggestion.
+2. Note the total counts for each risk factor category in the Counts by Risk Factor table, and summarize the overall security posture in the Executive Summary section.
+3. Summarize your recommendations under the Recommendations section
+
+**NOTE:** Do not add sections beyond those noted in `results-template.md`.

package/skills/supply-chain-risk-auditor/resources/results-template.md

@@ -0,0 +1,41 @@
+# Supply Chain Risk Report
+
+---
+
+## Metadata
+
+- **Scan Date**: [YYYY-MM-DD HH:MM:SS]
+- **Project**: [Project Name]
+- **Repositories Scanned**: [X repositories]
+- **Total Dependencies**: [Y dependencies]
+- **Scan Duration**: [Duration]
+
+---
+
+## Executive Summary
+
+### Counts by Risk Factor
+
+| Risk Factor | Dependencies | Total |
+|-------------|--------------|-------|
+| X           | X, Y, Z...   | #     |
+| X           | X, Y, Z...   | #     |
+| X           | X, Y, Z...   | #     |
+| **Total**   | —            | **#** |
+
+### High-Risk Dependencies
+
+The following dependencies have two or more risk factors.
+
+| Dependency Name | Risk Factors | Notes | Suggested Alternative |
+|-----------------|--------------|-------|-----------------------|
+| X               | X, Y, Z      | a short summary of the risk factors | **X** - short justification |
+| X               | X, Y, Z      | a short summary of the risk factors | **X** - short justification |
+| X               | X, Y, Z      | a short summary of the risk factors | **X** - short justification |
+
+## Suggested Alternatives
+
+## Report Generated By
+
+Supply Chain Risk Auditor Skill
+Generated: [YYYY-MM-DD HH:MM:SS]