codeforge-dev 1.10.0 → 1.12.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/references/milestones-template.md

@@ -0,0 +1,32 @@
+# Milestones
+
+> Features are organized by domain in `.specs/`. Milestones group features
+> into deliverable increments. See `BACKLOG.md` for the feature backlog.
+
+## How Milestones Work
+
+1. **Backlog** — All desired features live in `BACKLOG.md`, graded by priority.
+2. **Milestone scoping** — When ready to plan a deliverable, pull features from the backlog.
+3. **Spec first** — Each feature gets a spec (via `/spec-new`) before implementation begins.
+4. **Ship** — A milestone is done when all its specs are implemented and verified.
+
+Only the **current milestone** is defined in detail. Everything else is backlog.
+
+## Released
+
+_None yet._
+
+## Current
+
+### [Milestone Name]
+
+- [ ] `domain/feature-name.md` — [Brief description]
+- [ ] `domain/feature-name.md` — [Brief description]
+
+## Next
+
+> Scoped from `BACKLOG.md` when the current milestone is complete.
+
+## Out of Scope
+
+- [Items explicitly not planned]

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-new/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   "new feature spec", "write a spec for", "spec this feature",
   "start a new spec", "plan a feature", or needs to create a new
   specification file from the standard template.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Create New Feature Specification
@@ -14,7 +14,7 @@ version: 0.1.0
 
 A specification is a contract between the person requesting a feature and the person building it. Writing the spec BEFORE implementation forces you to think through edge cases, acceptance criteria, and scope boundaries while changes are cheap — before any code exists.
 
-Every project uses `.specs/` as the specification directory. Specs are version-organized, independently loadable, and should aim for ~200 lines.
+Every project uses `.specs/` as the specification directory. Specs are domain-organized, independently loadable, and should aim for ~200 lines.
 
 ---
 
@@ -22,33 +22,32 @@ Every project uses `.specs/` as the specification directory. Specs are version-o
 
 ### Step 1: Parse Arguments
 
-Extract the feature name and version from `$ARGUMENTS`:
+Extract the feature name from `$ARGUMENTS`:
 - **Feature name**: kebab-case identifier (e.g., `session-history`, `auth-flow`)
-- **Version**: semver string (e.g., `v0.3.0`)
 
-If arguments are missing, ask the user for:
-1. Feature name (what is being built)
-2. Target version (which release this belongs to)
+If the feature name is missing, ask the user what they want to spec.
 
-**Note:** Features should be pulled from the project's backlog (`BACKLOG.md`) into a version before creating a spec. If the feature isn't in the backlog yet, add it first, then assign it to a version.
+**Note:** Features should be pulled from the project's backlog (`BACKLOG.md`) into a milestone before creating a spec. If the feature isn't in the backlog yet, add it first, then assign it to a milestone.
 
-### Step 2: Determine File Path
+### Step 2: Determine Domain and File Path
 
-- **Multi-feature version** (directory already exists or multiple features planned):
-  `.specs/{version}/{feature-name}.md`
-- **Single-feature version** (one spec covers the whole version):
-  `.specs/{version}.md`
+Analyze the feature name and description to infer an appropriate domain folder:
+- Look at existing domain folders in `.specs/` for a natural fit
+- Consider the feature's area: `auth`, `search`, `ui`, `api`, `onboarding`, etc.
+- Present the inferred domain to the user for confirmation or override
+
+The file path is always: `.specs/{domain}/{feature-name}.md`
 
 If `.specs/` does not exist at the project root, create it.
 
-If `.specs/{version}/` does not exist and you're using the directory form, create it.
+If `.specs/{domain}/` does not exist, create it.
 
 ### Step 3: Create the Spec File
 
 Write the file using the standard template from `references/template.md`.
 
 Pre-fill:
-- **Version**: from arguments
+- **Domain**: from the inferred/confirmed domain
 - **Status**: `planned`
 - **Last Updated**: today's date (YYYY-MM-DD)
 - **Approval**: `draft`
@@ -73,7 +72,7 @@ After creating the file, guide the user through filling it out:
 ### Step 5: Validate
 
 Before finishing:
