module Shards::ClaudeConfig

Defined in:

mcp/claude_config.cr

Constant Summary

AGENT_COMPLIANCE_CHECKER = "---\nname: compliance-checker\ndescription: Specialized agent for running comprehensive compliance analysis on Crystal projects. Delegates to this agent when the user asks for a full compliance audit, security review, or pre-release check.\ntools: Bash, Read, Grep, Write\nmodel: sonnet\nmaxTurns: 15\n---\n\n# Compliance Checker Agent\n\nYou are a supply-chain compliance specialist for Crystal projects using shards-alpha. Your job is to run a comprehensive compliance analysis and produce a clear, actionable report.\n\n## Procedure\n\n### Step 1: Verify Project Setup\n\nCheck that `shard.yml` and `shard.lock` exist. If `shard.lock` is missing, run `shards-alpha install`.\n\n### Step 2: Run Vulnerability Audit\n\n```sh\nshards-alpha audit --format=json\n```\n\nRecord total vulnerabilities and breakdown by severity.\n\n### Step 3: Run License Scan\n\n```sh\nshards-alpha licenses --format=json --detect\n```\n\nRecord dependencies with valid SPDX licenses, missing licenses, and copyleft concerns.\n\n### Step 4: Run Policy Check\n\nIf `.shards-policy.yml` exists:\n\n```sh\nshards-alpha policy check --format=json\n```\n\nRecord errors and warnings. If no policy file exists, note the gap.\n\n### Step 5: Generate Compliance Report\n\nCompile findings into:\n\n**Executive Summary**\n- Overall status: PASS, ACTION_REQUIRED, or FAIL\n- Total dependency count\n\n**Vulnerability Findings**\n- List each vulnerability grouped by severity (critical first)\n\n**License Compliance**\n- List all dependencies with their licenses\n- Flag missing or problematic licenses\n\n**Policy Compliance**\n- List violations with remediation steps\n\n**Remediation Steps**\n- Specific version bumps for vulnerable dependencies\n- License additions for unlicensed dependencies\n- Policy file changes for violations\n\n### Step 6: Offer Additional Actions\n\n- Generate formal report: `shards-alpha compliance-report --format=html`\n- Generate SBOM: `shards-alpha sbom`\n- Create policy: `shards-alpha policy init`\n- View changes: `shards-alpha diff`\n\n## Important Notes\n\n- Run all commands from the project root.\n- Present findings in order of severity (most critical first).\n- Be specific in remediation advice."

AGENT_SECURITY_REVIEWER = "---\nname: security-reviewer\ndescription: Security-focused agent that analyzes dependencies for vulnerabilities and recommends patches. Delegates to this when the user asks about security posture or vulnerability remediation.\ntools: Bash, Read, Grep\nmodel: sonnet\nmaxTurns: 10\n---\n\n# Security Reviewer Agent\n\nYou are a dependency security analyst for Crystal projects using shards-alpha. Your focus is identifying vulnerabilities, prioritizing them by risk, and recommending specific remediation actions.\n\n## Procedure\n\n### Step 1: Run Vulnerability Audit\n\n```sh\nshards-alpha audit --format=json\n```\n\nIf exit code 0, report clean. If exit code 1, continue analysis.\n\n### Step 2: Categorize Results\n\nFor each vulnerability, extract: advisory ID, affected dependency, severity, summary, affected version range, fixed version. Group by severity (critical first).\n\n### Step 3: Prioritize by Risk\n\n1. **Critical** — Remote code execution, data exfiltration. Immediate action.\n2. **High** — Privilege escalation, auth bypass. Fix within days.\n3. **Medium** — Limited impact. Fix within a sprint.\n4. **Low** — Informational. Track and fix at convenience.\n\n### Step 4: Research Remediation\n\nCheck `shard.yml` for current version constraints. For each vulnerability determine the minimum fixing version.\n\n### Step 5: Recommend Fixes\n\n**Version Bump**: State the exact version constraint change needed.\n\n**Ignore with Justification**: If not applicable, recommend adding to `.shards-audit-ignore` with reason and 90-day expiry.\n\n**Dependency Replacement**: If unmaintained, recommend alternatives.\n\n### Step 6: Security Summary\n\n**Security Posture: [CLEAN | AT RISK | CRITICAL]**\n\nPresent: findings table, recommended shard.yml changes, ignore recommendations.\n\n## Important Notes\n\n- Never recommend ignoring critical/high vulnerabilities without strong justification.\n- Check if fixes introduce breaking changes before recommending major version bumps.\n- Present findings factually. Do not downplay security risks."

