diff --git a/.devcontainer/CHANGELOG.md b/.devcontainer/CHANGELOG.md index 3c0738d..ed0d765 100644 --- a/.devcontainer/CHANGELOG.md +++ b/.devcontainer/CHANGELOG.md @@ -52,6 +52,18 @@ ### Fixed +#### Post-Integration Review Fixes +- **skill-engine** — worktree skill definition uses weighted tuples (was plain strings, caused crash) +- **dangerous-command-blocker** — fail closed on unexpected exceptions (was fail-open) +- **ticket-workflow** — remove redundant `ValueError` from exception handlers +- **workspace-scope-guard** — use maxsplit in variable assignment detection +- **Shell scripts** — add executable bit to `check-setup.sh`, quote `PLUGIN_BLACKLIST` variable, add `set -uo pipefail` to tmux installer, replace deprecated `which` with `command -v`, normalize `&>` redirects in setup scripts +- **Documentation** — update agent count to 21, skill count to 38, plugin count to 14 across all docs site pages +- **Documentation** — add missing plugin pages for git-workflow and prompt-snippets +- **Documentation** — add `cc-orc` and `dbr` to commands reference +- **Documentation** — remove merge conflict marker from first-session.md +- **Documentation** — update architecture.md directory tree with new plugins + #### CodeRabbit Review Fixes - **`implementer.md`** — changed PostToolUse hook (fires every Edit) to Stop hook (fires once at task end) with 120s timeout; prevents redundant test runs during multi-file tasks - **`tester.md`** — increased Stop hook timeout from 30s to 120s to accommodate larger test suites diff --git a/.devcontainer/connect-external-terminal.sh b/.devcontainer/connect-external-terminal.sh index 4d7e58a..6161c27 100755 --- a/.devcontainer/connect-external-terminal.sh +++ b/.devcontainer/connect-external-terminal.sh @@ -49,7 +49,7 @@ echo "Found container: $CONTAINER_NAME ($CONTAINER_ID)" echo "" # Check if tmux is available in the container -if ! docker exec "$CONTAINER_ID" which tmux >/dev/null 2>&1; then +if ! docker exec "$CONTAINER_ID" command -v tmux >/dev/null 2>&1; then echo "ERROR: tmux is not installed in the container." echo "Rebuild the devcontainer to install the tmux feature." exit 1 diff --git a/.devcontainer/features/tmux/install.sh b/.devcontainer/features/tmux/install.sh index 1cc4dca..b564c33 100755 --- a/.devcontainer/features/tmux/install.sh +++ b/.devcontainer/features/tmux/install.sh @@ -1,7 +1,7 @@ #!/bin/bash # SPDX-License-Identifier: GPL-3.0-only # Copyright (c) 2026 Marcus Krueger -set -e +set -euo pipefail VERSION="${VERSION:-latest}" diff --git a/.devcontainer/plugins/devs-marketplace/plugins/dangerous-command-blocker/scripts/block-dangerous.py b/.devcontainer/plugins/devs-marketplace/plugins/dangerous-command-blocker/scripts/block-dangerous.py index 4c45eb9..1bebdf3 100644 --- a/.devcontainer/plugins/devs-marketplace/plugins/dangerous-command-blocker/scripts/block-dangerous.py +++ b/.devcontainer/plugins/devs-marketplace/plugins/dangerous-command-blocker/scripts/block-dangerous.py @@ -127,9 +127,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__": diff --git a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/scripts/skill-suggester.py b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/scripts/skill-suggester.py index 2b778fc..f6639de 100644 --- a/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/scripts/skill-suggester.py +++ b/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/scripts/skill-suggester.py @@ -546,18 +546,19 @@ }, "worktree": { "phrases": [ - "create a worktree", - "work in a worktree", - "git worktree", - "worktree", - "parallel branches", - "isolate my work", - "clean up worktrees", - "list worktrees", - "set up a worktree", - "enter worktree", + ("create a worktree", 0.9), + ("work in a worktree", 0.8), + ("git worktree", 0.9), + ("worktree", 0.7), + ("parallel branches", 0.6), + ("isolate my work", 0.5), + ("clean up worktrees", 0.8), + ("list worktrees", 0.7), + ("set up a worktree", 0.8), + ("enter worktree", 0.8), ], "terms": ["worktree", "EnterWorktree", "WorktreeCreate"], + "priority": 5, }, } diff --git a/.devcontainer/plugins/devs-marketplace/plugins/ticket-workflow/scripts/ticket-linker.py b/.devcontainer/plugins/devs-marketplace/plugins/ticket-workflow/scripts/ticket-linker.py index 24a73ce..0a06892 100644 --- a/.devcontainer/plugins/devs-marketplace/plugins/ticket-workflow/scripts/ticket-linker.py +++ b/.devcontainer/plugins/devs-marketplace/plugins/ticket-workflow/scripts/ticket-linker.py @@ -71,7 +71,7 @@ def fetch_ticket(number: int) -> str | None: try: data = json.loads(result.stdout) - except (json.JSONDecodeError, ValueError): + except json.JSONDecodeError: return None title = data.get("title", "(no title)") @@ -103,7 +103,7 @@ def main(): try: data = json.loads(raw) - except (json.JSONDecodeError, ValueError): + except json.JSONDecodeError: sys.exit(0) prompt = data.get("prompt", "") diff --git a/.devcontainer/plugins/devs-marketplace/plugins/workspace-scope-guard/scripts/guard-workspace-scope.py b/.devcontainer/plugins/devs-marketplace/plugins/workspace-scope-guard/scripts/guard-workspace-scope.py index a6bda4f..9e30ec1 100755 --- a/.devcontainer/plugins/devs-marketplace/plugins/workspace-scope-guard/scripts/guard-workspace-scope.py +++ b/.devcontainer/plugins/devs-marketplace/plugins/workspace-scope-guard/scripts/guard-workspace-scope.py @@ -157,7 +157,7 @@ def extract_primary_command(command: str) -> str: while i < len(tokens): tok = tokens[i] # Skip inline variable assignments: VAR=value - if "=" in tok and not tok.startswith("-") and tok.split("=")[0].isidentifier(): + if "=" in tok and not tok.startswith("-") and tok.split("=", 1)[0].isidentifier(): i += 1 continue # Skip sudo and its flags diff --git a/.devcontainer/scripts/check-setup.sh b/.devcontainer/scripts/check-setup.sh old mode 100644 new mode 100755 diff --git a/.devcontainer/scripts/setup-plugins.sh b/.devcontainer/scripts/setup-plugins.sh index 71f12b0..be51bd9 100755 --- a/.devcontainer/scripts/setup-plugins.sh +++ b/.devcontainer/scripts/setup-plugins.sh @@ -59,7 +59,7 @@ if [ -d "$MARKETPLACE_PATH/plugins" ]; then plugin_name=$(basename "$plugin_dir") # Skip blacklisted plugins - if echo ",$PLUGIN_BLACKLIST," | grep -q ",$plugin_name,"; then + if echo ",${PLUGIN_BLACKLIST}," | grep -q ",$plugin_name,"; then echo "[setup-plugins] Skipping $plugin_name (blacklisted)" continue fi diff --git a/.devcontainer/scripts/setup-projects.sh b/.devcontainer/scripts/setup-projects.sh index 2b194ce..a7ad5a4 100755 --- a/.devcontainer/scripts/setup-projects.sh +++ b/.devcontainer/scripts/setup-projects.sh @@ -178,7 +178,7 @@ start_watcher() { fi # Check if inotifywait is available (installed by tmux feature at build time) - if ! command -v inotifywait &>/dev/null; then + if ! command -v inotifywait >/dev/null 2>&1; then echo "$LOG_PREFIX WARNING: inotify-tools not installed, watcher disabled" return 1 fi diff --git a/.devcontainer/scripts/setup-terminal.sh b/.devcontainer/scripts/setup-terminal.sh index d56f46c..abc82ec 100755 --- a/.devcontainer/scripts/setup-terminal.sh +++ b/.devcontainer/scripts/setup-terminal.sh @@ -21,7 +21,7 @@ fi # === Merge or create keybindings === BINDING='{"key":"shift+enter","command":"workbench.action.terminal.sendSequence","args":{"text":"\\u001b\\r"},"when":"terminalFocus"}' -if [ -f "$KEYBINDINGS_FILE" ] && command -v jq &>/dev/null; then +if [ -f "$KEYBINDINGS_FILE" ] && command -v jq >/dev/null 2>&1; then # Merge into existing keybindings if jq empty "$KEYBINDINGS_FILE" 2>/dev/null; then jq ". + [$BINDING]" "$KEYBINDINGS_FILE" >"$KEYBINDINGS_FILE.tmp" && diff --git a/docs/src/content/docs/features/agents.md b/docs/src/content/docs/features/agents.md index b15f0b8..4bb25af 100644 --- a/docs/src/content/docs/features/agents.md +++ b/docs/src/content/docs/features/agents.md @@ -1,11 +1,11 @@ --- title: Agents -description: Complete reference for all 17 CodeForge agents — capabilities, tool access, and use cases. +description: Complete reference for all 21 CodeForge agents — capabilities, tool access, and use cases. sidebar: order: 2 --- -CodeForge provides 17 specialized agents, each configured with a focused system prompt, specific tool access, and domain expertise. Claude automatically delegates to the appropriate agent based on your request — ask about architecture and you get the architect; ask for a security review and you get the security auditor. +CodeForge provides 21 specialized agents, each configured with a focused system prompt, specific tool access, and domain expertise. Claude automatically delegates to the appropriate agent based on your request — ask about architecture and you get the architect; ask for a security review and you get the security auditor. ## How Agents Work diff --git a/docs/src/content/docs/features/index.md b/docs/src/content/docs/features/index.md index 6265c9c..c80ee18 100644 --- a/docs/src/content/docs/features/index.md +++ b/docs/src/content/docs/features/index.md @@ -13,24 +13,24 @@ This section is your reference guide to everything CodeForge provides. Whether y Out of the box, CodeForge gives you: -- **17 specialized AI agents** with focused expertise and safety-calibrated tool access -- **34 domain knowledge packs** (skills) for frameworks, patterns, and workflows -- **21 CLI tools** for session management, code quality, and development +- **21 specialized AI agents** with focused expertise and safety-calibrated tool access +- **38 domain knowledge packs** (skills) for frameworks, patterns, and workflows +- **22 CLI tools** for session management, code quality, and development - **3 layers of code intelligence** — AST-based search, syntax parsing, and LSP semantic analysis -- **12 plugins** that wire everything together with hooks, guards, and automation +- **14 plugins** that wire everything together with hooks, guards, and automation All of these features work together. An agent can load skills for domain expertise, use CLI tools for code quality checks, and leverage code intelligence for precise navigation — all orchestrated automatically. ## AI Agents -CodeForge includes **17 specialized AI agents**, each with focused expertise, calibrated tool access, and a detailed system prompt that shapes its behavior. When you ask Claude a question, the agent system automatically delegates to the right specialist — an architect for design questions, a security auditor for vulnerability reviews, a test writer for coverage gaps. +CodeForge includes **21 specialized AI agents**, each with focused expertise, calibrated tool access, and a detailed system prompt that shapes its behavior. When you ask Claude a question, the agent system automatically delegates to the right specialist — an architect for design questions, a security auditor for vulnerability reviews, a test writer for coverage gaps. Agents fall into two categories: -- **Read-only agents** (10 total) — can search, read, and analyze your codebase but never modify it. These include the architect, explorer, security auditor, researcher, dependency analyst, and spec-writer. -- **Full-access agents** (7 total) — can read, write, and execute commands. These include the test writer, refactorer, migrator, doc writer, and generalist. +- **Read-only agents** (11 total) — can search, read, and analyze your codebase but never modify it. These include the architect, explorer, investigator, security auditor, researcher, dependency analyst, and spec-writer. +- **Full-access agents** (10 total) — can read, write, and execute commands. These include the implementer, tester, documenter, test writer, refactorer, migrator, doc writer, and generalist. -A key distinction: CodeForge doesn't just add new agents — it **replaces Claude Code's six built-in agent types entirely**. A `PreToolUse` hook intercepts every agent spawn and transparently redirects stock agents (Explore, Plan, general-purpose, Bash, claude-code-guide, statusline-setup) to enhanced custom specialists with frontloaded skills, calibrated models, and safety hooks. You never interact with a generic agent — every request is silently upgraded. The remaining 11 agents (test-writer, refactorer, security-auditor, and others) are entirely new specialists with no built-in equivalent. +A key distinction: CodeForge doesn't just add new agents — it **replaces Claude Code's six built-in agent types entirely**. A `PreToolUse` hook intercepts every agent spawn and transparently redirects stock agents (Explore, Plan, general-purpose, Bash, claude-code-guide, statusline-setup) to enhanced custom specialists with frontloaded skills, calibrated models, and safety hooks. You never interact with a generic agent — every request is silently upgraded. The remaining 15 agents (test-writer, refactorer, security-auditor, and others) are entirely new specialists with no built-in equivalent. Key safety features set CodeForge agents apart: @@ -39,11 +39,11 @@ Key safety features set CodeForge agents apart: - **Hook enforcement** — read-only agents have bash guards that block any command that could modify files. The refactorer runs tests after every single edit. The test writer verifies all tests pass before completing. - **Built-in replacement** — all six of Claude Code's stock agents are intercepted at the hook level and replaced with strictly better specialists. This is enforced, not suggested. -[View all 17 agents →](./agents/) +[View all 21 agents →](./agents/) ## Skills -**34 domain-specific knowledge packs** give Claude deep expertise in frameworks, patterns, and workflows. The skill engine provides 21 core skills covering frameworks, practices, and Claude/CodeForge topics. Additional skills come from the spec-workflow (8), ticket-workflow (4), and agent-system (1) plugins. When you start discussing FastAPI routes or Svelte 5 runes, the skill engine detects the context and auto-suggests the relevant skill. Once loaded, the skill injects structured knowledge — best practices, code patterns, API references, and common pitfalls — directly into Claude's context for the current task. +**38 domain-specific knowledge packs** give Claude deep expertise in frameworks, patterns, and workflows. The skill engine provides 22 core skills covering frameworks, practices, and Claude/CodeForge topics. Additional skills come from the spec-workflow (8), ticket-workflow (4), git-workflow (2), agent-system (1), and prompt-snippets (1) plugins. When you start discussing FastAPI routes or Svelte 5 runes, the skill engine detects the context and auto-suggests the relevant skill. Once loaded, the skill injects structured knowledge — best practices, code patterns, API references, and common pitfalls — directly into Claude's context for the current task. Each skill is built around a "mental model" — a concise explanation of how a technology works, followed by concrete patterns, code examples, and guidance. This is not generic documentation; skills encode the kind of working knowledge a senior specialist carries. @@ -55,11 +55,11 @@ Skills cover three categories: | **Practices** | Testing, Debugging, Security, Refactoring, API Design | Methodology, checklists, and established patterns | | **Claude & CodeForge** | Agent SDK, Headless Mode, Skill Building, Spec Writing | Guidance for building on and extending CodeForge itself | -[View all 34 skills →](./skills/) +[View all 38 skills →](./skills/) ## CLI Tools -CodeForge pre-installs **21 tools and utilities** covering session management, code quality, language runtimes, and development infrastructure. Every tool is available on your `PATH` from the first terminal session — run `cc-tools` to see everything installed and its version. +CodeForge pre-installs **22 tools and utilities** covering session management, code quality, language runtimes, and development infrastructure. Every tool is available on your `PATH` from the first terminal session — run `cc-tools` to see everything installed and its version. Highlights include: @@ -89,9 +89,9 @@ CodeForge installs LSP servers for Python (Pyright), TypeScript/JavaScript, and | Category | Count | Highlights | |----------|-------|------------| -| [Agents](./agents/) | 17 | Architect, Explorer, Security Auditor, Test Writer, Refactorer, and 12 more | -| [Skills](./skills/) | 34 | FastAPI, Svelte 5, Docker, Testing, Debugging, Security, and 28 more | -| [CLI Tools](./tools/) | 21 | Session search, token tracking, code quality, formatters, and runtimes | +| [Agents](./agents/) | 21 | Architect, Explorer, Security Auditor, Test Writer, Refactorer, and 16 more | +| [Skills](./skills/) | 38 | FastAPI, Svelte 5, Docker, Testing, Debugging, Security, and 32 more | +| [CLI Tools](./tools/) | 22 | Session search, token tracking, code quality, formatters, and runtimes | | [Code Intelligence](./code-intelligence/) | 3 | ast-grep, tree-sitter, LSP servers for Python/TS/Go | ## How Features Are Delivered diff --git a/docs/src/content/docs/features/skills.md b/docs/src/content/docs/features/skills.md index 222be04..e1ea8e5 100644 --- a/docs/src/content/docs/features/skills.md +++ b/docs/src/content/docs/features/skills.md @@ -1,6 +1,6 @@ --- title: Skills -description: Complete reference for all 22 CodeForge skills — domain knowledge packs for frameworks, patterns, and workflows. +description: Complete reference for all 38 CodeForge skills — domain knowledge packs for frameworks, patterns, and workflows. sidebar: order: 3 --- diff --git a/docs/src/content/docs/getting-started/first-session.md b/docs/src/content/docs/getting-started/first-session.md index e693713..68d40d5 100644 --- a/docs/src/content/docs/getting-started/first-session.md +++ b/docs/src/content/docs/getting-started/first-session.md @@ -35,7 +35,7 @@ If something isn't working as expected in a CodeForge session, try `ccraw` to se When your session starts, several systems activate behind the scenes. You don't need to configure any of this — it just works. - **System prompt** — gives Claude context about your project, coding standards, and how to communicate. Customizable via [System Prompts](../customization/system-prompts/). -- **Plugin hooks** — 12 plugins fire automatically at key moments: blocking dangerous commands, guarding workspace scope, injecting git state, running code quality checks, and more. See the [Plugins Overview](../plugins/) for details on each one. +- **Plugin hooks** — 14 plugins fire automatically at key moments: blocking dangerous commands, guarding workspace scope, injecting git state, running code quality checks, and more. See the [Plugins Overview](../plugins/) for details on each one. - **Session context** — Claude always knows your current branch, uncommitted changes, recent commits, and active TODOs without you having to explain it. ## What to Try First @@ -96,7 +96,7 @@ claude-dashboard ## Agents and Skills -CodeForge includes **17 specialized agents** and **34 skills** that activate automatically based on what you're working on. You don't need to memorize names — just describe what you want, and Claude delegates to the right specialist. The examples in "What to Try First" above show this in action. +CodeForge includes **21 specialized agents** and **38 skills** that activate automatically based on what you're working on. You don't need to memorize names — just describe what you want, and Claude delegates to the right specialist. The examples in "What to Try First" above show this in action. - **[Agents](../features/agents/)** — specialized AI personas for architecture, debugging, testing, security, migrations, and more - **[Skills](../features/skills/)** — domain-specific knowledge packs (FastAPI, Docker, Svelte, debugging patterns, etc.) that the skill engine suggests automatically or you invoke with slash commands like `/spec-new` @@ -104,7 +104,6 @@ CodeForge includes **17 specialized agents** and **34 skills** that activate aut ## Understanding the Status Line If your terminal supports it, CodeForge provides a status line that shows session information at a glance. The `ccstatusline` feature adds session metadata to your terminal prompt, so you always know which session you're in and its current state. ->>>>>>> b9f14e6 (Add worktree skill for git worktree lifecycle guidance) ## Tips for Effective Sessions @@ -127,7 +126,7 @@ The session context plugin reminds you to commit when there are significant unco ## Next Steps - [Plugins Overview](../plugins/) — understand how each plugin enhances your workflow -- [Agents](../features/agents/) — explore all 17 specialized agents in detail +- [Agents](../features/agents/) — explore all 21 specialized agents in detail - [Skills](../features/skills/) — browse the complete skill catalog - [Configuration](../customization/configuration/) — customize CodeForge to match your preferences - [Commands Reference](../reference/commands/) — full reference for all CLI commands diff --git a/docs/src/content/docs/getting-started/index.md b/docs/src/content/docs/getting-started/index.md index 54372bf..40d3b9e 100644 --- a/docs/src/content/docs/getting-started/index.md +++ b/docs/src/content/docs/getting-started/index.md @@ -5,7 +5,7 @@ sidebar: order: 1 --- -CodeForge is a DevContainer configuration that transforms your development environment into an AI-powered workspace. It bundles 12 plugins, 21 tools, 17 specialized agents, and 34 skills into a single `npx codeforge-dev` install. +CodeForge is a DevContainer configuration that transforms your development environment into an AI-powered workspace. It bundles 14 plugins, 22 tools, 21 specialized agents, and 38 skills into a single `npx codeforge-dev` install. ## What is CodeForge? @@ -29,7 +29,7 @@ If you already have Docker and VS Code installed, you can go from zero to a runn **Start productive immediately.** New projects and new team members skip the setup ritual entirely. One command installs a complete, consistent environment with every tool pre-configured. -**AI that understands your workflow.** CodeForge doesn't just install Claude Code — it teaches it. System prompts, plugin hooks, and rules give Claude deep context about your project structure, coding standards, and preferred workflows. The agent system provides 17 specialized AI agents, each tuned for a specific task like architecture planning, debugging, or security auditing. +**AI that understands your workflow.** CodeForge doesn't just install Claude Code — it teaches it. System prompts, plugin hooks, and rules give Claude deep context about your project structure, coding standards, and preferred workflows. The agent system provides 21 specialized AI agents, each tuned for a specific task like architecture planning, debugging, or security auditing. **Safety built in.** Workspace scope guards prevent accidental writes outside your project directory. Dangerous command blockers catch destructive shell commands before they run. Protected file guards keep secrets and lock files safe. You get the power of AI-assisted development with guardrails that prevent costly mistakes. @@ -37,20 +37,22 @@ If you already have Docker and VS Code installed, you can go from zero to a runn ## What's Included -### 12 Plugins +### 14 Plugins Plugins are the backbone of CodeForge. They hook into Claude Code's lifecycle to enhance, guard, and automate your workflow. Highlights include: -- **Agent System** — 17 specialized agents for architecture, debugging, testing, security, and more +- **Agent System** — 21 specialized agents for architecture, debugging, testing, security, and more - **Skill Engine** — 22 domain-specific knowledge packs covering frameworks, patterns, and workflows - **Spec Workflow** — specification-driven development with 8 lifecycle skills - **Session Context** — automatic git state injection, TODO harvesting, and commit reminders - **Auto Code Quality** — formatting, linting, and advisory test runs on every change - **Safety Guards** — workspace scope, dangerous command blocking, and protected file enforcement +- **Git Workflow** — standalone /ship (review/commit/push/PR) and /pr:review commands +- **Prompt Snippets** — quick behavioral mode switches via /ps command See the [Plugins Overview](../plugins/) for the full list and detailed documentation. -### 21 Features and Tools +### 22 Features and Tools CodeForge installs a comprehensive toolchain so you never have to stop and install something mid-session: @@ -62,7 +64,7 @@ CodeForge installs a comprehensive toolchain so you never have to stop and insta See the [Features Overview](../features/) for the complete reference. -### 17 Custom Agents +### 21 Custom Agents Agents are specialized AI personas that Claude delegates to based on your request. Each agent carries domain-specific instructions and behavioral guidelines: @@ -71,11 +73,11 @@ Agents are specialized AI personas that Claude delegates to based on your reques - **Test Writer** — test generation with framework-aware patterns - **Security Auditor** — vulnerability detection and security review - **Refactorer** — safe, incremental code transformations -- And 12 more covering debugging, documentation, migration, performance, and beyond +- And 16 more covering debugging, documentation, migration, performance, and beyond See [Agents](../features/agents/) for the full roster. -### 34 Skills +### 38 Skills Skills are domain-specific knowledge packs that Claude can draw on. They provide curated best practices, patterns, and workflows for specific technologies and tasks: diff --git a/docs/src/content/docs/getting-started/installation.md b/docs/src/content/docs/getting-started/installation.md index d9f7ef0..47f9bbe 100644 --- a/docs/src/content/docs/getting-started/installation.md +++ b/docs/src/content/docs/getting-started/installation.md @@ -48,8 +48,8 @@ your-project/ │ ├── config/ │ │ ├── file-manifest.json # Controls config file deployment │ │ └── defaults/ # System prompts, settings, rules -│ ├── features/ # 21 custom DevContainer features -│ ├── plugins/ # 12 plugins with hooks and scripts +│ ├── features/ # 22 custom DevContainer features +│ ├── plugins/ # 14 plugins with hooks and scripts │ └── scripts/ # Setup and verification scripts └── ... (your existing files) ``` @@ -139,7 +139,7 @@ A few features ship with `"version": "none"` by default (shfmt, dprint, shellche ### Plugins -All 12 plugins are installed and active by default. They're configured through `settings.json` and managed by the plugin system. See the [Plugins Overview](../plugins/) for details on each plugin and how to enable or disable them. +All 14 plugins are installed and active by default. They're configured through `settings.json` and managed by the plugin system. See the [Plugins Overview](../plugins/) for details on each plugin and how to enable or disable them. ## Configuration diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 486eef7..5e5ff26 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -1,6 +1,6 @@ --- title: CodeForge -description: The complete Claude Code development environment. 12 plugins, 21 tools, 17 AI agents — battle-tested and ready to go. +description: The complete Claude Code development environment. 14 plugins, 22 tools, 21 AI agents — battle-tested and ready to go. template: splash hero: tagline: Your AI dev environment, battle-tested. diff --git a/docs/src/content/docs/plugins/agent-system.md b/docs/src/content/docs/plugins/agent-system.md index bfe54c6..118dde5 100644 --- a/docs/src/content/docs/plugins/agent-system.md +++ b/docs/src/content/docs/plugins/agent-system.md @@ -1,11 +1,11 @@ --- title: Agent System -description: The agent system plugin provides 17 specialized AI agents with automatic delegation, CWD injection, and read-only enforcement. +description: The agent system plugin provides 21 specialized AI agents with automatic delegation, CWD injection, and read-only enforcement. sidebar: order: 2 --- -The agent system is CodeForge's flagship plugin. It gives you access to 17 specialized AI agents, each purpose-built for a specific kind of development task — from architecture planning and code exploration to test writing and security auditing. When you make a request, the system automatically delegates to the most appropriate agent, so you get expert-level results without having to think about which tool to use. +The agent system is CodeForge's flagship plugin. It gives you access to 21 specialized AI agents, each purpose-built for a specific kind of development task — from architecture planning and code exploration to test writing and security auditing. When you make a request, the system automatically delegates to the most appropriate agent, so you get expert-level results without having to think about which tool to use. ## How Delegation Works @@ -105,7 +105,7 @@ Read-only agents don't just have instructions saying "don't write files." The gu ## Agent Reference -CodeForge includes 17 specialized agents. Each one is tailored for a specific class of development task. +CodeForge includes 21 specialized agents. Each one is tailored for a specific class of development task. ### Read-Only Agents diff --git a/docs/src/content/docs/plugins/git-workflow.md b/docs/src/content/docs/plugins/git-workflow.md new file mode 100644 index 0000000..0e7b06e --- /dev/null +++ b/docs/src/content/docs/plugins/git-workflow.md @@ -0,0 +1,102 @@ +--- +title: Git Workflow +description: Standalone git workflow commands for reviewing changes, committing, pushing, creating PRs, and reviewing PRs. +sidebar: + order: 12 +--- + +The git workflow plugin provides standalone git operations through two slash commands: `/ship` for the full review-commit-push-PR workflow, and `/pr:review` for reviewing existing pull requests. These commands work independently of the ticket workflow but optionally link to tickets when context exists. + +## Commands + +### `/ship` — Review, Commit, Push & Optional PR + +Reviews all changes (staged and unstaged), commits with a detailed message, pushes to remote, and optionally creates a pull request. + +**Usage:** +``` +/ship [optional commit message hint] +``` + +**Process:** +1. Gathers git context (status, diff, branch info, project rules) +2. Conducts full review (security, rules adherence, code quality, architecture, tests) +3. Presents findings by severity — user decides what to fix, defer to issues, or ignore +4. Drafts commit message — user must approve before committing +5. Commits and pushes +6. Asks whether to create a PR — only creates if user confirms + +**Review Categories:** +- Security (secrets, injection, auth/authz, data exposure, dependencies, input validation) +- Project Rules (CLAUDE.md, .claude/rules/*.md compliance) +- Code Quality (complexity, duplication, naming, error handling, SOLID violations, dead code) +- Architecture (pattern compliance, coupling, API contracts, cohesion) +- Tests (behavior coverage, test quality, brittleness, over/under-testing) + +**Finding Severity:** +- **Critical** — Must fix before commit (security vulnerability, data loss risk, breaking production) +- **High** — Should fix before commit (significant bug, major pattern violation, auth issue) +- **Medium** — Fix soon (code smell, minor bug, missing validation) +- **Low** — Nice to have (style issue, minor optimization, documentation gap) +- **Info** — Observations, questions, future considerations + +**Ticket Integration:** +If a ticket number is available from a prior `/ticket:work` call, `/ship` automatically links the commit and PR to that ticket. The command never prompts for a ticket — it works standalone. + +:::tip[Full Review Always Runs] +The `/ship` command performs a comprehensive review before every commit. This is not optional — it ensures code quality and security are checked at the point of commit, not later in the PR review. +::: + +### `/pr:review` — Review Existing PR + +Reviews an existing pull request and posts findings as a PR comment. Never approves or merges. + +**Usage:** +``` +/pr:review [PR number, URL, or omit for current branch] +``` + +**Process:** +1. Identifies target PR (by number, URL, or auto-detects from current branch) +2. Fetches PR details, diff, and reads changed files in full +3. Conducts aggressive analysis (attack surface, threat modeling, dependencies, rules, architecture, quality, tests, breaking changes) +4. Presents findings by severity — user selects what to include in review, create as issues, or ignore +5. Posts review comment to PR (never approves or merges) + +**Analysis Depth:** +PR review is deeper than commit review — it is the final gate before merge. Key differences: +- **Attack surface analysis** — maps every new endpoint, input vector, permission change, data flow, and external integration +- **Threat modeling** — for each significant feature: what could an attacker exploit? What data could be exfiltrated? What operations could be abused? +- **Dependency security** — lists all new dependencies with versions, checks for known CVEs, assesses supply chain risks, verifies license compatibility +- **Requirements verification** — if PR references a ticket, cross-references each requirement and acceptance criterion + +**Auto-Detection:** +The command tries three approaches to find the PR: +1. If you provide a PR number (e.g., `/pr:review 42`), it fetches that PR +2. If you provide a URL, it parses the number and fetches it +3. If you omit the argument, it auto-detects the PR for your current branch + +If all three fail, it prompts for the PR number. + +:::caution[Review Only, Never Merge] +The `/pr:review` command posts a review comment to the PR but never approves or merges. Human approval is always required before merge. The review is marked as "Requires human approval" and includes a footer noting it is automated. +::: + +## Hook Scripts + +The git-workflow plugin provides no hooks — all functionality is delivered through the two slash commands. + +## Integration with Ticket Workflow + +The git-workflow plugin optionally integrates with the [Ticket Workflow](./ticket-workflow/) plugin: +- If you used `/ticket:work` to start working on a ticket, `/ship` automatically detects the ticket context and links the commit and PR +- If you used `/ticket:create-pr`, you get ticket-aware PR creation through that workflow +- If you're working without a ticket, `/ship` and `/pr:review` work standalone — no prompts, no ticket required + +The git-workflow commands are designed to work whether you're following the ticket workflow or just doing ad-hoc work. + +## Related + +- [Ticket Workflow](./ticket-workflow/) — EARS-formatted ticket workflow that integrates with `/ship` +- [Session Context](./session-context/) — provides the git state that both commands rely on +- [Skills Reference](../features/skills/) — the `/ship` and `/pr:review` skills are also documented in the skills catalog diff --git a/docs/src/content/docs/plugins/index.md b/docs/src/content/docs/plugins/index.md index f6bd375..9065505 100644 --- a/docs/src/content/docs/plugins/index.md +++ b/docs/src/content/docs/plugins/index.md @@ -43,7 +43,7 @@ The `plugin.json` manifest is minimal — it identifies the plugin and its autho ```json { "name": "agent-system", - "description": "17 custom agents with built-in agent redirection, CWD injection, and read-only bash enforcement", + "description": "21 custom agents with built-in agent redirection, CWD injection, and read-only bash enforcement", "author": { "name": "AnExiledDev" } @@ -96,7 +96,7 @@ See [Hooks](../customization/hooks/) for the full hook API and configuration det ## Installed Plugins -CodeForge ships with 11 local marketplace plugins plus 1 external Anthropic plugin, organized into two categories: **core plugins** that provide primary functionality, and **safety and integration plugins** that protect your work and connect to external tools. +CodeForge ships with 13 local marketplace plugins plus 1 external Anthropic plugin, organized into two categories: **core plugins** that provide primary functionality, and **safety and integration plugins** that protect your work and connect to external tools. ### Core Plugins @@ -104,10 +104,12 @@ These plugins deliver the headline features of CodeForge — intelligent delegat | Plugin | What It Does | |--------|-------------| -| [Agent System](./agent-system/) | 17 specialized agents with automatic delegation, CWD injection, and read-only enforcement | +| [Agent System](./agent-system/) | 21 specialized agents with automatic delegation, CWD injection, and read-only enforcement | | [Skill Engine](./skill-engine/) | 22 domain skills with context-aware auto-suggestion | | [Spec Workflow](./spec-workflow/) | Full specification lifecycle from creation through implementation to as-built closure | | [Ticket Workflow](./ticket-workflow/) | GitHub issue integration with EARS-formatted tickets and automated PR reviews | +| [Git Workflow](./git-workflow/) | Standalone git operations: /ship (review/commit/push/PR) and /pr:review | +| [Prompt Snippets](./prompt-snippets/) | Quick behavioral mode switches via /ps command | ### Safety Plugins diff --git a/docs/src/content/docs/plugins/prompt-snippets.md b/docs/src/content/docs/plugins/prompt-snippets.md new file mode 100644 index 0000000..f175795 --- /dev/null +++ b/docs/src/content/docs/plugins/prompt-snippets.md @@ -0,0 +1,88 @@ +--- +title: Prompt Snippets +description: Quick behavioral mode switches via the /ps command for common workflow adjustments. +sidebar: + order: 13 +--- + +The prompt snippets plugin provides quick behavioral mode switches through the `/ps` command. Instead of writing out full instructions every time you want Claude to work differently (be brief, don't take action, build a plan first), you invoke a named snippet that applies a preset instruction for the remainder of the conversation. + +## How It Works + +Use `/ps` followed by a snippet name: + +``` +/ps noaction +``` + +Claude applies that snippet's instruction and follows it for the rest of the conversation unless you explicitly override it with another instruction or snippet. + +## Available Snippets + +| Snippet | Instruction | +|---------|-------------| +| `noaction` | Investigate and report only. Take no action — no edits, no commands, no file writes. | +| `brief` | Be concise. Short answers, no filler, no preamble. Answer the question and stop. | +| `plan` | Build a plan before taking any action. Do not implement until the plan is explicitly approved. | +| `go` | Proceed without asking for confirmation. Use your best judgment on all decisions. | +| `review` | Review and audit only. Report findings with specific file paths and line numbers. Do not modify anything. | +| `ship` | Commit all staged changes, push to remote, and create a pull request. | +| `deep` | Be thorough and comprehensive. Investigate in depth, consider edge cases, leave no stone unturned. | +| `hold` | Complete the current task but do not commit, push, or publish. Await my review before any git operations. | +| `recall` | Search past session history with `ccms --no-color --project "$(pwd)"` to find prior decisions, discussions, and context relevant to the current task. Summarize what you find before proceeding. | +| `wait` | When done, stop. Do not suggest next steps, ask follow-up questions, or continue with related work. Await further instructions. | + +:::tip[When to Use Snippets] +Snippets are most useful when you want to quickly adjust Claude's behavior without writing out full custom instructions. Common scenarios: +- `noaction` before asking exploratory questions ("What does this function do?") +- `brief` when you want quick answers without context +- `plan` before starting a complex feature +- `go` when you're confident and want Claude to proceed autonomously +- `recall` when you need to recover context from past sessions +::: + +## Composing Snippets + +Multiple snippets can be applied in one invocation by separating names with spaces: + +``` +/ps noaction brief +``` + +This applies both snippets. If instructions conflict, the **last snippet wins** for that specific behavior. For example: + +``` +/ps plan go +``` + +The `plan` snippet says "build a plan first," but `go` says "proceed without confirmation," so the net effect is: build a plan, but don't ask for approval before implementing it — just show the plan and start. + +## Snippet Persistence + +Snippets apply for the **remainder of the conversation** unless: +- You invoke `/ps` again with different snippets (replaces the previous ones) +- You give explicit instructions that override the snippet ("actually, go ahead and edit the file") +- The session ends (snippets don't persist across sessions) + +If you want to clear a snippet, you can either: +- Say "ignore the previous /ps instruction" +- Invoke `/ps` with an empty argument (this clears all active snippets) + +## Common Combinations + +| Combination | Effect | +|-------------|--------| +| `noaction brief` | Investigate and report, but keep answers short | +| `review deep` | Thorough audit with comprehensive findings, no modifications | +| `plan go` | Build a plan and implement it without asking for approval | +| `brief wait` | Short answer, no follow-up suggestions | +| `recall plan` | Search past sessions for context, then build a plan | + +## Hook Scripts + +The prompt-snippets plugin provides no hooks — all functionality is delivered through the `/ps` slash command. + +## Related + +- [Skills Reference](../features/skills/) — the `/ps` skill is also documented in the skills catalog +- [Session Context](./session-context/) — provides git state and TODO context that pairs well with `recall` snippet diff --git a/docs/src/content/docs/reference/architecture.md b/docs/src/content/docs/reference/architecture.md index ec7fe77..4460ce4 100644 --- a/docs/src/content/docs/reference/architecture.md +++ b/docs/src/content/docs/reference/architecture.md @@ -85,7 +85,7 @@ Additional hook points (`SessionStart`, `SubagentStart`, `TeammateIdle`, `TaskCo ### Agent System -The agent system provides specialized personas with constrained tools and focus areas. CodeForge ships 17 custom agents: +The agent system provides specialized personas with constrained tools and focus areas. CodeForge ships 21 custom agents: **How agent routing works:** @@ -111,7 +111,7 @@ Skills are Markdown knowledge files loaded on demand during a session: 4. The skill content is injected into the conversation context 5. Claude uses the skill knowledge for the current task -CodeForge ships 35 skills across the skill-engine, spec-workflow, ticket-workflow, and agent-system plugins. +CodeForge ships 38 skills across the skill-engine, spec-workflow, ticket-workflow, git-workflow, agent-system, and prompt-snippets plugins. ## Directory Structure @@ -141,11 +141,11 @@ CodeForge ships 35 skills across the skill-engine, spec-workflow, ticket-workflo | +-- tree-sitter/ # Syntax parsing | +-- ruff/ # Python formatter/linter | +-- biome/ # JS/TS formatter/linter -| +-- ... (21 features total) +| +-- ... (22 features total) +-- plugins/ | +-- devs-marketplace/ | +-- plugins/ -| +-- agent-system/ # 17 agents + redirection hooks +| +-- agent-system/ # 21 agents + redirection hooks | +-- skill-engine/ # 22 skills + auto-suggestion | +-- spec-workflow/ # 8 spec lifecycle skills | +-- session-context/ # Git state, TODOs, commit reminders @@ -153,8 +153,10 @@ CodeForge ships 35 skills across the skill-engine, spec-workflow, ticket-workflo | +-- dangerous-command-blocker/ # Block destructive commands | +-- protected-files-guard/ # Block edits to sensitive files | +-- workspace-scope-guard/ # Enforce project isolation -| +-- ticket-workflow/ # GitHub issue/PR workflow +| +-- ticket-workflow/ # 4 ticket lifecycle skills +| +-- git-workflow/ # 2 git operation skills (/ship, /pr:review) | +-- notify-hook/ # Desktop notifications +| +-- prompt-snippets/ # 1 behavioral mode switch skill | +-- codeforge-lsp/ # Language servers +-- scripts/ # Setup scripts (run via postStartCommand) +-- setup.sh # Main orchestrator diff --git a/docs/src/content/docs/reference/changelog.md b/docs/src/content/docs/reference/changelog.md index 6ef6048..5efbea8 100644 --- a/docs/src/content/docs/reference/changelog.md +++ b/docs/src/content/docs/reference/changelog.md @@ -49,6 +49,20 @@ For minor and patch updates, you can usually just rebuild the container. Check t ## Unreleased +### Fixed + +#### Post-Integration Review Fixes +- **skill-engine** — worktree skill definition uses weighted tuples (was plain strings, caused crash) +- **dangerous-command-blocker** — fail closed on unexpected exceptions (was fail-open) +- **ticket-workflow** — remove redundant `ValueError` from exception handlers +- **workspace-scope-guard** — use maxsplit in variable assignment detection +- **Shell scripts** — add executable bit to `check-setup.sh`, quote `PLUGIN_BLACKLIST` variable, add `set -uo pipefail` to tmux installer, replace deprecated `which` with `command -v`, normalize `&>` redirects in setup scripts +- **Documentation** — update agent count to 21, skill count to 38, plugin count to 14 across all docs site pages +- **Documentation** — add missing plugin pages for git-workflow and prompt-snippets +- **Documentation** — add `cc-orc` and `dbr` to commands reference +- **Documentation** — remove merge conflict marker from first-session.md +- **Documentation** — update architecture.md directory tree with new plugins + ### Changed #### Configuration diff --git a/docs/src/content/docs/reference/commands.md b/docs/src/content/docs/reference/commands.md index 4355b16..10e35e2 100644 --- a/docs/src/content/docs/reference/commands.md +++ b/docs/src/content/docs/reference/commands.md @@ -17,6 +17,7 @@ Commands for launching and managing Claude Code sessions. | `claude` | Identical to `cc` | `claude` | | `ccw` | Launch Claude Code with the writing system prompt (for docs and prose) | `ccw` | | `ccraw` | Launch vanilla Claude Code with no custom config, prompts, or plugins | `ccraw` | +| `cc-orc` | Launch Claude Code in orchestrator mode (delegation-first workflow) | `cc-orc` | All session commands auto-detect the Claude binary location: `~/.local/bin/claude` (native install) is preferred, then `/usr/local/bin/claude`, then PATH lookup. If ChromaTerm (`ct`) is installed, output is wrapped through it for color highlighting. @@ -43,6 +44,7 @@ Commands for session analysis, usage tracking, and system monitoring. | `agent-browser` | Headless Chromium browser for agent automation with accessibility tree snapshots | `agent-browser` | | `check-setup` | Verify CodeForge installation health -- checks tools, config, and aliases | `check-setup` | | `cc-tools` | List all installed CodeForge CLI tools with version info | `cc-tools` | +| `dbr` | Dynamic port forwarding via devcontainer-bridge (container↔host) | `dbr` | ### ccms Usage @@ -202,10 +204,10 @@ Commands come from different sources in the CodeForge setup: | Source | Commands | How Defined | |--------|----------|-------------| -| Shell aliases | `cc`, `claude`, `ccw`, `ccraw`, `check-setup` | `setup-aliases.sh` writes to `.bashrc`/`.zshrc` | +| Shell aliases | `cc`, `claude`, `ccw`, `ccraw`, `cc-orc`, `check-setup` | `setup-aliases.sh` writes to `.bashrc`/`.zshrc` | | Shell functions | `cc-tools` | `setup-aliases.sh` writes to `.bashrc`/`.zshrc` | -| DevContainer features | `ccms`, `ccusage`, `ccburn`, `ruff`, `biome`, `sg`, etc. | `install.sh` in each feature directory | -| Slash commands | `/spec-new`, `/ticket:new`, `/ship`, `/pr:review`, etc. | Skill SKILL.md files in plugin directories | +| DevContainer features | `ccms`, `ccusage`, `ccburn`, `ruff`, `biome`, `sg`, `dbr`, etc. | `install.sh` in each feature directory | +| Slash commands | `/spec-new`, `/ticket:new`, `/ship`, `/pr:review`, `/ps`, etc. | Skill SKILL.md files in plugin directories | | External features | `gh`, `docker`, `node`, `bun`, `cargo` | Installed via `devcontainer.json` features | :::tip[Listing All Tools] diff --git a/docs/src/content/docs/reference/index.md b/docs/src/content/docs/reference/index.md index 1dc9b70..be7e748 100644 --- a/docs/src/content/docs/reference/index.md +++ b/docs/src/content/docs/reference/index.md @@ -69,10 +69,10 @@ These are the files you will interact with most often when configuring CodeForge | Component | Count | Details | |-----------|-------|---------| -| DevContainer features | 21 | Runtimes, CLI tools, monitoring | -| Plugins | 12 | Safety, quality, workflow, intelligence | -| Agents | 17 | Specialized personas from explorer to security-auditor | -| Skills | 34 | On-demand knowledge across coding, testing, frameworks | +| DevContainer features | 22 | Runtimes, CLI tools, monitoring | +| Plugins | 14 | Safety, quality, workflow, intelligence | +| Agents | 21 | Specialized personas from explorer to security-auditor | +| Skills | 38 | On-demand knowledge across coding, testing, frameworks | | Built-in rules | 3 | Workspace scope, spec workflow, session search | | CLI commands | 10+ | Session, analysis, code quality, intelligence |