-- [ ] If the file exceeds ~200 lines, consider splitting into sub-specs
+- [ ] If the file exceeds ~200 lines, consider splitting into separate specs in the domain folder
 - [ ] No source code, SQL, or type definitions reproduced inline
 - [ ] Status is `planned` and Approval is `draft`
 - [ ] All required sections present (even if some are "N/A" or "TBD")
@@ -88,7 +87,7 @@ The `/spec-refine` skill walks through every `[assumed]` requirement with the us
 
 ## Sizing Guidelines
 
-- **Aim for ~200 lines per spec.** If a feature needs more, consider splitting into sub-specs with a parent `_overview.md` linking them.
+- **Aim for ~200 lines per spec.** If a feature needs more, consider splitting into separate specs in the domain folder.
 - **Reference, don't reproduce.** Write `see src/engine/db/migrations/002.sql lines 48-70` — never paste the SQL.
 - **Independently loadable.** Each spec file must be useful without loading any other file.
 - **EARS format for requirements.** Use the `specification-writing` skill for templates and examples.
@@ -97,7 +96,7 @@ The `/spec-refine` skill walks through every `[assumed]` requirement with the us
 
 ## Ambiguity Policy
 
-- If the user doesn't specify a version, ask — do not assume.
+- If the user doesn't specify a domain, infer one from the feature name and existing `.specs/` structure, then confirm with the user.
 - If the feature scope is unclear, write a minimal spec with `## Open Questions` listing what needs clarification.
 - If a spec already exists for this feature, inform the user and suggest `/spec-update` instead.
 

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-new/references/template.md