CLAUDE_MD = "# Shards-Alpha: Supply Chain Compliance for Crystal\n\nThis project uses shards-alpha, a Crystal package manager with built-in supply chain compliance tools.\n\n## Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `shards-alpha install` | Install dependencies from shard.yml |\n| `shards-alpha update` | Update dependencies to latest compatible versions |\n| `shards-alpha audit` | Scan dependencies for known vulnerabilities (OSV database) |\n| `shards-alpha licenses` | List dependency licenses with SPDX compliance checking |\n| `shards-alpha policy check` | Check dependencies against policy rules |\n| `shards-alpha diff` | Show dependency changes between lockfile states |\n| `shards-alpha compliance-report` | Generate unified compliance report |\n| `shards-alpha sbom` | Generate Software Bill of Materials (SPDX/CycloneDX) |\n\n## Quick Compliance Check\n\n```sh\nshards-alpha audit # Check for vulnerabilities\nshards-alpha licenses --check # Verify license compliance\nshards-alpha policy check # Enforce dependency policies\n```\n\n## Key Files\n\n| File | Purpose |\n|------|---------|\n| `shard.yml` | Dependency specification |\n| `shard.lock` | Locked dependency versions |\n| `.shards-policy.yml` | Dependency policy rules (optional) |\n| `.shards-audit-ignore` | Suppressed vulnerability IDs (optional) |\n\n## MCP Compliance Server\n\nAn MCP server exposes all compliance tools for AI agent integration:\n\n```sh\nshards-alpha mcp-server # Start stdio MCP server\nshards-alpha mcp-server --interactive # Manual testing mode\n```\n\nSupports MCP protocol versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05."

FILES = {".claude/CLAUDE.md" => CLAUDE_MD, ".claude/settings.json" => SETTINGS_JSON, ".claude/skills/audit/SKILL.md" => SKILL_AUDIT, ".claude/skills/licenses/SKILL.md" => SKILL_LICENSES, ".claude/skills/policy-check/SKILL.md" => SKILL_POLICY_CHECK, ".claude/skills/diff-deps/SKILL.md" => SKILL_DIFF_DEPS, ".claude/skills/compliance-report/SKILL.md" => SKILL_COMPLIANCE_REPORT, ".claude/skills/sbom/SKILL.md" => SKILL_SBOM, ".claude/skills/shards-cli/SKILL.md" => SKILL_SHARDS_CLI, ".claude/skills/shards-cli/reference/commands.md" => REF_COMMANDS, ".claude/skills/shards-cli/reference/shard-yml-format.md" => REF_SHARD_YML, ".claude/skills/shards-cli/reference/ai-docs-guide.md" => REF_AI_DOCS, ".claude/agents/compliance-checker.md" => AGENT_COMPLIANCE_CHECKER, ".claude/agents/security-reviewer.md" => AGENT_SECURITY_REVIEWER}

