codeforge-dev 1.14.2 → 2.0.1

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/researcher.md

@@ -5,10 +5,12 @@ description: >-
   and gathers information from the web to answer technical questions. Use when
   the user asks "how does X work", "find information about", "what's the best
   approach for", "investigate this", "research", "look into", "compare X vs Y",
-  "explain this concept", or needs codebase analysis, library evaluation,
-  technology comparison, or technical deep-dives. Reports structured findings
-  with citations without modifying any files. Do not use for code
-  modifications, file writing, or implementation tasks.
+  "explain this concept", "evaluate options for", "should we use X or Y",
+  "which library should we use", or needs codebase analysis, library evaluation,
+  technology comparison, or technical deep-dives that require web access.
+  Reports structured findings with citations without modifying any files.
+  Do not use for code modifications, file writing, or implementation tasks.
+  For codebase-only exploration without web access, use explorer instead.
 tools: Read, Glob, Grep, WebSearch, WebFetch, Bash
 model: sonnet
 color: cyan
@@ -17,6 +19,12 @@ memory:
   scope: user
 skills:
   - documentation-patterns
+hooks:
+  PreToolUse:
+    - matcher: Bash
+      type: command
+      command: "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guard-readonly-bash.py --mode general-readonly"
+      timeout: 5
 ---
 
 # Research Agent
@@ -55,6 +63,16 @@ When uncertain, investigate first — read the code, check the docs — rather t
 - Mark uncertainty explicitly. Distinguish confirmed facts from inference.
 - Reference code locations as `file_path:line_number`.
 
+## Handling Uncertainty
+
+You are a subagent — you CANNOT ask the user questions directly.
+
+When you encounter ambiguity, make your best judgment and flag it clearly:
+- Include an `## Assumptions` section in your findings listing what you assumed and why
+- For each assumption, note the alternative interpretation
+- Continue working — do not block on ambiguity
+- When search results are inconclusive, present what you found with confidence levels rather than blocking
+
 ## Critical Constraints
 
 - **NEVER** modify, create, write, or delete any file — you have no undo mechanism for destructive actions, and your role is strictly investigative.
@@ -78,7 +96,7 @@ Before searching, decompose the user's question:
 3. **Identify keywords** — What function names, class names, config keys, or technical terms should you search for?
 4. **Identify deliverable** — Does the user want a summary, a comparison, a recommendation, or an explanation?
 
-If the question is ambiguous, state your interpretation before proceeding so the user can correct course early.
+If the question is ambiguous, state your interpretation in an `## Assumptions` section and proceed with your best judgment (per "Handling Uncertainty" above).
 
 ### Phase 2: Codebase Investigation (Always First)
 

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/security-auditor.md

@@ -1,12 +1,17 @@
 ---
 name: security-auditor
 description: >-
-  Read-only security analysis agent that audits codebases for vulnerabilities,
-  checks OWASP Top 10 patterns, scans for hardcoded secrets, and reviews
-  dependency security. Use when the user asks "audit this for security",
-  "check for vulnerabilities", "scan for secrets", "review auth security",
-  "find hardcoded credentials", "check dependency vulnerabilities", "OWASP
-  review", "security check", or needs a security assessment of any code.
+  Read-only security analysis agent that audits APPLICATION CODE for
+  vulnerabilities, checks OWASP Top 10 patterns, scans for hardcoded secrets,
+  and reviews authentication/authorization logic. Use when the user asks
+  "audit this for security", "check for vulnerabilities", "scan for secrets",
+  "review auth security", "find hardcoded credentials", "OWASP review",
+  "security check", "code review for security", "check for injection",
+  "review access control", or needs a security assessment of code patterns,
+  auth flows, or input handling. Focuses primarily on CODE-LEVEL security
+  and includes basic dependency scanning as part of comprehensive audits.
+  For dedicated dependency analysis or supply-chain investigations,
+  prefer dependency-analyst.
   Reports findings with severity ratings and remediation guidance without
   modifying any files. Do not use for fixing vulnerabilities or
   implementing security changes — audit and reporting only.
