@qball-inc/the-bulwark 1.0.0

package/skills/anthropic-validator/references/agents-checklist.md

@@ -0,0 +1,131 @@
+# Agents Validation Checklist (Fallback)
+
+This checklist is used when dynamic documentation fetch fails. May be outdated - prefer fetched standards.
+
+**Last Updated**: 2026-01-17
+
+---
+
+## Agent Definition Format
+
+Custom sub-agents are markdown files with YAML frontmatter:
+
+```markdown
+---
+name: agent-name
+description: What this agent does
+model: sonnet
+tools:
+  - Read
+  - Glob
+  - Grep
+skills:
+  - skill-name
+---
+
+# Agent Name
+
+Instructions for the agent...
+```
+
+---
+
+## Frontmatter Requirements
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Agent name, should match filename |
+| `description` | string | What the agent does |
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `model` | string | `haiku`, `sonnet`, or `opus` |
+| `tools` | array | Allowed tools for this agent |
+| `skills` | array | Skills to load |
+
+---
+
+## File Locations
+
+### Lookup Priority (highest to lowest)
+
+1. CLI flag: `--agent agent-name`
+2. Project: `.claude/agents/{name}.md`
+3. User: `~/.claude/agents/{name}.md`
+4. Plugin: `agents/{name}.md` (at plugin root)
+5. Built-in agents
+
+### Invocation
+
+```
+Task tool with subagent_type: "agent-name"
+```
+
+---
+
+## Critical Rules
+
+- [ ] File is markdown with `.md` extension
+- [ ] Frontmatter is valid YAML between `---` markers
+- [ ] `name` field is present
+- [ ] `description` field is present
+- [ ] File is in valid location (see lookup priority)
+
+## High Priority
+
+- [ ] `model` is one of: `haiku`, `sonnet`, `opus`
+- [ ] `tools` contains only valid tool names
+- [ ] `skills` contains only existing skill names
+- [ ] Name matches filename (without `.md`)
+
+## Medium Priority
+
+- [ ] Clear instructions in body
+- [ ] Appropriate model for task complexity
+- [ ] Tools are minimal (principle of least privilege)
+
+## Low Priority
+
+- [ ] Consistent formatting
+- [ ] Example usage documented
+- [ ] Related agents/skills referenced
+
+---
+
+## Valid Tools
+
+Common tools that can be listed in `tools` array:
+
+- `Read` - Read files
+- `Write` - Write files
+- `Edit` - Edit files
+- `Glob` - Find files by pattern
+- `Grep` - Search file contents
+- `Bash` - Execute commands
+- `Task` - Spawn sub-agents (note: sub-agents cannot spawn sub-agents)
+- `WebFetch` - Fetch web content
+- `WebSearch` - Search the web
+
+---
+
+## Common Violations
+
+| Violation | Severity | Remediation |
+|-----------|----------|-------------|
+| Missing frontmatter | Critical | Add `---` markers with YAML |
+| Missing `name` | Critical | Add `name: agent-name` |
+| Missing `description` | Critical | Add `description: ...` |
+| Invalid `model` | High | Use `haiku`, `sonnet`, or `opus` |
+| Invalid tool in `tools` | High | Use valid tool names |
+| Wrong file location | High | Move to valid location |
+| Name/filename mismatch | Medium | Align name with filename |
+
+---
+
+## Sub-Agent Constraints
+
+**Important**: Sub-agents cannot spawn other sub-agents. If your workflow requires sequential agent invocation, use "Main Context Orchestration" pattern where the main Claude context orchestrates agents sequentially.

package/skills/anthropic-validator/references/commands-checklist.md