REF_AI_DOCS = "# AI Documentation Distribution Guide\n\n## Overview\n\nShards can distribute AI coding agent documentation alongside library code. When you run `shards install`, AI docs from dependencies are automatically installed into your project's `.claude/` directory.\n\n## How It Works\n\nShards automatically detects these locations in dependencies:\n\n| Source in shard | What it is |\n|-----------------|------------|\n| `.claude/skills/<name>/` | Claude Code skills |\n| `.claude/agents/<name>.md` | Agent definitions |\n| `CLAUDE.md` | General AI context |\n| `.mcp.json` | MCP server configs |\n\nFiles are namespaced by shard name to avoid conflicts:\n\n| Source | Destination |\n|--------|-------------|\n| `.claude/skills/<name>/` | `.claude/skills/<shard>--<name>/` |\n| `.claude/agents/<name>.md` | `.claude/agents/<shard>--<name>.md` |\n| `CLAUDE.md` | `.claude/skills/<shard>--docs/SKILL.md` |\n| `.mcp.json` | Merged into `.mcp-shards.json` |\n\n## Publishing AI Docs\n\nCreate `.claude/skills/` in your shard with `SKILL.md` files containing YAML frontmatter:\n\n```markdown\n---\nname: getting-started\ndescription: How to get started with your_shard\nuser-invocable: false\n---\n# Getting Started\n...\n```\n\nOr simply add a `CLAUDE.md` at your shard root for basic documentation.\n\n## User Customization\n\n- **Unmodified files**: Auto-updated on `shards update`\n- **Modified files**: Preserved on update\n- **View changes**: `shards ai-docs diff <shard>`\n- **Reset to upstream**: `shards ai-docs reset <shard>`"

REF_COMMANDS = "# Shards CLI Commands Reference\n\n## shards install\n\nInstall dependencies from `shard.yml`. Creates `shard.lock` if it doesn't exist.\n\n```\nshards install [options]\n```\n\n## shards update\n\nUpdate dependencies to latest compatible versions.\n\n```\nshards update [shard_names...] [options]\n```\n\n## shards build\n\nBuild targets defined in `shard.yml`.\n\n```\nshards build [targets...] [-- build_options...]\n```\n\n## shards check\n\nVerify all dependencies are installed and match `shard.lock`.\n\n## shards list\n\nList installed dependencies.\n\n```\nshards list [--tree]\n```\n\n## shards lock\n\nLock dependencies without installing.\n\n```\nshards lock [--print] [--update [shards...]]\n```\n\n## shards outdated\n\nShow outdated dependencies.\n\n```\nshards outdated [--pre]\n```\n\n## shards prune\n\nRemove unused dependencies from `lib/`.\n\n## shards init\n\nGenerate a new `shard.yml`.\n\n## shards version\n\nPrint the shard version from `shard.yml`.\n\n```\nshards version [path]\n```\n\n## shards audit\n\nScan dependencies for known vulnerabilities via OSV database.\n\n```\nshards audit [--severity=LEVEL] [--format=FORMAT] [--fail-above=LEVEL] [--offline]\n```\n\n## shards licenses\n\nList dependency licenses with SPDX validation.\n\n```\nshards licenses [--check] [--detect] [--format=FORMAT] [--include-dev]\n```\n\n## shards policy\n\nManage dependency policies.\n\n```\nshards policy check [--strict] [--format=FORMAT]\nshards policy init\nshards policy show\n```\n\n## shards diff\n\nShow dependency changes between lockfile states.\n\n```\nshards diff [--from=REF] [--to=REF] [--format=FORMAT]\n```\n\n## shards compliance-report\n\nGenerate unified compliance report.\n\n```\nshards compliance-report [--format=FORMAT] [--sections=LIST] [--reviewer=EMAIL]\n```\n\n## shards sbom\n\nGenerate Software Bill of Materials.\n\n```\nshards sbom [--format=spdx|cyclonedx] [--output=FILE] [--include-dev]\n```\n\n## shards mcp-server\n\nStart MCP compliance server for AI agent integration.\n\n```\nshards mcp-server # Start stdio server\nshards mcp-server --interactive # Interactive testing mode\nshards mcp-server init # Configure .mcp.json and .claude/\nshards mcp-server --help # Show help\n```"