@@ -55,6 +60,15 @@ When uncertain, investigate first — read the code, check the docs — rather t
 - Mark uncertainty explicitly. Distinguish confirmed facts from inference.
 - Reference code locations as `file_path:line_number`.
 
+## Handling Uncertainty
+
+You are a subagent — you CANNOT ask the user questions directly.
+
+When you encounter ambiguity, make your best judgment and flag it clearly:
+- Include an `## Assumptions` section listing what you assumed and why
+- For each assumption, note the alternative interpretation
+- Continue working — do not block on ambiguity
+
 ## Critical Constraints
 
 - **NEVER** modify, create, write, or delete any file — you are an auditor, not a remediator. Fixing vulnerabilities is the developer's responsibility.

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/spec-writer.md

@@ -54,6 +54,18 @@ When uncertain, investigate first — read the code, check the docs — rather t
 - Mark uncertainty explicitly. Distinguish confirmed facts from inference.
 - Reference code locations as `file_path:line_number`.
 
+## Question Surfacing Protocol
+
+You are a subagent — you CANNOT ask the user questions directly.
+
+When you encounter ambiguity that affects specification accuracy:
+1. Place unresolvable decisions in the `## Open Questions` section with options and trade-offs — do NOT make them requirements
+2. For scope-level ambiguity (e.g., "which feature should I spec?"), include a `## BLOCKED: Questions` section and return a draft limited to what you can determine from context — do not guess scope
+3. Tag all requirements you author as `[assumed]` — never `[user-approved]`
+4. Present specs for review with prominent open questions so the orchestrator can relay them to the user
+
+Your Open Questions section IS your question-surfacing mechanism. Make it prominent and actionable.
+
 ## Critical Constraints
 
 - **NEVER** write implementation code. Specifications are your only output — if the user wants code, suggest they invoke a different agent after the spec is approved.

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/statusline-config.md

@@ -20,6 +20,16 @@ memory:
 
 You are a **status line configuration specialist** for Claude Code. You create and update the `statusLine` command in the user's Claude Code settings, converting shell PS1 prompts, building custom status displays, and integrating project-specific information into the status bar.
 
+## Question Surfacing Protocol
+
+You are a subagent — you CANNOT ask the user questions directly.
+
+When you hit ambiguity that affects correctness:
+1. STOP working on the ambiguous area
+2. Include a `## BLOCKED: Questions` section in your output
+3. For each question: what you need to know, why, and what options you see
+4. Return partial results + questions — the orchestrator will relay to the user
+
 ## Critical Constraints
 
 - **NEVER** modify any file other than Claude Code settings files (`~/.claude/settings.json` or the target of its symlink).
@@ -154,7 +164,7 @@ If a custom status line feature (`ccstatusline`) is installed, check for a wrapp
 
 ### Creating from Scratch
 
-1. Ask the user what information they want displayed (model, directory, git branch, context usage, etc.).
+1. If the caller specified what to display, use that. If not, include a `## BLOCKED: Questions` section listing what information the user might want (model, directory, git branch, context usage) — the orchestrator will relay the answer.
 2. Build the command using the StatusLine JSON input schema.
 3. Test for correctness (ensure `jq` queries match the schema).
 4. Update settings.
@@ -171,7 +181,7 @@ If a custom status line feature (`ccstatusline`) is installed, check for a wrapp
 - **PS1 conversion request**: Follow the Converting PS1 workflow. Show the original PS1 and the converted command for verification.
 - **Custom status line request**: Follow the Creating from Scratch workflow. Suggest useful fields from the JSON schema.
 - **Modification request**: Follow the Modifying Existing workflow. Show before and after.