@@ -0,0 +1,102 @@
+# Commands Validation Checklist (Fallback)
+
+This checklist is used when dynamic documentation fetch fails. May be outdated - prefer fetched standards.
+
+**Last Updated**: 2026-01-17
+
+---
+
+## Commands and Skills Merge
+
+As of Claude Code v2.1.3 (January 2026), **commands and skills are merged**. Skills can be invoked as commands:
+
+```bash
+/skill-name arg1 arg2
+```
+
+---
+
+## Invocation Patterns
+
+### Basic Invocation
+
+```bash
+/my-skill                    # No arguments
+/my-skill path/to/file       # Single argument
+/my-skill arg1 arg2 arg3     # Multiple arguments
+```
+
+### Argument Access
+
+| Variable | Description |
+|----------|-------------|
+| `$ARGUMENTS` | All arguments as single string |
+| `$1`, `$2`, etc. | Positional arguments |
+| `${ENV_VAR}` | Environment variable |
+
+---
+
+## Visibility Control
+
+### user-invocable Field
+
+| Value | Effect |
+|-------|--------|
+| `true` | Skill appears in `/` menu |
+| `false` | Skill hidden from `/` menu |
+| (omitted) | Defaults to `true` |
+
+### When to Hide
+
+Set `user-invocable: false` for:
+- Internal/helper skills
+- Skills only meant for other skills to load
+- Pipeline-stage skills
+
+---
+
+## Critical Rules
+
+- [ ] Skill exists at `skills/{name}/SKILL.md`
+- [ ] Frontmatter is valid YAML
+- [ ] Name is valid (alphanumeric, hyphens)
+
+## High Priority
+
+- [ ] `user-invocable` is boolean if present
+- [ ] Arguments handled correctly in skill body
+- [ ] Clear usage documentation in skill
+
+## Medium Priority
+
+- [ ] Default behavior when no arguments provided
+- [ ] Error handling for invalid arguments
+- [ ] Examples show argument usage
+
+## Low Priority
+
+- [ ] Consistent argument naming
+- [ ] Help text for complex arguments
+
+---
+
+## Common Violations
+
+| Violation | Severity | Remediation |
+|-----------|----------|-------------|
+| Invalid skill name | High | Use alphanumeric and hyphens only |
+| Missing SKILL.md | Critical | Create skill file |
+| Invalid frontmatter | Critical | Fix YAML syntax |
+| Undocumented arguments | Medium | Add usage examples |
+
+---
+
+## Migration from Legacy Commands
+
+If migrating from separate `commands/` directory:
+
+1. Create skill at `skills/{command-name}/SKILL.md`
+2. Move command logic to skill body
+3. Set `user-invocable: true`
+4. Update any references to use `/skill-name` pattern
+5. Remove old command file

package/skills/anthropic-validator/references/hooks-checklist.md