REF_SHARD_YML = "# shard.yml Format Reference\n\n## Required Fields\n\n```yaml\nname: my_shard # Shard name\nversion: 1.0.0 # Semantic version\n```\n\n## Optional Fields\n\n```yaml\ndescription: My shard description\nauthors:\n - Author Name <email@example.com>\ncrystal: \">= 1.0.0, < 2.0.0\"\nlicense: MIT\nrepository: https://github.com/user/repo\n```\n\n## Dependencies\n\n```yaml\ndependencies:\n kemal:\n github: kemalcr/kemal\n version: ~> 1.0\n\n my_lib:\n git: https://example.com/repo.git\n branch: main\n\n local_dep:\n path: ../local_dep\n\ndevelopment_dependencies:\n ameba:\n github: crystal-ameba/ameba\n```\n\n### Dependency Sources\n\n| Key | Description |\n|-----|-------------|\n| `github: user/repo` | GitHub repository |\n| `gitlab: user/repo` | GitLab repository |\n| `bitbucket: user/repo` | Bitbucket repository |\n| `git: <url>` | Any git repository URL |\n| `path: <path>` | Local path dependency |\n\n### Version Constraints\n\n| Pattern | Meaning |\n|---------|---------|\n| `~> 1.0` | >= 1.0.0, < 2.0.0 |\n| `~> 1.0.3` | >= 1.0.3, < 1.1.0 |\n| `>= 1.0, < 2.0` | Range |\n| `1.0.0` | Exact version |\n\n## Build Targets\n\n```yaml\ntargets:\n my_app:\n main: src/my_app.cr\n```\n\n## Scripts\n\n```yaml\nscripts:\n postinstall: make ext\n```"

SETTINGS_JSON = "{\n \"permissions\": {\n \"allow\": [\n \"Bash(shards-alpha audit *)\",\n \"Bash(shards-alpha licenses *)\",\n \"Bash(shards-alpha policy *)\",\n \"Bash(shards-alpha diff *)\",\n \"Bash(shards-alpha compliance-report *)\",\n \"Bash(shards-alpha sbom *)\",\n \"Bash(shards-alpha mcp-server *)\",\n \"Bash(crystal build *)\",\n \"Bash(crystal spec *)\",\n \"Bash(crystal tool format *)\"\n ]\n }\n}"

SKILL_AUDIT = "---\nname: audit\ndescription: Scan project dependencies for known security vulnerabilities using the OSV database. Use when reviewing dependencies for security issues.\nallowed-tools: Bash, Read, Grep\nuser-invocable: true\nargument-hint: [--severity=high] [--offline]\n---\n\n# Audit Dependencies for Vulnerabilities\n\nRun a vulnerability scan against all locked dependencies using the OSV database.\n\n## Steps\n\n1. Verify that `shard.lock` exists in the project root. If it does not, inform the user they need to run `shards-alpha install` first.\n\n2. Run the audit command with the user's requested options:\n ```sh\n shards-alpha audit [OPTIONS]\n ```\n\n Common options to pass through from user arguments:\n - `--severity=LEVEL` — Filter results to only show vulnerabilities at or above this severity (low, medium, high, critical)\n - `--format=FORMAT` — Output format: `terminal` (default), `json`, `sarif`\n - `--fail-above=LEVEL` — Only exit non-zero for vulnerabilities at or above this severity\n - `--ignore=ID[,ID]` — Comma-separated advisory IDs to suppress\n - `--ignore-file=PATH` — Path to ignore file (default: `.shards-audit-ignore`)\n - `--offline` — Use cached vulnerability data only, no network requests\n - `--update-db` — Force a cache refresh before scanning\n\n3. Interpret the exit code:\n - Exit 0: No vulnerabilities found (or all filtered/ignored). Report this as a clean scan.\n - Exit 1: Vulnerabilities found matching the severity threshold.\n\n4. If vulnerabilities are found, summarize the results:\n - Group findings by severity (critical, high, medium, low)\n - For each vulnerability, report: advisory ID, affected dependency, affected versions, severity, and summary\n - Highlight any critical or high severity issues first\n\n5. Provide remediation advice:\n - Check if newer versions of affected dependencies are available that fix the vulnerability\n - Suggest specific version bumps in `shard.yml` where applicable\n - If a vulnerability cannot be fixed by upgrading, suggest adding it to `.shards-audit-ignore` with a reason and expiry date\n - Mention the `--fail-above` flag for CI pipelines that should only block on critical issues\n\n6. For JSON output (`--format=json`), parse the structured data to provide a more detailed breakdown. For SARIF output (`--format=sarif`), note that this is designed for GitHub Code Scanning integration.\n\n## Example Invocations\n\n```sh\n# Basic scan\nshards-alpha audit\n\n# Only show high and critical vulnerabilities\nshards-alpha audit --severity=high\n\n# CI-friendly: fail only on critical, output SARIF for GitHub\nshards-alpha audit --format=sarif --fail-above=critical\n\n# Offline scan with cached data\nshards-alpha audit --offline\n```"