-- **No PS1 found**: Report that no PS1 was found in any shell config file and ask the user for specific instructions.
+- **No PS1 found**: Report that no PS1 was found in any shell config file and include a `## BLOCKED: Questions` section requesting specific instructions from the user via the orchestrator.
 - **Complex status line**: If the command would be very long, recommend the script file approach.
 - If git commands are included in the status line script, they should use `--no-optional-locks` to avoid interfering with other git operations.
 

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/test-writer.md

@@ -5,10 +5,11 @@ description: >-
   test suites. Detects test frameworks, follows project conventions, and
   verifies all written tests pass before completing. Use when the user asks
   "write tests for", "add tests", "increase test coverage", "create unit tests",
-  "add integration tests", "test this function", "test this module", or needs
-  automated test coverage for any code. Supports pytest, Vitest, Jest, Go
-  testing, and Rust test frameworks. Do not use for modifying
-  application source code, fixing bugs, or implementing features.
+  "add integration tests", "test this function", "test this module", "run the
+  tests", "verify tests pass", "check test coverage", or needs automated test
+  coverage for any code. Supports pytest, Vitest, Jest, Go testing, and Rust
+  test frameworks. Do not use for modifying application source code, fixing
+  bugs, or implementing features.
 tools: Read, Write, Edit, Glob, Grep, Bash
 model: opus
 color: green
@@ -23,7 +24,7 @@ hooks:
   Stop:
     - type: command
       command: "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/verify-tests-pass.py"
-      timeout: 30
+      timeout: 120
 ---
 
 # Test Writer Agent
@@ -124,6 +125,20 @@ When uncertain, investigate first — read the code, check the docs — rather t
 - Mark uncertainty explicitly. Distinguish confirmed facts from inference.
 - Reference code locations as `file_path:line_number`.
 
+## Question Surfacing Protocol
+
+You are a subagent — you CANNOT ask the user questions directly.
+
+When you hit ambiguity that affects test correctness:
+1. STOP working on the ambiguous area
+2. Include a `## BLOCKED: Questions` section in your output
+3. Common blocking situations:
+   - No test framework detected and none specified
+   - Expected behavior unclear — code does X but it might be a bug
+   - Test scope ambiguous — unit vs integration vs E2E not specified
+4. For discovered bugs: include a prominent `## Bugs Discovered` section — this is high-priority information for the orchestrator
+5. Return partial results (tests for clear areas) + questions for ambiguous areas
+
 ## Critical Constraints
 
 - **NEVER** modify source code files — you only create and edit test files. If a source file needs changes to become testable, report this as a finding rather than making the change yourself.
@@ -278,8 +293,8 @@ go test -v ./path/to/package/...
 - **Module/directory requested** (e.g., "Add tests for the API module"): Discover all source files in the module, prioritize by complexity and criticality, write tests for each starting with the most important.
 - **Coverage increase requested** (e.g., "Increase test coverage for auth"): Find existing tests, identify gaps using coverage data or manual analysis, fill gaps with targeted tests for uncovered branches.
 - **No specific target** (e.g., "Write tests"): Scan the project for the least-tested areas, prioritize critical paths (auth, payments, data validation), and work through them systematically.
-- **Ambiguous scope**: If the user says "test this" without specifying what, check if they have a file open or recently discussed a specific module. If unclear, ask which module or file to target.
-- **No test framework found**: Report this explicitly, recommend a framework based on the project's language, and ask the user how to proceed before writing anything.
+- **Ambiguous scope**: If the user says "test this" without specifying what, check if they have a file open or recently discussed a specific module. If still unclear, include a `## BLOCKED: Questions` section per the Question Surfacing Protocol asking which module or file to target.
+- **No test framework found**: Report this explicitly, recommend a framework based on the project's language, and include a `## BLOCKED: Questions` section asking how to proceed before writing anything.
 - If you cannot determine expected behavior for a function (no docs, no examples, unclear logic), state this explicitly in your output and write tests for the behavior you *can* verify, noting the gaps.
 - **Spec-linked testing**: When specs exist in `.specs/`, check if acceptance
   criteria are defined for the area being tested. Report which criteria your tests

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/scripts/guard-readonly-bash.py