@@ -9,7 +9,7 @@ Standard template for all feature specifications. Copy this structure when creat
 ```markdown
 # Feature: [Name]
 
-**Version:** v0.X.0
+**Domain:** [domain-name]
 **Status:** planned
 **Last Updated:** YYYY-MM-DD
 **Approval:** draft
@@ -22,6 +22,8 @@ Standard template for all feature specifications. Copy this structure when creat
 
 [Testable criteria. Use Given/When/Then for complex flows, checklists for simple features, or tables for business rules. Every criterion must be verifiable.]
 
+[Markers: `[ ]` = not started, `[~]` = implemented but not yet verified, `[x]` = verified (tests pass). During `/spec-build`, criteria progress from `[ ]` to `[~]` during implementation, then to `[x]` after review.]
+
 - [ ] [Criterion 1]
 - [ ] [Criterion 2]
 - [ ] [Criterion 3]
@@ -126,4 +128,12 @@ Standard template for all feature specifications. Copy this structure when creat
 | `draft` | Spec has unvalidated assumptions — NOT approved for implementation |
 | `user-approved` | All requirements are `[user-approved]` — ready for implementation |
 
-**Workflow:** `/spec-new` creates → `/spec-refine` validates → implementation begins → `/spec-update` closes the loop.
+## Acceptance Criteria Markers
+
+| Marker | Meaning |
+|--------|---------|
+| `[ ]` | Not started |
+| `[~]` | Implemented, not yet verified — code written, tests not confirmed |
+| `[x]` | Verified — tests pass, behavior confirmed |
+
+**Workflow:** `/spec-new` creates → `/spec-refine` validates → `/spec-build` implements + closes the loop (or implement manually → `/spec-review` verifies → `/spec-update` closes the loop).

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-review/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: spec-review
+description: >-
+  This skill should be used when the user asks to "review the spec",
+  "check spec adherence", "verify implementation", "spec-review",
+  "does code match spec", "audit implementation", or needs a standalone
+  deep implementation review that reads the code and confirms full
+  adherence to a specification.
+version: 0.1.0
+---
+
+# Spec Implementation Review
+
+## Mental Model
+
+A spec is a contract — but contracts only matter if someone verifies them. `/spec-review` is the verification step: given a spec and the code that claims to implement it, does the code actually do what the spec says?
+
+This is a standalone, single-spec, deep implementation review. Unlike `/spec-check` (which audits metadata health across all specs without reading code) and unlike `/spec-build` Phase 4 (which is locked inside the build workflow), `/spec-review` can be invoked independently at any time after implementation exists.
+
+Use cases:
+
+- **Manual implementation** — you built a feature without `/spec-build` and want to verify the work before running `/spec-update`
+- **Post-change regression check** — re-verify after modifying an already-implemented feature
+- **Pre-release audit** — confirm a feature still matches its spec before shipping
+- **Onboarding verification** — check if what's in the code matches what the spec says
+
+```
+Lifecycle positioning:
+
+/spec-new → /spec-refine → implement (manually or via /spec-build) → /spec-review → /spec-update
+
+Or with /spec-build (which has its own Phase 4):
+/spec-new → /spec-refine → /spec-build (includes review) → done
+
+/spec-review is independent — usable at any time after implementation exists.
+```
+
+---
+
+## Relationship to Other Skills
+
+| Skill | What it does | How `/spec-review` differs |
+|-------|-------------|---------------------------|
+| `/spec-check` | Batch metadata audit (all specs, no code reading) | Single-spec deep code audit |
+| `/spec-build` Phase 4 | Same depth, but embedded in the build workflow | Standalone, invokable independently |
+| `/spec-update` | Updates spec metadata after implementation | `/spec-review` audits first, then recommends `/spec-update` |
+
+---
+
+## Spec Edits During Review
+
+`/spec-review` makes limited spec edits — just enough to record what it verified:
+
+- Upgrade `[ ]` or `[~]` → `[x]` for criteria verified by passing tests
+- Downgrade `[x]` → `[ ]` if a previously-verified criterion now fails (regression)
+- Add entries to `## Discrepancies` for gaps found
+- Update `## Key Files` if paths are stale (files moved/deleted/added)
+- Update `**Last Updated:**` date
+
+It does NOT change `**Status:**` or add `## Implementation Notes` — that's `/spec-update`'s job. Clear boundary: `/spec-review` verifies and records findings; `/spec-update` closes the loop.
+
+---
+
+## Workflow
+
+### Step 1: Discovery
+
+**Find the spec.** Match `$ARGUMENTS` (feature name or path) against:
+
+```
+Glob: .specs/**/*.md
+```
+
+If ambiguous, list matching specs and ask which one to review.
+
+**Read the full spec.** Extract:
+
+- All FR-* and NFR-* requirements with their EARS-format text
+- All acceptance criteria with current markers (`[ ]`, `[~]`, `[x]`)
+- Key Files — every file path listed
+- Out of Scope — boundaries to respect
+- Discrepancies — any existing entries
+
+**Gate check.** `/spec-review` works on any spec with implementation to review:
+
+| Approval | Status | Action |
+|----------|--------|--------|
+| `user-approved` | `planned` | Proceed (reviewing work done against approved spec) |
+| `user-approved` | `partial` or `implemented` | Proceed (re-reviewing) |
+| `draft` | any | **Warn**: "This spec is `draft`. Requirements may not be validated. Consider running `/spec-refine` first. Proceed anyway?" |
+
+Unlike `/spec-build` which hard-blocks on `draft` (because it's about to write code), `/spec-review` is read-heavy — reviewing existing code against a draft spec is still useful, even if the spec itself isn't finalized.
+
+**Read every Key File.** Read all files listed in the spec's `## Key Files` section. These are the files the spec author identified as implementing the feature. Understanding them is prerequisite to the audit.
+
+---
+
+### Step 2: Requirement Coverage Audit
+
+Walk every FR-* and NFR-* requirement from the spec. Use the Spec Implementation Review Checklist at `spec-build/references/review-checklist.md` sections 4A and 4D as the authoritative guide.
+
+**For each FR-* requirement:**
+
+1. Identify the file(s) and function(s) that implement it
+2. Verify the implementation matches the EARS-format requirement text
+3. Confirm the requirement is fully addressed (not partially)
+4. Note if the requirement was met through a different approach than planned
+
+**For each NFR-* requirement:**
+
+1. Identify how the non-functional requirement is enforced
+2. Verify measurable NFRs have been tested or measured
+3. Confirm the NFR is met under expected conditions, not just ideal conditions
+
+**Cross-checks:**
+
+- Every FR-* has corresponding code — no requirements were skipped
+- Every NFR-* has corresponding enforcement — no hand-waving
+- No code was written that doesn't map to a requirement (scope creep check)
+- Out of Scope items from the spec were NOT implemented
+
+---
+
+### Step 3: Acceptance Criteria Verification
+
+For each acceptance criterion, locate or write the corresponding test. Use the Spec Implementation Review Checklist at `spec-build/references/review-checklist.md` sections 4B and 4C as the authoritative guide.
+
+**For each criterion:**
+
+1. Locate the corresponding test (unit, integration, or manual verification)
+2. If no test exists: **write one** — verification requires evidence, "no test exists" is not a valid review outcome
+3. Run the test
+4. If test passes → upgrade marker to `[x]` in the spec
+5. If test fails → note the failure, set marker to `[ ]`, document the issue
+
+**Summary checks:**
+
+- Count total criteria vs. verified `[x]` — report the ratio
+- Flag any criteria still `[ ]` (not started or regressed)
+- Flag any criteria that cannot be tested — document why and note as discrepancy
+- Verify tests actually test the criterion, not just exercise the code path
+
+**Code quality spot-check** per checklist section 4C:
+
+- Error handling at appropriate boundaries
+- No hardcoded values that should be configurable
+- Functions short and single-purpose
+- Nesting depth within limits
+- No regressions in existing tests
+
+---
+
+### Step 4: Report & Spec Updates
+
+#### Summary Report
+
+Present a structured report:
+
+```
+## Spec Implementation Review
+
+**Spec:** [feature name] ([spec file path])
+**Date:** YYYY-MM-DD
+**Reviewer:** /spec-review
+
+### Requirement Coverage
+- Functional: N/M addressed
+- Non-Functional: N/M addressed
+- Gaps: [list or "None"]
+
+### Acceptance Criteria
+- [x] Verified: N
+- [~] Implemented, pending: N
+- [ ] Not started / regressed: N
+- Failures: [list or "None"]
+
+### Code Quality
+- Issues found: [list or "None"]
+- Regressions: [list or "None"]
+
+### Spec Consistency
+- Key Files updates needed: [list or "None"]
+- Discrepancies: [list or "None"]
+
+### Recommendation
+[ ] All clear — run `/spec-update` to close the loop
+[ ] Fix issues first: [specific list]
+[ ] Requires user input: [specific questions]
+```
+
+#### Spec Edits
+
+Apply limited edits to the spec file:
+
+1. **Acceptance criteria markers** — update based on test results:
+   - Passed tests: upgrade `[ ]` or `[~]` → `[x]`
+   - Failed tests: downgrade `[x]` → `[ ]` (regression), keep `[ ]` or `[~]` as-is
+2. **Discrepancies** — add entries for any gaps found between spec and implementation
+3. **Key Files** — update paths if files moved, were deleted, or new files were created
+4. **Last Updated** — set to today's date
+
+Do NOT modify `**Status:**` or `## Implementation Notes` — those are `/spec-update`'s responsibility.
+
+#### Next Action
+
+Based on the review outcome, recommend:
+
+- **All clear**: "Run `/spec-update` to close the loop and mark the spec as implemented."
+- **Issues found**: "Fix the issues listed above, then re-run `/spec-review` to verify."
+- **User input needed**: Present specific questions and wait for direction.
+
+---
+
+## Ambiguity Policy
+
+- If `$ARGUMENTS` matches multiple specs, list them and ask which to review.
+- If a spec has no acceptance criteria, warn and offer to review requirements only.
+- If Key Files reference paths that don't exist, flag them as stale in the report and update the spec's Key Files section.
+- If the spec has no requirements section, warn that there's nothing to audit against and suggest running `/spec-new` or `/spec-update` to add requirements.
+- If all criteria are already `[x]`, still run the full review — regressions happen.
+
+---
+
+## Anti-Patterns
+
+- **Skipping test verification**: Marking criteria as `[x]` without running actual tests. Every `[x]` must be backed by a passing test or confirmed behavior.
+- **Reviewing without reading code**: The review must read the implementation files, not just check metadata. That's what `/spec-check` is for.
+- **Modifying implementation**: `/spec-review` is a review, not a fix. Report issues; don't fix them. The user decides what to do next.
+- **Changing spec status**: `/spec-review` records findings. `/spec-update` changes status. Respect the boundary.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-update/SKILL.md

@@ -26,6 +26,8 @@ Before performing an as-built update, check the spec's `**Approval:**` status:
 
 This is a warning, not a blocker — the user decides whether to refine first or update as-is.
 
+For manually-implemented features (not using `/spec-build`), consider running `/spec-review` first to verify implementation adherence before updating the spec.
+
 ---
 
 ## The 6-Step Workflow
@@ -56,6 +58,7 @@ Review each acceptance criterion in the spec:
 - Mark as `[x]` if the criterion is met and verified (tests pass, behavior confirmed)
 - Leave as `[ ]` if not yet implemented
 - Add a note next to deferred criteria explaining why
+- If a criterion is marked `[~]` (implemented but not yet verified from a `/spec-build` run), treat it as `[ ]` — verify it now and upgrade to `[x]` if confirmed, or leave as `[ ]` if unverifiable
 
 If criteria were met through different means than originally planned, note the deviation.
 
@@ -81,7 +84,7 @@ Verify paths exist before listing them. Use absolute project-relative paths.
 ### Step 6: Update Metadata
 
 - Set `**Last Updated:**` to today's date (YYYY-MM-DD)
-- Verify `**Version:**` is correct
+- Verify `**Domain:**` is correct
 - Preserve the `**Approval:**` status — do NOT downgrade `user-approved` to `draft`
 - If the as-built update introduces new decisions not in the original spec, add them to `## Resolved Questions` if the user confirmed them, or `## Open Questions` if they were assumed during implementation
 
@@ -121,9 +124,10 @@ Before finishing the update:
 - [ ] Implementation Notes document deviations from original spec
 - [ ] File paths in Key Files are accurate and verified
 - [ ] Last Updated date is today
+- [ ] `**Domain:**` is correct for the spec's location
 - [ ] `**Approval:**` status is preserved (not downgraded)
 - [ ] New implementation decisions are tracked in Resolved Questions or Open Questions
-- [ ] If the spec has grown past ~200 lines, note it and suggest splitting in a future pass
+- [ ] If the spec has grown past ~200 lines, note it and suggest splitting into separate specs in the domain folder
 - [ ] If `**Approval:**` is still `draft`, user was warned and confirmed proceeding
 - [ ] No source code was pasted inline (references only)
 

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/specification-writing/SKILL.md

@@ -176,7 +176,7 @@ Every spec file starts with metadata:
 
 ```
 # Feature: [Name]
-**Version:** v0.X.0
+**Domain:** [domain-name]
 **Status:** implemented | partial | planned
 **Last Updated:** YYYY-MM-DD
 **Approval:** draft | user-approved

package/.devcontainer/plugins/devs-marketplace/plugins/codeforge-lsp/.claude-plugin/plugin.json

@@ -1,7 +1,40 @@
 {
-  "name": "codeforge-lsp",
-  "description": "LSP servers for CodeForge (Python, TypeScript, Go)",
-  "author": {
-    "name": "AnExiledDev"
-  }
+	"name": "codeforge-lsp",
+	"description": "LSP servers for CodeForge (Python, TypeScript, Go)",
+	"author": {
+		"name": "AnExiledDev"
+	},
+	"lspServers": {
+		"pyright": {
+			"command": "pyright-langserver",
+			"args": ["--stdio"],
+			"extensionToLanguage": {
+				".py": "python",
+				".pyi": "python"
+			}
+		},
+		"typescript": {
+			"command": "typescript-language-server",
+			"args": ["--stdio"],
+			"extensionToLanguage": {
+				".ts": "typescript",
+				".tsx": "typescriptreact",
+				".js": "javascript",
+				".jsx": "javascriptreact",
+				".mts": "typescript",
+				".cts": "typescript",
+				".mjs": "javascript",
+				".cjs": "javascript"
+			}
+		},
+		"gopls": {
+			"command": "gopls",
+			"args": ["serve"],
+			"extensionToLanguage": {
+				".go": "go",
+				".mod": "go.mod",
+				".sum": "go.sum"
+			}
+		}
+	}
 }

package/.devcontainer/plugins/devs-marketplace/plugins/codeforge-lsp/README.md

@@ -0,0 +1,41 @@
+# codeforge-lsp
+
+Purely declarative Claude Code plugin that registers Language Server Protocol (LSP) servers for Python, TypeScript/JavaScript, and Go. No hooks, no scripts — just server definitions in the plugin manifest.
+
+## What It Does
+
+Provides Claude Code with language intelligence (type checking, diagnostics, go-to-definition) by registering three LSP servers:
+
+| Server | Command | Languages | File Extensions |
+|--------|---------|-----------|-----------------|
+| [Pyright](https://github.com/microsoft/pyright) | `pyright-langserver --stdio` | Python | `.py`, `.pyi` |
+| [TypeScript Language Server](https://github.com/typescript-language-server/typescript-language-server) | `typescript-language-server --stdio` | TypeScript, JavaScript | `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs` |
+| [gopls](https://pkg.go.dev/golang.org/x/tools/gopls) | `gopls serve` | Go | `.go`, `.mod`, `.sum` |
+
+Servers activate only if their binary is available on PATH. Missing servers are silently skipped — the plugin never fails on a missing tool.
+
+## How It Works
+
+The plugin uses the `lspServers` field in `plugin.json` to declare server configurations. Claude Code reads this at startup and launches each server whose command binary exists. There is no hook logic or runtime behavior — everything is static configuration.
+
+Each server maps file extensions to language identifiers. When Claude Code opens a file matching a registered extension, it routes it to the corresponding LSP server for diagnostics, completions, and other language features.
+
+## Plugin Structure
+
+```
+codeforge-lsp/
+├── .claude-plugin/
+│   └── plugin.json    # Plugin metadata + LSP server definitions
+└── README.md          # This file
+```
+
+## Requirements
+
+- Claude Code with LSP plugin support
+- Install the language servers you need:
+
+| Server | Install |
+|--------|---------|
+| Pyright | `npm i -g pyright` |
+| TypeScript Language Server | `npm i -g typescript-language-server typescript` |
+| gopls | `go install golang.org/x/tools/gopls@latest` |

package/.devcontainer/plugins/devs-marketplace/plugins/dangerous-command-blocker/README.md

@@ -0,0 +1,72 @@
+# dangerous-command-blocker
+
+Claude Code plugin that intercepts Bash tool calls and blocks destructive commands before they execute. Acts as a safety net against accidental or misguided destructive operations.
+
+## What It Does
+
+Inspects every Bash command Claude attempts to run against a set of dangerous patterns. If a match is found, the command is blocked with an error message explaining why. Safe commands pass through untouched.
+
+### Blocked Patterns
+
+| Category | Examples |
+|----------|----------|
+| Destructive filesystem deletion | `rm -rf /`, `rm -rf ~`, `rm -rf ../` |
+| Privileged deletion | `sudo rm` |
+| World-writable permissions | `chmod 777`, `chmod -R 777` |
+| Force push to main/master | `git push --force origin main`, `git push -f origin master` |
+| Bare force push | `git push -f`, `git push --force` (no branch specified) |
+| Git history destruction | `git reset --hard origin/main`, `git clean -f` |
+| System directory writes | `> /usr/`, `> /etc/`, `> /bin/`, `> /sbin/` |
+| Disk formatting | `mkfs.*`, `dd of=/dev/` |
+| Docker container escape | `docker run --privileged`, `docker run -v /:/...` |
+| Destructive Docker operations | `docker stop`, `docker rm`, `docker kill`, `docker rmi` |
+| Dangerous find operations | `find -exec rm`, `find -delete` |
+
+## How It Works
+
+### Hook Lifecycle
+
+```
+Claude calls the Bash tool
+  │
+  └─→ PreToolUse hook fires for Bash
+       │
+       └─→ block-dangerous.py reads the command from stdin
+            │
+            ├─→ Pattern match found → exit 2 (block with error)
+            └─→ No match → exit 0 (allow)
+```
+
+### Exit Code Behavior
+
+| Exit Code | Meaning |
+|-----------|---------|
+| 0 | Command is safe — allow execution |
+| 2 | Command matches a dangerous pattern — block with error message |
+
+### Error Handling
+
+- **JSON parse failure**: Fails closed (exit 2) — if the input can't be read, the command is blocked
+- **Other exceptions**: Fails open (exit 0) — logs the error to stderr but does not block
+
+### Timeout
+
+The hook has a 5-second timeout. If the script takes longer, Claude Code proceeds with the command.
+
+## Plugin Structure
+
+```
+dangerous-command-blocker/
+├── .claude-plugin/
+│   └── plugin.json          # Plugin metadata
+├── hooks/
+│   └── hooks.json           # PreToolUse/Bash hook registration
+├── scripts/
+│   └── block-dangerous.py   # Pattern matcher (PreToolUse)
+└── README.md                # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Claude Code with plugin hook support