SKILL_COMPLIANCE_REPORT = "---\nname: compliance-report\ndescription: Generate comprehensive supply-chain compliance reports. Use before releases or for audit documentation.\nallowed-tools: Bash, Read, Grep, Write\nuser-invocable: true\nargument-hint: [--sections=sbom,audit,licenses] [--reviewer=email]\n---\n\n# Generate Supply-Chain Compliance Report\n\nProduce a unified compliance report combining SBOM, vulnerability audit, license compliance, policy evaluation, integrity verification, and change history into a single document suitable for SOC2 and ISO 27001 auditors.\n\n## Steps\n\n1. Verify prerequisites:\n - `shard.yml` must exist in the project root\n - `shard.lock` must exist (run `shards-alpha install` if missing)\n - For policy sections, `.shards-policy.yml` should exist (optional but recommended)\n\n2. Run the compliance report command with the user's requested options:\n ```sh\n shards-alpha compliance-report [OPTIONS]\n ```\n\n Available options:\n - `--format=FORMAT` — Output format: `json` (default), `html`, `markdown`\n - `--output=PATH` — Output file path (default: `{project}-compliance-report.{ext}`)\n - `--sections=LIST` — Comma-separated sections to include (default: `all`)\n - `--reviewer=EMAIL` — Add reviewer attestation with timestamp to the report\n - `--since=DATE` — Filter change history to entries after this date\n - `--sign` — Create a detached GPG signature (`.sig` file)\n\n3. Available sections:\n\n | Section | Description |\n |---------|-------------|\n | `sbom` | SPDX 2.3 dependency inventory |\n | `audit` | OSV vulnerability scan results |\n | `licenses` | License inventory and compliance |\n | `policy` | Policy rule evaluation results |\n | `integrity` | SHA-256 checksum verification |\n | `changelog` | Dependency change history |\n\n4. Interpret the overall status:\n - **PASS** — No vulnerabilities, no policy violations, integrity verified\n - **ACTION_REQUIRED** — Medium-severity findings or warnings present\n - **FAIL** — Critical or high vulnerabilities, or policy/license failures\n\n5. Summarize the report for the user:\n - Overall compliance status\n - Total dependency count (direct and transitive)\n - Vulnerability summary by severity\n - License compliance status\n - Policy evaluation results\n\n## Example Invocations\n\n```sh\n# Full compliance report in HTML for auditors\nshards-alpha compliance-report --format=html --reviewer=security@company.com\n\n# Quick check with just SBOM and integrity sections\nshards-alpha compliance-report --sections=sbom,integrity\n\n# JSON report for CI artifact archival\nshards-alpha compliance-report --output=compliance-report.json\n\n# Markdown report for documentation\nshards-alpha compliance-report --format=markdown\n```"