@@ -513,8 +513,9 @@ def check_git_readonly(command: str) -> str | None:
                 # Resolve git global flags to find the real subcommand
                 # e.g. git -C /path --no-pager log -> subcommand is "log"
                 sub = None
+                sub_idx = 0
                 skip_next = False
-                for w in words[1:]:
+                for idx, w in enumerate(words[1:], start=1):
                     if skip_next:
                         skip_next = False
                         continue
@@ -524,6 +525,7 @@ def check_git_readonly(command: str) -> str | None:
                     if w.startswith("-"):
                         continue
                     sub = w
+                    sub_idx = idx
                     break
 
                 if sub is None:
@@ -545,16 +547,18 @@ def check_git_readonly(command: str) -> str | None:
                             "-l",
                             "--get-regexp",
                         }
-                        if not (set(words[2:]) & safe_flags):
+                        if not (set(words[sub_idx + 1 :]) & safe_flags):
                             return "Blocked: 'git config' is only allowed with --get or --list"
 
                     elif sub == "stash":
                         # Only allow "stash list" and "stash show"
-                        if len(words) > 2 and words[2] not in ("list", "show"):
-                            return f"Blocked: 'git stash {words[2]}' is not allowed in read-only mode"
+                        if len(words) <= sub_idx + 1:
+                            return "Blocked: bare 'git stash' (equivalent to push) is not allowed in read-only mode"
+                        if words[sub_idx + 1] not in ("list", "show"):
+                            return f"Blocked: 'git stash {words[sub_idx + 1]}' is not allowed in read-only mode"
 
                     else:
-                        for w in words[2:]:
+                        for w in words[sub_idx + 1 :]:
                             if w in restricted:
                                 return f"Blocked: 'git {sub} {w}' is not allowed in read-only mode"
 

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/scripts/redirect-builtin-agents.py

@@ -18,7 +18,6 @@ Exit 0: No redirect needed (passthrough) or redirect applied (with JSON output)
 """
 
 import json
-import os
 import sys
 from datetime import datetime, timezone
 
@@ -39,13 +38,11 @@ PLUGIN_PREFIX = "agent-system"
 # Handles cases where the model uses the short name directly
 UNQUALIFIED_MAP = {v: f"{PLUGIN_PREFIX}:{v}" for v in REDIRECT_MAP.values()}
 
-LOG_FILE = os.environ.get("AGENT_REDIRECT_LOG", "/tmp/agent-redirect.log")
+LOG_FILE = "/tmp/agent-redirect.log"
 
 
 def log(message: str) -> None:
-    """Append a timestamped log entry if logging is enabled."""
-    if not LOG_FILE:
-        return
+    """Append a timestamped log entry."""
     try:
         with open(LOG_FILE, "a") as f:
             ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S")

package/.devcontainer/plugins/devs-marketplace/plugins/auto-code-quality/README.md

@@ -120,7 +120,7 @@ This plugin bundles functionality that may overlap with other plugins. If you're
 - `auto-linter` — linting is included here
 - `code-directive` `collect-edited-files.py` hook — file collection is included here
 
-The temp file prefixes are different (`claude-cq-*` vs `claude-edited-files-*` / `claude-lint-files-*`), so enabling both won't corrupt data — but files would be formatted and linted twice.
+All pipelines use the `claude-cq-*` temp file prefix, so enabling both won't corrupt data — but files would be formatted and linted twice.
 
 ## Plugin Structure
 

package/.devcontainer/plugins/devs-marketplace/plugins/auto-code-quality/scripts/advisory-test-runner.py

@@ -25,7 +25,7 @@ def get_edited_files(session_id: str) -> list[str]:
     Relies on collect-edited-files.py writing paths to a temp file.
     Returns deduplicated list of paths that still exist on disk.
     """