@@ -0,0 +1,151 @@
+# Hooks Validation Checklist (Fallback)
+
+This checklist is used when dynamic documentation fetch fails. May be outdated - prefer fetched standards.
+
+**Last Updated**: 2026-01-17
+
+---
+
+## Hook Types
+
+| Type | Trigger | Use Case |
+|------|---------|----------|
+| `PreToolUse` | Before tool execution | Validation, blocking |
+| `PostToolUse` | After tool execution | Logging, side effects |
+| `SubagentStart` | When subagent spawns | Tracking, setup |
+| `SubagentStop` | When subagent completes | Finalization, cleanup |
+| `Notification` | System notifications | Alerts, logging |
+
+---
+
+## Configuration Format
+
+### settings.json Structure (Project Hooks)
+
+**Events WITH matcher support** (PreToolUse, PostToolUse, PermissionRequest):
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          { "type": "command", "command": "script.sh", "timeout": 5000 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Events WITHOUT matcher support** (SubagentStart, SubagentStop, Stop, UserPromptSubmit):
+```json
+{
+  "hooks": {
+    "SubagentStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "script.sh", "timeout": 5000 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Note**: The `hooks` array wrapper is REQUIRED for all event types, even without a matcher.
+
+### Field Requirements
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `matcher` | **Only for PreToolUse/PostToolUse** | string | Regex pattern for matching |
+| `hooks` | Yes | array | Array of hook definitions |
+| `type` | Yes | string | `command` or `prompt` |
+| `command` | Yes (if type=command) | string | Shell command to execute |
+| `timeout` | No | number | Timeout in milliseconds |
+| `once` | No | boolean | Run only once per session |
+
+### Matcher Support by Event Type
+
+| Event | Supports Matcher? |
+|-------|-------------------|
+| PreToolUse | Yes |
+| PostToolUse | Yes |
+| PermissionRequest | Yes |
+| SubagentStart | **No** |
+| SubagentStop | **No** |
+| Stop | **No** |
+| UserPromptSubmit | **No** |
+
+---
+
+## Environment Variables
+
+### PreToolUse / PostToolUse
+
+| Variable | Description |
+|----------|-------------|
+| `$CLAUDE_TOOL_NAME` | Name of the tool |
+| `$CLAUDE_TOOL_INPUT` | JSON input to tool |
+| `$CLAUDE_TOOL_OUTPUT` | JSON output (PostToolUse only) |
+
+### SubagentStart / SubagentStop
+
+| Variable | Description |
+|----------|-------------|
+| `$CLAUDE_SUBAGENT_TYPE` | Type/name of subagent |
+| `$CLAUDE_SUBAGENT_PROMPT` | Prompt given to subagent (Start only) |
+
+### Plugin Hooks
+
+| Variable | Description |
+|----------|-------------|
+| `$CLAUDE_PLUGIN_ROOT` | Plugin root directory |
+| `$CLAUDE_PROJECT_DIR` | Project directory |
+
+---
+
+## Critical Rules
+
+- [ ] Event type is valid (PreToolUse, PostToolUse, SubagentStart, etc.)
+- [ ] `hooks` array wrapper is present (required for ALL event types)
+- [ ] Each hook has `type` field (`command` or `prompt`)
+- [ ] Each hook has `command` field (if type=command)
+- [ ] JSON syntax is valid
+- [ ] For PreToolUse/PostToolUse: `matcher` is valid regex pattern
+- [ ] For SubagentStart/SubagentStop: NO `matcher` field (not supported)
+
+## High Priority
+
+- [ ] `once: true` used appropriately (SessionStart scenarios)
+- [ ] `timeout` specified (recommended 5000ms for scripts)
+- [ ] Script paths are correct (use `$CLAUDE_PROJECT_DIR` or `$CLAUDE_PLUGIN_ROOT`)
+- [ ] Exit codes used correctly (0=success, 1=warning, 2=block)
+
+## Medium Priority
+
+- [ ] Matcher patterns are specific (not overly broad)
+- [ ] Commands are efficient (avoid long-running)
+- [ ] Error handling in scripts
+
+## Low Priority
+
+- [ ] Comments/documentation for complex hooks
+- [ ] Consistent naming conventions
+
+---
+
+## Common Violations
+
+| Violation | Severity | Remediation |
+|-----------|----------|-------------|
+| Invalid event type | Critical | Use valid event from list |
+| Invalid JSON | Critical | Fix JSON syntax |
+| Missing `hooks` array wrapper | Critical | Wrap hook definitions in `"hooks": [...]` |
+| Missing `type` in hook | Critical | Add `"type": "command"` |
+| Missing `command` in hook | Critical | Add `"command": "script.sh"` |
+| `matcher` on non-matcher event | High | Remove `matcher` from SubagentStart/SubagentStop/Stop |
+| Script not found | High | Check path, use env variables |
+| No `once: true` for SessionStart | Medium | Add if hook should run once |
+| No `timeout` specified | Low | Add `"timeout": 5000` for predictable behavior |

package/skills/anthropic-validator/references/mcp-checklist.md

@@ -0,0 +1,136 @@
+# MCP Validation Checklist (Fallback)
+
+This checklist is used when dynamic documentation fetch fails. May be outdated - prefer fetched standards.
+
+**Last Updated**: 2026-01-17
+
+---
+
+## MCP Overview
+
+Model Context Protocol (MCP) servers extend Claude Code with custom tools via a standardized protocol.
+
+---
+
+## Configuration
+
+### Location
+
+MCP servers are configured in `.claude/mcp.json` or via settings.
+
+### Configuration Format
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "node",
+      "args": ["path/to/server.js"],
+      "env": {
+        "API_KEY": "${API_KEY}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Transport Types
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| `stdio` | Standard input/output | Local servers, scripts |
+| `http` | HTTP requests | Remote servers |
+| `sse` | Server-Sent Events | Streaming responses |
+
+---
+
+## Tool Definition
+
+MCP servers expose tools with this schema:
+
+```json
+{
+  "name": "tool-name",
+  "description": "What the tool does",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "param1": {
+        "type": "string",
+        "description": "Parameter description"
+      }
+    },
+    "required": ["param1"]
+  }
+}
+```
+
+---
+
+## Critical Rules
+
+- [ ] Configuration JSON is valid
+- [ ] Server command/path exists
+- [ ] Required environment variables available
+- [ ] Tools have valid schemas
+
+## High Priority
+
+- [ ] No secrets hardcoded (use `${ENV_VAR}`)
+- [ ] Tool names are unique
+- [ ] Descriptions are clear
+- [ ] Input schemas are valid JSON Schema
+
+## Medium Priority
+
+- [ ] Server handles errors gracefully
+- [ ] Timeout configuration appropriate
+- [ ] Resource cleanup on shutdown
+
+## Low Priority
+
+- [ ] Consistent naming conventions
+- [ ] Documentation for custom tools
+- [ ] Example usage provided
+
+---
+
+## Security Considerations
+
+### Critical
+
+- [ ] No API keys or secrets in config files
+- [ ] Use environment variable interpolation: `${API_KEY}`
+- [ ] Validate all inputs in server code
+- [ ] Limit file system access
+
+### High
+
+- [ ] Network requests only to trusted hosts
+- [ ] No command injection vulnerabilities
+- [ ] Proper permission scoping
+
+---
+
+## Common Violations
+
+| Violation | Severity | Remediation |
+|-----------|----------|-------------|
+| Invalid JSON | Critical | Fix JSON syntax |
+| Hardcoded secrets | Critical | Use `${ENV_VAR}` |
+| Missing server file | Critical | Check path |
+| Invalid tool schema | High | Fix JSON Schema |
+| Missing descriptions | Medium | Add tool descriptions |
+| Missing env vars | High | Set required variables |
+
+---
+
+## Testing MCP Servers
+
+1. Verify server starts without errors
+2. Test each tool with valid inputs
+3. Test error handling with invalid inputs
+4. Verify no secrets in logs
+5. Check resource cleanup

package/skills/anthropic-validator/references/plugins-checklist.md

@@ -0,0 +1,148 @@
+# Plugins Validation Checklist (Fallback)
+
+This checklist is used when dynamic documentation fetch fails. May be outdated - prefer fetched standards.
+
+**Last Updated**: 2026-01-17
+
+---
+
+## Plugin Structure
+
+Plugins package skills, agents, and hooks for distribution.
+
+### Required Structure
+
+```
+plugin-name/
+├── .claude-plugin/
+│   └── plugin.json          # Manifest (ONLY file in .claude-plugin/)
+├── agents/                  # At root, NOT in .claude-plugin/
+│   └── *.md
+├── skills/                  # At root, NOT in .claude-plugin/
+│   └── skill-name/
+│       └── SKILL.md
+└── hooks/                   # At root, NOT in .claude-plugin/
+    └── hooks.json
+```
+
+### Critical Rule
+
+All component directories (`agents/`, `skills/`, `hooks/`) MUST be at plugin root, NOT inside `.claude-plugin/`.
+
+---
+
+## Plugin Manifest
+
+### Location
+
+`.claude-plugin/plugin.json`
+
+### Format
+
+```json
+{
+  "name": "plugin-name",
+  "version": "1.0.0",
+  "description": "What this plugin provides",
+  "skills": [
+    "skill-one",
+    "skill-two"
+  ],
+  "agents": [
+    "agent-one"
+  ]
+}
+```
+
+---
+
+## Critical Rules
+
+- [ ] `.claude-plugin/plugin.json` exists
+- [ ] Manifest JSON is valid
+- [ ] `name` field present and valid
+- [ ] Component directories at root (not in .claude-plugin/)
+
+## High Priority
+
+- [ ] `version` follows semver
+- [ ] `description` explains plugin purpose
+- [ ] All skills listed in manifest exist in `skills/`
+- [ ] All agents listed in manifest exist in `agents/`
+- [ ] Skills follow flat directory structure (one level)
+
+## Medium Priority
+
+- [ ] README.md documents usage
+- [ ] License file present
+- [ ] No unused skills/agents
+- [ ] Consistent naming
+
+## Low Priority
+
+- [ ] Example configurations
+- [ ] Changelog maintained
+- [ ] Contributing guidelines
+
+---
+
+## Skills Directory Structure
+
+### Flat Structure (Required)
+
+```
+skills/
+├── skill-one/
+│   └── SKILL.md
+├── skill-two/
+│   ├── SKILL.md
+│   └── references/
+└── skill-three/
+    └── SKILL.md
+```
+
+### Invalid Structure
+
+```
+skills/
+├── atomic/              # NO nested categories
+│   └── skill-one/
+└── composite/           # NO nested categories
+    └── skill-two/
+```
+
+---
+
+## Common Violations
+
+| Violation | Severity | Remediation |
+|-----------|----------|-------------|
+| Missing plugin.json | Critical | Create `.claude-plugin/plugin.json` |
+| Invalid JSON | Critical | Fix JSON syntax |
+| Components in .claude-plugin/ | Critical | Move to root level |
+| Nested skills structure | High | Flatten to single level |
+| Missing manifest entry | High | Add to skills/agents array |
+| Unlisted component | Medium | Add to manifest or remove |
+
+---
+
+## Installation
+
+Plugins can be installed via:
+
+1. Local path: `claude plugins add /path/to/plugin`
+2. Git repository: `claude plugins add https://github.com/org/plugin`
+3. npm package: `claude plugins add @org/plugin`
+
+---
+
+## Environment Variables
+
+Plugins have access to:
+
+| Variable | Description |
+|----------|-------------|
+| `$CLAUDE_PLUGIN_ROOT` | Absolute path to plugin directory |
+| `$CLAUDE_PROJECT_DIR` | Absolute path to project directory |
+
+Use these in hooks and scripts for portable paths.