SKILL_DIFF_DEPS = "---\nname: diff-deps\ndescription: Show dependency changes between lockfile states. Use when reviewing what changed after updates.\nallowed-tools: Bash, Read, Grep\nuser-invocable: true\nargument-hint: [--from=HEAD --to=current]\n---\n\n# Show Dependency Changes Between Lockfile States\n\nCompare two states of shard.lock to see what dependencies were added, removed, or updated.\n\n## Steps\n\n1. Verify that `shard.lock` exists in the project root. If it does not, inform the user there is nothing to diff.\n\n2. Run the diff command with the user's requested options:\n ```sh\n shards-alpha diff [OPTIONS]\n ```\n\n Available options:\n - `--from=REF` — Starting state (default: `HEAD`). Can be a git ref, file path ending in `.lock`, or `current`\n - `--to=REF` — Ending state (default: `current`). Same ref types as `--from`\n - `--format=FORMAT` — Output format: `terminal` (default), `json`, `markdown`\n\n3. Interpret the reference types:\n - `current` — Reads the current `shard.lock` from disk\n - A git ref (`HEAD`, `main`, `v1.0.0`, a commit SHA) — Extracts `shard.lock` from that point in git history via `git show`\n - A file path ending in `.lock` — Reads from an arbitrary lockfile on disk\n\n4. Summarize the changes:\n - **Added dependencies**: New dependencies not present in the \"from\" state. Report name, version, and source.\n - **Removed dependencies**: Dependencies present in \"from\" but absent in \"to\". Report name and previous version.\n - **Updated dependencies**: Dependencies present in both states but with different versions. Report name, old version, new version, and whether it was an upgrade or downgrade.\n - **Unchanged count**: How many dependencies remained the same.\n\n5. Provide context for the changes:\n - For major version bumps, warn about potential breaking changes\n - For added dependencies, note if they are transitive (pulled in by another dependency)\n - For removed dependencies, note if the removal might affect other parts of the project\n\n6. For markdown output (`--format=markdown`), mention this format is useful for including in PR descriptions to document dependency changes.\n\n## Example Invocations\n\n```sh\n# What changed since the last commit?\nshards-alpha diff\n\n# What changed since a release tag?\nshards-alpha diff --from=v1.0.0\n\n# Compare two specific lockfiles\nshards-alpha diff --from=before.lock --to=after.lock\n\n# Generate markdown for a PR description\nshards-alpha diff --from=main --format=markdown\n\n# JSON output for tooling\nshards-alpha diff --format=json\n```"

SKILL_LICENSES = "---\nname: licenses\ndescription: List and check dependency licenses for SPDX compliance. Use when auditing license compatibility or checking policy.\nallowed-tools: Bash, Read, Grep\nuser-invocable: true\nargument-hint: [--check] [--detect]\n---\n\n# List and Check Dependency Licenses\n\nAudit all locked dependency licenses for SPDX compliance and policy conformance.\n\n## Steps\n\n1. Verify that `shard.lock` exists in the project root. If it does not, inform the user they need to run `shards-alpha install` first.\n\n2. Run the licenses command with the user's requested options:\n ```sh\n shards-alpha licenses [OPTIONS]\n ```\n\n Available options to pass through:\n - `--format=FORMAT` — Output format: `terminal` (default), `json`, `csv`, `markdown`\n - `--check` — Exit 1 if any license policy violations are found\n - `--detect` — Use heuristic detection to identify licenses from LICENSE/COPYING files when shard.yml does not declare one\n - `--include-dev` — Include development dependencies in the scan\n - `--policy=PATH` — Path to a license policy YAML file\n\n3. Interpret the output:\n - Each dependency is listed with its name, version, declared license, and SPDX validity status\n - SPDX validation checks against 52 common SPDX identifiers and supports compound expressions (AND, OR, WITH operators)\n\n4. Summarize the findings:\n - Total number of dependencies scanned\n - Count of dependencies with valid SPDX licenses\n - Count of dependencies with missing or invalid licenses\n - Any policy violations if `--check` was used\n\n5. Flag potential issues:\n - Dependencies with no declared license (legal risk for commercial projects)\n - Dependencies with non-standard or unrecognized license identifiers\n - Copyleft licenses (GPL, AGPL) that may be incompatible with proprietary projects\n - If `--detect` was used, note which licenses were detected heuristically vs declared\n\n6. Provide recommendations:\n - For missing licenses, suggest the user contact the dependency maintainer or check the repository directly\n - For policy violations, explain which rule was violated and how to resolve it\n - For CSV or markdown output, note these formats are useful for legal review or PR descriptions\n\n## Example Invocations\n\n```sh\n# Basic license listing\nshards-alpha licenses\n\n# Check against policy, fail on violations\nshards-alpha licenses --check\n\n# Detect licenses from LICENSE files when not declared\nshards-alpha licenses --detect\n\n# Generate CSV for legal team review\nshards-alpha licenses --format=csv\n\n# Full scan including dev dependencies with detection\nshards-alpha licenses --detect --include-dev --format=json\n```"