-    tmp_path = f"/tmp/claude-edited-files-{session_id}"
+    tmp_path = f"/tmp/claude-cq-edited-{session_id}"
     try:
         with open(tmp_path, "r") as f:
             raw = f.read()
@@ -310,7 +310,9 @@ def main():
         )
     except subprocess.TimeoutExpired:
         json.dump(
-            {"systemMessage": f"[Tests] {framework} timed out after {TIMEOUT_SECONDS}s"},
+            {
+                "systemMessage": f"[Tests] {framework} timed out after {TIMEOUT_SECONDS}s"
+            },
             sys.stdout,
         )
         sys.exit(0)

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

@@ -14,7 +14,8 @@ Inspects every Bash command Claude attempts to run against a set of dangerous pa
 | 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) |
+| Bare force push | `git push -f`, `git push --force`, `git push --force-with-lease` |
+| Remote branch deletion | `git push origin --delete`, `git push origin :branch` |
 | Git history destruction | `git reset --hard origin/main`, `git clean -f` |
 | System directory writes | `> /usr/`, `> /etc/`, `> /bin/`, `> /sbin/` |
 | Disk formatting | `mkfs.*`, `dd of=/dev/` |
@@ -47,7 +48,7 @@ Claude calls the Bash tool
 ### 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
+- **Other exceptions**: Fails closed (exit 2) — logs the error to stderr and blocks
 
 ### Timeout
 

package/.devcontainer/plugins/devs-marketplace/plugins/dangerous-command-blocker/scripts/block-dangerous.py

@@ -11,6 +11,13 @@ import json
 import re
 import sys
 