SKILL_POLICY_CHECK = "---\nname: policy-check\ndescription: Check dependencies against policy rules in .shards-policy.yml. Use when verifying compliance before releases.\nallowed-tools: Bash, Read, Grep, Write\nuser-invocable: true\nargument-hint: [--strict]\n---\n\n# Check Dependencies Against Policy Rules\n\nEvaluate all locked dependencies against the rules defined in `.shards-policy.yml`.\n\n## Steps\n\n1. Check if `.shards-policy.yml` exists in the project root:\n - If it exists, read it to understand the active policy rules before running the check.\n - If it does not exist, ask the user if they want to create one with `shards-alpha policy init`, which generates a starter policy file.\n\n2. Run the policy check with the user's requested options:\n ```sh\n shards-alpha policy check [OPTIONS]\n ```\n\n Available options:\n - `--strict` — Treat warnings as errors (useful for CI gates)\n - `--format=FORMAT` — Output format: `terminal` (default), `json`\n\n Other policy subcommands:\n - `shards-alpha policy init` — Create a starter `.shards-policy.yml`\n - `shards-alpha policy show` — Display a summary of the current policy\n\n3. Interpret the results:\n - **Error violations** block installation: blocked dependencies, denied sources, minimum version failures\n - **Warning violations** are displayed but do not block: missing licenses, postinstall script auditing\n\n4. Summarize the findings:\n - Total rules evaluated\n - Number of errors (blocking violations)\n - Number of warnings (non-blocking violations)\n - List each violation with the dependency name, rule that was violated, and the reason\n\n5. For each violation, suggest a fix:\n - **Blocked dependency**: Remove it from shard.yml or update the policy to allow it with a documented reason\n - **Disallowed source host**: Move the dependency to an allowed host or add the host to `rules.sources.allowed_hosts`\n - **Disallowed organization**: Add the org to `rules.sources.allowed_orgs` for that host\n - **Minimum version failure**: Update the dependency version in shard.yml to meet the minimum\n - **Missing license**: Add a license to the dependency's shard.yml or set `rules.security.require_license: false`\n - **Postinstall script warning**: Review the script for safety, then either allow it or set `rules.security.block_postinstall: true` to block\n\n6. If the user wants to modify the policy, offer to edit `.shards-policy.yml` directly with the needed changes.\n\n## Policy File Structure\n\nThe policy file `.shards-policy.yml` supports these rule categories:\n- `rules.sources` — Allowed hosts, allowed organizations, deny path dependencies\n- `rules.dependencies` — Blocked dependencies with reasons, minimum version requirements\n- `rules.security` — Require licenses, block/audit postinstall scripts\n- `rules.custom` — Regex patterns to allow or block dependency names\n\n## Example Invocations\n\n```sh\n# Basic policy check\nshards-alpha policy check\n\n# Strict mode for CI (warnings become errors)\nshards-alpha policy check --strict\n\n# JSON output for tooling\nshards-alpha policy check --format=json\n\n# Create a starter policy\nshards-alpha policy init\n\n# View current policy summary\nshards-alpha policy show\n```"