+FORCE_PUSH_SUGGESTION = (
+    "Blocked: force push is not allowed. "
+    "If you rebased and need to update a remote branch, use "
+    "`git merge origin/main` instead of `git rebase` to avoid "
+    "diverged history that requires force push."
+)
+
 DANGEROUS_PATTERNS = [
     # Destructive filesystem deletion
     (
@@ -79,28 +86,95 @@ DANGEROUS_PATTERNS = [
     (r"\brm\s+.*-[^\s]*r[^\s]*f[^\s]*\s+\.\./", "Blocked: rm -rf on parent directory"),
     (r"\bfind\s+.*-exec\s+rm\b", "Blocked: find -exec rm is dangerous"),
     (r"\bfind\s+.*-delete\b", "Blocked: find -delete is dangerous"),
-    # Git history destruction
-    (r"\bgit\s+push\s+-f\b", "Blocked: bare force push - specify remote and branch"),
-    (
-        r"\bgit\s+push\s+--force\b",
-        "Blocked: bare force push - specify remote and branch",
-    ),
+    # Git history destruction — force push (all variants)
+    (r"\bgit\s+push\s+-f\b", FORCE_PUSH_SUGGESTION),
+    (r"\bgit\s+push\s+--force\b", FORCE_PUSH_SUGGESTION),
+    (r"\bgit\s+push\s+--force-with-lease\b", FORCE_PUSH_SUGGESTION),
     (
         r"\bgit\s+clean\s+-[^\s]*f",
         "Blocked: git clean -f removes untracked files permanently",
     ),
+    # Remote branch deletion — closes open PRs and destroys remote history
+    (
+        r"\bgit\s+push\s+\S+\s+--delete\b",
+        "Blocked: deleting remote branches closes any associated pull requests. "
+        "Do not delete remote branches as a workaround for force push blocks.",
+    ),
+    (
+        r"\bgit\s+push\s+--delete\b",
+        "Blocked: deleting remote branches closes any associated pull requests. "
+        "Do not delete remote branches as a workaround for force push blocks.",
+    ),
+    (
+        r"\bgit\s+push\s+\S+\s+:\S",
+        "Blocked: push with colon-refspec deletes remote branches and closes "
+        "associated pull requests. Do not use as a workaround for force push blocks.",
+    ),
+    # Symbolic chmod equivalents of 777
+    (
+        r"\bchmod\s+a=rwx\b",
+        "Blocked: chmod a=rwx is equivalent to 777 — security vulnerability",
+    ),
+    (
+        r"\bchmod\s+0777\b",
+        "Blocked: chmod 0777 creates security vulnerability",
+    ),
+    # SetUID/SetGID bits
+    (
+        r"\bchmod\s+u\+s\b",
+        "Blocked: chmod u+s sets SetUID bit — privilege escalation risk",
+    ),
+    (
+        r"\bchmod\s+g\+s\b",
+        "Blocked: chmod g+s sets SetGID bit — privilege escalation risk",
+    ),
+    # Destructive Docker operations (additional)
+    (
+        r"\bdocker\s+system\s+prune\b",
+        "Blocked: docker system prune removes all unused data",
+    ),
+    (
+        r"\bdocker\s+volume\s+rm\b",
+        "Blocked: docker volume rm destroys persistent data",
+    ),
+    # Git history rewriting
+    (
+        r"\bgit\s+filter-branch\b",
+        "Blocked: git filter-branch rewrites repository history",
+    ),
+    # Plus-refspec force push (git push origin +main)
+    (
+        r"\bgit\s+push\s+\S+\s+\+\S",
+        "Blocked: plus-refspec push (+ref) is a force push that destroys history",
+    ),
+    # Force push variant: --force-if-includes
+    (r"\bgit\s+push\s+.*--force-if-includes\b", FORCE_PUSH_SUGGESTION),
 ]
 
 
-def check_command(command: str) -> tuple[bool, str]:
-    """Check if command matches any dangerous pattern.
+def strip_command_prefixes(command: str) -> str:
+    """Strip common command prefixes that bypass word-boundary matching.
 
-    Returns:
-        (is_dangerous, message)
+    Handles: backslash prefix (\\rm), command prefix, env prefix.
     """
-    for pattern, message in DANGEROUS_PATTERNS:
-        if re.search(pattern, command, re.IGNORECASE):
-            return True, message
+    stripped = command
+    # Strip leading backslash from commands (e.g. \rm -> rm)
+    stripped = re.sub(r"(?:^|(?<=\s))\\(?=\w)", "", stripped)
+    # Strip 'command' prefix (e.g. 'command rm' -> 'rm')
+    stripped = re.sub(r"\bcommand\s+", "", stripped)
+    # Strip 'env' prefix with optional VAR=val args (e.g. 'env VAR=x rm' -> 'rm')
+    stripped = re.sub(r"\benv\s+(?:\w+=\S+\s+)*", "", stripped)
+    return stripped
+
+
+def check_command(command: str) -> tuple[bool, str]:
+    """Check if command matches any dangerous pattern."""
+    stripped = strip_command_prefixes(command)
+    # Check both original and stripped versions
+    for cmd in (command, stripped):
+        for pattern, message in DANGEROUS_PATTERNS:
+            if re.search(pattern, cmd, re.IGNORECASE):
+                return True, message
     return False, ""
 
 
@@ -127,9 +201,9 @@ def main():
         # Fail closed: can't parse means can't verify safety
         sys.exit(2)
     except Exception as e:
-        # Log error but don't block on hook failure
+        # Fail closed: unexpected errors should block, not allow
         print(f"Hook error: {e}", file=sys.stderr)
-        sys.exit(0)
+        sys.exit(2)
 
 
 if __name__ == "__main__":

package/.devcontainer/plugins/devs-marketplace/plugins/git-workflow/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "git-workflow",
+  "description": "Standalone git workflow: review, commit, push, PR creation, and PR review",
+  "author": {
+    "name": "AnExiledDev"
+  }
+}

package/.devcontainer/plugins/devs-marketplace/plugins/git-workflow/README.md

@@ -0,0 +1,125 @@
+# git-workflow
+
+Claude Code plugin that provides standalone git workflow commands. Not tied to the EARS ticket lifecycle — works independently, but optionally links to tickets when context exists.
+
+## What It Does
+
+Provides two slash commands for shipping code and reviewing pull requests.
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ship` | Review all changes, commit with a detailed message, push, and optionally create a PR |
+| `/pr:review` | Review an existing PR by number/URL or auto-detect from current branch (never merges) |
+
+## How It Works
+
+### `/ship` Workflow
+
+```text
+/ship [optional commit message hint]
+  │
+  └─→ Gather context (git status, diff, branch, project rules)
+       │
+       └─→ Full review (security, rules, quality, architecture, tests)
+            │
+            └─→ Present findings → User decisions (fix/issue/ignore)
+                 │
+                 └─→ Draft commit message → User approval
+                      │
+                      └─→ Commit + Push
+                           │
+                           └─→ AskUserQuestion: "Create a PR?"
+                                │
+                                ├─→ Yes: Create PR (+ link ticket if context exists)
+                                └─→ No: Done
+```
+
+### `/pr:review` Workflow
+
+```text
+/pr:review [PR number, URL, or omit for auto-detect]
+  │
+  └─→ Identify target PR (argument, auto-detect, or ask)
+       │
+       └─→ Fetch PR details + diff + changed files
+            │
+            └─→ Aggressive analysis (attack surface, threats, deps, rules, architecture, quality, tests, breaking changes)
+                 │
+                 └─→ Present findings → User decisions (note/issue/ignore)
+                      │
+                      └─→ Post review comment (NEVER approve/merge)
+```
+
+### Ticket Awareness
+
+Both commands are **optionally ticket-aware**:
+- If a ticket number exists in the session context (from a prior `/ticket:work` call), it is linked in commit messages, PRs, and issue comments
+- If reviewing a PR that references a ticket in its body (`Closes #N`, `Refs #N`), requirements are verified against the diff
+- Neither command prompts for a ticket — they work fully standalone
+
+### Review Depth
+
+| Command | Review Depth | Purpose |
+|---------|-------------|---------|
+| `/ship` | Full (same as `/ticket:review-commit`) | Pre-commit gate — catches issues before they enter history |
+| `/pr:review` | Aggressive (same as `/ticket:create-pr`) | Final gate — deep security, threat modeling, and architecture review |
+
+### Finding Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| Critical | Active vulnerability, data exposure, auth bypass, breaking production |
+| High | Security weakness, significant bug, major pattern violation |
+| Medium | Code smell, minor vulnerability, missing validation |
+| Low | Style, optimization, minor improvements |
+| Info | Observations, questions, future considerations |
+
+## Installation
+
+### CodeForge DevContainer
+
+Pre-installed and activated automatically — no setup needed.
+
+### From GitHub
+
+Use this plugin in any Claude Code setup:
+
+1. Clone the [CodeForge](https://github.com/AnExiledDev/CodeForge) repository:
+
+   ```bash
+   git clone https://github.com/AnExiledDev/CodeForge.git
+   ```
+
+2. Enable the plugin in your `.claude/settings.json`:
+
+   ```json
+   {
+     "enabledPlugins": {
+       "git-workflow@<clone-path>/.devcontainer/plugins/devs-marketplace": true
+     }
+   }
+   ```
+
+   Replace `<clone-path>` with the absolute path to your CodeForge clone.
+
+## Plugin Structure
+
+```text
+git-workflow/
+├── .claude-plugin/
+│   └── plugin.json          # Plugin metadata
+├── skills/
+│   ├── ship/
+│   │   └── SKILL.md         # /ship command definition
+│   └── pr-review/
+│       └── SKILL.md         # /pr:review command definition
+└── README.md                # This file
+```
+
+## Requirements
+
+- Claude Code with plugin command support
+- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated
+- A GitHub repository as the working context