SKILL_SBOM = "---\nname: sbom\ndescription: Generate a Software Bill of Materials (SBOM) in SPDX or CycloneDX format. Use for supply-chain transparency.\nallowed-tools: Bash, Read\nuser-invocable: true\nargument-hint: [--format=spdx|cyclonedx]\n---\n\n# Generate Software Bill of Materials (SBOM)\n\nProduce a complete inventory of all project dependencies in an industry-standard SBOM format.\n\n## Steps\n\n1. Verify that `shard.lock` exists in the project root. If it does not, inform the user they need to run `shards-alpha install` first.\n\n2. Run the SBOM generation command:\n ```sh\n shards-alpha sbom [OPTIONS]\n ```\n\n Available options:\n - `--format=FORMAT` — SBOM format: `spdx` (default) or `cyclonedx`\n - `--output=FILE` — Output file path\n - `--include-dev` — Include development dependencies in the SBOM\n\n3. Supported formats:\n\n **SPDX 2.3 (default)**: Linux Foundation standard, required by US EO 14028.\n **CycloneDX 1.6**: OWASP standard focused on security and risk analysis.\n\n4. Summarize the generated SBOM:\n - Total number of components listed\n - Document creation timestamp\n - Output file location\n - Whether dev dependencies were included or excluded\n\n## Example Invocations\n\n```sh\n# Generate SPDX SBOM (default)\nshards-alpha sbom\n\n# Generate CycloneDX SBOM\nshards-alpha sbom --format=cyclonedx\n\n# Custom output path\nshards-alpha sbom --output=artifacts/sbom.spdx.json\n\n# Include development dependencies\nshards-alpha sbom --include-dev\n```"

SKILL_SHARDS_CLI = "---\nname: shards-cli\ndescription: Crystal Shards package manager CLI reference. Provides guidance on shard.yml format, dependency management, installation, building, and AI docs distribution.\nuser-invocable: false\n---\n\n# Crystal Shards CLI\n\nShards is the dependency manager for Crystal. It reads `shard.yml` to resolve, install, and update dependencies from source repositories.\n\n## Common Workflows\n\n### Install dependencies\n```\nshards install # Install from shard.yml, using shard.lock if present\nshards install --production # Frozen + without development dependencies\nshards install --skip-ai-docs # Skip AI documentation installation\n```\n\n### Update dependencies\n```\nshards update # Update all to latest compatible versions\nshards update kemal # Update only kemal\n```\n\n### Build targets\n```\nshards build # Build all targets\nshards build my_app # Build specific target\nshards build --release # Build with --release flag\n```\n\n### Supply chain compliance\n```\nshards audit # Vulnerability scan\nshards licenses # License compliance\nshards policy check # Policy enforcement\nshards diff # Dependency changes\nshards compliance-report # Full compliance report\nshards sbom # Software Bill of Materials\n```\n\n### Other commands\n```\nshards check # Verify all dependencies are installed\nshards list # List installed dependencies\nshards list --tree # List with dependency tree\nshards outdated # Show outdated dependencies\nshards prune # Remove unused dependencies from lib/\nshards version # Print shard version\nshards init # Generate a new shard.yml\n```\n\n## Key Flags\n\n| Flag | Description |\n|------|-------------|\n| `--frozen` | Strictly install locked versions from shard.lock |\n| `--without-development` | Skip development dependencies |\n| `--production` | Same as `--frozen --without-development` |\n| `--skip-postinstall` | Skip postinstall scripts |\n| `--skip-ai-docs` | Skip AI documentation installation |\n| `--jobs=N` | Parallel downloads (default: 8) |\n\n## Reference\n\n- [shard.yml format](reference/shard-yml-format.md)\n- [All CLI commands](reference/commands.md)\n- [AI docs distribution guide](reference/ai-docs-guide.md)"

Class Method Summary

• .install(path : String) : Array(String)

Class Method Detail