diff --git a/.bin/install-commands.sh b/.bin/install-commands.sh deleted file mode 100755 index 475b272..0000000 --- a/.bin/install-commands.sh +++ /dev/null @@ -1,312 +0,0 @@ -#!/usr/bin/env bash -# Context Engineering Kit - Commands Installer -# -# Install for Cursor (default, project-level): -# curl -fsSL https://raw.githubusercontent.com/NeoLabHQ/context-engineering-kit/main/.bin/install-commands.sh | bash -# -# Install for Cursor globally (user-level): -# curl -fsSL https://raw.githubusercontent.com/NeoLabHQ/context-engineering-kit/main/.bin/install-commands.sh | bash -s -- --global -# -# Install for OpenCode: -# curl -fsSL https://raw.githubusercontent.com/NeoLabHQ/context-engineering-kit/main/.bin/install-commands.sh | bash -s -- --agent opencode -# -# Install for OpenCode globally: -# curl -fsSL https://raw.githubusercontent.com/NeoLabHQ/context-engineering-kit/main/.bin/install-commands.sh | bash -s -- --agent opencode --global -# -# This script downloads all plugin commands from the Context Engineering Kit -# and installs them to the appropriate commands directory. - -set -euo pipefail - -# Configuration -REPO_OWNER="NeoLabHQ" -REPO_NAME="context-engineering-kit" -BRANCH="master" -BASE_URL="https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/refs/heads/${BRANCH}" - -# Default agent -AGENT="cursor" - -# Global installation flag -GLOBAL=false - -# Colors for output -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -BLUE='\033[0;34m' -CYAN='\033[0;36m' -NC='\033[0m' # No Color - -# Logging functions -info() { echo -e "${BLUE}[INFO]${NC} $*"; } -success() { echo -e "${GREEN}[OK]${NC} $*"; } -warn() { echo -e "${YELLOW}[WARN]${NC} $*"; } -error() { echo -e "${RED}[ERROR]${NC} $*" >&2; } - -# Agent configurations -# Format: install_dir:display_name -declare -A AGENT_CONFIG=( - ["cursor"]=".claude/commands:Cursor" # Cursor uses claude code commands folder by some reason - ["opencode"]=".opencode/commands:OpenCode" - ["claude"]=".claude/commands:Claude Code" - ["windsurf"]=".windsurf/commands:Windsurf" - ["cline"]=".cline/commands:Cline" -) - -# Global agent configurations (user-level installation) -# Format: install_dir:display_name -declare -A AGENT_CONFIG_GLOBAL=( - ["cursor"]="${HOME}/.cursor/commands:Cursor (global)" - ["opencode"]="${HOME}/.config/opencode/command:OpenCode (global)" - ["claude"]="${HOME}/.claude/commands:Claude Code (global)" - ["windsurf"]="${HOME}/.windsurf/commands:Windsurf (global)" - ["cline"]="${HOME}/.cline/commands:Cline (global)" -) - -# Show help -show_help() { - echo "" - echo "Context Engineering Kit - Commands Installer" - echo "" - echo "Usage:" - echo " curl -fsSL | bash -s -- [OPTIONS]" - echo " ./install-commands.sh [OPTIONS]" - echo "" - echo "Options:" - echo " -a, --agent Target agent/IDE (default: cursor)" - echo " -g, --global Install to user-level directory (e.g., ~/.cursor/commands)" - echo " -d, --dir Custom install directory (overrides --agent and --global)" - echo " -l, --list List available agents" - echo " -h, --help Show this help message" - echo "" - echo "Supported agents:" - for agent in "${!AGENT_CONFIG[@]}"; do - local config="${AGENT_CONFIG[$agent]}" - local global_config="${AGENT_CONFIG_GLOBAL[$agent]}" - local dir="${config%%:*}" - local global_dir="${global_config%%:*}" - local name="${config#*:}" - printf " %-12s → %s (global: %s)\n" "$agent" "$dir" "$global_dir" - done | sort - echo "" - echo "Examples:" - echo " # Install for Cursor (default, project-level)" - echo " curl -fsSL | bash" - echo "" - echo " # Install for Cursor globally (user-level)" - echo " curl -fsSL | bash -s -- --global" - echo "" - echo " # Install for OpenCode globally" - echo " curl -fsSL | bash -s -- --agent opencode --global" - echo "" - echo " # Install to custom directory" - echo " curl -fsSL | bash -s -- --dir ./my-commands" - echo "" -} - -# List available agents -list_agents() { - echo "" - echo "Available agents:" - echo "" - # Sort agent names first, then iterate - local sorted_agents - sorted_agents=$(printf '%s\n' "${!AGENT_CONFIG[@]}" | sort) - while IFS= read -r agent; do - local config="${AGENT_CONFIG[$agent]}" - local global_config="${AGENT_CONFIG_GLOBAL[$agent]}" - local dir="${config%%:*}" - local global_dir="${global_config%%:*}" - printf " ${CYAN}%-12s${NC} → %s\n" "$agent" "$dir" - printf " --global: %s\n" "$global_dir" - done <<< "$sorted_agents" - echo "" -} - -# Parse command line arguments -parse_args() { - while [[ $# -gt 0 ]]; do - case $1 in - -a|--agent) - AGENT="$2" - shift 2 - ;; - -g|--global) - GLOBAL=true - shift - ;; - -d|--dir) - CUSTOM_DIR="$2" - shift 2 - ;; - -l|--list) - list_agents - exit 0 - ;; - -h|--help) - show_help - exit 0 - ;; - *) - error "Unknown option: $1" - show_help - exit 1 - ;; - esac - done -} - -# Get install directory for agent -get_install_dir() { - if [[ -n "${CUSTOM_DIR:-}" ]]; then - echo "$CUSTOM_DIR" - return - fi - - if [[ -z "${AGENT_CONFIG[$AGENT]:-}" ]]; then - error "Unknown agent: $AGENT" - echo "" - list_agents - exit 1 - fi - - local config - if [[ "$GLOBAL" == true ]]; then - config="${AGENT_CONFIG_GLOBAL[$AGENT]}" - else - config="${AGENT_CONFIG[$AGENT]}" - fi - echo "${config%%:*}" -} - -# Get display name for agent -get_agent_name() { - if [[ -n "${CUSTOM_DIR:-}" ]]; then - echo "Custom" - return - fi - - local config - if [[ "$GLOBAL" == true ]]; then - config="${AGENT_CONFIG_GLOBAL[$AGENT]}" - else - config="${AGENT_CONFIG[$AGENT]}" - fi - echo "${config#*:}" -} - -# Plugin definitions with their commands -# Format: plugin_name:command1,command2,command3 -PLUGINS=( - "code-review:review-local-changes,review-pr" - "customaize-agent:apply-anthropic-skill-best-practices,create-agent,create-command,create-hook,create-skill,create-workflow-command,test-prompt,test-skill" - "ddd:setup-code-formating" - "docs:update-docs" - "fpf:actualize,decay,propose-hypotheses,query,reset,status" - "git:analyze-issue,attach-review-to-pr,commit,create-pr,load-issues" - "kaizen:analyse-problem,analyse,cause-and-effect,plan-do-check-act,root-cause-tracing,why" - "mcp:build-mcp,setup-arxiv-mcp,setup-codemap-cli,setup-context7-mcp,setup-serena-mcp" - "reflexion:critique,memorize,reflect" - "sadd:do-competitively,do-in-parallel,do-in-steps,judge-with-debate,judge,launch-sub-agent,tree-of-thoughts" - "sdd:00-setup,01-specify,02-plan,03-tasks,04-implement,05-document,brainstorm,create-ideas" - "tdd:fix-tests,write-tests" - "tech-stack:add-typescript-best-practices" -) - -CURSOR_PLUGINS=( - "customaize-agent:apply-anthropic-skill-best-practices,create-agent,create-command,create-hook,create-skill,create-workflow-command" - "ddd:setup-code-formating" - "docs:update-docs" - "git:analyze-issue,attach-review-to-pr,commit,create-pr,load-issues" - "kaizen:analyse-problem,analyse,cause-and-effect,plan-do-check-act,root-cause-tracing,why" - "reflexion:critique,memorize,reflect" - "tech-stack:add-typescript-best-practices" -) - - -# Main installation function -install_commands() { - local install_dir - local agent_name - - install_dir=$(get_install_dir) - agent_name=$(get_agent_name) - - echo "" - echo "╔════════════════════════════════════════════════════════════╗" - echo "║ Context Engineering Kit - Commands Installer ║" - echo "╚════════════════════════════════════════════════════════════╝" - echo "" - - info "Target: ${agent_name}" - - # Create installation directory - mkdir -p "$install_dir" - info "Installing commands to ${install_dir}/" - echo "" - - local total_commands=0 - local installed_commands=0 - local failed_commands=0 - - # Select plugins array based on agent - local plugins_to_install - if [[ "$AGENT" == "cursor" ]]; then - plugins_to_install=("${CURSOR_PLUGINS[@]}") - else - plugins_to_install=("${PLUGINS[@]}") - fi - - for plugin_entry in "${plugins_to_install[@]}"; do - # Parse plugin name and commands - local plugin_name="${plugin_entry%%:*}" - local commands_str="${plugin_entry#*:}" - - info "Installing ${plugin_name} commands..." - - # Split commands by comma - IFS=',' read -ra commands <<< "$commands_str" - - for cmd in "${commands[@]}"; do - total_commands=$((total_commands + 1)) - - local source_url="${BASE_URL}/plugins/${plugin_name}/commands/${cmd}.md" - local target_file="${install_dir}/${cmd}.md" - - if curl -fsSL "$source_url" -o "$target_file"; then - success " ✓ ${plugin_name}:${cmd}" - installed_commands=$((installed_commands + 1)) - else - warn " ✗ ${plugin_name}:${cmd} - failed to download" - failed_commands=$((failed_commands + 1)) - rm -f "$target_file" || true - fi - done - done - - echo "" - echo "════════════════════════════════════════════════════════════" - echo "" - success "Installation complete!" - echo "" - info "Summary:" - echo " • Agent: ${agent_name}" - echo " • Commands installed: ${installed_commands}/${total_commands}" - if [ "$failed_commands" -gt 0 ]; then - warn " • Failed: ${failed_commands}" - fi - echo " • Location: ${install_dir}/" - echo "" - info "Usage in ${agent_name}:" - echo " Type '/' in chat to see available commands" - echo " Commands are named: -" - echo " Example: /code-review-review-pr" - echo "" - info "Documentation: https://github.com/${REPO_OWNER}/${REPO_NAME}" - echo "" -} - -# Parse arguments and run -parse_args "$@" -install_commands diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 58fcfd1..f1dae56 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,7 +1,7 @@ { "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", "name": "context-engineering-kit", - "version": "2.2.3", + "version": "3.0.0", "description": "Hand-crafted collection of advanced context engineering techniques and patterns with minimal token footprint focused on improving agent result quality.", "owner": { "name": "NeoLabHQ", @@ -11,7 +11,7 @@ { "name": "reflexion", "description": "Collection of commands that force LLM to reflect on previous response and output. Based on papers like Self-Refine and Reflexion. These techniques improve the output of large language models by introducing feedback and refinement loops.", - "version": "1.1.4", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -20,20 +20,20 @@ "category": "productivity" }, { - "name": "code-review", + "name": "review", "description": "Introduce codebase and PR review commands and skills using multiple specialized agents.", - "version": "1.1.1", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" }, - "source": "./plugins/code-review", + "source": "./plugins/review", "category": "productivity" }, { "name": "git", "description": "Introduces commands for commit and PRs creation, plus skills for git worktrees and notes.", - "version": "1.2.0", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -44,7 +44,7 @@ { "name": "tdd", "description": "Introduces commands for test-driven development, common anti-patterns and skills for testing using subagents.", - "version": "1.1.0", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -55,7 +55,7 @@ { "name": "sadd", "description": "Introduces skills for subagent-driven development, dispatches fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates.", - "version": "1.3.3", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -66,7 +66,7 @@ { "name": "ddd", "description": "Introduces command to update CLAUDE.md with best practices for domain-driven development, focused on quality of code, includes Clean Architecture, SOLID principles, and other design patterns.", - "version": "2.0.0", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -77,7 +77,7 @@ { "name": "sdd", "description": "Specification Driven Development workflow commands and agents, based on Github Spec Kit and OpenSpec. Uses specialized agents for effective context management and quality review.", - "version": "2.1.1", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -88,7 +88,7 @@ { "name": "kaizen", "description": "Inspired by Japanese continuous improvement philosophy, Agile and Lean development practices. Introduces commands for analysis of root cause of issues and problems, including 5 Whys, Cause and Effect Analysis, and other techniques.", - "version": "1.0.0", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -99,7 +99,7 @@ { "name": "customaize-agent", "description": "Commands and skills for writing and refining commands, hooks, skills for Claude Code, includes Anthropic Best Practices and Agent Persuasion Principles that can be useful for sub-agent workflows.", - "version": "1.4.0", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -110,7 +110,7 @@ { "name": "docs", "description": "Commands for analysing project, writing and refining documentation.", - "version": "1.2.0", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -121,7 +121,7 @@ { "name": "tech-stack", "description": "Commands for setup or update of CLAUDE.md file with best practices for specific language or framework.", - "version": "1.0.0", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -132,7 +132,7 @@ { "name": "mcp", "description": "Commands for setup well known MCP server integration if needed and update CLAUDE.md file with requirement to use this MCP server for current project.", - "version": "1.2.1", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" @@ -143,7 +143,7 @@ { "name": "fpf", "description": "First Principles Framework (FPF) for structured reasoning. Implements ADI (Abduction-Deduction-Induction) cycle for hypothesis generation, logical verification, empirical validation, and auditable decision-making.", - "version": "1.1.1", + "version": "3.0.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" diff --git a/.claude/commands/bump-plugin.md b/.claude/commands/bump-plugin.md index 23185f2..99a0900 100644 --- a/.claude/commands/bump-plugin.md +++ b/.claude/commands/bump-plugin.md @@ -6,12 +6,12 @@ allowed-tools: Bash(just set-version*), Bash(just set-marketplace-version*), Bas # Bump Plugin Version -Detect changed plugins and bump their versions along with the marketplace version. +If not instructions from user provided, detect changed plugins and bump their versions along with the marketplace version. ## Current State -- Git status: !`git status --short` -- Changed files in plugins: !`git diff --name-only HEAD | grep "^plugins/" | cut -d'/' -f2 | sort -u` +- Git status: `git status --short` +- Changed files in plugins: `git diff --name-only HEAD | grep "^plugins/" | cut -d'/' -f2 | sort -u` ## Instructions diff --git a/.devcontainer/configure-claude.sh b/.devcontainer/configure-claude.sh index 0529e18..51ecbbb 100644 --- a/.devcontainer/configure-claude.sh +++ b/.devcontainer/configure-claude.sh @@ -15,7 +15,7 @@ if [ ! -f ~/.claude/settings.json ]; then cat > ~/.claude/settings.json << 'EOF' { "permissions": { - "defaultMode": "bypassPermissions" + "defaultMode": "auto" }, "hooks": { "SessionStart": [ @@ -23,7 +23,7 @@ if [ ! -f ~/.claude/settings.json ]; then "hooks": [ { "type": "command", - "command": "echo 'git diff:' && git diff --stat && echo 'git status:' && git status" + "command": "echo 'codemap . && git diff:' && git diff --stat && echo 'git status:' && git status" } ] } @@ -43,16 +43,6 @@ EOF echo "✅ Created ~/.claude/settings.json with bypass permissions." fi -if [ ! -f ~/.claude.json ]; then - echo "🔧 Creating ~/.claude.json..." - cat > ~/.claude.json << 'EOF' -{ - "autoCompactEnabled": false -} -EOF - echo "✅ Created ~/.claude.json with autoCompactEnabled set to false." -fi - retry() { local max_attempts="${RETRY_ATTEMPTS:-3}" local delay="${RETRY_DELAY:-1}" @@ -83,7 +73,20 @@ retry claude plugin marketplace add NeoLabHQ/context-engineering-kit retry claude plugin install sdd@context-engineering-kit retry claude plugin install sadd@context-engineering-kit retry claude plugin install git@context-engineering-kit +retry claude plugin install ddd@context-engineering-kit +retry claude plugin install code-review@context-engineering-kit +# Merge only autoUpdates / autoCompactEnabled so we never replace the whole file (preserves other keys). +CLAUDE_JSON="/home/node/.claude.json" +echo "🔧 Ensuring ${CLAUDE_JSON} has autoUpdates and autoCompactEnabled..." +tmp="$(mktemp)" +if [ -f "$CLAUDE_JSON" ]; then + jq '. + {autoUpdates: true, autoCompactEnabled: false, hasCompletedOnboarding: true}' "$CLAUDE_JSON" >"$tmp" +else + jq -n '{autoUpdates: true, autoCompactEnabled: false, hasCompletedOnboarding: true}' >"$tmp" +fi +mv "$tmp" "$CLAUDE_JSON" +echo "✅ ${CLAUDE_JSON} updated (autoUpdates=true, autoCompactEnabled=false; other keys preserved)." echo "🚀 Claude Code environment ready." echo "Use 'claude' to run Claude Code" \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 9b28adc..65c798e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,7 +28,7 @@ context-engineering-kit/ ## Available Plugins -code-review, customaize-agent, ddd, docs, git, kaizen, mcp, reflexion, sadd, sdd, tdd, tech-stack +review, customaize-agent, ddd, docs, git, kaizen, mcp, reflexion, sadd, sdd, tdd, tech-stack ## Development Commands diff --git a/README.md b/README.md index 251daa5..5fbbc3b 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,10 @@ The marketplace is based on prompts used daily by our company developers for a l Updates from key releases: -- **v2.0.0:** [Spec-Driven Development plugin](https://cek.neolab.finance/plugins/sdd) was rewritten from scratch. It is now able to produce working code in 99% of cases on real-life production projects! -- **v2.1.0:** [Spec-Driven Development plugin](https://cek.neolab.finance/plugins/sdd) agents include high-level code quality guidelines from [DDD plugin](https://cek.neolab.finance/plugins/ddd). +- **v3.0.0:** Added support for AMP and Hermes agents. [Tech Stack plugin](https://cek.neolab.finance/plugins/tech-stack) now automatically injects typescript best practices when agent reads or writes TypeScript files. - **v2.2.0:** [Subagent-Driven Development plugin](https://cek.neolab.finance/plugins/sadd) now works as a distilled version of [SDD plugin](https://cek.neolab.finance/plugins/sdd) using meta-judge and judge sub-agents for specification generation on the fly and in parallel to implementation. [DDD plugin](https://cek.neolab.finance/plugins/ddd) now includes Clean Architecture, DDD, SOLID, Functional Programming, and other pattern examples as rules that are automatically added to the context during code writing. +- **v2.1.0:** [Spec-Driven Development plugin](https://cek.neolab.finance/plugins/sdd) agents include high-level code quality guidelines from [DDD plugin](https://cek.neolab.finance/plugins/ddd). +- **v2.0.0:** [Spec-Driven Development plugin](https://cek.neolab.finance/plugins/sdd) was rewritten from scratch. It is now able to produce working code in 99% of cases on real-life production projects! ## Quick Start @@ -179,7 +180,7 @@ The three plugins in this marketplace are designed to improve how accurately and Resolves all issues similarly to /do-and-judge, but separately per file group -/plan + /implement +/plan-task + /implement-task 94% 93% 85% @@ -188,7 +189,7 @@ The three plugins in this marketplace are designed to improve how accurately and Performs the /do-in-steps flow, but the specification mitigates issues caused by inconsistent architecture and codebase size -/brainstorm + /plan + /implement +/brainstorm + /plan-task + /implement-task 95% 95% 90% @@ -197,7 +198,7 @@ The three plugins in this marketplace are designed to improve how accurately and Brainstorming decreases the number of incorrect decisions and missed requirements -/plan + human review + /implement +/plan-task + human review + /implement-task 99% 99% 99% @@ -220,7 +221,7 @@ To view all available plugins: - [Reflexion](https://cek.neolab.finance/plugins/reflexion) - Introduces feedback and refinement loops to improve output quality. - [Spec-Driven Development](https://cek.neolab.finance/plugins/sdd) - Introduces commands for specification-driven development, based on Continuous Learning + LLM-as-Judge + Agent Swarm. Achieves **development as compilation** through reliable code generation. -- [Code Review](https://cek.neolab.finance/plugins/code-review) - Introduces codebase and PR review commands and skills using multiple specialized agents. +- [Review](https://cek.neolab.finance/plugins/review) - Introduces code and PR review commands and skills using multiple specialized agents with impact/confidence filtering. - [Git](https://cek.neolab.finance/plugins/git) - Introduces commands for commit and PR creation. - [Test-Driven Development](https://cek.neolab.finance/plugins/tdd) - Introduces commands for test-driven development, common anti-patterns and skills for testing using subagents. - [Subagent-Driven Development](https://cek.neolab.finance/plugins/sadd) - Introduces skills for subagent-driven development, which dispatches a fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates. @@ -229,9 +230,15 @@ To view all available plugins: - [Kaizen](https://cek.neolab.finance/plugins/kaizen) - Inspired by Japanese continuous improvement philosophy, Agile and Lean development practices. Introduces commands for analysis of root causes of issues and problems, including 5 Whys, Cause and Effect Analysis, and other techniques. - [Customaize Agent](https://cek.neolab.finance/plugins/customaize-agent) - Commands and skills for writing and refining commands, hooks, and skills for Claude Code. Includes Anthropic Best Practices and [Agent Persuasion Principles](https://arxiv.org/abs/2508.00614) that can be useful for sub-agent workflows. - [Docs](https://cek.neolab.finance/plugins/docs) - Commands for analyzing projects, writing and refining documentation. -- [Tech Stack](https://cek.neolab.finance/plugins/tech-stack) - Commands for setting up or updating CLAUDE.md file with best practices for specific languages or frameworks. +- [Tech Stack](https://cek.neolab.finance/plugins/tech-stack) - Rules for language-specific best practices, automatically applied when working on matching file types. - [MCP](https://cek.neolab.finance/plugins/mcp) - Commands for setting up well-known MCP server integration if needed and updating CLAUDE.md file with requirements to use this MCP server for the current project. +## Stay ahead + +Star Context Engineering Kit on GitHub to support it's development and get notified about new features and updates. + +Star Context Engineering Kit on GitHub + ### [Reflexion](https://cek.neolab.finance/plugins/reflexion) Collection of commands that force the LLM to reflect on the previous response and output. Includes **automatic reflection hooks** that trigger when you include "reflect" in your prompt. @@ -260,20 +267,20 @@ They are proven to **increase output quality by 8–21%** based on both automati On top of that, the plugin is based on the [Agentic Context Engineering](https://arxiv.org/abs/2510.04618) paper that uses memory updates after reflection, and **consistently outperforms strong baselines by 10.6%** on agents. -### [Code Review](https://cek.neolab.finance/plugins/code-review) +### [Review](https://cek.neolab.finance/plugins/review) -Comprehensive code review commands using multiple specialized agents for thorough code quality evaluation. +Comprehensive code and PR review commands using multiple specialized agents for thorough code quality evaluation with impact/confidence filtering. **How to install** ```bash -/plugin install code-review@NeoLabHQ/context-engineering-kit +/plugin install review@NeoLabHQ/context-engineering-kit ``` **Commands** -- [/code-review:review-local-changes](https://cek.neolab.finance/plugins/code-review/review-local-changes) - Comprehensive review of local uncommitted changes using specialized agents with code improvement suggestions -- [/code-review:review-pr](https://cek.neolab.finance/plugins/code-review/review-pr) - Comprehensive pull request review using specialized agents +- [/review-local-changes](https://cek.neolab.finance/plugins/review/review-local-changes) - Comprehensive review of local uncommitted changes using specialized agents with code improvement suggestions +- [/review-pr](https://cek.neolab.finance/plugins/review/review-pr) - Comprehensive pull request review using specialized agents **Agents** @@ -300,18 +307,15 @@ Commands and skills for streamlined Git operations including commits, pull reque **Commands** -- [/git:commit](https://cek.neolab.finance/plugins/git/commit) - Create well-formatted commits with conventional commit messages and emoji -- [/git:create-pr](https://cek.neolab.finance/plugins/git/create-pr) - Create pull requests using GitHub CLI with proper templates and formatting -- [/git:analyze-issue](https://cek.neolab.finance/plugins/git/analyze-issue) - Analyze a GitHub issue and create a detailed technical specification -- [/git:load-issues](https://cek.neolab.finance/plugins/git/load-issues) - Load all open issues from GitHub and save them as markdown files -- [/git:create-worktree](https://cek.neolab.finance/plugins/git/create-worktree) - Create git worktrees for parallel development with automatic dependency installation -- [/git:compare-worktrees](https://cek.neolab.finance/plugins/git/compare-worktrees) - Compare files and directories between git worktrees -- [/git:merge-worktree](https://cek.neolab.finance/plugins/git/merge-worktree) - Merge changes from worktrees with selective checkout, cherry-picking, or patch selection +- [/commit](https://cek.neolab.finance/plugins/git/commit) - Create well-formatted commits with conventional commit messages and emoji +- [/create-pr](https://cek.neolab.finance/plugins/git/create-pr) - Create pull requests using GitHub CLI with proper templates and formatting +- [/analyze-issue](https://cek.neolab.finance/plugins/git/analyze-issue) - Analyze a GitHub issue and create a detailed technical specification +- [/load-issues](https://cek.neolab.finance/plugins/git/load-issues) - Load all open issues from GitHub and save them as markdown files +- [/worktree](https://cek.neolab.finance/plugins/git/git-worktrees) - Create, compare, and merge git worktrees for parallel development with automatic dependency installation **Skills** -- **worktrees** - Git worktree commands and workflow patterns for parallel branch development -- **notes** - Git notes commands for attaching non-invasive metadata to commits +- [notes](https://cek.neolab.finance/plugins/git/git-notes) - Skill about using git notes to add metadata to commits without changing history. ### [Test-Driven Development](https://cek.neolab.finance/plugins/tdd) @@ -325,8 +329,8 @@ Commands and skills for test-driven development with anti-pattern detection. **Commands** -- [/tdd:write-tests](https://cek.neolab.finance/plugins/tdd/write-tests) - Systematically add test coverage for local code changes using specialized review and development agents -- [/tdd:fix-tests](https://cek.neolab.finance/plugins/tdd/fix-tests) - Fix failing tests after business logic changes or refactoring using orchestrated agents +- [/write-tests](https://cek.neolab.finance/plugins/tdd/write-tests) - Systematically add test coverage for local code changes using specialized review and development agents +- [/fix-tests](https://cek.neolab.finance/plugins/tdd/fix-tests) - Fix failing tests after business logic changes or refactoring using orchestrated agents **Skills** @@ -344,14 +348,14 @@ Execution framework for competitive generation, multi-agent evaluation, and suba **Commands** -- [/sadd:launch-sub-agent](https://cek.neolab.finance/plugins/sadd/launch-sub-agent) - Launch focused sub-agents with intelligent model selection, Zero-shot CoT reasoning, and self-critique verification -- [/sadd:do-and-judge](https://cek.neolab.finance/plugins/sadd/do-and-judge) - Execute a single task with implementation sub-agent, independent judge verification, and automatic retry loop until passing -- [/sadd:do-in-parallel](https://cek.neolab.finance/plugins/sadd/do-in-parallel) - Execute the same task across multiple independent targets in parallel with context isolation -- [/sadd:do-in-steps](https://cek.neolab.finance/plugins/sadd/do-in-steps) - Execute complex tasks through sequential sub-agent orchestration with automatic decomposition and context passing -- [/sadd:do-competitively](https://cek.neolab.finance/plugins/sadd/do-competitively) - Execute tasks through competitive generation, multi-judge evaluation, and evidence-based synthesis to produce superior results -- [/sadd:tree-of-thoughts](https://cek.neolab.finance/plugins/sadd/tree-of-thoughts) - Execute complex reasoning through systematic exploration of solution space, pruning unpromising branches, and synthesizing the best solution -- [/sadd:judge-with-debate](https://cek.neolab.finance/plugins/sadd/judge-with-debate) - Evaluate solutions through iterative multi-judge debate with consensus building or disagreement reporting -- [/sadd:judge](https://cek.neolab.finance/plugins/sadd/judge) - Evaluate completed work using LLM-as-Judge with structured rubrics and evidence-based scoring +- [/launch-sub-agent](https://cek.neolab.finance/plugins/sadd/launch-sub-agent) - Launch focused sub-agents with intelligent model selection, Zero-shot CoT reasoning, and self-critique verification +- [/do-and-judge](https://cek.neolab.finance/plugins/sadd/do-and-judge) - Execute a single task with implementation sub-agent, independent judge verification, and automatic retry loop until passing +- [/do-in-parallel](https://cek.neolab.finance/plugins/sadd/do-in-parallel) - Execute the same task across multiple independent targets in parallel with context isolation +- [/do-in-steps](https://cek.neolab.finance/plugins/sadd/do-in-steps) - Execute complex tasks through sequential sub-agent orchestration with automatic decomposition and context passing +- [/do-competitively](https://cek.neolab.finance/plugins/sadd/do-competitively) - Execute tasks through competitive generation, multi-judge evaluation, and evidence-based synthesis to produce superior results +- [/tree-of-thoughts](https://cek.neolab.finance/plugins/sadd/tree-of-thoughts) - Execute complex reasoning through systematic exploration of solution space, pruning unpromising branches, and synthesizing the best solution +- [/judge-with-debate](https://cek.neolab.finance/plugins/sadd/judge-with-debate) - Evaluate solutions through iterative multi-judge debate with consensus building or disagreement reporting +- [/judge](https://cek.neolab.finance/plugins/sadd/judge) - Evaluate completed work using LLM-as-Judge with structured rubrics and evidence-based scoring **Skills** @@ -366,13 +370,13 @@ This plugin is designed to consistently produce working code. It was tested on r #### Key Features -- **Development as compilation** — The plugin works like a "compilation" or "nightly build" for your development process: `task specs → run /sdd:implement → working code`. After writing your prompt, you can launch the plugin and expect a working result when you come back. The time it takes depends on task complexity — simple tasks may finish in 30 minutes, while complex ones can take a few days. +- **Development as compilation** — The plugin works like a "compilation" or "nightly build" for your development process: `task specs → run /implement-task → working code`. After writing your prompt, you can launch the plugin and expect a working result when you come back. The time it takes depends on task complexity — simple tasks may finish in 30 minutes, while complex ones can take a few days. - **Benchmark-level quality in real life** — Model benchmarks improve with each release, yet real-world results usually stay the same. That's because benchmarks reflect the best possible output a model can achieve, whereas in practice LLMs tend to drift toward sub-optimal solutions that can be wrong or non-functional. This plugin uses a variety of patterns to keep the model working at its peak performance. - **Customizable** — Balance result quality and process speed by adjusting command parameters. Learn more in the [Customization](./customization.md) section. - **Developer time-efficient** — The overall process is designed to minimize developer time and reduce the number of interactions, while still producing results better than what a model can generate from scratch. However, overall quality is highly proportional to the time you invest in iterating and refining the specification. - **Industry-standard** — The plugin's specification template is based on the arc42 standard, adjusted for LLM capabilities. Arc42 is a widely adopted, high-quality standard for software development documentation used by many companies and organizations. - **Works best in complex or large codebases** — While most other frameworks work best for new projects and greenfield development, this plugin is designed to perform better the more existing code and well-structured architecture you have. At each planning phase it includes a **codebase impact analysis** step that evaluates which files may be affected and which patterns to follow to achieve the desired result. -- **Simple** — This plugin avoids unnecessary complexity and mainly uses just 3 commands, offloading process complexity to the model via multi-agent orchestration. `/sdd:implement` is a single command that produces working code from a task specification. To create that specification, you run `/sdd:add-task` and `/sdd:plan`, which analyze your prompt and iteratively refine the specification until it meets the required quality. +- **Simple** — This plugin avoids unnecessary complexity and mainly uses just 3 commands, offloading process complexity to the model via multi-agent orchestration. `/implement-task` is a single command that produces working code from a task specification. To create that specification, you run `/sdd:add-task` and `/plan-task`, which analyze your prompt and iteratively refine the specification until it meets the required quality. #### Quick Start @@ -384,10 +388,10 @@ Then run the following commands: ```bash # create .specs/tasks/draft/design-auth-middleware.feature.md file with initial prompt -/sdd:add-task "Design and implement authentication middleware with JWT support" +/add-task "Design and implement authentication middleware with JWT support" # write detailed specification for the task -/sdd:plan +/plan-task # will move task to .specs/tasks/todo/ folder ``` @@ -395,7 +399,7 @@ Restart the Claude Code session to clear context and start fresh. Then run the f ```bash # implement the task -/sdd:implement @.specs/tasks/todo/design-auth-middleware.feature.md +/implement-task @.specs/tasks/todo/design-auth-middleware.feature.md # produces working implementation and moves the task to .specs/tasks/done/ folder ``` @@ -404,28 +408,28 @@ Restart the Claude Code session to clear context and start fresh. Then run the f **Commands** -- [/sdd:add-task](https://cek.neolab.finance/plugins/sdd/add-task) - Create task template file with initial prompt -- [/sdd:plan](https://cek.neolab.finance/plugins/sdd/plan) - Analyze prompt, generate required skills and refine task specification -- [/sdd:implement](https://cek.neolab.finance/plugins/sdd/implement) - Produce a working implementation of the task and verify it +- [/add-task](https://cek.neolab.finance/plugins/sdd/add-task) - Create task template file with initial prompt +- [/plan-task](https://cek.neolab.finance/plugins/sdd/plan) - Analyze prompt, generate required skills and refine task specification +- [/implement-task](https://cek.neolab.finance/plugins/sdd/implement) - Produce a working implementation of the task and verify it Additional commands useful before creating a task: -- [/sdd:create-ideas](https://cek.neolab.finance/plugins/sdd/create-ideas) - Generate diverse ideas on a given topic using creative sampling techniques -- [/sdd:brainstorm](https://cek.neolab.finance/plugins/sdd/brainstorm) - Refine vague ideas into fully-formed designs through collaborative dialogue +- [/create-ideas](https://cek.neolab.finance/plugins/sdd/create-ideas) - Generate diverse ideas on a given topic using creative sampling techniques +- [/brainstorm](https://cek.neolab.finance/plugins/sdd/brainstorm) - Refine vague ideas into fully-formed designs through collaborative dialogue **Agents** | Agent | Description | Used By | |-------|-------------|---------| -| `researcher` | Technology research, dependency analysis, best practices | `/sdd:plan` (Phase 2a) | -| `code-explorer` | Codebase analysis, pattern identification, architecture mapping | `/sdd:plan` (Phase 2b) | -| `business-analyst` | Requirements discovery, stakeholder analysis, specification writing | `/sdd:plan` (Phase 2c) | -| `software-architect` | Architecture design, component design, implementation planning | `/sdd:plan` (Phase 3) | -| `tech-lead` | Task decomposition, dependency mapping, risk analysis | `/sdd:plan` (Phase 4) | -| `team-lead` | Step parallelization, agent assignment, execution planning | `/sdd:plan` (Phase 5) | -| `qa-engineer` | Verification rubrics, quality gates, LLM-as-Judge definitions | `/sdd:plan` (Phase 6) | -| `developer` | Code implementation, TDD execution, quality review, verification | `/sdd:implement` | -| `tech-writer` | Technical documentation writing, API guides, architecture updates, lessons learned | `/sdd:implement` | +| `researcher` | Technology research, dependency analysis, best practices | `/plan-task` (Phase 2a) | +| `code-explorer` | Codebase analysis, pattern identification, architecture mapping | `/plan-task` (Phase 2b) | +| `business-analyst` | Requirements discovery, stakeholder analysis, specification writing | `/plan-task` (Phase 2c) | +| `software-architect` | Architecture design, component design, implementation planning | `/plan-task` (Phase 3) | +| `tech-lead` | Task decomposition, dependency mapping, risk analysis | `/plan-task` (Phase 4) | +| `team-lead` | Step parallelization, agent assignment, execution planning | `/plan-task` (Phase 5) | +| `qa-engineer` | Verification rubrics, quality gates, LLM-as-Judge definitions | `/plan-task` (Phase 6) | +| `developer` | Code implementation, TDD execution, quality review, verification | `/implement-task` | +| `tech-writer` | Technical documentation writing, API guides, architecture updates, lessons learned | `/implement-task` | #### Patterns @@ -454,7 +458,7 @@ Learn more about available customization options in [Customization](https://cek. ### [Domain-Driven Development](https://cek.neolab.finance/plugins/ddd) -Commands for setting up domain-driven development best practices focused on code quality. +Code quality framework with rules for Clean Architecture, SOLID principles, and Domain-Driven Design patterns. **How to install** @@ -462,10 +466,6 @@ Commands for setting up domain-driven development best practices focused on code /plugin install ddd@NeoLabHQ/context-engineering-kit ``` -**Commands** - -- [/ddd:setup-code-formatting](https://cek.neolab.finance/plugins/ddd/setup-code-formating) - Sets up code formatting rules and style guidelines in CLAUDE.md - **Rules** - 15 composable rules covering Clean Architecture, SOLID principles, Command-Query Separation, Functional Core/Imperative Shell, Explicit Control Flow, Domain-Specific Naming, and more. See [rules reference](https://cek.neolab.finance/plugins/ddd/rules) @@ -501,7 +501,7 @@ Then, audit for bias, decide, and document the rationale in a durable record. ```bash # Execute complete FPF cycle from hypothesis to decision -/fpf:propose-hypotheses What caching strategy should we use? +/propose-hypotheses What caching strategy should we use? # The workflow will: # 1. Initialize context and .fpf/ directory @@ -515,12 +515,12 @@ Then, audit for bias, decide, and document the rationale in a durable record. **Commands** -- [/fpf:propose-hypotheses](https://cek.neolab.finance/plugins/fpf/propose-hypotheses) - Execute complete FPF cycle from hypothesis to decision (main workflow) -- [/fpf:status](https://cek.neolab.finance/plugins/fpf/status) - Show current FPF phase and hypothesis counts -- [/fpf:query](https://cek.neolab.finance/plugins/fpf/query) - Search knowledge base with assurance info -- [/fpf:decay](https://cek.neolab.finance/plugins/fpf/decay) - Manage evidence freshness (refresh/deprecate/waive) -- [/fpf:actualize](https://cek.neolab.finance/plugins/fpf/actualize) - Reconcile knowledge with codebase changes -- [/fpf:reset](https://cek.neolab.finance/plugins/fpf/reset) - Archive session and return to IDLE +- [/propose-hypotheses](https://cek.neolab.finance/plugins/fpf/propose-hypotheses) - Execute complete FPF cycle from hypothesis to decision (main workflow) +- [/status](https://cek.neolab.finance/plugins/fpf/status) - Show current FPF phase and hypothesis counts +- [/query](https://cek.neolab.finance/plugins/fpf/query) - Search knowledge base with assurance info +- [/decay](https://cek.neolab.finance/plugins/fpf/decay) - Manage evidence freshness (refresh/deprecate/waive) +- [/actualize](https://cek.neolab.finance/plugins/fpf/actualize) - Reconcile knowledge with codebase changes +- [/reset](https://cek.neolab.finance/plugins/fpf/reset) - Archive session and return to IDLE **Agent** @@ -538,12 +538,12 @@ Continuous improvement methodology inspired by Japanese philosophy and Agile pra **Commands** -- [/kaizen:analyse](https://cek.neolab.finance/plugins/kaizen/analyse) - Auto-selects best Kaizen method (Gemba Walk, Value Stream, or Muda) for target analysis -- [/kaizen:analyse-problem](https://cek.neolab.finance/plugins/kaizen/analyse-problem) - Comprehensive A3 one-page problem analysis with root cause and action plan -- [/kaizen:why](https://cek.neolab.finance/plugins/kaizen/why) - Iterative Five Whys root cause analysis drilling from symptoms to fundamentals -- [/kaizen:root-cause-tracing](https://cek.neolab.finance/plugins/kaizen/root-cause-tracing) - Systematically traces bugs backward through call stack to identify source of invalid data or incorrect behavior -- [/kaizen:cause-and-effect](https://cek.neolab.finance/plugins/kaizen/cause-and-effect) - Systematic Fishbone analysis exploring problem causes across six categories -- [/kaizen:plan-do-check-act](https://cek.neolab.finance/plugins/kaizen/plan-do-check-act) - Iterative PDCA cycle for systematic experimentation and continuous improvement +- [/analyse](https://cek.neolab.finance/plugins/kaizen/analyse) - Auto-selects best Kaizen method (Gemba Walk, Value Stream, or Muda) for target analysis +- [/analyse-problem](https://cek.neolab.finance/plugins/kaizen/analyse-problem) - Comprehensive A3 one-page problem analysis with root cause and action plan +- [/why](https://cek.neolab.finance/plugins/kaizen/why) - Iterative Five Whys root cause analysis drilling from symptoms to fundamentals +- [/root-cause-tracing](https://cek.neolab.finance/plugins/kaizen/root-cause-tracing) - Systematically traces bugs backward through call stack to identify source of invalid data or incorrect behavior +- [/cause-and-effect](https://cek.neolab.finance/plugins/kaizen/cause-and-effect) - Systematic Fishbone analysis exploring problem causes across six categories +- [/plan-do-check-act](https://cek.neolab.finance/plugins/kaizen/plan-do-check-act) - Iterative PDCA cycle for systematic experimentation and continuous improvement **Skills** @@ -588,12 +588,12 @@ Commands for project analysis and documentation management based on proven writi **Commands** -- [/docs:update-docs](https://cek.neolab.finance/plugins/docs/update-docs) - Update implementation documentation after completing development phases -- [/docs:write-concisely](https://cek.neolab.finance/plugins/docs/write-concisely) - Apply *The Elements of Style* principles to make documentation clearer and more professional +- [/update-docs](https://cek.neolab.finance/plugins/docs/update-docs) - Update implementation documentation after completing development phases +- [/write-concisely](https://cek.neolab.finance/plugins/docs/write-concisely) - Apply *The Elements of Style* principles to make documentation clearer and more professional ### [Tech Stack](https://cek.neolab.finance/plugins/tech-stack) -Commands for setting up language and framework-specific best practices. +Rules for language and framework-specific best practices, automatically applied when the agent works on matching file types. **How to install** @@ -601,9 +601,10 @@ Commands for setting up language and framework-specific best practices. /plugin install tech-stack@NeoLabHQ/context-engineering-kit ``` -**Commands** +**Rules** + +- TypeScript Best Practices - Type system guidelines, code style, async patterns, and code quality standards, automatically loaded when agent reading or writing `.ts` files -- [/tech-stack:add-typescript-best-practices](https://cek.neolab.finance/plugins/tech-stack/add-typescript-best-practices) - Setup TypeScript best practices and code style rules in CLAUDE.md ### [MCP](https://cek.neolab.finance/plugins/mcp) diff --git a/docs/README.md b/docs/README.md index 3cf7811..1deac9b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,7 +32,7 @@ Browse our specialized plugins organized by area of focus: ### Quality & Refinement -
ReflexionSelf-refinement loopsreflexion
Code ReviewMulti-agent code review systemcode-review
KaizenContinuous improvement methodologykaizen
+
ReflexionSelf-refinement loopsreflexion
Code ReviewMulti-agent code review systemreview
KaizenContinuous improvement methodologykaizen
### Development Workflows diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index e97c3dd..0916257 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -3,7 +3,6 @@ * [Context Engineering Kit](README.md) * [Getting Started](getting-started.md) * [Guides](guides/README.md) - * [Project Setup](guides/project-setup.md) * [Reliable Engineering through Spec-Driven Development](guides/spec-driven-development.md) * [File Structure Context](guides/file-structure-context.md) * [Feature Development](guides/feature-development.md) @@ -16,10 +15,10 @@ * [CI/CD Integration](guides/ci-integration.md) * [Creating Custom Extensions](guides/custom-extensions.md) * [Plugins](plugins/README.md) - * [Code Review](plugins/code-review/README.md) - * [review-local-changes](plugins/code-review/review-local-changes.md) - * [review-pr](plugins/code-review/review-pr.md) - * [Usage Examples](plugins/code-review/usage-examples.md) + * [Review](plugins/review/README.md) + * [review-local-changes](plugins/review/review-local-changes.md) + * [review-pr](plugins/review/review-pr.md) + * [Usage Examples](plugins/review/usage-examples.md) * [Customize Agent](plugins/customaize-agent/README.md) * [create-agent](plugins/customaize-agent/create-agent.md) * [create-command](plugins/customaize-agent/create-command.md) @@ -34,7 +33,6 @@ * [prompt-engineering](plugins/customaize-agent/prompt-engineering.md) * [Usage Examples](plugins/customaize-agent/usage-examples.md) * [Domain-Driven Development](plugins/ddd/README.md) - * [setup-code-formating](plugins/ddd/setup-code-formating.md) * [Rules](plugins/ddd/rules.md) * [Usage Examples](plugins/ddd/usage-examples.md) * [Docs](plugins/docs/README.md) @@ -48,13 +46,10 @@ * [analyze-issue](plugins/git/analyze-issue.md) * [attach-review-to-pr](plugins/git/attach-review-to-pr.md) * [commit](plugins/git/commit.md) - * [compare-worktrees](plugins/git/compare-worktrees.md) * [create-pr](plugins/git/create-pr.md) - * [create-worktree](plugins/git/create-worktree.md) * [load-issues](plugins/git/load-issues.md) - * [merge-worktree](plugins/git/merge-worktree.md) - * [notes](plugins/git/notes.md) - * [worktrees](plugins/git/worktrees.md) + * [git-notes](plugins/git/git-notes.md) + * [git-worktrees](plugins/git/git-worktrees.md) * [Kaizen](plugins/kaizen/README.md) * [analyse-problem](plugins/kaizen/analyse-problem.md) * [kaizen](plugins/kaizen/kaizen.md) @@ -91,8 +86,8 @@ * [Usage Examples](plugins/sadd/usage-examples.md) * [Spec-Driven Development](plugins/sdd/README.md) * [add-task](plugins/sdd/add-task.md) - * [plan](plugins/sdd/plan.md) - * [implement](plugins/sdd/implement.md) + * [plan-task](plugins/sdd/plan-task.md) + * [implement-task](plugins/sdd/implement-task.md) * [brainstorm](plugins/sdd/brainstorm.md) * [create-ideas](plugins/sdd/create-ideas.md) * [Refining Specifications and Code](plugins/sdd/refine.md) @@ -104,8 +99,7 @@ * [test-driven-development](plugins/tdd/test-driven-development.md) * [Usage Examples](plugins/tdd/usage-examples.md) * [Tech Stack](plugins/tech-stack/README.md) - * [add-typescript-best-practices](plugins/tech-stack/add-typescript-best-practices.md) - * [Usage Examples](plugins/tech-stack/usage-examples.md) + * [TypeScript Best Practices](plugins/tech-stack/typescript-best-practices.md) * [Concepts](concepts.md) * [Best Practices](best-practices.md) * [Reference](reference/README.md) diff --git a/docs/assets/context-engineering-kit-like.gif b/docs/assets/context-engineering-kit-like.gif new file mode 100644 index 0000000..b2ac1ad Binary files /dev/null and b/docs/assets/context-engineering-kit-like.gif differ diff --git a/docs/best-practices.md b/docs/best-practices.md index 221e5b6..d9fb237 100644 --- a/docs/best-practices.md +++ b/docs/best-practices.md @@ -7,7 +7,7 @@ ```bash # ❌ Don't install all plugins /plugin install reflexion@NeoLabHQ/context-engineering-kit -/plugin install code-review@NeoLabHQ/context-engineering-kit +/plugin install review@NeoLabHQ/context-engineering-kit /plugin install sdd@NeoLabHQ/context-engineering-kit # ... (if you won't use them all) @@ -17,100 +17,28 @@ ## Maximizing Quality -**Use quality gates:** - -- Review after implementation -- Reflect before finalizing -- Critique for critical code - -**Leverage specialized agents:** - -- Code review agents catch domain-specific issues -- SDD agents provide specialized expertise -- Multiple agents offer diverse perspectives - -**Maintain CLAUDE.md:** - -- Update after major work -- Review and refine regularly -- Reference it actively - -**Follow methodologies:** - -- TDD prevents untested code -- SDD ensures comprehensive specifications -- DDD maintains clean architecture - - -### Project-Specific Adaptation - -**Small projects:** - -- Focus on reflexion and code-review plugins -- Skip full SDD workflow for simple features -- Use git plugin for clean commits - -**Large projects:** - -- Full SDD workflow for complex features -- Multiple specialized agents in parallel -- Comprehensive CLAUDE.md maintenance - -**Team projects:** - -- Document everything in CLAUDE.md -- Use SDD for shared understanding -- Review all PRs with code-review agents - -**Solo projects:** - -- Balance quality and velocity -- Use commands judiciously -- Focus on learning and improvement - -### Getting Help - -Each command has a description of how it should be used and what it does. - -**Command help:** +By using multiple plugins together you can maximize quality of results. For example, by combining `review`, `sdd`, `sadd`, `ddd` and `git` plugins, you can follow this workflow: ```bash -/help +# Create task file +/add-tash "Add OAuth2 based authentication" +# Write detailed specification by following Clean Architecture from DDD plugin +/plan-task +# Write code by following DDD and SOLID principles from DDD plugin +/implement-task +# Review code by following review plugin +/review-local-changes and write found issues to review.md file +# Fix found issues +/do-in-steps fix issues from review.md file +# Commit and create PR +/create-pr ``` -Shows all available commands with descriptions. +### Use commands tailored to task size -### Best Practices for CLAUDE.md - -**Keep it curated:** - -- Remove outdated information -- Consolidate duplicate insights -- Organize by topic for easy reference - -**Use it actively:** - -- Reference it when starting new features -- Update it after completing major work -- Review it during code reviews - -**Make it actionable:** - -- Write specific guidance, not generic advice -- Include examples and anti-patterns -- Link to relevant documentation - -**Version control:** - -- Commit `CLAUDE.md` with code changes -- Track evolution of project knowledge -- Review changes during pull requests - -**Balance detail and brevity:** - -- Detailed enough to be useful -- Concise enough to remain readable -- Focus on project-specific insights +- Small tasks - `/do-and-judge` from `sadd` plugin +- Medium tasks - `/do-in-steps` from `sadd` plugin +- Large tasks - `/plan-task` and `/implement-task` from `sdd` plugin ### Using CLAUDE.md Effectively @@ -124,38 +52,11 @@ Read CLAUDE.md and follow its guidelines ```bash # Reflect on implementation -/reflexion:reflect +/reflect # Memorize key insights to CLAUDE.md -/reflexion:memorize +/memorize ``` -**When setting up new project:** - -```bash -# Establish constitution -/sdd:00-setup Use FastAPI, PostgreSQL, follow Clean Architecture - -# Add language best practices -/tech-stack:add-typescript-best-practices - -# Setup code quality standards -/ddd:setup-code-formating -``` - -**Regular maintenance:** - -- Review and consolidate monthly -- Remove obsolete guidance -- Update based on team retrospectives -- Refine based on recurring issues - ---- - -### Hook - -A script or command that executes automatically at specific points in a workflow, typically Git hooks (pre-commit, pre-push, etc.). -**CEK usage**: The customaize-agent plugin includes `/customaize-agent:create-hook` for setting up automated testing and quality checks. -**Related**: [Customaize Agent Plugin](../plugins/customaize-agent/) diff --git a/docs/concepts.md b/docs/concepts.md index f6a20df..75854fb 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -27,28 +27,22 @@ After installing a plugin, its commands become available. View all commands: /help ``` -Commands are namespaced by plugin, making their origin clear: - -- `/reflexion:reflect` - From the reflexion plugin -- `/git:commit` - From the git plugin -- `/sdd:01-specify` - From the sdd plugin ### Command Syntax ```bash -/plugin-name:command-name [optional-argument] +/command-name [optional-argument] ``` **Examples:** ```bash # No argument required -/reflexion:reflect -/git:commit +/reflect +/commit # With argument -/sdd:01-specify Add user authentication with OAuth -/kaizen:analyse Target the checkout flow for optimization +/add-task Add user authentication with OAuth ``` --- @@ -119,13 +113,13 @@ Main Claude Session (You) ```bash # Launches multiple code review agents -/code-review:review-local-changes +/review-local-changes # Launches business-analyst agent -/sdd:01-specify Add user authentication +/add-task Add user authentication # Launches researcher, code-explorer, and software-architect agents -/sdd:02-plan +/plan-task ``` **Manual invocation** - Request specific agents directly: @@ -153,10 +147,10 @@ Workflow commands combine multiple sub-tasks into a single invocation: ### Example: FPF Propose-Hypotheses Workflow -The FPF plugin's `/fpf:propose-hypotheses` command demonstrates this pattern: +The FPF plugin's `/propose-hypotheses` command demonstrates this pattern: ``` -/fpf:propose-hypotheses How should we implement caching? +/propose-hypotheses How should we implement caching? │ ├── Step 1: Initialize Context (FPF Agent) │ └── Creates .fpf/context.md @@ -195,8 +189,8 @@ The FPF plugin's `/fpf:propose-hypotheses` command demonstrates this pattern: | Use Case | Approach | |----------|----------| | Complete end-to-end process | Workflow command | -| Check current state | Utility command (`/fpf:status`) | -| Manage specific aspect | Utility command (`/fpf:decay`) | +| Check current state | Utility command (`/status`) | +| Manage specific aspect | Utility command (`/decay`) | | Iterate on single phase | Individual task prompts | --- @@ -293,7 +287,7 @@ Several plugins read from and write to `CLAUDE.md`: ```bash # After reflecting, save insights to CLAUDE.md -/reflexion:memorize +/memorize ``` **What it adds:** @@ -304,36 +298,12 @@ Several plugins read from and write to `CLAUDE.md`: - Common mistakes to avoid - Successful approaches to replicate -**Tech Stack plugin** - Adds language/framework practices: - -```bash -/tech-stack:add-typescript-best-practices -``` - -**What it adds:** - -- Language-specific best practices -- Framework usage patterns -- Code style guidelines -- Common anti-patterns for the tech stack - -**DDD plugin** - Sets up code quality standards: - -```bash -/ddd:setup-code-formating -``` - -**What it adds:** -- Code formatting rules -- Architecture principles -- SOLID principle applications -- Clean Architecture patterns **MCP plugin** - Documents MCP server requirements: ```bash -/mcp:setup-context7-mcp +/setup-context7-mcp ``` **What it adds:** @@ -341,16 +311,3 @@ Several plugins read from and write to `CLAUDE.md`: - MCP server integration requirements - When and how to use specific MCP servers - Configuration and usage patterns - -**SDD plugin** - Establishes project constitution: - -```bash -/sdd:00-setup Use NestJS, follow SOLID and Clean Architecture -``` - -**What it adds:** - -- Project constitution and governance -- Core architectural principles -- Technology stack decisions -- Development standards diff --git a/docs/getting-started.md b/docs/getting-started.md index 5e6ba8c..56078ac 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -44,7 +44,7 @@ Then add the Context Engineering Kit marketplace to make all plugins available: /plugin ``` -You should see a list of available plugins from the marketplace, including reflexion, code-review, git, sdd, and others. +You should see a list of available plugins from the marketplace, including reflexion, review, git, sdd, and others. ### Step 2: Install Your First Plugin @@ -115,7 +115,7 @@ Install a specific plugin from the marketplace: # Examples /plugin install reflexion@NeoLabHQ/context-engineering-kit -/plugin install code-review@NeoLabHQ/context-engineering-kit +/plugin install review@NeoLabHQ/context-engineering-kit /plugin install sdd@NeoLabHQ/context-engineering-kit ``` @@ -125,7 +125,7 @@ Explore the [full plugin catalog](plugins/) to find tools that match your workfl **Popular plugins to explore next:** -* [**Code Review**](plugins/code-review/) - Multi-agent code review with specialized reviewers (security, bugs, quality, tests) +* [**Review**](plugins/review/) - Multi-agent code and PR review with specialized reviewers (security, bugs, quality, tests) * [**Git**](plugins/git/) - Streamlined Git workflows, commit creation, PR management * [**Spec-Driven Development**](plugins/sdd/) - Complete 6-stage workflow from specification to documentation * [**Test-Driven Development**](plugins/tdd/) - TDD best practices and anti-pattern detection diff --git a/docs/guides/brainstorming-to-implementation.md b/docs/guides/brainstorming-to-implementation.md index 68ff156..60e6e04 100644 --- a/docs/guides/brainstorming-to-implementation.md +++ b/docs/guides/brainstorming-to-implementation.md @@ -14,9 +14,8 @@ For well-defined requirements, skip brainstorming and use [Spec-Driven Developme ## Plugins needed for this workflow - [SDD](../plugins/sdd/README.md) -- [Code Review](../plugins/code-review/README.md) +- [Review](../plugins/review/README.md) - [Git](../plugins/git/README.md) -- [FPF](../plugins/fpf/README.md) (optional, for systematic hypothesis evaluation) ## Workflow @@ -59,10 +58,10 @@ For well-defined requirements, skip brainstorming and use [Spec-Driven Developme ### 1. Brainstorm the idea -Use the `/sdd:brainstorm` command to start a collaborative dialogue. The LLM will explore your project context and ask clarifying questions one at a time. +Use the `/brainstorm` command to start a collaborative dialogue. The LLM will explore your project context and ask clarifying questions one at a time. ```bash -/sdd:brainstorm Users want better search but requirements are unclear +/brainstorm Users want better search but requirements are unclear ``` After starting, the LLM will: @@ -95,34 +94,6 @@ The LLM will present options like: After reviewing options, select your preferred approach or ask for more exploration. The LLM leads with its recommendation and explains the reasoning. -#### Using FPF for Systematic Evaluation - -For architectural decisions with long-term consequences, consider using the [FPF plugin](../plugins/fpf/README.md) to systematically evaluate approaches: - -```bash -/fpf:propose-hypotheses What caching strategy should we use for our API? -``` - -FPF provides: - -- **Structured hypothesis generation** - Multiple competing options with diverse perspectives -- **Logical verification** - Check each option against project constraints -- **Evidence validation** - Empirical testing with trust scores -- **Auditable decisions** - Full reasoning trail preserved in `.fpf/` directory - -**When to use FPF vs SDD brainstorming:** - -| Scenario | Use FPF | Use SDD Brainstorming | -|----------|---------|----------------------| -| Architectural decisions with long-term impact | Yes | No | -| Multiple viable approaches needing systematic comparison | Yes | Maybe | -| Decisions requiring audit trails | Yes | No | -| Quick exploration of ideas | No | Yes | -| Easily reversible decisions | No | Yes | -| Time-critical situations | No | Yes | - -See [FPF plugin documentation](../plugins/fpf/README.md) for detailed workflow steps. - ### 3. Present design The LLM presents the validated approach as a design document in 200-300 word sections, checking after each section whether it looks right. @@ -140,10 +111,10 @@ After each section, confirm it matches your expectations or request changes. Onc ### 4. Create task and plan specification -Use the `/sdd:add-task` command to create a task file from the refined design, then `/sdd:plan` to generate a detailed specification with architecture, implementation steps, and verification criteria. +Use the `/add-task` command to create a task file from the refined design, then `/plan-task` to generate a detailed specification with architecture, implementation steps, and verification criteria. ```bash -/sdd:add-task "Implement faceted search with Elasticsearch, filters, and autocomplete" +/add-task "Implement faceted search with Elasticsearch, filters, and autocomplete" ``` After LLM completes, review the task file in `.specs/tasks/draft/`. You can adjust the task file to incorporate additional details from the brainstorming session. @@ -151,17 +122,17 @@ After LLM completes, review the task file in `.specs/tasks/draft/`. You can adju Then run planning to generate the full specification: ```bash -/sdd:plan +/plan-task ``` -After LLM completes, review the refined specification in `.specs/tasks/todo/`. The plan includes architecture design, implementation steps with parallelization, and verification rubrics. You can adjust and run `/sdd:plan --refine` to iterate. +After LLM completes, review the refined specification in `.specs/tasks/todo/`. The plan includes architecture design, implementation steps with parallelization, and verification rubrics. You can adjust and run `/plan-task --refine` to iterate. ### 5. Implement features -Use the `/sdd:implement` command to execute the implementation. This produces working code with tests and verification. +Use the `/implement-task` command to execute the implementation. This produces working code with tests and verification. ```bash -/sdd:implement +/implement-task ``` During implementation, the LLM executes each step with quality gates, writes tests, and verifies the solution works as expected. More info in [Spec-Driven Development](./spec-driven-development.md) workflow. @@ -171,9 +142,9 @@ During implementation, the LLM executes each step with quality gates, writes tes Complete the workflow with code review and pull request creation. ```bash -/code-review:review-local-changes -/git:commit -/git:create-pr +/review-local-changes +/commit +/create-pr ``` After completion, your feature is ready for merge. diff --git a/docs/guides/bug-investigation.md b/docs/guides/bug-investigation.md index edf9b17..85d58f3 100644 --- a/docs/guides/bug-investigation.md +++ b/docs/guides/bug-investigation.md @@ -15,7 +15,7 @@ For simple, obvious bugs (typos, single-line fixes), use [Feature Development](. - [Git](../plugins/git/README.md) - [Kaizen](../plugins/kaizen/README.md) -- [Code Review](../plugins/code-review/README.md) +- [Review](../plugins/review/README.md) - [Reflexion](../plugins/reflexion/README.md) ## Workflow @@ -73,30 +73,30 @@ For simple, obvious bugs (typos, single-line fixes), use [Feature Development](. ### 1. Load issue context -Use the `/git:analyze-issue` command to load the bug report from GitHub and extract technical details. +Use the `/analyze-issue` command to load the bug report from GitHub and extract technical details. ```bash -/git:analyze-issue #123 +/analyze-issue #123 ``` After LLM completes, you will have a structured understanding of the bug symptoms, reproduction steps, affected areas, and any related issues or context from the discussion. ### 2. Trace root cause -Use the `/kaizen:root-cause-tracing` command to systematically trace the bug backward through the call stack. +Use the `/root-cause-tracing` command to systematically trace the bug backward through the call stack. ```bash -/kaizen:root-cause-tracing +/root-cause-tracing ``` After LLM completes, you will have identified where invalid data originates or where incorrect behavior starts. This traces from the symptom (e.g., wrong output) back to the source (e.g., missing validation in input handler). ### 3. Analyze with Five Whys -Use the `/kaizen:why` command to drill deeper into why the root cause exists in the first place. +Use the `/why` command to drill deeper into why the root cause exists in the first place. ```bash -/kaizen:why +/why ``` After LLM completes, you will understand not just what went wrong, but why the codebase allowed it to happen. This reveals systemic issues like missing tests, unclear specifications, or architectural gaps that enabled the bug. @@ -121,30 +121,30 @@ Claude will implement the fix and automatically review it for correctness. ### 5. Review fix -Use the `/code-review:review-local-changes` command to ensure the fix is correct and doesn't introduce new issues. +Use the `/review-local-changes` command to ensure the fix is correct and doesn't introduce new issues. ```bash -/code-review:review-local-changes +/review-local-changes ``` After LLM completes, address any findings from the multi-agent review. Pay special attention to Bug Hunter findings (new edge cases) and Test Coverage (ensuring the bug has regression tests). ### 6. Preserve learnings -Use the `/reflexion:memorize` command to capture insights from this bug investigation for future reference. +Use the `/memorize` command to capture insights from this bug investigation for future reference. ```bash -/reflexion:memorize Bug pattern: race conditions in Redis operations +/memorize Bug pattern: race conditions in Redis operations ``` After LLM completes, your CLAUDE.md will be updated with learnings about this bug pattern, helping prevent similar issues in future development. This builds institutional knowledge about your codebase's pitfalls. ### 7. Commit with context -Use the `/git:commit` command to create a well-documented commit that links to the issue and explains the fix. +Use the `/commit` command to create a well-documented commit that links to the issue and explains the fix. ```bash -/git:commit +/commit ``` After LLM completes, your commit will follow conventional commit format with the bug fix type, proper scope, and reference to the issue (e.g., `Fixes #123`). This creates a searchable history for future debugging. @@ -158,7 +158,7 @@ The Kaizen plugin offers additional analysis techniques for different scenarios: Use Fishbone (Cause-and-Effect) analysis to explore causes across six categories: ```bash -/kaizen:cause-and-effect +/cause-and-effect ``` ### For comprehensive problem documentation @@ -166,7 +166,7 @@ Use Fishbone (Cause-and-Effect) analysis to explore causes across six categories Use A3 analysis for a one-page problem summary with root cause and action plan: ```bash -/kaizen:analyse-problem +/analyse-problem ``` ### For iterative experimentation @@ -174,5 +174,5 @@ Use A3 analysis for a one-page problem summary with root cause and action plan: Use PDCA (Plan-Do-Check-Act) cycle when the fix requires testing hypotheses: ```bash -/kaizen:plan-do-check-act +/plan-do-check-act ``` diff --git a/docs/guides/ci-integration.md b/docs/guides/ci-integration.md index e2b1f3d..7c9ea7f 100644 --- a/docs/guides/ci-integration.md +++ b/docs/guides/ci-integration.md @@ -71,12 +71,12 @@ jobs: use_sticky_comment: true plugin_marketplaces: https://github.com/NeoLabHQ/context-engineering-kit.git - plugins: "code-review@context-engineering-kit\ngit@context-engineering-kit\ntdd@context-engineering-kit\nsadd@context-engineering-kit\nddd@context-engineering-kit\nsdd@context-engineering-kit\nkaizen@context-engineering-kit" + plugins: "review@context-engineering-kit\ngit@context-engineering-kit\ntdd@context-engineering-kit\nsadd@context-engineering-kit\nddd@context-engineering-kit\nsdd@context-engineering-kit\nkaizen@context-engineering-kit" - prompt: '/code-review:review-pr ${{ github.repository }}/pull/${{ github.event.pull_request.number }} Note: The PR branch is already checked out in the current working directory.' + prompt: '/review-pr ${{ github.repository }}/pull/${{ github.event.pull_request.number }} Note: The PR branch is already checked out in the current working directory.' # Skill and Bash(gh pr comment:*) is required for review, the rest is optional, but recommended for better context and quality of the review. - claude_args: '--allowed-tools "Skill,Bash,Glob,Grep,Read,Task,mcp__github_inline_comment__create_inline_comment,Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr edit:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh api:*)"' + claude_args: '--allowed-tools "Skill,Bash,Glob,Grep,Read,Task,mcp__github_inline_comment__create_inline_comment,Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr edit:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh api:*)" --system-prompt "Follow /review-pr skill EXACTLY!!!"' ``` ## How It Works diff --git a/docs/guides/code-quality-improvement.md b/docs/guides/code-quality-improvement.md index 2156d36..55932d6 100644 --- a/docs/guides/code-quality-improvement.md +++ b/docs/guides/code-quality-improvement.md @@ -16,7 +16,7 @@ For root cause analysis of bugs and incidents, use the [Debugging and Root Cause - [Kaizen](../plugins/kaizen/README.md) - [Reflexion](../plugins/reflexion/README.md) -- [Code Review](../plugins/code-review/README.md) +- [Review](../plugins/review/README.md) - [Git](../plugins/git/README.md) ## Workflow @@ -74,30 +74,30 @@ For root cause analysis of bugs and incidents, use the [Debugging and Root Cause ### 1. Analyze target area -Use the `/kaizen:analyse` command to intelligently analyze your target area for improvement opportunities. The command auto-selects the best analysis method: Gemba Walk (code exploration), Value Stream Mapping (workflow/process), or Muda Analysis (waste identification). +Use the `/analyse` command to intelligently analyze your target area for improvement opportunities. The command auto-selects the best analysis method: Gemba Walk (code exploration), Value Stream Mapping (workflow/process), or Muda Analysis (waste identification). ```bash -/kaizen:analyse Target the checkout flow for performance optimization +/analyse Target the checkout flow for performance optimization ``` After LLM completes, review the analysis findings including identified waste, bottlenecks, or gaps between documentation and reality. The output provides actionable insights categorized by priority. ### 2. Get multi-perspective critique -Use the `/reflexion:critique` command to get comprehensive feedback from multiple specialized perspectives. This surfaces issues that might be missed by a single analysis approach. +Use the `/critique` command to get comprehensive feedback from multiple specialized perspectives. This surfaces issues that might be missed by a single analysis approach. ```bash -/reflexion:critique +/critique ``` After LLM completes, review the structured feedback from multiple judges covering different aspects like security, performance, maintainability, and design. Note the consensus points and any areas of disagreement. ### 3. Plan improvements with PDCA cycle -Use the `/kaizen:plan-do-check-act` command to create a structured improvement plan with measurable success criteria. This ensures changes are systematic and results can be verified. +Use the `/plan-do-check-act` command to create a structured improvement plan with measurable success criteria. This ensures changes are systematic and results can be verified. ```bash -/kaizen:plan-do-check-act Reduce API response time by 50% +/plan-do-check-act Reduce API response time by 50% ``` After LLM completes, review the PDCA plan which includes: @@ -120,30 +120,30 @@ After LLM completes, the changes are applied to your local working directory. Th ### 5. Review local changes -Use the `/code-review:review-local-changes` command to verify the quality of implemented changes before committing. +Use the `/review-local-changes` command to verify the quality of implemented changes before committing. ```bash -/code-review:review-local-changes +/review-local-changes ``` After LLM completes, review the findings from multiple specialized agents (Bug Hunter, Security Auditor, Code Quality Reviewer, etc.). Address any critical or high-priority issues before proceeding. If the review identifies significant problems, iterate back to step 4. ### 6. Preserve learnings -Use the `/reflexion:memorize` command to capture valuable insights from this improvement cycle for future reference. +Use the `/memorize` command to capture valuable insights from this improvement cycle for future reference. ```bash -/reflexion:memorize Performance optimization patterns for checkout flow +/memorize Performance optimization patterns for checkout flow ``` After LLM completes, the insights are added to your project's CLAUDE.md file. This builds a knowledge base of patterns, pitfalls, and solutions that improve future development. ### 7. Create conventional commit -Use the `/git:commit` command to create a well-formatted commit message following conventional commit standards. +Use the `/commit` command to create a well-formatted commit message following conventional commit standards. ```bash -/git:commit +/commit ``` After LLM completes, review the generated commit message which describes the improvement, its rationale, and measurable impact. The commit is ready to push to your repository. @@ -154,26 +154,26 @@ Depending on your improvement goal, you may want to use specialized Kaizen comma ### For comprehensive problem documentation -Use `/kaizen:analyse-problem` when you need a structured A3 one-page analysis with background, root cause, countermeasures, and implementation plan. +Use `/analyse-problem` when you need a structured A3 one-page analysis with background, root cause, countermeasures, and implementation plan. ```bash -/kaizen:analyse-problem API response times degraded after last release +/analyse-problem API response times degraded after last release ``` ### For iterative root cause investigation -Use `/kaizen:why` (Five Whys) when you need to drill from symptoms to fundamental causes through iterative questioning. +Use `/why` (Five Whys) when you need to drill from symptoms to fundamental causes through iterative questioning. ```bash -/kaizen:why Why is the checkout page loading slowly? +/why Why is the checkout page loading slowly? ``` ### For systematic cause exploration -Use `/kaizen:cause-and-effect` (Fishbone analysis) when exploring causes across multiple categories: People, Process, Technology, Methods, Environment, and Materials. +Use `/cause-and-effect` (Fishbone analysis) when exploring causes across multiple categories: People, Process, Technology, Methods, Environment, and Materials. ```bash -/kaizen:cause-and-effect Investigate causes of high memory usage in production +/cause-and-effect Investigate causes of high memory usage in production ``` ## Tips for Effective Quality Improvement diff --git a/docs/guides/competitivy-generation.md b/docs/guides/competitivy-generation.md index 86aa354..6b98212 100644 --- a/docs/guides/competitivy-generation.md +++ b/docs/guides/competitivy-generation.md @@ -22,7 +22,7 @@ For simple features that don't require competitive exploration, use [Feature Dev - [SADD](../plugins/sadd/README.md) - Competitive execution - [TDD](../plugins/tdd/README.md) - Test coverage -- [Code Review](../plugins/code-review/README.md) - Final validation +- [Review](../plugins/review/README.md) - Final validation - [Git](../plugins/git/README.md) - Version control ## Workflow @@ -62,10 +62,10 @@ For simple features that don't require competitive exploration, use [Feature Dev ### 1. Competitive Implementation -Use `/sadd:do-competitively` to generate multiple solutions, evaluate them independently, and synthesize the best elements. +Use `/do-competitively` to generate multiple solutions, evaluate them independently, and synthesize the best elements. ```bash -/sadd:do-competitively "Implement JWT authentication middleware with token refresh, rate limiting, and secure session management" +/do-competitively "Implement JWT authentication middleware with token refresh, rate limiting, and secure session management" ``` **What happens:** @@ -76,49 +76,49 @@ Use `/sadd:do-competitively` to generate multiple solutions, evaluate them indep For specific output location: ```bash -/sadd:do-competitively "Design user authentication schema" --output "src/models/auth.ts" +/do-competitively "Design user authentication schema" --output "src/models/auth.ts" ``` With custom evaluation criteria: ```bash -/sadd:do-competitively "Create API rate limiting middleware" --criteria "security,performance,maintainability" +/do-competitively "Create API rate limiting middleware" --criteria "security,performance,maintainability" ``` After completion, review the synthesized solution to ensure it meets your requirements. ### 2. Write Tests -Use `/tdd:write-tests` to generate comprehensive test coverage for the synthesized solution. +Use `/write-tests` to generate comprehensive test coverage for the synthesized solution. ```bash -/tdd:write-tests +/write-tests ``` Or with specific focus: ```bash -/tdd:write-tests Focus on security edge cases and error handling +/write-tests Focus on security edge cases and error handling ``` Verify all tests pass before continuing. ### 3. Review Local Changes -Use `/code-review:review-local-changes` for final multi-agent validation. +Use `/review-local-changes` for final multi-agent validation. ```bash -/code-review:review-local-changes +/review-local-changes ``` Address Critical and High priority findings before committing. ### 4. Create Commit -Use `/git:commit` to create a well-formatted conventional commit. +Use `/commit` to create a well-formatted conventional commit. ```bash -/git:commit +/commit ``` ## Quality Comparison @@ -134,14 +134,14 @@ Use `/git:commit` to create a well-formatted conventional commit. ## Advanced: Combining with Tree of Thoughts -For tasks requiring exploration before commitment, use `/sadd:tree-of-thoughts` first: +For tasks requiring exploration before commitment, use `/tree-of-thoughts` first: ```bash # Explore approaches first -/sadd:tree-of-thoughts "Design caching strategy for high-traffic API" +/tree-of-thoughts "Design caching strategy for high-traffic API" # Then implement the winning approach competitively -/sadd:do-competitively "Implement Redis-based caching with the write-through pattern identified above" +/do-competitively "Implement Redis-based caching with the write-through pattern identified above" ``` ## Advanced: Debate-Based Evaluation @@ -150,10 +150,10 @@ For highest-stakes decisions where consensus is critical: ```bash # Implement competitively -/sadd:do-competitively "Design payment processing flow" --output "src/services/payment.ts" +/do-competitively "Design payment processing flow" --output "src/services/payment.ts" # Evaluate with iterative debate -/sadd:judge-with-debate --solution "src/services/payment.ts" --task "Payment processing implementation" --criteria "security:30,correctness:30,reliability:20,performance:20" +/judge-with-debate --solution "src/services/payment.ts" --task "Payment processing implementation" --criteria "security:30,correctness:30,reliability:20,performance:20" ``` ## Tips diff --git a/docs/guides/custom-extensions.md b/docs/guides/custom-extensions.md index 06f3572..8721fb7 100644 --- a/docs/guides/custom-extensions.md +++ b/docs/guides/custom-extensions.md @@ -63,10 +63,10 @@ After LLM completes, it will report whether the command handles scenarios correc ### 3. Document the extension -Use the `/docs:update-docs` command to add the new command to project documentation. +Use the `/update-docs` command to add the new command to project documentation. ```bash -/docs:update-docs +/update-docs ``` After LLM completes, your command will be documented and discoverable by the team. @@ -135,10 +135,10 @@ After LLM completes, your skill will be optimized for discoverability, progressi ### 4. Document the extension -Use the `/docs:update-docs` command to add the new skill to project documentation. +Use the `/update-docs` command to add the new skill to project documentation. ```bash -/docs:update-docs +/update-docs ``` After LLM completes, your skill will be documented and the team can discover and use it. @@ -308,4 +308,4 @@ Make skills discoverable: | Test skill under pressure | `/customaize-agent:test-skill` | | Apply Anthropic best practices | `/customaize-agent:apply-anthropic-skill-best-practices` | | Create git hook | `/customaize-agent:create-hook` | -| Document changes | `/docs:update-docs` | +| Document changes | `/update-docs` | diff --git a/docs/guides/decision-making.md b/docs/guides/decision-making.md index cc6e43b..88338d2 100644 --- a/docs/guides/decision-making.md +++ b/docs/guides/decision-making.md @@ -76,10 +76,10 @@ For quick decisions with obvious solutions, skip FPF and decide directly. For de ### 1. Generate hypotheses -Use the `/fpf:propose-hypotheses` command to start the FPF cycle. The FPF agent will generate 3-5 competing hypotheses for your problem. +Use the `/propose-hypotheses` command to start the FPF cycle. The FPF agent will generate 3-5 competing hypotheses for your problem. ```bash -/fpf:propose-hypotheses What caching strategy should we use? +/propose-hypotheses What caching strategy should we use? ``` After starting, the FPF agent will: @@ -217,7 +217,7 @@ This ensures accountability and prevents AI from making unsupervised decisions. ### Starting the workflow ```bash -/fpf:propose-hypotheses What caching strategy should we use for the product catalog? +/propose-hypotheses What caching strategy should we use for the product catalog? ``` ### Generated hypotheses (L0) @@ -333,7 +333,7 @@ Evidence expires. A benchmark from 6 months ago may not reflect current performa ### Check stale evidence ```bash -/fpf:decay +/decay ``` The decay command shows evidence that needs attention: @@ -392,10 +392,10 @@ FPF integrates with other workflows at decision points: Use FPF to decide on architecture approach before creating the spec: ```bash -/fpf:propose-hypotheses What architecture pattern should we use for this feature? +/propose-hypotheses What architecture pattern should we use for this feature? # Review DRR and select approach /sdd:add-task "Implement feature using [selected approach]" -/sdd:plan +/plan-task ``` ### During brainstorming @@ -405,10 +405,10 @@ Use FPF to evaluate alternative designs: ```bash /sdd:brainstorm Users want better search but requirements are unclear # After exploring approaches, use FPF to decide -/fpf:propose-hypotheses Which search implementation should we choose? +/propose-hypotheses Which search implementation should we choose? # Continue with selected approach /sdd:add-task "Implement search with [selected approach]" -/sdd:plan +/plan-task ``` ### For technical decisions @@ -416,9 +416,9 @@ Use FPF to evaluate alternative designs: Use FPF for any architectural choice needing audit trail: ```bash -/fpf:propose-hypotheses How should we deploy our application? -/fpf:propose-hypotheses What testing strategy should we use? -/fpf:propose-hypotheses Which database should we choose? +/propose-hypotheses How should we deploy our application? +/propose-hypotheses What testing strategy should we use? +/propose-hypotheses Which database should we choose? ``` ## Utility Commands @@ -427,11 +427,11 @@ FPF provides utility commands for managing the knowledge base: | Command | Description | |---------|-------------| -| `/fpf:status` | Show current FPF phase and hypothesis counts | -| `/fpf:query` | Search knowledge base with assurance info | -| `/fpf:decay` | Manage evidence freshness (refresh/deprecate/waive) | -| `/fpf:actualize` | Reconcile knowledge with codebase changes | -| `/fpf:reset` | Archive session and return to IDLE | +| `/status` | Show current FPF phase and hypothesis counts | +| `/query` | Search knowledge base with assurance info | +| `/decay` | Manage evidence freshness (refresh/deprecate/waive) | +| `/actualize` | Reconcile knowledge with codebase changes | +| `/reset` | Archive session and return to IDLE | ## Related Resources diff --git a/docs/guides/feature-development.md b/docs/guides/feature-development.md index ba7d333..24bd077 100644 --- a/docs/guides/feature-development.md +++ b/docs/guides/feature-development.md @@ -15,7 +15,7 @@ For complex features requiring architecture planning, use [Spec-Driven Developme - [Reflexion](../plugins/reflexion/README.md) - [TDD](../plugins/tdd/README.md) -- [Code Review](../plugins/code-review/README.md) +- [Review](../plugins/review/README.md) - [Git](../plugins/git/README.md) ## Workflow @@ -83,55 +83,55 @@ After it finish reflection and fixes, review the generated code to ensure it add ### 2. Write tests -Use the `/tdd:write-tests` command to generate tests covering the changes you made. You can optionally specify areas to focus on. +Use the `/write-tests` command to generate tests covering the changes you made. You can optionally specify areas to focus on. ```bash -/tdd:write-tests +/write-tests ``` Or with specific focus areas: ```bash -/tdd:write-tests Focus on edge cases and error handling +/write-tests Focus on edge cases and error handling ``` After LLM completes, verify that all tests pass. If tests fail, ask the LLM to fix the issues before continuing. ### 3. Review local changes -Use the `/code-review:review-local-changes` command to run a comprehensive multi-agent code review on your uncommitted changes. +Use the `/review-local-changes` command to run a comprehensive multi-agent code review on your uncommitted changes. ```bash -/code-review:review-local-changes +/review-local-changes ``` After LLM completes, review the findings organized by severity (Critical, High, Medium, Low). Address Critical and High priority issues before committing. You can ask the LLM to fix specific issues. ### 4. Preserve learnings -Use the `/reflexion:memorize` command to save valuable insights and patterns discovered during development to your project memory. +Use the `/memorize` command to save valuable insights and patterns discovered during development to your project memory. ```bash -/reflexion:memorize +/memorize ``` Or with specific context: ```bash -/reflexion:memorize "Email validation patterns and regex considerations" +/memorize "Email validation patterns and regex considerations" ``` After LLM completes, the insights are saved to CLAUDE.md, making them available for future development sessions. ### 5. Create commit -Use the `/git:commit` command to create a well-formatted conventional commit with appropriate emoji. +Use the `/commit` command to create a well-formatted conventional commit with appropriate emoji. ```bash -/git:commit +/commit ``` -After LLM completes, a commit is created with a descriptive message following conventional commit format. You can then push your changes or create a pull request using `/git:create-pr`. +After LLM completes, a commit is created with a descriptive message following conventional commit format. You can then push your changes or create a pull request using `/create-pr`. ## Tips diff --git a/docs/guides/pr-review.md b/docs/guides/pr-review.md index 028286e..64e7d34 100644 --- a/docs/guides/pr-review.md +++ b/docs/guides/pr-review.md @@ -4,7 +4,7 @@ Comprehensive pull request review using specialized agents to catch issues befor Other types of reviews: -- Local changes only - For pre-commit local review, use `/code-review:review-local-changes` command directly. +- Local changes only - For pre-commit local review, use `/review-local-changes` command directly. - CI Integration - You can automate PR reviews using GitHub Actions. See the [CI/CD Integration guide](./ci-integration.md) for setup instructions. @@ -17,7 +17,7 @@ Other types of reviews: ## Plugins needed for this workflow -- [Code Review](../plugins/code-review/README.md) +- [Review](../plugins/review/README.md) - [Reflexion](../plugins/reflexion/README.md) - [Git](../plugins/git/README.md) @@ -76,10 +76,10 @@ Other types of reviews: ### 1. Review PR with specialized agents -Use the `/code-review:review-pr` command to analyze a pull request with six specialized agents: Bug Hunter, Security Auditor, Test Coverage Reviewer, Code Quality Reviewer, Contracts Reviewer, and Historical Context Reviewer. +Use the `/review-pr` command to analyze a pull request with six specialized agents: Bug Hunter, Security Auditor, Test Coverage Reviewer, Code Quality Reviewer, Contracts Reviewer, and Historical Context Reviewer. ```bash -/code-review:review-pr #123 +/review-pr #123 ``` After LLM completes, you receive a structured report with findings categorized by severity (Critical, High, Medium, Low). Each agent provides specific findings with file locations and line references. @@ -122,20 +122,20 @@ After LLM completes, the issues should be resolved in your local working directo ### 4. Re-review local changes -Use the `/code-review:review-local-changes` command to verify your fixes resolve the identified issues and do not introduce new problems. +Use the `/review-local-changes` command to verify your fixes resolve the identified issues and do not introduce new problems. ```bash -/code-review:review-local-changes +/review-local-changes ``` After LLM completes, compare the new findings with the original PR review. If Critical or High priority issues remain, return to step 3 and continue fixing. Repeat until the review is clean. ### 5. Get final critique -Use the `/reflexion:critique` command to get an additional multi-perspective review before pushing. This provides a final quality check from multiple specialized judges. +Use the `/critique` command to get an additional multi-perspective review before pushing. This provides a final quality check from multiple specialized judges. ```bash -/reflexion:critique +/critique ``` After LLM completes, review the critique feedback. Address any significant concerns raised. The critique offers perspectives that complement the code review agents. @@ -152,10 +152,10 @@ After push completes, the PR will be updated with your fixes. Reviewers can now ### 7. Preserve learnings -Use the `/reflexion:memorize` command to save valuable patterns, decisions, and insights discovered during the review process to your project memory. +Use the `/memorize` command to save valuable patterns, decisions, and insights discovered during the review process to your project memory. ```bash -/reflexion:memorize +/memorize ``` After LLM completes, your CLAUDE.md file is updated with learnings from this review cycle. These insights help improve future development and reviews. @@ -166,7 +166,7 @@ After LLM completes, your CLAUDE.md file is updated with learnings from this rev **Iterate efficiently**: Run review commands after each batch of fixes rather than after each individual fix to save time. -**Learn from patterns**: Use `/reflexion:memorize` to capture recurring issues as project guidelines to prevent them in future PRs. +**Learn from patterns**: Use `/memorize` to capture recurring issues as project guidelines to prevent them in future PRs. **Combine perspectives**: The six review agents and reflexion critique provide complementary views - consider all perspectives before marking issues as resolved. diff --git a/docs/guides/project-setup.md b/docs/guides/project-setup.md deleted file mode 100644 index 011cd6a..0000000 --- a/docs/guides/project-setup.md +++ /dev/null @@ -1,115 +0,0 @@ -# Project Setup - -Initialize new projects with established best practices, coding standards, and tooling from day one. - -## When to Use - -- Starting a new project from scratch -- Onboarding an existing codebase to Context Engineering Kit -- Establishing consistent development standards across a team -- Setting up AI-assisted development infrastructure - -## Plugins needed for this workflow - -- [Tech Stack](../plugins/tech-stack/README.md) -- [DDD](../plugins/ddd/README.md) -- [MCP](../plugins/mcp/README.md) -- [Docs](../plugins/docs/README.md) - -## Workflow - -### How It Works - -```md -┌─────────────────────────────────────────────┐ -│ 1. Setup Language Best Practices │ -│ (update CLAUDE.md) │ -└────────────────────┬────────────────────────┘ - │ - │ add language-specific guidelines - ▼ -┌─────────────────────────────────────────────┐ -│ 2. Setup Code Quality Standards │ -│ (update CLAUDE.md) │ -└────────────────────┬────────────────────────┘ - │ - │ add formatting and style rules - ▼ -┌─────────────────────────────────────────────┐ -│ 3. Setup MCP Servers (optional) │ -│ (configure external tools) │ -└────────────────────┬────────────────────────┘ - │ - │ enable documentation and code retrieval - ▼ -┌─────────────────────────────────────────────┐ -│ 4. Document Project Setup │ -│ (update docs/ directory) │ -└─────────────────────────────────────────────┘ -``` - -### 0. Init claude code - -Use the `/init` command to initialize your project. - -```bash -claude /init -``` - -After LLM completes, review the `CLAUDE.md` file and adjust any principles or constraints. - -### 1. Setup language best practices - -Use the `/tech-stack:add-typescript-best-practices` command to add language-specific coding standards to your `CLAUDE.md` file. - -```bash -/tech-stack:add-typescript-best-practices -``` - -After LLM completes, review the added guidelines in `CLAUDE.md`. These rules ensure consistent code style and patterns across all AI-assisted development. - -### 2. Setup code quality standards - -Use the `/ddd:setup-code-formating` command to establish code formatting rules and style guidelines. - -```bash -/ddd:setup-code-formating -``` - -After LLM completes, review the formatting rules added to `CLAUDE.md`. These standards ensure consistent code structure following Clean Architecture and SOLID principles. - -### 3. Setup MCP servers (optional) - -Use MCP commands to integrate external tools that enhance AI capabilities. Choose based on your project needs: - -**For documentation retrieval** - loads documentation for specific technologies: - -```bash -/mcp:setup-context7-mcp -``` - -**For semantic code retrieval** - enables advanced code search and editing: - -```bash -/mcp:setup-serena-mcp -``` - -After LLM completes for each command, follow the setup instructions provided. MCP servers extend Claude's capabilities with project-specific context. - -### 4. Document project setup - -Use the `/docs:update-docs` command to generate initial project documentation based on your setup. - -```bash -/docs:update-docs -``` - -After LLM completes, review the generated documentation in the `docs/` directory. This provides a foundation for onboarding team members and maintaining project knowledge. - -## What You Get - -After completing this workflow, your project will have: - -- **`CLAUDE.md`** - AI assistant configuration with coding standards -- **`docs/`** - Initial project documentation -- **MCP integrations** - Enhanced tooling for documentation and code retrieval (if configured) diff --git a/docs/plugins/README.md b/docs/plugins/README.md index aefa360..efd76bd 100644 --- a/docs/plugins/README.md +++ b/docs/plugins/README.md @@ -9,7 +9,7 @@ This directory contains comprehensive documentation for all 13 plugins in the Co ## Quick Navigation * [Reflexion](reflexion/) - Self-refinement and iterative improvement -* [Code Review](code-review/) - Multi-agent code quality analysis +* [Review](review/) - Multi-agent code quality analysis * [Git](git/) - Streamlined Git operations * [Test-Driven Development](tdd/) - TDD methodology and best practices * [Subagent-Driven Development](sadd/) - Task delegation with quality gates @@ -54,7 +54,7 @@ Self-refinement framework that introduces feedback and refinement loops to impro [Full Documentation](reflexion/) -#### Code Review +#### Review Comprehensive code review using multiple specialized agents for thorough quality evaluation. @@ -66,7 +66,7 @@ Comprehensive code review using multiple specialized agents for thorough quality **When to use:** Before committing changes or creating pull requests. -[Full Documentation](code-review/) +[Full Documentation](review/) ### Development Workflows @@ -145,7 +145,6 @@ Code quality and architecture patterns including Clean Architecture and SOLID pr **Key Features:** -* Code formatting setup * 14 composable rules organized into Architecture, Function Design, Explicitness, and Code Quality categories * Covers Clean Architecture, Command-Query Separation, Functional Core/Imperative Shell, and more diff --git a/docs/plugins/customaize-agent/README.md b/docs/plugins/customaize-agent/README.md index 68af7e8..49d94a6 100644 --- a/docs/plugins/customaize-agent/README.md +++ b/docs/plugins/customaize-agent/README.md @@ -58,9 +58,9 @@ The plugin is built on Anthropic's official skill authoring best practices and r ## Skills -- [customaize-agent:prompt-engineering](./prompt-engineering.md) - Advanced prompt engineering techniques including Anthropic's official best practices and research-backed persuasion principles. -- [customaize-agent:context-engineering](./context-engineering.md) - Use when writing, editing, or optimizing commands, skills, or sub-agent prompts. Provides deep understanding of context mechanics in agent systems. -- [customaize-agent:agent-evaluation](./agent-evaluation.md) - Use when testing prompt effectiveness, validating context engineering choices, or measuring agent improvement quality. +- [prompt-engineering](./prompt-engineering.md) - Advanced prompt engineering techniques including Anthropic's official best practices and research-backed persuasion principles. +- [context-engineering](./context-engineering.md) - Use when writing, editing, or optimizing commands, skills, or sub-agent prompts. Provides deep understanding of context mechanics in agent systems. +- [agent-evaluation](./agent-evaluation.md) - Use when testing prompt effectiveness, validating context engineering choices, or measuring agent improvement quality. ## Theoretical Foundation diff --git a/docs/plugins/customaize-agent/usage-examples.md b/docs/plugins/customaize-agent/usage-examples.md index 7fef127..48e7d19 100644 --- a/docs/plugins/customaize-agent/usage-examples.md +++ b/docs/plugins/customaize-agent/usage-examples.md @@ -57,7 +57,7 @@ Flag for manual review: > /customaize-agent:test-prompt .claude/commands/validate-api.md # Document the new command -> /docs:update-docs +> /update-docs ``` --- @@ -462,7 +462,7 @@ All baseline failures resolved. ```bash # Apply TDD to both code AND prompts -> /tdd:write-tests src/auth.ts # For code +> /write-tests src/auth.ts # For code > /customaize-agent:test-prompt .claude/commands/auth-flow.md # For prompts diff --git a/docs/plugins/ddd/README.md b/docs/plugins/ddd/README.md index 47b3522..4b9d124 100644 --- a/docs/plugins/ddd/README.md +++ b/docs/plugins/ddd/README.md @@ -28,23 +28,8 @@ These principles address the core challenge of software development: **managing > claude "Use DDD rules to implement user authentication" ``` -## Code Formatting - -To enable code formatting rules, you can use the following command: - -```bash -/ddd:setup-code-formating -``` - [Usage Examples](./usage-examples.md) -## Commands - -### setup-code-formating - -Establishes consistent code formatting rules and style guidelines by updating your project's CLAUDE.md file with enforced standards. -See [setup-code-formating.md](./setup-code-formating.md) for detailed command documentation. - ## Rules The DDD plugin includes 14 rules organized into four categories that activate automatically when writing or reviewing code. Each rule targets specific file patterns and has an assigned impact level. diff --git a/docs/plugins/ddd/setup-code-formating.md b/docs/plugins/ddd/setup-code-formating.md deleted file mode 100644 index 6eef47a..0000000 --- a/docs/plugins/ddd/setup-code-formating.md +++ /dev/null @@ -1,57 +0,0 @@ -# /ddd:setup-code-formating - Code Style Configuration - -Establishes consistent code formatting rules and style guidelines by updating your project's CLAUDE.md file with enforced standards. - -- Purpose - Configure AI-assisted development with consistent code style -- Output - Updated CLAUDE.md with formatting rules - -```bash -/ddd:setup-code-formating -``` - -## Arguments - -None required - creates standard formatting configuration. - -## How It Works - -1. **Configuration Detection**: Checks for existing CLAUDE.md in the project root -2. **Standards Application**: Adds or updates the Code Style Rules section with: - - Semicolon usage rules - - Quote style enforcement - - Curly brace conventions - - Indentation standards - - Import ordering guidelines - -3. **Persistent Memory**: Rules are written to CLAUDE.md, ensuring all future AI interactions follow the same standards - -**Formatting Rules Applied** - -The command configures the following standards: - -| Rule | Setting | Purpose | -|------|---------|---------| -| Semicolons | No semicolons | Cleaner, modern JavaScript/TypeScript | -| Quotes | Single quotes | Consistency across codebase | -| Curly braces | Minimal (no unnecessary) | Reduced visual noise | -| Indentation | 2 spaces | Readable, compact code | -| Import order | External, Internal, Types | Logical organization | - -## Usage Examples - -```bash -# Basic setup - adds formatting rules to CLAUDE.md -/ddd:setup-code-formating - -# Typically used during project initialization -/sdd:00-setup Use React, TypeScript, Node.js -/tech-stack:add-typescript-best-practices -/ddd:setup-code-formating -``` - -## Best Practices - -- Run early in project setup - Establish standards before significant code is written -- Combine with linting tools - Use ESLint/Prettier to enforce rules automatically -- Team alignment - Ensure all team members use the same CLAUDE.md configuration -- Review generated rules - Adjust the CLAUDE.md output if your project has different conventions diff --git a/docs/plugins/ddd/usage-examples.md b/docs/plugins/ddd/usage-examples.md index 82de21c..85ed4d1 100644 --- a/docs/plugins/ddd/usage-examples.md +++ b/docs/plugins/ddd/usage-examples.md @@ -4,43 +4,6 @@ Real-world scenarios demonstrating effective use of the Domain-Driven Developmen ## Examples -### Project Initialization with DDD Standards - -**Scenario**: You're starting a new TypeScript project and want to establish consistent code quality from day one. - -```bash -# Initialize Claude for your project -/init - -# Set up project constitution with Clean Architecture -/sdd:00-setup Use TypeScript, PostgreSQL, Clean Architecture, domain-driven design - -# Add TypeScript-specific best practices -/tech-stack:add-typescript-best-practices - -# Add code formatting standards -/ddd:setup-code-formating -``` - -**Expected Flow**: - -1. Project gets CLAUDE.md with base configuration -2. Constitution establishes architectural principles in `specs/constitution.md` -3. TypeScript guidelines added to CLAUDE.md -4. Code formatting rules enforced in CLAUDE.md - -**Resulting CLAUDE.md Section**: -```markdown -## Code Style Rules - -### Code Formatting - -- No semicolons (enforced) -- Single quotes (enforced) -- No unnecessary curly braces (enforced) -- 2-space indentation -- Import order: external -> internal -> types -``` ### Implementing a Feature with DDD Principles @@ -276,14 +239,10 @@ export class PhoneNumber { **Scenario**: Designing a new microservice that needs clear bounded context boundaries. ```bash -# Define the bounded context -/sdd:00-setup Payment microservice with Clean Architecture, bounded context for payment processing -# Set up code standards -/ddd:setup-code-formating # Design the domain model -claude "design the domain model for a payment processing bounded context" +claude "design the domain model for a payment processing bounded context for payment microservice with Clean Architecture, bounded context for payment processing" ``` **Expected Domain Model**: @@ -374,28 +333,26 @@ Suggested Refactoring: claude "implement order processing with Clean Architecture" # Reflect on architectural decisions -/reflexion:reflect architecture +/reflect architecture # Save learnings -/reflexion:memorize --section="Architecture Decisions" +/memorize --section="Architecture Decisions" ``` ### With SDD for Full Development Lifecycle ```bash -# Setup -/sdd:00-setup E-commerce platform with Clean Architecture -/ddd:setup-code-formating -# Specification -/sdd:01-brainstorm Shopping cart feature -/sdd:02-draft-spec +# Define +/brainstorm Add shopping cart feature +/add-task + +# Plan specification +/plan-task # Implementation (DDD skill active) -/sdd:04-implement +/implement-task -# Documentation -/sdd:05-document ``` ### With Code Review for Quality Gates @@ -405,7 +362,7 @@ claude "implement order processing with Clean Architecture" claude "add payment processing integration" # Review for DDD compliance -/code-review:review-local-changes +/review-local-changes # The software-architecture skill ensures review checks: # - Layer boundaries diff --git a/docs/plugins/docs/README.md b/docs/plugins/docs/README.md index aa26496..263a6d7 100644 --- a/docs/plugins/docs/README.md +++ b/docs/plugins/docs/README.md @@ -35,13 +35,13 @@ The plugin guides you through: # Update project documentation after implementing features > claude "implement user profile settings page" -> /docs:update-docs +> /update-docs # Focus on specific documentation type -> /docs:update-docs api +> /update-docs api # Target specific directory -> /docs:update-docs src/payments/ +> /update-docs src/payments/ ``` [Usage Examples](./usage-examples.md) diff --git a/docs/plugins/docs/update-docs.md b/docs/plugins/docs/update-docs.md index 01db03d..453f46d 100644 --- a/docs/plugins/docs/update-docs.md +++ b/docs/plugins/docs/update-docs.md @@ -1,4 +1,4 @@ -# /docs:update-docs - Documentation Update +# /update-docs - Documentation Update Comprehensive documentation update command that analyzes your project, identifies documentation needs, and creates or updates documentation following best practices. @@ -6,7 +6,7 @@ Comprehensive documentation update command that analyzes your project, identifie - Output - Updated README files, API docs, JSDoc comments, and guides ```bash -/docs:update-docs ["target directory or documentation type"] +/update-docs ["target directory or documentation type"] ``` ## Arguments @@ -79,20 +79,20 @@ Optional target specification: ```bash # Full project documentation update -> /docs:update-docs +> /update-docs # Update API documentation after adding new endpoints > claude "add /api/v2/subscriptions endpoint" -> /docs:update-docs api +> /update-docs api # Document a specific module after changes -> /docs:update-docs src/payments/ +> /update-docs src/payments/ # Focus on README files only -> /docs:update-docs readme +> /update-docs readme # Update JSDoc comments for complex business logic -> /docs:update-docs jsdoc +> /update-docs jsdoc ``` ## Quality Gates diff --git a/docs/plugins/docs/usage-examples.md b/docs/plugins/docs/usage-examples.md index 6264f33..fd02fd4 100644 --- a/docs/plugins/docs/usage-examples.md +++ b/docs/plugins/docs/usage-examples.md @@ -13,7 +13,7 @@ Real-world scenarios demonstrating effective use of the Docs plugin for maintain > claude "implement user authentication with JWT tokens" # Update documentation to reflect changes -> /docs:update-docs +> /update-docs ``` **Expected Flow**: @@ -48,7 +48,7 @@ Real-world scenarios demonstrating effective use of the Docs plugin for maintain > claude "add /api/v2/products endpoint with CRUD operations" # Update API documentation specifically -> /docs:update-docs api +> /update-docs api ``` **Expected Flow**: @@ -105,7 +105,7 @@ Create a new product. > claude "add Stripe subscription support to payments module" # Document the specific module -> /docs:update-docs src/payments/ +> /update-docs src/payments/ ``` **Expected Flow**: @@ -150,7 +150,7 @@ See: [Payment Integration Guide](../../docs/guides/payments.md) for detailed set ```bash # Run full documentation audit and update -> /docs:update-docs +> /update-docs ``` **Expected Flow**: @@ -192,7 +192,7 @@ See: [Payment Integration Guide](../../docs/guides/payments.md) for detailed set ```bash # Update JSDoc comments for complex code -> /docs:update-docs jsdoc +> /update-docs jsdoc ``` **Expected Flow**: @@ -239,7 +239,7 @@ async function calculateShipping( ```bash # Update only README files -> /docs:update-docs readme +> /update-docs readme ``` **Expected Flow**: @@ -281,13 +281,13 @@ async function calculateShipping( > /reflexion:reflect # 3. Write tests -> /tdd:write-tests +> /write-tests # 4. Review code -> /code-review:review-local-changes +> /review-local-changes # 5. Update documentation -> /docs:update-docs +> /update-docs # 6. Commit everything > /git:commit @@ -304,7 +304,7 @@ async function calculateShipping( > /sdd:05-document # Feature-specific docs # Broader project documentation update -> /docs:update-docs +> /update-docs ``` ### Documentation After Refactoring @@ -314,10 +314,10 @@ async function calculateShipping( > claude "refactor authentication to use middleware pattern" # Review the changes -> /code-review:review-local-changes +> /review-local-changes # Update affected documentation -> /docs:update-docs src/auth/ +> /update-docs src/auth/ # Save refactoring insights > /reflexion:memorize "Authentication refactoring patterns" @@ -330,13 +330,13 @@ async function calculateShipping( > claude "migrate /api/users to v2 with breaking changes" # Document the migration -> /docs:update-docs api +> /update-docs api # Add migration guide > claude "create migration guide from v1 to v2 API" # Validate documentation -> /docs:update-docs +> /update-docs ``` ## Common Patterns @@ -345,11 +345,11 @@ async function calculateShipping( | Scenario | Command | Focus | |----------|---------|-------| -| After implementing feature | `/docs:update-docs` | Full assessment | -| After adding API endpoints | `/docs:update-docs api` | API documentation | -| After module changes | `/docs:update-docs src/module/` | Module-specific | -| Periodic maintenance | `/docs:update-docs` | Full audit | -| Before release | `/docs:update-docs` | Comprehensive review | +| After implementing feature | `/update-docs` | Full assessment | +| After adding API endpoints | `/update-docs api` | API documentation | +| After module changes | `/update-docs src/module/` | Module-specific | +| Periodic maintenance | `/update-docs` | Full audit | +| Before release | `/update-docs` | Comprehensive review | ### Documentation Priority Order diff --git a/docs/plugins/docs/write-concisely.md b/docs/plugins/docs/write-concisely.md index 374a66e..0ed6c3e 100644 --- a/docs/plugins/docs/write-concisely.md +++ b/docs/plugins/docs/write-concisely.md @@ -1,4 +1,4 @@ -# /docs:write-concisely - Clear and Concise Writing +# /write-concisely - Clear and Concise Writing Apply William Strunk Jr.'s *The Elements of Style* principles to documentation. Makes writing clearer, stronger, and more professional. @@ -6,7 +6,7 @@ Apply William Strunk Jr.'s *The Elements of Style* principles to documentation. - Output - Documentation with improved clarity and reduced word count ```bash -/docs:write-concisely ["text or file to improve"] +/write-concisely ["text or file to improve"] ``` ## Arguments @@ -62,14 +62,14 @@ The skill enforces six essential writing rules: ```bash # Improve a specific document -> /docs:write-concisely docs/getting-started.md +> /write-concisely docs/getting-started.md # Apply to inline text -> /docs:write-concisely "There is no doubt but that the system is working" +> /write-concisely "There is no doubt but that the system is working" # Result: "The system works" # Review recent documentation changes -> /docs:write-concisely +> /write-concisely ``` ## Quality Metrics diff --git a/docs/plugins/fpf/README.md b/docs/plugins/fpf/README.md index c617950..d8c1978 100644 --- a/docs/plugins/fpf/README.md +++ b/docs/plugins/fpf/README.md @@ -41,7 +41,7 @@ Implementation based on [quint-code](https://github.com/m0n0x41d/quint-code) by /plugin install fpf@NeoLabHQ/context-engineering-kit # Start a decision process -/fpf:propose-hypotheses What caching strategy should we use? +/propose-hypotheses What caching strategy should we use? # Commad will perform majority of orcestration and launch subagents to perform the work. # Additionaly you will be asked to add your own hypotheses and review the results. @@ -52,7 +52,7 @@ Implementation based on [quint-code](https://github.com/m0n0x41d/quint-code) by ``` ┌─────────────────────────────────────────────────────────────────┐ │ 1. Initialize Context │ -│ /fpf:propose-hypotheses │ +│ /propose-hypotheses │ │ (create .fpf/ directory structure) │ └────────────────────────┬────────────────────────────────────────┘ │ @@ -108,7 +108,7 @@ Implementation based on [quint-code](https://github.com/m0n0x41d/quint-code) by ## Commands Overview -### /fpf:propose-hypotheses - Decision Cycle +### /propose-hypotheses - Decision Cycle Execute the complete FPF cycle from hypothesis generation through evidence validation to decision. @@ -116,7 +116,7 @@ Execute the complete FPF cycle from hypothesis generation through evidence valid - Output - `.fpf/decisions/DRR--.md` with winner and rationale ```bash -/fpf:propose-hypotheses [problem or decision to make] +/propose-hypotheses [problem or decision to make] ``` #### Arguments @@ -182,16 +182,16 @@ The workflow follows three inference modes: ```bash # Caching strategy decision -/fpf:propose-hypotheses What caching strategy should we use? +/propose-hypotheses What caching strategy should we use? # Deployment approach -/fpf:propose-hypotheses How should we deploy our application? +/propose-hypotheses How should we deploy our application? # Architecture decision -/fpf:propose-hypotheses Should we use microservices or monolith? +/propose-hypotheses Should we use microservices or monolith? # Technology selection -/fpf:propose-hypotheses Which database should we use for high-write workloads? +/propose-hypotheses Which database should we use for high-write workloads? ``` #### When to Use @@ -218,7 +218,7 @@ Time-critical situations where the overhead isn't justified --- -### /fpf:status - Check Progress +### /status - Check Progress Show current FPF phase, hypothesis counts, and any warnings about stale evidence. @@ -226,7 +226,7 @@ Show current FPF phase, hypothesis counts, and any warnings about stale evidence - Output - Status table with phase, counts, and warnings ```bash -/fpf:status +/status ``` #### Arguments @@ -247,7 +247,7 @@ None required. ```bash # Check current status -/fpf:status +/status ``` **Example Output:** @@ -286,7 +286,7 @@ All systems nominal. --- -### /fpf:query - Search Knowledge Base +### /query - Search Knowledge Base Search the FPF knowledge base for hypotheses, evidence, or decisions with assurance information. @@ -294,7 +294,7 @@ Search the FPF knowledge base for hypotheses, evidence, or decisions with assura - Output - Search results with layer, R_eff, and evidence counts ```bash -/fpf:query [keyword or hypothesis name] +/query [keyword or hypothesis name] ``` #### Arguments @@ -313,13 +313,13 @@ Keyword to search for, specific hypothesis name, or "DRR" to list decisions. ```bash # Search by keyword -/fpf:query caching +/query caching # Query specific hypothesis -/fpf:query redis-caching +/query redis-caching # List all decisions -/fpf:query DRR +/query DRR ``` **Example Output (keyword search):** @@ -363,21 +363,21 @@ Evidence: 2 files --- -### /fpf:decay - Manage Evidence Freshness +### /decay - Manage Evidence Freshness Check for stale evidence and choose how to handle it: refresh, deprecate, or waive. - Purpose - Maintain evidence validity over time - Output - Updated evidence status and trust scores -Evidence expires. A benchmark from six months ago might not reflect current performance. `/fpf:decay` shows you what's stale and gives you three options: +Evidence expires. A benchmark from six months ago might not reflect current performance. `/decay` shows you what's stale and gives you three options: - Refresh — Re-run tests to get fresh evidence - Deprecate — Downgrade the hypothesis if the decision needs rethinking - Waive — Accept the risk temporarily with documented rationale ```bash -/fpf:decay waive the benchmark until February, we'll re-test after launch +/decay waive the benchmark until February, we'll re-test after launch ``` #### Arguments @@ -399,7 +399,7 @@ None required. Command is interactive. ```bash # Check for stale evidence -/fpf:decay +/decay # Natural language waiver # User: Waive the benchmark until February, we'll re-run after migration. @@ -419,7 +419,7 @@ None required. Command is interactive. --- -### /fpf:actualize - Reconcile with Codebase +### /actualize - Reconcile with Codebase Update the knowledge base to reflect codebase changes that may affect existing hypotheses. @@ -433,7 +433,7 @@ This command serves as the Observe phase of the FPF's Canonical Evolution Loop ( - Flagging Outdated Decisions: Identifies decisions whose underlying evidence chain has been impacted by recent code changes. ```bash -/fpf:actualize +/actualize ``` #### How It Works @@ -447,10 +447,10 @@ This command serves as the Observe phase of the FPF's Canonical Evolution Loop ( ```bash # After major refactoring -/fpf:actualize +/actualize # After dependency updates -/fpf:actualize +/actualize ``` #### Best practices @@ -461,7 +461,7 @@ This command serves as the Observe phase of the FPF's Canonical Evolution Loop ( --- -### /fpf:reset - Start Fresh +### /reset - Start Fresh Archive the current session and return to IDLE state for a new reasoning cycle. @@ -469,7 +469,7 @@ Archive the current session and return to IDLE state for a new reasoning cycle. - Output - Archived session in `.fpf/sessions/` ```bash -/fpf:reset +/reset ``` #### Arguments @@ -490,7 +490,7 @@ None required. Command is interactive. #### Usage Examples ```bash -/fpf:reset +/reset # Agent: What type of reset would you like? # 1. Soft Reset - Archive current session, start fresh diff --git a/docs/plugins/fpf/architecture.md b/docs/plugins/fpf/architecture.md index 6bd8007..995c616 100644 --- a/docs/plugins/fpf/architecture.md +++ b/docs/plugins/fpf/architecture.md @@ -6,7 +6,7 @@ FPF plugin strictly separates the **User Experience** from the **Assurance Layer ### Surface (What You See) -Clean, concise summaries in the chat. When you run a command like `/fpf:propose-hypotheses`, you get a readable output that shows: +Clean, concise summaries in the chat. When you run a command like `/propose-hypotheses`, you get a readable output that shows: - Generated hypotheses with brief descriptions - Current assurance levels @@ -54,8 +54,8 @@ The AI can recommend, but architectural decisions flow through human judgment. T | Level | Name | Meaning | Promotion Path | |-------|------|---------|----------------| -| L0 | Observation | Unverified hypothesis or note | → `/fpf:propose-hypotheses verify step` | -| L1 | Substantiated | Passed logical consistency check | → `/fpf:propose-hypotheses validate step` | +| L0 | Observation | Unverified hypothesis or note | → `/propose-hypotheses verify step` | +| L1 | Substantiated | Passed logical consistency check | → `/propose-hypotheses validate step` | | L2 | Verified | Empirically tested and confirmed | Terminal | | Invalid | Disproved | Failed verification (kept for learning) | Terminal | @@ -79,7 +79,7 @@ FPF plugin's assurance calculator applies a **Congruence Penalty** based on the Evidence expires. That benchmark you ran six months ago? The library has been updated twice since then. Your numbers might not be accurate anymore. -Every piece of evidence has a `valid_until` date. When evidence expires, the decision it supports becomes **questionable** — not necessarily wrong, just unverified. The `/fpf:decay` command shows you what's stale and lets you: +Every piece of evidence has a `valid_until` date. When evidence expires, the decision it supports becomes **questionable** — not necessarily wrong, just unverified. The `/decay` command shows you what's stale and lets you: - **Refresh** — Re-run tests to get fresh proof - **Deprecate** — Downgrade the hypothesis if the decision needs rethinking diff --git a/docs/plugins/fpf/evidence-freshness.md b/docs/plugins/fpf/evidence-freshness.md index 5ddcd8e..e41cf1e 100644 --- a/docs/plugins/fpf/evidence-freshness.md +++ b/docs/plugins/fpf/evidence-freshness.md @@ -20,10 +20,10 @@ Quint Code makes this visible instead of hiding it. ## Checking Your Evidence -Run `/fpf:decay` to see what's stale: +Run `/decay` to see what's stale: ``` -/fpf:decay +/decay ``` You'll get a freshness report showing which holons have expired evidence: @@ -53,7 +53,7 @@ When you see stale evidence, you have three options: **When:** The decision is still correct, you just need fresh proof. -**How:** Run `/fpf:propose-hypotheses run only validation step` on the hypothesis to gather new evidence. +**How:** Run `/propose-hypotheses run only validation step` on the hypothesis to gather new evidence. ``` User: The Redis benchmark is old but Redis is still the right choice. @@ -120,7 +120,7 @@ The agent sees the freshness report and understands context. When you say "waive If you want to be explicit, you can: ``` -/fpf:decay --waive ev-benchmark-2024-06-15 --until 2025-02-01 --rationale "Migration pending" +/decay --waive ev-benchmark-2024-06-15 --until 2025-02-01 --rationale "Migration pending" ``` But natural language works fine. @@ -138,14 +138,14 @@ Think of it like a chain. Three strong links and one rusted link? The chain brea ### Weekly Maintenance ``` -/fpf:decay # What's stale? +/decay # What's stale? # For each item: refresh, deprecate, or waive ``` ### Before a Release ``` -/fpf:decay # Check for stale decisions +/decay # Check for stale decisions # Either refresh evidence or explicitly waive with rationale # Waivers become part of release documentation ``` @@ -155,7 +155,7 @@ Think of it like a chain. Three strong links and one rusted link? The chain brea Dependency update? API change? Security advisory? ``` -/fpf:decay # What's affected? +/decay # What's affected? # Deprecate obsolete decisions # Start new hypothesis cycle for replacements ``` diff --git a/docs/plugins/git/README.md b/docs/plugins/git/README.md index a0cf862..2427fcc 100644 --- a/docs/plugins/git/README.md +++ b/docs/plugins/git/README.md @@ -22,37 +22,34 @@ Most commands require GitHub CLI (`gh`) for full functionality including creatin /plugin install git@NeoLabHQ/context-engineering-kit # Create a well-formatted commit -> /git:commit +> /commit # Create a pull request -> /git:create-pr +> /create-pr ``` #### Analyze Open GitHub issues ```bash # Load all open issues -> /git:load-issues +> /load-issues # Analyze a GitHub issue -> /git:analyze-issue 123 +> /analyze-issue 123 ``` [Usage Examples](./usage-examples.md) ## Commands -- [/git:commit](./commit.md) - Create well-formatted commits with conventional commit messages and emoji. -- [/git:create-pr](./create-pr.md) - Create pull requests using GitHub CLI with proper templates and formatting. -- [/git:analyze-issue](./analyze-issue.md) - Analyze a GitHub issue and create a detailed technical specification. -- [/git:load-issues](./load-issues.md) - Load all open issues from GitHub and save them as markdown files. -- [/git:attach-review-to-pr](./attach-review-to-pr.md) - Add line-specific review comments to pull requests using GitHub CLI API. -- [/git:create-worktree](./create-worktree.md) - Create and setup git worktrees for parallel development with automatic dependency installation. -- [/git:compare-worktrees](./compare-worktrees.md) - Compare files and directories between git worktrees or worktree and current branch. -- [/git:merge-worktree](./merge-worktree.md) - Merge changes from worktrees into current branch with selective file checkout, cherry-picking, interactive patch selection, or manual merge. +- [/commit](./commit.md) - Create well-formatted commits with conventional commit messages and emoji. +- [/create-pr](./create-pr.md) - Create pull requests using GitHub CLI with proper templates and formatting. +- [/analyze-issue](./analyze-issue.md) - Analyze a GitHub issue and create a detailed technical specification. +- [/load-issues](./load-issues.md) - Load all open issues from GitHub and save them as markdown files. +- [/attach-review-to-pr](./attach-review-to-pr.md) - Add line-specific review comments to pull requests using GitHub CLI API. +- [/worktrees](./git-worktrees.md) - Create, compare, and merge git worktrees for parallel development with automatic dependency installation ## Skills -- [worktrees](./worktrees.md) - Skill for Parallel Branch Development in same file system using git worktrees. -- [notes](./notes.md) - Skill about using git notes to add metadata to commits without changing history. +- [notes](./git-notes.md) - Skill about using git notes to add metadata to commits without changing history. diff --git a/docs/plugins/git/attach-review-to-pr.md b/docs/plugins/git/attach-review-to-pr.md index 91283df..132fd3f 100644 --- a/docs/plugins/git/attach-review-to-pr.md +++ b/docs/plugins/git/attach-review-to-pr.md @@ -20,6 +20,6 @@ PR number or URL (optional - can work with current branch). > /git:attach-review-to-pr 456 # After code review -> /code-review:review-pr 456 +> /review-pr 456 > /git:attach-review-to-pr 456 ``` diff --git a/docs/plugins/git/commit.md b/docs/plugins/git/commit.md index f7855ed..d2c7c43 100644 --- a/docs/plugins/git/commit.md +++ b/docs/plugins/git/commit.md @@ -47,7 +47,7 @@ Optional flags like `--no-verify` to skip pre-commit checks. > /git:commit --no-verify # After code review -> /code-review:review-local-changes +> /review-local-changes > /git:commit ``` diff --git a/docs/plugins/git/compare-worktrees.md b/docs/plugins/git/compare-worktrees.md deleted file mode 100644 index 1a53e41..0000000 --- a/docs/plugins/git/compare-worktrees.md +++ /dev/null @@ -1,35 +0,0 @@ -# /git:compare-worktrees - Compare Worktrees - -Compare files and directories between git worktrees or worktree and current branch. - -- Purpose - Understand differences across branches/worktrees before merging -- Output - Diff output with clear headers and statistics - -```bash -/git:compare-worktrees [paths...] [--stat] -``` - -## Arguments - -- `` - File(s) or directory(ies) to compare -- `` - Worktree path or branch name to compare -- `--stat` - Show summary statistics only - -## Usage Examples - -```bash -# Compare specific file -> /git:compare-worktrees src/app.js - -# Compare multiple paths -> /git:compare-worktrees src/app.js src/utils/ package.json - -# Compare entire directory -> /git:compare-worktrees src/ - -# Get summary statistics -> /git:compare-worktrees --stat - -# Interactive mode (lists worktrees) -> /git:compare-worktrees -``` diff --git a/docs/plugins/git/create-worktree.md b/docs/plugins/git/create-worktree.md deleted file mode 100644 index aa26873..0000000 --- a/docs/plugins/git/create-worktree.md +++ /dev/null @@ -1,42 +0,0 @@ -# /git:create-worktree - Create Worktrees - -Create and setup git worktrees for parallel development with automatic dependency installation. - -- Purpose - Enable parallel branch development without stashing or context switching -- Output - New worktree with dependencies installed - -```bash -/git:create-worktree | --list -``` - -## Arguments - -- `` - Descriptive name for the worktree (e.g., "refactor auth system", "fix login bug") -- `--list` - Show existing worktrees - -## How It Works - -1. **Type Detection**: Auto-detects branch type from name (feature, fix, hotfix, refactor, etc.) -2. **Branch Resolution**: Creates or tracks existing local/remote branch -3. **Worktree Creation**: Creates sibling directory with pattern `../-` -4. **Dependency Installation**: Detects project type and runs appropriate install command - -**Supported Project Types**: Node.js (npm/yarn/pnpm/bun), Python (pip/poetry), Rust (cargo), Go, Ruby, PHP - -## Usage Examples - -```bash -# Create feature worktree (default type) -> /git:create-worktree auth system -# Branch: feature/auth-system → ../myproject-auth-system - -# Create fix worktree -> /git:create-worktree fix login error -# Branch: fix/login-error → ../myproject-login-error - -# Create hotfix while feature work continues -> /git:create-worktree hotfix critical bug - -# List existing worktrees -> /git:create-worktree --list -``` diff --git a/docs/plugins/git/notes.md b/docs/plugins/git/git-notes.md similarity index 96% rename from docs/plugins/git/notes.md rename to docs/plugins/git/git-notes.md index d7a6768..b788c25 100644 --- a/docs/plugins/git/notes.md +++ b/docs/plugins/git/git-notes.md @@ -1,4 +1,4 @@ -# notes - Commit Metadata Annotations +# git-notes - Commit Metadata Annotations Use when adding metadata to commits without changing history, tracking review status, test results, code quality annotations, or supplementing commit messages post-hoc. diff --git a/docs/plugins/git/git-worktrees.md b/docs/plugins/git/git-worktrees.md new file mode 100644 index 0000000..71bba41 --- /dev/null +++ b/docs/plugins/git/git-worktrees.md @@ -0,0 +1,149 @@ +# git-worktrees - Parallel Branch Development + +Use when working on multiple branches simultaneously, context switching without stashing, reviewing PRs while developing, testing in isolation, or comparing implementations across branches. + +- Purpose - Provide git worktree commands and workflow patterns for parallel development +- Core Principle - One worktree per active branch; switch contexts by changing directories + +**Key Concepts** + +| Concept | Description | +|---------|-------------| +| Main worktree | Original working directory from `git clone` or `git init` | +| Linked worktree | Additional directories created with `git worktree add` | +| Shared `.git` | All worktrees share same Git object database (no duplication) | +| Branch lock | Each branch can only be checked out in ONE worktree at a time | + +**Quick Reference** + +| Task | Command | +|------|---------| +| Create worktree (existing branch) | `git worktree add ` | +| Create worktree (new branch) | `git worktree add -b ` | +| List all worktrees | `git worktree list` | +| Remove worktree | `git worktree remove ` | +| Compare files between worktrees | `diff /file /file` | +| Get one file from another branch | `git checkout -- ` | +| Cherry-pick a commit | `git cherry-pick ` | + +**Common Workflows** + +- **Feature + Hotfix in Parallel** - Create worktree for hotfix while feature work continues +- **PR Review While Working** - Create temporary worktree to review PRs without stashing +- **Compare Implementations** - Create worktrees for different versions to diff side-by-side +- **Long-Running Tasks** - Run tests in isolated worktree while continuing development + +## Creating Worktrees + +Create and setup git worktrees for parallel development with automatic dependency installation. + +```bash +/worktrees create +/worktrees --list +``` + +| Argument | Description | +|----------|-------------| +| `` | Branch name (multi-word supported, e.g., `auth system`), auto-detects type from keywords like feature, fix, hotfix, refactor | +| `--list` | List all existing worktrees | + +**How It Works** + +1. **Type Detection**: Auto-detects branch type from name (feature, fix, hotfix, refactor, etc.) +2. **Branch Resolution**: Creates or tracks existing local/remote branch +3. **Worktree Creation**: Creates sibling directory with pattern `../-` +4. **Dependency Installation**: Detects project type and runs appropriate install command + +**Supported Project Types**: Node.js (npm/yarn/pnpm/bun), Python (pip/poetry), Rust (cargo), Go, Ruby, PHP + +**Usage Examples** + +```bash +# Create feature worktree (default type) +> /worktrees create auth system +# Branch: feature/auth-system -> ../myproject-auth-system + +# Create fix worktree +> /worktrees create fix login error +# Branch: fix/login-error -> ../myproject-login-error + +# Create hotfix while feature work continues +> /worktrees create hotfix critical bug + +# List existing worktrees +> /worktrees --list +``` + +## Comparing Worktrees + +Compare files and directories between git worktrees or worktree and current branch. + +```bash +/worktrees compare [paths...] [--stat] +``` + +| Argument | Description | +|----------|-------------| +| `` | File(s) or directory(ies) to compare | +| `` | Worktree path or branch name to compare | +| `--stat` | Show summary statistics only | + +**Usage Examples** + +```bash +# Compare specific file +> /worktrees compare src/app.js + +# Compare multiple paths +> /worktrees compare src/app.js src/utils/ package.json + +# Compare entire directory +> /worktrees compare src/ + +# Get summary statistics +> /worktrees compare --stat + +# Interactive mode (lists worktrees) +> /worktrees compare +``` + +## Merging from Worktrees + +Merge changes from worktrees into current branch with selective file checkout, cherry-picking, interactive patch selection, or manual merge. + +```bash +/worktrees merge [path|commit] [--from ] [--patch] [--interactive] +``` + +| Argument | Description | +|----------|-------------| +| `` | File path, directory, or commit SHA to merge | +| `--from ` | Source worktree path or branch name | +| `--patch` | Interactively select hunks within files | +| `--interactive` | Guided merge mode with strategy selection | + +**Merge Strategies** + +| Strategy | Use When | Command Pattern | +|----------|----------|-----------------| +| **Selective File** | Need complete file(s) from another branch | `git checkout -- ` | +| **Interactive Patch** | Need specific changes within a file | `git checkout -p -- ` | +| **Cherry-Pick Selective** | Need a commit but not all its changes | `git cherry-pick --no-commit` + selective staging | +| **Manual Merge** | Full branch merge with control | `git merge --no-commit` + selective staging | +| **Multi-Source** | Combining files from multiple branches | Multiple `git checkout -- ` | + +**Usage Examples** + +```bash +# Merge single file +> /worktrees merge src/app.js --from ../project-feature + +# Interactive patch selection (select specific hunks) +> /worktrees merge src/utils.js --patch + +# Cherry-pick specific commit +> /worktrees merge abc1234 + +# Full guided mode +> /worktrees merge --interactive +``` diff --git a/docs/plugins/git/merge-worktree.md b/docs/plugins/git/merge-worktree.md deleted file mode 100644 index 2ac010a..0000000 --- a/docs/plugins/git/merge-worktree.md +++ /dev/null @@ -1,44 +0,0 @@ -# /git:merge-worktree - Merge from Worktrees - -Merge changes from worktrees into current branch with selective file checkout, cherry-picking, interactive patch selection, or manual merge. - -- Purpose - Selectively merge changes without full branch merges -- Output - Merged files with optional cleanup - -```bash -/git:merge-worktree [path|commit] [--from ] [--patch] [--interactive] -``` - -## Arguments - -- `` - File or directory to merge -- `` - Commit name to cherry-pick -- `--from ` - Source worktree path -- `--patch` / `-p` - Interactive patch selection mode -- `--interactive` - Guided mode - -## Merge Strategies - -| Strategy | Use When | Command Pattern | -|----------|----------|-----------------| -| **Selective File** | Need complete file(s) from another branch | `git checkout -- ` | -| **Interactive Patch** | Need specific changes within a file | `git checkout -p -- ` | -| **Cherry-Pick Selective** | Need a commit but not all its changes | `git cherry-pick --no-commit` + selective staging | -| **Manual Merge** | Full branch merge with control | `git merge --no-commit` + selective staging | -| **Multi-Source** | Combining files from multiple branches | Multiple `git checkout -- ` | - -## Usage Examples - -```bash -# Merge single file -> /git:merge-worktree src/app.js --from ../project-feature - -# Interactive patch selection (select specific hunks) -> /git:merge-worktree src/utils.js --patch - -# Cherry-pick specific commit -> /git:merge-worktree abc1234 - -# Full guided mode -> /git:merge-worktree --interactive -``` diff --git a/docs/plugins/git/worktrees.md b/docs/plugins/git/worktrees.md deleted file mode 100644 index 7224b15..0000000 --- a/docs/plugins/git/worktrees.md +++ /dev/null @@ -1,31 +0,0 @@ -# worktrees - Parallel Branch Development - -Use when working on multiple branches simultaneously, context switching without stashing, reviewing PRs while developing, testing in isolation, or comparing implementations across branches. - -- Purpose - Provide git worktree commands and workflow patterns for parallel development -- Core Principle - One worktree per active branch; switch contexts by changing directories - -**Key Concepts** - -| Concept | Description | -|---------|-------------| -| Main worktree | Original working directory from `git clone` or `git init` | -| Linked worktree | Additional directories created with `git worktree add` | -| Shared `.git` | All worktrees share same Git object database (no duplication) | -| Branch lock | Each branch can only be checked out in ONE worktree at a time | - -**Quick Reference** - -| Task | Command | -|------|---------| -| Create worktree (existing branch) | `git worktree add ` | -| Create worktree (new branch) | `git worktree add -b ` | -| List all worktrees | `git worktree list` | -| Remove worktree | `git worktree remove ` | - -**Common Workflows** - -- **Feature + Hotfix in Parallel** - Create worktree for hotfix while feature work continues -- **PR Review While Working** - Create temporary worktree to review PRs without stashing -- **Compare Implementations** - Create worktrees for different versions to diff side-by-side -- **Long-Running Tasks** - Run tests in isolated worktree while continuing development diff --git a/docs/plugins/kaizen/README.md b/docs/plugins/kaizen/README.md index 2372662..f7fb672 100644 --- a/docs/plugins/kaizen/README.md +++ b/docs/plugins/kaizen/README.md @@ -24,25 +24,25 @@ They are based on the idea that most bugs and quality issues are symptoms of dee /plugin install kaizen@NeoLabHQ/context-engineering-kit # Investigate a bug's root cause -> /kaizen:why "API returns 500 error on checkout" +> /why "API returns 500 error on checkout" # Analyze code for improvement opportunities -> /kaizen:analyse src/checkout/ +> /analyse src/checkout/ # Document a complex problem comprehensively -> /kaizen:analyse-problem "Database connection exhaustion during peak traffic" +> /analyse-problem "Database connection exhaustion during peak traffic" ``` [Usage Examples](./usage-examples.md) ## Commands -- [/kaizen:why](./why.md) - Five Whys Root Cause Analysis. Iterative questioning technique that drills from surface symptoms to fundamental root causes by repeatedly asking "why." -- [/kaizen:root-cause-tracing](./root-cause-tracing.md) - Bug Tracing Through Call Stack. Systematically traces bugs backward through the call stack to identify where invalid data or incorrect behavior originates. -- [/kaizen:cause-and-effect](./cause-and-effect.md) - Fishbone Analysis. Systematic exploration of problem causes across six categories using the Ishikawa (Fishbone) diagram approach. -- [/kaizen:analyse-problem](./analyse-problem.md) - A3 Problem Analysis. Comprehensive one-page problem documentation using the A3 format, covering Background, Current Condition, Goal, Root Cause, Countermeasures, Implementation Plan, and Follow-up. -- [/kaizen:analyse](./analyse.md) - Smart Analysis Method Selection. Intelligently selects and applies the most appropriate Kaizen analysis technique based on what you're analyzing: Gemba Walk, Value Stream Mapping, or Muda (Waste) Analysis. -- [/kaizen:plan-do-check-act](./plan-do-check-act.md) - PDCA Improvement Cycle. Four-phase iterative cycle for continuous improvement through systematic experimentation: Plan, Do, Check, Act. +- [/why](./why.md) - Five Whys Root Cause Analysis. Iterative questioning technique that drills from surface symptoms to fundamental root causes by repeatedly asking "why." +- [/root-cause-tracing](./root-cause-tracing.md) - Bug Tracing Through Call Stack. Systematically traces bugs backward through the call stack to identify where invalid data or incorrect behavior originates. +- [/cause-and-effect](./cause-and-effect.md) - Fishbone Analysis. Systematic exploration of problem causes across six categories using the Ishikawa (Fishbone) diagram approach. +- [/analyse-problem](./analyse-problem.md) - A3 Problem Analysis. Comprehensive one-page problem documentation using the A3 format, covering Background, Current Condition, Goal, Root Cause, Countermeasures, Implementation Plan, and Follow-up. +- [/analyse](./analyse.md) - Smart Analysis Method Selection. Intelligently selects and applies the most appropriate Kaizen analysis technique based on what you're analyzing: Gemba Walk, Value Stream Mapping, or Muda (Waste) Analysis. +- [/plan-do-check-act](./plan-do-check-act.md) - PDCA Improvement Cycle. Four-phase iterative cycle for continuous improvement through systematic experimentation: Plan, Do, Check, Act. ## Skills diff --git a/docs/plugins/kaizen/analyse-problem.md b/docs/plugins/kaizen/analyse-problem.md index 71b842c..ae1f505 100644 --- a/docs/plugins/kaizen/analyse-problem.md +++ b/docs/plugins/kaizen/analyse-problem.md @@ -1,4 +1,4 @@ -# /kaizen:analyse-problem - A3 Problem Analysis +# /analyse-problem - A3 Problem Analysis Comprehensive one-page problem documentation using the A3 format, covering Background, Current Condition, Goal, Root Cause, Countermeasures, Implementation Plan, and Follow-up. @@ -6,7 +6,7 @@ Comprehensive one-page problem documentation using the A3 format, covering Backg - Output - Structured A3 report with actionable implementation plan ```bash -/kaizen:analyse-problem ["problem description"] +/analyse-problem ["problem description"] ``` ## Arguments @@ -31,13 +31,13 @@ This format forces concise, complete thinking that fits on one page. ```bash # Document a production incident -> /kaizen:analyse-problem "API downtime due to connection pool exhaustion" +> /analyse-problem "API downtime due to connection pool exhaustion" # Analyze a security vulnerability -> /kaizen:analyse-problem "Critical SQL injection vulnerability discovered" +> /analyse-problem "Critical SQL injection vulnerability discovered" # Plan a major improvement initiative -> /kaizen:analyse-problem "CI/CD pipeline takes 45 minutes" +> /analyse-problem "CI/CD pipeline takes 45 minutes" ``` ### Example Output Structure diff --git a/docs/plugins/kaizen/analyse.md b/docs/plugins/kaizen/analyse.md index 4617b23..66651b3 100644 --- a/docs/plugins/kaizen/analyse.md +++ b/docs/plugins/kaizen/analyse.md @@ -1,4 +1,4 @@ -# /kaizen:analyse - Smart Analysis Method Selection +# /analyse - Smart Analysis Method Selection Intelligently selects and applies the most appropriate Kaizen analysis technique based on what you're analyzing: Gemba Walk, Value Stream Mapping, or Muda (Waste) Analysis. @@ -6,7 +6,7 @@ Intelligently selects and applies the most appropriate Kaizen analysis technique - Output - Detailed analysis using the most appropriate technique ```bash -/kaizen:analyse ["target description"] +/analyse ["target description"] ``` ## Arguments @@ -52,13 +52,13 @@ Optional target description (e.g., code area, workflow, or inefficiencies to inv ```bash # Explore unfamiliar code -> /kaizen:analyse authentication implementation +> /analyse authentication implementation # Optimize a workflow -> /kaizen:analyse deployment pipeline +> /analyse deployment pipeline # Find waste in codebase -> /kaizen:analyse codebase for inefficiencies +> /analyse codebase for inefficiencies ``` ## Best Practices @@ -67,4 +67,4 @@ Optional target description (e.g., code area, workflow, or inefficiencies to inv - Use VSM for process improvements - CI/CD, deployment, code review workflows - Use Muda for efficiency audits - Technical debt, cleanup initiatives - Combine methods - Gemba Walk can lead to Muda analysis findings -- Document findings - Use /kaizen:analyse-problem for comprehensive documentation +- Document findings - Use /analyse-problem for comprehensive documentation diff --git a/docs/plugins/kaizen/cause-and-effect.md b/docs/plugins/kaizen/cause-and-effect.md index a8b81d6..6f10874 100644 --- a/docs/plugins/kaizen/cause-and-effect.md +++ b/docs/plugins/kaizen/cause-and-effect.md @@ -1,4 +1,4 @@ -# /kaizen:cause-and-effect - Fishbone Analysis +# /cause-and-effect - Fishbone Analysis Systematic exploration of problem causes across six categories using the Ishikawa (Fishbone) diagram approach. @@ -6,7 +6,7 @@ Systematic exploration of problem causes across six categories using the Ishikaw - Output - Structured analysis across People, Process, Technology, Environment, Methods, and Materials ```bash -/kaizen:cause-and-effect ["problem description"] +/cause-and-effect ["problem description"] ``` ## Arguments @@ -32,13 +32,13 @@ Optional problem description to analyze. If not provided, you will be prompted f ```bash # Analyze performance issues -> /kaizen:cause-and-effect "API responses take 3+ seconds" +> /cause-and-effect "API responses take 3+ seconds" # Investigate test reliability -> /kaizen:cause-and-effect "15% of test runs fail, passing on retry" +> /cause-and-effect "15% of test runs fail, passing on retry" # Understand delivery delays -> /kaizen:cause-and-effect "Feature took 12 weeks instead of 3" +> /cause-and-effect "Feature took 12 weeks instead of 3" ``` ### Example Output @@ -79,5 +79,5 @@ SOLUTIONS (Priority Order): - Do not stop at first cause - Explore deeply within each category - Look for cross-category connections - Some causes span multiple domains - Root causes usually involve process or methods - Not just technology -- Combine with /kaizen:why - Use Five Whys to dig deeper on specific causes +- Combine with /why - Use Five Whys to dig deeper on specific causes - Prioritize by impact x feasibility / effort - Focus on highest-value fixes diff --git a/docs/plugins/kaizen/plan-do-check-act.md b/docs/plugins/kaizen/plan-do-check-act.md index abc43d0..1f59691 100644 --- a/docs/plugins/kaizen/plan-do-check-act.md +++ b/docs/plugins/kaizen/plan-do-check-act.md @@ -1,4 +1,4 @@ -# /kaizen:plan-do-check-act - PDCA Improvement Cycle +# /plan-do-check-act - PDCA Improvement Cycle Four-phase iterative cycle for continuous improvement through systematic experimentation: Plan, Do, Check, Act. @@ -6,7 +6,7 @@ Four-phase iterative cycle for continuous improvement through systematic experim - Output - PDCA cycle documentation with baseline, hypothesis, results, and next steps ```bash -/kaizen:plan-do-check-act ["improvement goal"] +/plan-do-check-act ["improvement goal"] ``` ## Arguments @@ -18,7 +18,7 @@ Optional improvement goal or problem to address. If not provided, you will be pr **Phase 1: PLAN** 1. Define the problem or improvement goal 2. Analyze current state (baseline metrics) -3. Identify root causes (use /kaizen:why or /kaizen:cause-and-effect) +3. Identify root causes (use /why or /cause-and-effect) 4. Develop hypothesis: "If we change X, Y will improve" 5. Design experiment: what to change, how to measure 6. Set success criteria (measurable targets) @@ -46,13 +46,13 @@ Optional improvement goal or problem to address. If not provided, you will be pr ```bash # Reduce build time -> /kaizen:plan-do-check-act "Reduce Docker build from 45min to under 10min" +> /plan-do-check-act "Reduce Docker build from 45min to under 10min" # Improve code quality -> /kaizen:plan-do-check-act "Reduce production bugs from 8 to 4 per month" +> /plan-do-check-act "Reduce production bugs from 8 to 4 per month" # Speed up code review -> /kaizen:plan-do-check-act "Reduce PR merge time from 3 days to 1 day" +> /plan-do-check-act "Reduce PR merge time from 3 days to 1 day" ``` **Example Cycle**: diff --git a/docs/plugins/kaizen/root-cause-tracing.md b/docs/plugins/kaizen/root-cause-tracing.md index c508096..127fa95 100644 --- a/docs/plugins/kaizen/root-cause-tracing.md +++ b/docs/plugins/kaizen/root-cause-tracing.md @@ -1,4 +1,4 @@ -# /kaizen:root-cause-tracing - Bug Tracing Through Call Stack +# /root-cause-tracing - Bug Tracing Through Call Stack Systematically traces bugs backward through the call stack to identify where invalid data or incorrect behavior originates. @@ -6,7 +6,7 @@ Systematically traces bugs backward through the call stack to identify where inv - Output - Trace chain from symptom to original trigger with fix recommendation ```bash -/kaizen:root-cause-tracing +/root-cause-tracing ``` ## Arguments @@ -31,10 +31,10 @@ Never fix just where the error appears. Trace back to find the original trigger. ```bash # After encountering a deep stack error -> /kaizen:root-cause-tracing +> /root-cause-tracing # When debugging file creation in wrong location -> /kaizen:root-cause-tracing +> /root-cause-tracing ``` ### Example Trace diff --git a/docs/plugins/kaizen/usage-examples.md b/docs/plugins/kaizen/usage-examples.md index 2062efd..beedf7f 100644 --- a/docs/plugins/kaizen/usage-examples.md +++ b/docs/plugins/kaizen/usage-examples.md @@ -10,7 +10,7 @@ Real-world scenarios demonstrating effective use of the Kaizen plugin for root c ```bash # Start with Five Whys to find root cause -> /kaizen:why "Users see 500 error on checkout during peak hours" +> /why "Users see 500 error on checkout during peak hours" ``` **Expected Flow**: @@ -46,7 +46,7 @@ Solutions: > claude "Add index on transactions.user_id and update migration" # Memorize the pattern for future reference -> /reflexion:memorize "Database performance patterns" +> /memorize "Database performance patterns" ``` --- @@ -57,7 +57,7 @@ Solutions: ```bash # Use Fishbone analysis for multi-factor investigation -> /kaizen:cause-and-effect "E2E tests fail intermittently, pass on retry" +> /cause-and-effect "E2E tests fail intermittently, pass on retry" ``` **Expected Fishbone Output**: @@ -107,7 +107,7 @@ SOLUTIONS (Priority Order): **Follow-up with PDCA**: ```bash # Plan systematic improvement -> /kaizen:plan-do-check-act "Reduce flaky test rate from 15% to under 2%" +> /plan-do-check-act "Reduce flaky test rate from 15% to under 2%" ``` --- @@ -118,7 +118,7 @@ SOLUTIONS (Priority Order): ```bash # Create comprehensive A3 problem analysis -> /kaizen:analyse-problem "Production database outage during peak traffic" +> /analyse-problem "Production database outage during peak traffic" ``` **Expected A3 Output**: @@ -259,7 +259,7 @@ DATE: 2024-11-14 ```bash # Start PDCA cycle for measured improvement -> /kaizen:plan-do-check-act "Reduce Docker build time from 45 minutes to under 10 minutes" +> /plan-do-check-act "Reduce Docker build time from 45 minutes to under 10 minutes" ``` **Expected PDCA Cycle**: @@ -357,7 +357,7 @@ ACT: ```bash # Use smart analysis to auto-select best method -> /kaizen:analyse authentication module for technical debt +> /analyse authentication module for technical debt ``` **Kaizen auto-selects Muda (Waste) Analysis**: @@ -456,7 +456,7 @@ Estimated Recovery: ```bash # Use root cause tracing for deep stack bugs -> /kaizen:root-cause-tracing +> /root-cause-tracing ``` **Expected Trace**: @@ -542,7 +542,7 @@ VERIFICATION: ```bash # Use analyse with Gemba Walk focus -> /kaizen:analyse authentication implementation +> /analyse authentication implementation ``` **Kaizen selects Gemba Walk**: @@ -634,59 +634,57 @@ Priority: LOW ```bash # Investigate bug root cause -> /kaizen:why "Why does the payment fail for international cards?" +> /why "Why does the payment fail for international cards?" # After understanding root cause, memorize the pattern -> /reflexion:memorize "International payment processing patterns" +> /memorize "International payment processing patterns" ``` ### With Code Review ```bash # Get code review first -> /code-review:review-local-changes +> /review-local-changes # Analyze any quality issues found -> /kaizen:cause-and-effect "High complexity in reviewed code" +> /cause-and-effect "High complexity in reviewed code" # Plan systematic improvement -> /kaizen:plan-do-check-act "Reduce cyclomatic complexity" +> /plan-do-check-act "Reduce cyclomatic complexity" ``` ### With Git (Full Bug Fix Workflow) ```bash # 1. Load issue context -> /git:analyze-issue #456 +> /analyze-issue #456 # 2. Trace to root cause -> /kaizen:root-cause-tracing +> /root-cause-tracing # 3. Understand why it happened -> /kaizen:why +> /why # 4. Implement fix based on root cause > claude "Fix the issue based on root cause analysis" # 5. Memorize learnings -> /reflexion:memorize "Bug patterns from issue #456" +> /memorize "Bug patterns from issue #456" # 6. Commit with context -> /git:commit +> /commit ``` ### With SDD (Quality Improvement After Implementation) ```bash # After implementing feature -> /sdd:04-implement +> /implement-task # Analyze for waste and improvements -> /kaizen:analyse "Check implementation for waste" +> /analyse "Check implementation for waste" # If issues found, plan improvement -> /kaizen:plan-do-check-act "Optimize implementation" +> /plan-do-check-act "Optimize implementation" -# Document final implementation -> /sdd:05-document ``` diff --git a/docs/plugins/kaizen/why.md b/docs/plugins/kaizen/why.md index b1a7ff3..7944bf8 100644 --- a/docs/plugins/kaizen/why.md +++ b/docs/plugins/kaizen/why.md @@ -1,4 +1,4 @@ -# /kaizen:why - Five Whys Root Cause Analysis +# /why - Five Whys Root Cause Analysis Iterative questioning technique that drills from surface symptoms to fundamental root causes by repeatedly asking "why." @@ -6,7 +6,7 @@ Iterative questioning technique that drills from surface symptoms to fundamental - Output - Chain of causation leading to actionable root cause ```bash -/kaizen:why ["issue or symptom description"] +/why ["issue or symptom description"] ``` ## Arguments @@ -34,13 +34,13 @@ Optional description of the issue or symptom to analyze. If not provided, you wi ```bash # Investigate a production bug -> /kaizen:why "Users see 500 error on checkout" +> /why "Users see 500 error on checkout" # Analyze a recurring issue -> /kaizen:why "E2E tests fail intermittently" +> /why "E2E tests fail intermittently" # Understand a performance problem -> /kaizen:why "Feature deployment takes 2 hours" +> /why "Feature deployment takes 2 hours" ``` ### Example Output diff --git a/docs/plugins/mcp/usage-examples.md b/docs/plugins/mcp/usage-examples.md index 893d74f..186cff3 100644 --- a/docs/plugins/mcp/usage-examples.md +++ b/docs/plugins/mcp/usage-examples.md @@ -16,7 +16,7 @@ Real-world scenarios demonstrating effective use of the MCP plugin for documenta > /plugin install mcp@NeoLabHQ/context-engineering-kit # Configure documentation access -> /mcp:setup-context7-mcp nextjs 14, prisma, typescript, zod +> /setup-context7-mcp nextjs 14, prisma, typescript, zod ``` **Expected Flow**: @@ -56,7 +56,7 @@ After setup, when you ask about Next.js Server Actions or Prisma relations, the > cd existing-project # Let the command analyze your project -> /mcp:setup-context7-mcp +> /setup-context7-mcp ``` **Expected Flow**: @@ -85,7 +85,7 @@ Setting up documentation for: react, @reduxjs/toolkit, express, postgresql, type ```bash # Set up Codemap CLI for codebase visualization -> /mcp:setup-codemap-cli +> /setup-codemap-cli ``` **Expected Flow**: @@ -149,7 +149,7 @@ Updated .gitignore with .codemap/ directory. ```bash # Set up Serena for semantic analysis -> /mcp:setup-serena-mcp +> /setup-serena-mcp ``` **Expected Flow**: @@ -176,7 +176,7 @@ Configuration needed: 1. Add Serena to your MCP configuration 2. Restart Claude to load the new MCP server -After restart, run: /mcp:setup-serena-mcp continue +After restart, run: /setup-serena-mcp continue ``` **After Successful Setup**: @@ -214,10 +214,10 @@ Updated CLAUDE.md with Serena usage guidelines. ```bash # First, set up documentation access -> /mcp:setup-context7-mcp react, graphql, @apollo/client +> /setup-context7-mcp react, graphql, @apollo/client # Then, set up semantic code analysis -> /mcp:setup-serena-mcp +> /setup-serena-mcp ``` **Result in CLAUDE.md**: @@ -260,7 +260,7 @@ Key usage points: ```bash # Set up paper search MCP via Docker MCP -> /mcp:setup-arxiv-mcp +> /setup-arxiv-mcp ``` **Expected Flow**: @@ -330,7 +330,7 @@ Paper Search MCP is now configured! ```bash # Start the MCP server development guide -> /mcp:build-mcp +> /build-mcp # When prompted, describe your use case: > "I want to build an MCP server that lets the LLM read and post messages @@ -440,7 +440,7 @@ async def search_messages(params: SearchMessagesInput) -> str: **Scenario**: Your company has an internal API for managing customer data and you want LLM access. ```bash -> /mcp:build-mcp +> /build-mcp > "Build an MCP server for our internal Customer API at https://api.internal.com I need to search customers, view customer details, and update customer status" @@ -509,20 +509,21 @@ Try: ```bash # Set up MCP servers at project start -> /mcp:setup-context7-mcp react, typescript, prisma -> /mcp:setup-serena-mcp +> /setup-context7-mcp react, typescript, prisma +> /setup-serena-mcp # Research phase - Context7 provides current documentation -> /sdd:01-research +> /add-task "Integrate prisma for database operations" +> /plan-task # Implementation - Serena helps navigate codebase -> /sdd:04-implement +> /implement-task # Review with semantic understanding -> /reflexion:critique +> /critique # Save learnings -> /reflexion:memorize +> /memorize ``` **How MCP Enhances Each Phase**: @@ -541,7 +542,7 @@ Try: **Scenario**: Context7 cannot find documentation for a library you need. ```bash -> /mcp:setup-context7-mcp obscure-library +> /setup-context7-mcp obscure-library # Response: # Documentation not found for: obscure-library @@ -568,7 +569,7 @@ Try: **Scenario**: Serena fails to index your project correctly. ```bash -> /mcp:setup-serena-mcp +> /setup-serena-mcp # Issue: Indexing failed for src/generated/* # These files are auto-generated and should be excluded @@ -581,7 +582,7 @@ Try: > "Configure Serena to exclude the src/generated directory from indexing" # Re-run indexing -> /mcp:setup-serena-mcp +> /setup-serena-mcp # Result: # Indexing complete: @@ -596,54 +597,55 @@ Try: ```bash # Set up documentation, then verify configuration -> /mcp:setup-context7-mcp react, nextjs -> /reflexion:reflect +> /setup-context7-mcp react, nextjs +> /reflect # After building a custom MCP server, get comprehensive review -> /mcp:build-mcp -> /reflexion:critique -> /reflexion:memorize "MCP server design patterns" +> /build-mcp +> /critique +> /memorize "MCP server design patterns" ``` ### With SDD (Spec-Driven Development) ```bash # Documentation access improves research quality -> /mcp:setup-context7-mcp -> /sdd:01-research +> /setup-context7-mcp +> /add-task "Integrate prisma for database operations" +> /plan-task # Semantic analysis helps implementation -> /mcp:setup-serena-mcp -> /sdd:04-implement +> /setup-serena-mcp +> /implement-task ``` ### With TDD ```bash # Semantic analysis helps find test targets -> /mcp:setup-serena-mcp -> /tdd:write-tests +> /setup-serena-mcp +> /write-tests ``` ### With Kaizen ```bash # Semantic analysis aids root cause investigation -> /mcp:setup-serena-mcp -> /kaizen:why "Why is the authentication failing?" +> /setup-serena-mcp +> /why "Why is the authentication failing?" # Codemap visualizes codebase for root cause tracing -> /mcp:setup-codemap-cli -> /kaizen:root-cause-tracing +> /setup-codemap-cli +> /root-cause-tracing ``` ### With Feature Development Workflow ```bash # Set up complete MCP tooling for a new project -> /mcp:setup-context7-mcp react, typescript, prisma -> /mcp:setup-serena-mcp -> /mcp:setup-codemap-cli +> /setup-context7-mcp react, typescript, prisma +> /setup-serena-mcp +> /setup-codemap-cli # Now Claude has: # - Up-to-date documentation access (Context7) diff --git a/docs/plugins/reflexion/README.md b/docs/plugins/reflexion/README.md index 525e49e..4d42e7d 100644 --- a/docs/plugins/reflexion/README.md +++ b/docs/plugins/reflexion/README.md @@ -83,9 +83,9 @@ The plugin includes optional hooks that automatically trigger reflection when yo ## Commands -- [/reflexion:reflect](./reflect.md) - Self-Refinement. Reflect on previous response and output, based on Self-refinement framework for iterative improvement with complexity triage and verification -- [/reflexion:critique](./critique.md) - Multi-Perspective Critique. Memorize insights from reflections and updates CLAUDE.md file with this knowledge. Curates insights from reflections and critiques into CLAUDE.md using Agentic Context Engineering -- [/reflexion:memorize](./memorize.md) - Memorize insights from reflections and updates CLAUDE.md file with this knowledge. Curates insights from reflections and critiques into CLAUDE.md using Agentic Context Engineering +- [/reflect](./reflect.md) - Self-Refinement. Reflect on previous response and output, based on Self-refinement framework for iterative improvement with complexity triage and verification +- [/critique](./critique.md) - Multi-Perspective Critique. Comprehensive multi-perspective review using specialized judges with debate and consensus building +- [/memorize](./memorize.md) - Memory Updates. Curates insights from reflections and critiques into CLAUDE.md using Agentic Context Engineering ## Theoretical Foundation diff --git a/docs/plugins/reflexion/critique.md b/docs/plugins/reflexion/critique.md index cd3341a..cb597d5 100644 --- a/docs/plugins/reflexion/critique.md +++ b/docs/plugins/reflexion/critique.md @@ -1,12 +1,12 @@ -# /reflexion:critique - Multi-Perspective Critique +# /critique - Multi-Perspective Critique -Memorize insights from reflections and updates CLAUDE.md file with this knowledge. Curates insights from reflections and critiques into CLAUDE.md using Agentic Context Engineering +Comprehensive multi-perspective review using specialized judges with debate and consensus building - Purpose - Multi-perspective comprehensive review - Output - Structured feedback from multiple judges ```bash -/reflexion:critique ["scope or focus area"] +/critique ["scope or focus area"] ``` ## Arguments @@ -37,16 +37,16 @@ Each judge provides a score out of 10: ```bash # Review recent work from conversation -> /reflexion:critique +> /critique # Review specific files -> /reflexion:critique src/auth/*.ts +> /critique src/auth/*.ts # Review with security focus -> /reflexion:critique --focus=security +> /critique --focus=security # Review a git commit range -> /reflexion:critique HEAD~3..HEAD +> /critique HEAD~3..HEAD ``` ## Best practices diff --git a/docs/plugins/reflexion/usage-examples.md b/docs/plugins/reflexion/usage-examples.md index 08565a9..ffc5c98 100644 --- a/docs/plugins/reflexion/usage-examples.md +++ b/docs/plugins/reflexion/usage-examples.md @@ -13,7 +13,7 @@ The simplest way to use reflection is with the automatic hooks. Include the word > claude "implement user authentication, then reflect" # Claude implements the feature, then automatically: -# 1. Runs /reflexion:reflect +# 1. Runs /reflect # 2. Reviews its own work # 3. Fixes any issues found or suggests improvements ``` @@ -42,7 +42,7 @@ The simplest way to use reflection is with the automatic hooks. Include the word > claude "create a function to format phone numbers to (XXX) XXX-XXXX format" # Quick reflection -> /reflexion:reflect +> /reflect ``` **Expected Flow**: @@ -70,16 +70,16 @@ Reflection Output: > claude "implement OAuth2 authentication with Google and GitHub providers" # Comprehensive multi-perspective review -> /reflexion:critique +> /critique # Address findings > claude "implement the Critical and High priority items from the critique" # Quick check -> /reflexion:reflect +> /reflect # Save learnings -> /reflexion:memorize +> /memorize ``` **Expected Critique Output**: @@ -108,7 +108,7 @@ High Priority: > claude "implement Stripe payment processing with subscription support" # Reflect on implementation -> /reflexion:reflect +> /reflect ``` **Reflection finds optimization opportunity**: @@ -126,10 +126,10 @@ Performance Analysis: > claude "refactor payment processing to use background jobs" # Confirm improvement -> /reflexion:reflect +> /reflect # Save pattern -> /reflexion:memorize +> /memorize ``` **Memorized Knowledge** (added to CLAUDE.md): @@ -157,16 +157,16 @@ Performance Analysis: > claude "design a caching strategy for our product catalog API" # Get multi-perspective review -> /reflexion:critique +> /critique # Debate reveals issues > claude "update caching design based on critique" # Re-evaluate -> /reflexion:critique +> /critique # Finalize -> /reflexion:memorize --section="Architecture Decisions" +> /memorize --section="Architecture Decisions" ``` **First Critique**: @@ -192,33 +192,32 @@ Verdict: ✅ Ready to ship > claude "implement caching layer" # First reflection -> /reflexion:reflect +> /reflect # Address issues and reflect again > claude "fix the issues identified" -> /reflexion:reflect +> /reflect # Capture final insights -> /reflexion:memorize +> /memorize ``` ## Integration with Other Plugins ### With Code Review ```bash -> /code-review:review-local-changes -> /reflexion:memorize "Code review findings" +> /review-local-changes +> /memorize "Code review findings" ``` ### With SDD ```bash -> /sdd:04-implement -> /reflexion:reflect -> /sdd:05-document +> /implement-task +> /reflect ``` ### With Kaizen ```bash -> /kaizen:why "Why did the bug occur?" -> /reflexion:memorize "Root cause patterns" +> /why "Why did the bug occur?" +> /memorize "Root cause patterns" ``` diff --git a/plugins/code-review/README.md b/docs/plugins/review/README.md similarity index 85% rename from plugins/code-review/README.md rename to docs/plugins/review/README.md index c7b2bd5..97a3ade 100644 --- a/plugins/code-review/README.md +++ b/docs/plugins/review/README.md @@ -1,4 +1,4 @@ -# Code Review Plugin +# Review Plugin Comprehensive multi-agent code review system that examines code from multiple specialized perspectives to catch bugs, security issues, and quality problems before they reach production. @@ -17,13 +17,24 @@ The Code Review plugin implements a multi-agent code review system where special ```bash # Install the plugin -/plugin install code-review@NeoLabHQ/context-engineering-kit +/plugin install review@NeoLabHQ/context-engineering-kit # Review uncommitted local changes -> /code-review:review-local-changes +> /review-local-changes + +``` + +## Advanced Usage + +```bash +# Review with lower impact threshold +> /review-local-changes --min-impact medium # Review a pull request -> /code-review:review-pr #123 +> /review-pr #123 + +# Review PR with only critical issues +> /review-pr --min-impact critical ``` [Usage Examples](./usage-examples.md) @@ -51,8 +62,8 @@ Code Review Command ## Commands -- [/code-review:review-local-changes](./review-local-changes.md) - Local Changes Review -- [/code-review:review-pr](./review-pr.md) - Pull Request Review +- [/review-local-changes](./review-local-changes.md) - Local Changes Review +- [/review-pr](./review-pr.md) - Pull Request Review ## Review Agents @@ -138,7 +149,7 @@ on: pull_request: types: - opened - - synchronize # remove if want to run only, when PR is opened + - synchronize # remove if want to run only when PR is opened - ready_for_review - reopened # Uncomment to limit which files can trigger the workflow @@ -168,7 +179,7 @@ jobs: uses: actions/checkout@v4 with: fetch-depth: 1 - + - name: Run Claude Code Review id: claude-review uses: anthropics/claude-code-action@v1 @@ -178,12 +189,12 @@ jobs: use_sticky_comment: true plugin_marketplaces: https://github.com/NeoLabHQ/context-engineering-kit.git - plugins: "code-review@context-engineering-kit\ngit@context-engineering-kit\ntdd@context-engineering-kit\nsadd@context-engineering-kit\nddd@context-engineering-kit\nsdd@context-engineering-kit\nkaizen@context-engineering-kit" + plugins: "review@context-engineering-kit\ngit@context-engineering-kit\ntdd@context-engineering-kit\nsadd@context-engineering-kit\nddd@context-engineering-kit\nsdd@context-engineering-kit\nkaizen@context-engineering-kit" - prompt: '/code-review:review-pr ${{ github.repository }}/pull/${{ github.event.pull_request.number }} Note: The PR branch is already checked out in the current working directory.' + prompt: '/review-pr ${{ github.repository }}/pull/${{ github.event.pull_request.number }} Note: The PR branch is already checked out in the current working directory.' # Skill and Bash(gh pr comment:*) is required for review, the rest is optional, but recommended for better context and quality of the review. - claude_args: '--allowed-tools "Skill,Bash,Glob,Grep,Read,Task,mcp__github_inline_comment__create_inline_comment,Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr edit:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh api:*)"' + claude_args: '--allowed-tools "Skill,Bash,Glob,Grep,Read,Task,mcp__github_inline_comment__create_inline_comment,Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr edit:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh api:*)" --system-prompt "Follow /review-pr skill EXACTLY!!!"' ``` ## Output Formats diff --git a/docs/plugins/code-review/review-local-changes.md b/docs/plugins/review/review-local-changes.md similarity index 87% rename from docs/plugins/code-review/review-local-changes.md rename to docs/plugins/review/review-local-changes.md index d77e663..8314637 100644 --- a/docs/plugins/code-review/review-local-changes.md +++ b/docs/plugins/review/review-local-changes.md @@ -1,4 +1,4 @@ -# /code-review:review-local-changes - Local Changes Review +# /review-local-changes - Local Changes Review Review uncommitted local changes using all specialized agents with code improvement suggestions. @@ -6,7 +6,7 @@ Review uncommitted local changes using all specialized agents with code improvem - Output - Structured report with findings by severity ```bash -/code-review:review-local-changes [review-aspects] [--min-impact critical|high|medium|medium-low|low] [--json] +/review-local-changes [review-aspects] [--min-impact critical|high|medium|medium-low|low] [--json] ``` ## Arguments @@ -58,23 +58,23 @@ Review uncommitted local changes using all specialized agents with code improvem ```bash # Review all local changes (default: --min-impact high, markdown output) -> /code-review:review-local-changes +> /review-local-changes # Focus on security aspects -> /code-review:review-local-changes security +> /review-local-changes security # Lower the threshold to catch medium-impact issues -> /code-review:review-local-changes --min-impact medium +> /review-local-changes --min-impact medium # Focus on security and performance, medium threshold -> /code-review:review-local-changes security, performance --min-impact medium +> /review-local-changes security, performance --min-impact medium # Critical-only issues in JSON for programmatic consumption -> /code-review:review-local-changes --min-impact critical --json +> /review-local-changes --min-impact critical --json # After implementing a feature > claude "implement user authentication" -> /code-review:review-local-changes +> /review-local-changes ``` ### JSON Output diff --git a/docs/plugins/code-review/review-pr.md b/docs/plugins/review/review-pr.md similarity index 87% rename from docs/plugins/code-review/review-pr.md rename to docs/plugins/review/review-pr.md index 9c3f0f6..bd9f59b 100644 --- a/docs/plugins/code-review/review-pr.md +++ b/docs/plugins/review/review-pr.md @@ -1,4 +1,4 @@ -# /code-review:review-pr - Pull Request Review +# /review-pr - Pull Request Review Comprehensive pull request review using all specialized agents. Posts only high-confidence, high-value inline comments directly on PR lines - no overall review report. @@ -6,7 +6,7 @@ Comprehensive pull request review using all specialized agents. Posts only high- - Output - Inline comments on specific lines (only issues that pass confidence/impact thresholds) ```bash -/code-review:review-pr [review-aspects] [--min-impact critical|high|medium|medium-low|low] +/review-pr [review-aspects] [--min-impact critical|high|medium|medium-low|low] ``` ## CI/CD Integration @@ -57,19 +57,19 @@ You can integrate this plugin with your CI/CD pipeline by using Offical Anthropi ```bash # Review PR by number -> /code-review:review-pr #123 +> /review-pr #123 # Review PR with focus on security -> /code-review:review-pr security +> /review-pr security # Include medium-impact issues and above -> /code-review:review-pr --min-impact medium +> /review-pr --min-impact medium # Combine focus areas with a lower impact threshold -> /code-review:review-pr security, performance --min-impact medium-low +> /review-pr security, performance --min-impact medium-low # Review current branch's PR (defaults to --min-impact high) -> /code-review:review-pr +> /review-pr ``` diff --git a/docs/plugins/code-review/usage-examples.md b/docs/plugins/review/usage-examples.md similarity index 87% rename from docs/plugins/code-review/usage-examples.md rename to docs/plugins/review/usage-examples.md index 779b818..22be8d1 100644 --- a/docs/plugins/code-review/usage-examples.md +++ b/docs/plugins/review/usage-examples.md @@ -1,6 +1,6 @@ -# Code Review Plugin - Usage Examples +# Review Plugin - Usage Examples -Real-world scenarios demonstrating effective use of the Code Review plugin. +Real-world scenarios demonstrating effective use of the code Review plugin. ## Basic Workflows @@ -13,7 +13,7 @@ Real-world scenarios demonstrating effective use of the Code Review plugin. > claude "add user registration endpoint" # Review before commit -> /code-review:review-local-changes +> /review-local-changes ``` **Review Output**: @@ -34,10 +34,10 @@ Action Required: Fix critical issues before committing > claude "hash passwords with bcrypt and add email validation" # Re-review -> /code-review:review-local-changes +> /review-local-changes # Clean review - commit -> /git:commit "Add user registration with validation and security" +> /commit "Add user registration with validation and security" ``` ### Example 2: Pull Request Review @@ -46,10 +46,10 @@ Action Required: Fix critical issues before committing ```bash # Create PR -> /git:create-pr "Add payment processing" +> /create-pr "Add payment processing" # Review PR #456 -> /code-review:review-pr 456 +> /review-pr 456 ``` **Review Findings**: @@ -85,7 +85,7 @@ Verdict: Request changes for security and race condition > claude "implement OAuth2 authentication with Google provider" # Security-focused review -> /code-review:review-local-changes security +> /review-local-changes security ``` **Security Findings**: @@ -115,10 +115,10 @@ High Risk: > claude "implement all critical and high security fixes" # Verify security -> /code-review:review-local-changes security +> /review-local-changes security # Clean security audit -> /git:commit "Add OAuth2 with security best practices" +> /commit "Add OAuth2 with security best practices" ``` ## Test Coverage Reviews @@ -132,7 +132,7 @@ High Risk: > claude "add shopping cart functionality" # Test coverage review -> /code-review:review-local-changes tests +> /review-local-changes tests ``` **Coverage Analysis**: @@ -166,10 +166,10 @@ Test Quality Issues: > claude "add all missing test cases identified by code review" # Verify coverage -> /code-review:review-local-changes tests +> /review-local-changes tests # Coverage now: 82% ✓ -> /git:commit "Add shopping cart with comprehensive tests" +> /commit "Add shopping cart with comprehensive tests" ``` ## Code Quality Improvements @@ -182,7 +182,7 @@ Test Quality Issues: # Review existing code > claude "review src/legacy/order-processor.js for refactoring opportunities" -> /code-review:review-local-changes +> /review-local-changes ``` **Quality Assessment**: @@ -236,19 +236,19 @@ High Priority: ```bash # Apply refactorings incrementally > claude "extract methods from OrderProcessor" -> /code-review:review-local-changes +> /review-local-changes > claude "add error handling and logging" -> /code-review:review-local-changes +> /review-local-changes > claude "apply SOLID principles" -> /code-review:review-local-changes +> /review-local-changes # Final quality check -> /code-review:review-local-changes +> /review-local-changes # Code Quality Score: 8/10 ✓ -> /git:commit "Refactor OrderProcessor - improved quality from 3/10 to 8/10" +> /commit "Refactor OrderProcessor - improved quality from 3/10 to 8/10" ``` ## Contract Validation @@ -262,7 +262,7 @@ High Priority: > claude "add POST /api/v2/orders endpoint" # Contract review -> /code-review:review-local-changes contracts +> /review-local-changes contracts ``` **Contract Findings**: @@ -300,9 +300,9 @@ Documentation: > claude "fix all contract issues and update OpenAPI spec" # Verify contracts -> /code-review:review-local-changes contracts +> /review-local-changes contracts -> /git:commit "Add POST /api/v2/orders with consistent contracts" +> /commit "Add POST /api/v2/orders with consistent contracts" ``` ## Integration Patterns @@ -316,25 +316,25 @@ Documentation: > claude "add real-time notifications" # Multi-layered review -> /code-review:review-local-changes +> /review-local-changes # Fix high/critical issues > claude "address all critical and high priority findings" # Deep reflection -> /reflexion:critique +> /critique # Additional perspective caught architectural concerns # Apply all feedback > claude "address reflexion critique findings" # Final verification -> /code-review:review-local-changes +> /review-local-changes # Clean ✓ # Save learnings -> /reflexion:memorize +> /memorize -> /git:commit "Add real-time notifications with comprehensive quality review" +> /commit "Add real-time notifications with comprehensive quality review" ``` ### Example 8: Code Review + SDD Workflow @@ -343,15 +343,14 @@ Documentation: ```bash # Specify and plan -> /sdd:01-specify "Add webhook system for third-party integrations" -> /sdd:02-plan -> /sdd:03-tasks +> /add-task "Add webhook system for third-party integrations" +> /plan-task # Implement -> /sdd:04-implement +> /implement-task # Code review after implementation -> /code-review:review-local-changes +> /review-local-changes ``` **Review finds issues**: @@ -370,13 +369,13 @@ High: > claude "fix critical and high priority code review findings" # Verify fixes -> /code-review:review-local-changes -# Clean ✓ +> /review-local-changes +# Found 7 issues -# Document -> /sdd:05-document +# Fix issues +> /do-in-steps fix all issues -> /git:commit "Add webhook system with security and validation" +> /commit "Add webhook system with security and validation" ``` ## Historical Context Usage @@ -389,7 +388,7 @@ High: # Add new authentication method > claude "add API key authentication to existing auth system" -> /code-review:review-local-changes +> /review-local-changes ``` **Historical Context Findings**: @@ -424,10 +423,10 @@ Similar Past Issues: # Align with existing patterns > claude "refactor to match existing authentication patterns and use factory pattern" -> /code-review:review-local-changes +> /review-local-changes # Historical context issues resolved ✓ -> /git:commit "Add API key authentication following existing patterns" +> /commit "Add API key authentication following existing patterns" ``` ## Bug Prevention @@ -440,7 +439,7 @@ Similar Past Issues: # Implement recommendation algorithm > claude "implement product recommendation algorithm based on user behavior" -> /code-review:review-local-changes +> /review-local-changes ``` **Bug Hunter Findings**: @@ -485,10 +484,10 @@ Edge Cases Not Handled: > claude "fix all bug hunter findings" # Verify fixes -> /code-review:review-local-changes +> /review-local-changes # No critical bugs ✓ -> /git:commit "Add recommendation engine with bug fixes" +> /commit "Add recommendation engine with bug fixes" ``` ## Performance Reviews @@ -501,7 +500,7 @@ Edge Cases Not Handled: # Optimize search endpoint > claude "optimize product search to handle 1000 req/sec" -> /code-review:review-local-changes +> /review-local-changes ``` **Code Quality Reviewer Notes**: @@ -541,13 +540,13 @@ Suggested Optimizations: > claude "implement all performance optimizations" # Verify improvements -> /code-review:review-local-changes +> /review-local-changes # No performance concerns ✓ # Benchmark > claude "add performance tests to verify 1000 req/sec target" -> /git:commit "Optimize product search for high throughput" +> /commit "Optimize product search for high throughput" ``` ## Continuous Improvement @@ -556,25 +555,25 @@ Suggested Optimizations: **Week 1**: First PR ```bash -> /code-review:review-pr 100 +> /review-pr 100 # Result: 15 issues found (3 critical, 5 high, 7 medium) ``` **Week 2**: After learning from review ```bash -> /code-review:review-pr 110 +> /review-pr 110 # Result: 8 issues found (1 critical, 2 high, 5 medium) ``` **Week 3**: Habits forming ```bash -> /code-review:review-pr 120 +> /review-pr 120 # Result: 3 issues found (0 critical, 1 high, 2 medium) ``` **Week 4**: Consistent quality ```bash -> /code-review:review-pr 130 +> /review-pr 130 # Result: 1 issue found (0 critical, 0 high, 1 medium) # Verdict: ✅ Ready to ship ``` diff --git a/docs/plugins/sadd/usage-examples.md b/docs/plugins/sadd/usage-examples.md index 0790756..10badde 100644 --- a/docs/plugins/sadd/usage-examples.md +++ b/docs/plugins/sadd/usage-examples.md @@ -386,7 +386,7 @@ All issues resolved in parallel - 15 minutes total vs ~45 minutes sequential. ```bash # Run additional review after SADD completes -> /code-review:review-local-changes +> /review-local-changes # Address any additional findings > claude "Fix the medium priority issues from code review" diff --git a/docs/plugins/sdd/README.md b/docs/plugins/sdd/README.md index a657813..515b582 100644 --- a/docs/plugins/sdd/README.md +++ b/docs/plugins/sdd/README.md @@ -6,13 +6,13 @@ This plugin is designed to consistently and reproducibly produce working code. I ## Key Features -- **Development as compilation** — The plugin functions like a "compilation" or "nightly build" for your development process: `task specs → run /sdd:implement → working code`. After writing your prompt, you can launch the plugin and expect a functional result when you return. The completion time depends on task complexity — simple tasks may finish within 30 minutes, while complex ones can take several days. +- **Development as compilation** — The plugin functions like a "compilation" or "nightly build" for your development process: `task specs → run /implement-task → working code`. After writing your prompt, you can launch the plugin and expect a functional result when you return. The completion time depends on task complexity — simple tasks may finish within 30 minutes, while complex ones can take several days. - **Benchmark-level quality in real life** — Model benchmarks improve with each release, yet real-world results often stagnate. This is because benchmarks reflect the best possible output a model can achieve, whereas in practice LLMs tend to drift toward sub-optimal, non-functional solutions. This plugin uses a variety of patterns to keep the model operating at peak performance. - **Customizable** — Balance result quality and process speed by adjusting command parameters. Learn more in the [Customization](customization.md) section. - **Developer time-efficiency** — The overall process is designed to minimize developer time and reduce the number of interactions, while still producing results superior to what a model can generate from scratch. However, overall quality is proportional to the time invested in iterating on and refining the specification. - **Industry-standard** — The plugin's specification template is based on the arc42 standard, adjusted for LLM capabilities. Arc42 is a widely adopted, high-quality standard for software development documentation used by many organizations. - **Works best in complex or large codebases** — While most other frameworks work best for new projects and greenfield development, this plugin is designed to perform better as your codebase grows and your architecture becomes more structured. Each planning phase includes a **codebase impact analysis** step that evaluates which files may be affected and which patterns to follow to achieve the desired result. -- **Simple** — This plugin avoids unnecessary complexity by primarily using only three commands, offloading process complexity to the model via multi-agent orchestration. `/sdd:implement` is a single command that produces functional code from a task specification. To create that specification, you run `/sdd:add-task` and `/sdd:plan`, which analyze your prompt and iteratively refine the specification until it meets the required quality standards. +- **Simple** — This plugin avoids unnecessary complexity by primarily using only three commands, offloading process complexity to the model via multi-agent orchestration. `/implement-task` is a single command that produces functional code from a task specification. To create that specification, you run `/sdd:add-task` and `/plan-task`, which analyze your prompt and iteratively refine the specification until it meets the required quality standards. ## Quick Start @@ -31,10 +31,10 @@ Then run the following commands: ```bash # Create the .specs/tasks/draft/design-auth-middleware.feature.md file with the initial prompt -/sdd:add-task "Design and implement authentication middleware with JWT support" +/add-task "Design and implement authentication middleware with JWT support" # Write a detailed specification for the task -/sdd:plan +/plan-task # Moves the task to the .specs/tasks/todo/ folder ``` @@ -42,7 +42,7 @@ Run `/clear` (or re-open Claude Code) to clear context and start fresh. Then run ```bash # Implement the task -/sdd:implement @.specs/tasks/todo/design-auth-middleware.feature.md +/implement-task @.specs/tasks/todo/design-auth-middleware.feature.md # Produces a working implementation and moves the task to the .specs/tasks/done/ folder ``` @@ -54,19 +54,19 @@ Run `/clear` (or re-open Claude Code) to clear context and start fresh. Then run End-to-end task implementation process from initial prompt to pull request, including commands from the [git](../git/README.md) plugin: -- `/sdd:add-task` → Creates a `.specs/tasks/draft/..md` file with the initial task description. -- `/sdd:plan` → Generates a `.claude/skills//SKILL.md` file with the skills needed to implement the task (by analyzing the library and framework documentation used in the codebase), then updates the task file with a refined specification and moves it to `.specs/tasks/todo/`. -- `/sdd:implement` → Produces a working implementation, verifies it, then moves the task to `.specs/tasks/done/`. -- `/git:commit` → Commits changes. -- `/git:create-pr` → Creates a pull request. +- `/add-task` → Creates a `.specs/tasks/draft/..md` file with the initial task description. +- `/plan-task` → Generates a `.claude/skills//SKILL.md` file with the skills needed to implement the task (by analyzing the library and framework documentation used in the codebase), then updates the task file with a refined specification and moves it to `.specs/tasks/todo/`. +- `/implement-task` → Produces a working implementation, verifies it, then moves the task to `.specs/tasks/done/`. +- `/commit` → Commits changes. +- `/create-pr` → Creates a pull request. ``` 1. Create 2. Plan 3. Implement 4. Ship +-------------+ +-----------+ +---------------+ +-----------------+ -|/sdd:add-task| | /sdd:plan | |/sdd:implement | | /git:commit | +|/add-task| | /plan-task | |/implement-task| | /commit | +------+------+ +-----+-----+ +------+--------+ | | | | | | | v | - v v v |/git:create-pr | + v v v |/create-pr | +-------+---------+ | Task Lifecycle | @@ -80,14 +80,14 @@ End-to-end task implementation process from initial prompt to pull request, incl Core workflow commands: -- [/sdd:add-task](add-task.md) - Create task template file with initial prompt -- [/sdd:plan](plan.md) - Analyze prompt, generate required skills and refine task specification -- [/sdd:implement](implement.md) - Produce working implementation of the task and verify it +- [/add-task](add-task.md) - Create task template file with initial prompt +- [/plan-task](plan-task.md) - Analyze prompt, generate required skills and refine task specification +- [/implement-task](implement-task.md) - Produce working implementation of the task and verify it Additional commands useful before creating a task: -- [/sdd:create-ideas](create-ideas.md) - Generate diverse ideas on a given topic using creative sampling techniques -- [/sdd:brainstorm](brainstorm.md) - Refine vague ideas into fully-formed designs through collaborative dialogue +- [/create-ideas](create-ideas.md) - Generate diverse ideas on a given topic using creative sampling techniques +- [/brainstorm](brainstorm.md) - Refine vague ideas into fully-formed designs through collaborative dialogue ## Available Agents @@ -95,15 +95,15 @@ The SDD plugin uses specialized agents for different phases of development: | Agent | Description | Used By | |-------|-------------|---------| -| `researcher` | Technology research, dependency analysis, best practices | `/sdd:plan` (Phase 2a) | -| `code-explorer` | Codebase analysis, pattern identification, architecture mapping | `/sdd:plan` (Phase 2b) | -| `business-analyst` | Requirements discovery, stakeholder analysis, specification writing | `/sdd:plan` (Phase 2c) | -| `software-architect` | Architecture design, component design, implementation planning | `/sdd:plan` (Phase 3) | -| `tech-lead` | Task decomposition, dependency mapping, risk analysis | `/sdd:plan` (Phase 4) | -| `team-lead` | Step parallelization, agent assignment, execution planning | `/sdd:plan` (Phase 5) | -| `qa-engineer` | Verification rubrics, quality gates, LLM-as-Judge definitions | `/sdd:plan` (Phase 6) | -| `developer` | Code implementation, TDD execution, quality review, verification | `/sdd:implement` | -| `tech-writer` | Technical documentation, API guides, architecture updates, and lessons learned | `/sdd:implement` | +| `researcher` | Technology research, dependency analysis, best practices | `/plan-task` (Phase 2a) | +| `code-explorer` | Codebase analysis, pattern identification, architecture mapping | `/plan-task` (Phase 2b) | +| `business-analyst` | Requirements discovery, stakeholder analysis, specification writing | `/plan-task` (Phase 2c) | +| `software-architect` | Architecture design, component design, implementation planning | `/plan-task` (Phase 3) | +| `tech-lead` | Task decomposition, dependency mapping, risk analysis | `/plan-task` (Phase 4) | +| `team-lead` | Step parallelization, agent assignment, execution planning | `/plan-task` (Phase 5) | +| `qa-engineer` | Verification rubrics, quality gates, LLM-as-Judge definitions | `/plan-task` (Phase 6) | +| `developer` | Code implementation, TDD execution, quality review, verification | `/implement-task` | +| `tech-writer` | Technical documentation, API guides, architecture updates, and lessons learned | `/implement-task` | ## Patterns @@ -120,7 +120,7 @@ Key patterns implemented in this plugin: This plugin is not a "vibe coding" solution, though it can function like one out of the box. By default, it is designed to work from a single prompt through to task completion, making reasonable assumptions and evidence-based decisions instead of constantly asking for clarification. This is because developer time is more valuable than model time, allowing the developer to decide how much time is worth spending on a task. The plugin will always produce functional results, but quality may be sub-optimal without human feedback. -To improve quality, you can correct the generated specification or leave comments using `//`, then run the `/sdd:plan` command again with the `--refine` flag. You can also verify each planning and implementation phase by adding the `--human-in-the-loop` flag. Majority of researches show that human feedback is the most effective way to improve results. +To improve quality, you can correct the generated specification or leave comments using `//`, then run the `/plan-task` command again with the `--refine` flag. You can also verify each planning and implementation phase by adding the `--human-in-the-loop` flag. Majority of researches show that human feedback is the most effective way to improve results. Our tests showed that even when the initially generated specification was incorrect due to missing information or task complexity, the agent was still able to self-correct until it reached a working solution. However, this process often took longer, as the agent explored incorrect paths and stopped more frequently. To avoid this, we strongly recommend decomposing complex tasks into smaller, separate tasks with dependencies and reviewing the specification for each one. You can add dependencies between tasks as arguments to the `/sdd:add-task` command, and the model will link them by adding a `depends_on` section to the task file's frontmatter. @@ -130,17 +130,17 @@ Learn more about available customization options in [Customization](customizatio ## FAQ -**Do I need to re-run `/plan` or `/implement` after context compaction (`/compact`)?** +**Do I need to re-run `/plan-task` or `/implement-task` after context compaction (`/compact`)?** -After compaction, close the terminal and resume with `/plan --continue` or `/implement --continue`. This produces more predictable results than continuing in a compacted context. Using `/model sonnet[1m]` reduces compaction frequency. +After compaction, close the terminal and resume with `/plan-task --continue` or `/implement-task --continue`. This produces more predictable results than continuing in a compacted context. Using `/model sonnet[1m]` reduces compaction frequency. -**Do I need to prefix every prompt with `/plan` or `/implement`?** +**Do I need to prefix every prompt with `/plan-task` or `/implement-task`?** -No. Run these commands once to start the workflow. The only time to invoke them again is when you change the specification or code and want agents to update misaligned sections — use `/plan --refine` or `/implement --refine`. +No. Run these commands once to start the workflow. The only time to invoke them again is when you change the specification or code and want agents to update misaligned sections — use `/plan-task --refine` or `/implement-task --refine`. -**Should I clear context between `/plan` and `/implement`?** +**Should I clear context between `/plan-task` and `/implement-task`?** -Yes. Run `/clear` (or re-open Claude Code) after `/plan` completes and before running `/implement`. The planning phase fills the context with analysis artifacts; a clean context gives implementation agents better results. +Yes. Run `/clear` (or re-open Claude Code) after `/plan-task` completes and before running `/implement-task`. The planning phase fills the context with analysis artifacts; a clean context gives implementation agents better results. ## Theoretical Foundation diff --git a/docs/plugins/sdd/add-task.md b/docs/plugins/sdd/add-task.md index 2dc829a..cf9fd7a 100644 --- a/docs/plugins/sdd/add-task.md +++ b/docs/plugins/sdd/add-task.md @@ -1,12 +1,12 @@ -# /sdd:add-task - Draft Task Creation +# /add-task - Draft Task Creation -Create a draft task file that captures the user's intent with structured metadata, proper classification, and dependency tracking — ready for refinement by `/sdd:plan`. +Create a draft task file that captures the user's intent with structured metadata, proper classification, and dependency tracking — ready for refinement by `/plan-task`. - Purpose — Transform a user prompt into a well-structured draft task file with an action-oriented title, type classification, and optional dependencies - Output — Task file at `.specs/tasks/draft/..md` ```bash -/sdd:add-task "Task description" [dependency-file-paths...] +/add-task "Task description" [dependency-file-paths...] ``` ## Arguments @@ -136,25 +136,25 @@ depends_on: ```bash # Simple feature request -/sdd:add-task "Add user profile view with name, email, and avatar" +/add-task "Add user profile view with name, email, and avatar" # Bug report -/sdd:add-task "Fix login timeout on slow connections" +/add-task "Fix login timeout on slow connections" # Refactoring task -/sdd:add-task "Restructure authentication module for better testability" +/add-task "Restructure authentication module for better testability" # Task with dependency -/sdd:add-task "Add role-based access control" @.specs/tasks/draft/implement-user-auth-service.feature.md +/add-task "Add role-based access control" @.specs/tasks/draft/implement-user-auth-service.feature.md # Multiple dependencies -/sdd:add-task "Implement dashboard analytics" @.specs/tasks/draft/implement-auth.feature.md @.specs/tasks/draft/add-user-tracking.feature.md +/add-task "Implement dashboard analytics" @.specs/tasks/draft/implement-auth.feature.md @.specs/tasks/draft/add-user-tracking.feature.md # Test task -/sdd:add-task "Add unit tests for payment processing service" +/add-task "Add unit tests for payment processing service" # CI/CD task -/sdd:add-task "Add GitHub Actions workflow for automated testing" +/add-task "Add GitHub Actions workflow for automated testing" ``` ## Artifacts Generated @@ -163,21 +163,21 @@ depends_on: .specs/ └── tasks/ └── draft/ - └── ..md # Draft task file (ready for /sdd:plan) + └── ..md # Draft task file (ready for /plan-task) ``` ## What Happens Next After creating a draft task, proceed with the SDD workflow: -1. **Plan** — Run `/sdd:plan` to refine the draft into a full specification with architecture, implementation steps, and verification rubrics -2. **Implement** — Run `/sdd:implement` to execute the planned steps with quality-gated verification +1. **Plan** — Run `/plan-task` to refine the draft into a full specification with architecture, implementation steps, and verification rubrics +2. **Implement** — Run `/implement-task` to execute the planned steps with quality-gated verification 3. **Ship** — Use `/git:commit` and `/git:create-pr` to deliver ```bash -/sdd:add-task "Add validation to form inputs" -/sdd:plan @.specs/tasks/draft/add-validation-form-inputs.feature.md -/sdd:implement +/add-task "Add validation to form inputs" +/plan-task @.specs/tasks/draft/add-validation-form-inputs.feature.md +/implement-task ``` ## Best Practices @@ -185,5 +185,5 @@ After creating a draft task, proceed with the SDD workflow: - Keep descriptions focused — one task per prompt; decompose large features into multiple dependent tasks. - Provide dependencies explicitly — use task file paths as additional arguments when tasks have ordering requirements. - Use natural language — the agent infers type and title from your description; no special formatting is needed. -- Review the draft — verify the generated title and type before running `/sdd:plan`. +- Review the draft — verify the generated title and type before running `/plan-task`. - Decompose before planning — creating smaller tasks with dependencies produces better specifications than one large task. diff --git a/docs/plugins/sdd/brainstorm.md b/docs/plugins/sdd/brainstorm.md index 3945576..33a6ae5 100644 --- a/docs/plugins/sdd/brainstorm.md +++ b/docs/plugins/sdd/brainstorm.md @@ -1,4 +1,4 @@ -# /sdd:brainstorm - Idea Refinement +# /brainstorm - Idea Refinement Transform rough ideas into fully-formed designs through collaborative dialogue, incremental validation, and design documentation. @@ -6,7 +6,7 @@ Transform rough ideas into fully-formed designs through collaborative dialogue, - Output - Design document in `.specs/plans/.design.md` ```bash -/sdd:brainstorm initial feature concept +/brainstorm initial feature concept ``` ## Arguments @@ -53,16 +53,16 @@ Optional initial concept to explore. Can be vague: "something to help with user ```bash # Start with vague idea -/sdd:brainstorm Something to improve user onboarding +/brainstorm Something to improve user onboarding # More specific concept -/sdd:brainstorm Real-time collaboration features for document editing +/brainstorm Real-time collaboration features for document editing # Technical exploration -/sdd:brainstorm Caching strategy for our product catalog API +/brainstorm Caching strategy for our product catalog API # Process improvement -/sdd:brainstorm Automated deployment pipeline for our microservices +/brainstorm Automated deployment pipeline for our microservices ``` ## Best practices @@ -71,4 +71,4 @@ Optional initial concept to explore. Can be vague: "something to help with user - Be open to alternatives - The first idea isn't always best - Engage with questions - Your answers shape the design - Validate incrementally - Catch issues early in design sections -- Save the design - Use as input for `/sdd:add-task` +- Save the design - Use as input for `/add-task` diff --git a/docs/plugins/sdd/create-ideas.md b/docs/plugins/sdd/create-ideas.md index aee6305..b1761b4 100644 --- a/docs/plugins/sdd/create-ideas.md +++ b/docs/plugins/sdd/create-ideas.md @@ -1,14 +1,14 @@ -# /sdd:create-ideas - Idea Generation +# /create-ideas - Idea Generation Generate ideas in one shot using creative sampling. Based on [Verbalized Sampling](https://arxiv.org/abs/2510.01171) - a training-free prompting strategy to mitigate mode collapse in LLMs by requesting responses with probabilities. Achieves 2-3x diversity improvement while maintaining quality. -Different from `/sdd:brainstorm`, by much simpler and faster approach, but focused on generating ideas in one shot, don't include refinement, focuses on creativity. Can be used for any other purpose that include creative thinking. +Different from `/brainstorm`, by much simpler and faster approach, but focused on generating ideas in one shot, don't include refinement, focuses on creativity. Can be used for any other purpose that include creative thinking. - Purpose - Generate responses which require high diversity and creativity, like brainstorming or creative writing - Output - List of ideas with text and probability scores ```bash -/sdd:create-ideas [topic or problem] [optional: number of ideas] +/create-ideas [topic or problem] [optional: number of ideas] ``` ## Arguments @@ -30,25 +30,25 @@ Topic or problem to generate ideas for. Optionally specify the number of ideas t ```bash # Generate creative ideas for a feature -/sdd:create-ideas ways to improve user onboarding +/create-ideas ways to improve user onboarding # Brainstorm solutions to a problem -/sdd:create-ideas reduce API response times +/create-ideas reduce API response times # Creative writing prompts -/sdd:create-ideas write jokes about cats +/create-ideas write jokes about cats # Generate more ideas -/sdd:create-ideas 10 marketing slogans for a fitness app +/create-ideas 10 marketing slogans for a fitness app # Technical alternatives -/sdd:create-ideas caching strategies for real-time data +/create-ideas caching strategies for real-time data ``` ## When to Use -- **Use `/sdd:create-ideas`** when you need quick, diverse ideas without refinement -- **Use `/sdd:brainstorm`** when you need thorough exploration with validation and documentation +- **Use `/create-ideas`** when you need quick, diverse ideas without refinement +- **Use `/brainstorm`** when you need thorough exploration with validation and documentation ## Best practices diff --git a/docs/plugins/sdd/implement.md b/docs/plugins/sdd/implement-task.md similarity index 93% rename from docs/plugins/sdd/implement.md rename to docs/plugins/sdd/implement-task.md index 34b0064..044bf35 100644 --- a/docs/plugins/sdd/implement.md +++ b/docs/plugins/sdd/implement-task.md @@ -1,4 +1,4 @@ -# /sdd:implement - Task Implementation with Verification +# /implement-task - Task Implementation with Verification Execute task implementation steps using automated LLM-as-Judge quality verification, sequential and parallel execution, and Definition of Done (DoD) validation. @@ -6,7 +6,7 @@ Execute task implementation steps using automated LLM-as-Judge quality verificat - **Output**: Working code with passing tests; task moved to `.specs/tasks/done/`. ```bash -/sdd:implement [task-file] [options] +/implement-task [task-file] [options] ``` ## Arguments @@ -197,37 +197,37 @@ After each specified step passes: ```bash # Implement a specific task -/sdd:implement add-validation.feature.md +/implement-task add-validation.feature.md # Auto-select task from todo/ or in-progress/ (if only 1 task) -/sdd:implement +/implement-task # Continue from last completed step -/sdd:implement add-validation.feature.md --continue +/implement-task add-validation.feature.md --continue # Refine after manually fixing project files -/sdd:implement add-validation.feature.md --refine +/implement-task add-validation.feature.md --refine # Human review after every step -/sdd:implement add-validation.feature.md --human-in-the-loop +/implement-task add-validation.feature.md --human-in-the-loop # Human review after specific steps only -/sdd:implement add-validation.feature.md --human-in-the-loop 2,4,6 +/implement-task add-validation.feature.md --human-in-the-loop 2,4,6 # Stricter quality threshold (both standard and critical set to 4.5) -/sdd:implement critical-api.feature.md --target-quality 4.5 +/implement-task critical-api.feature.md --target-quality 4.5 # Different thresholds for standard (3.5) and critical (4.5) -/sdd:implement add-validation.feature.md --target-quality 3.5,4.5 +/implement-task add-validation.feature.md --target-quality 3.5,4.5 # Unlimited iterations until quality threshold met -/sdd:implement add-validation.feature.md --max-iterations unlimited +/implement-task add-validation.feature.md --max-iterations unlimited # Skip judges for fast execution (no quality gates) -/sdd:implement add-validation.feature.md --skip-judges +/implement-task add-validation.feature.md --skip-judges # Combined: continue with human review -/sdd:implement add-validation.feature.md --continue --human-in-the-loop +/implement-task add-validation.feature.md --continue --human-in-the-loop ``` ## Task Lifecycle diff --git a/docs/plugins/sdd/plan.md b/docs/plugins/sdd/plan-task.md similarity index 94% rename from docs/plugins/sdd/plan.md rename to docs/plugins/sdd/plan-task.md index 01d24fb..11328f0 100644 --- a/docs/plugins/sdd/plan.md +++ b/docs/plugins/sdd/plan-task.md @@ -1,4 +1,4 @@ -# /sdd:plan - Task Refinement & Planning +# /plan-task - Task Refinement & Planning Refine a draft task specification into a fully planned, implementation-ready task through multi-agent analysis, architecture synthesis, and quality-gated verification. @@ -6,7 +6,7 @@ Refine a draft task specification into a fully planned, implementation-ready tas - Output - A refined task file moved to `.specs/tasks/todo/`, plus skill files in `.claude/skills/` and analysis files in `.specs/analysis/` ```bash -/sdd:plan .specs/tasks/draft/add-validation.feature.md [options] +/plan-task .specs/tasks/draft/add-validation.feature.md [options] ``` ## Arguments @@ -171,25 +171,25 @@ You can also pass a requirement change directly: `/plan --refine +/plan-task --refine ``` The agent incorporates your change and re-runs affected stages. @@ -18,20 +18,20 @@ The agent incorporates your change and re-runs affected stages. ```bash # Change authentication strategy -/plan --refine Use session-based auth instead of JWT +/plan-task --refine Use session-based auth instead of JWT # Add a constraint the agent missed -/plan --refine The API must support pagination with cursor-based navigation, not offset +/plan-task --refine The API must support pagination with cursor-based navigation, not offset # Narrow the scope -/plan --refine Remove the admin dashboard from this task, we will handle it separately +/plan-task --refine Remove the admin dashboard from this task, we will handle it separately ``` ### Option B: Edit the spec, then refine 1. Edit the task file in `.specs/tasks/todo/` 2. Add `//` comments to lines that need clarification -3. Run `/plan --refine` +3. Run `/plan-task --refine` The agent detects your edits, identifies the earliest modified section, and re-runs all stages from that point onward. Earlier sections remain unchanged. @@ -45,24 +45,24 @@ The agent detects your edits, identifies the earliest modified section, and re-r - PostgreSQL with Prisma ORM ``` -Then run `/plan --refine`. The agent re-runs from architecture synthesis onward, producing new implementation steps for GraphQL while preserving the research and business analysis stages. +Then run `/plan-task --refine`. The agent re-runs from architecture synthesis onward, producing new implementation steps for GraphQL while preserving the research and business analysis stages. ### What `--refine` compares -By default, `--refine` diffs local (unstaged) changes against staged changes. Both `/plan` and `/implement` stage their output at the end, so any manual edits you make afterward appear as unstaged changes. +By default, `--refine` diffs local (unstaged) changes against staged changes. Both `/plan-task` and `/implement-task` stage their output at the end, so any manual edits you make afterward appear as unstaged changes. -To compare against the last commit instead, specify it: `/plan --refine compare with last commit`. +To compare against the last commit instead, specify it: `/plan-task --refine compare with last commit`. ## After Implementation -When requirements change after `/implement` completes, choose based on the scope of the change: +When requirements change after `/implement-task` completes, choose based on the scope of the change: ### Small code adjustments Edit the code directly, then run: ```bash -/implement --refine +/implement-task --refine ``` The agent detects your changes, maps them to implementation steps, and aligns the rest of the codebase. If the judge passes your fix, it is accepted as-is. If it fails, the agent adjusts surrounding code to match your intent. @@ -100,12 +100,12 @@ If requirements changed substantially, create a new task: ```bash /sdd:add-task "Refactor authentication implementation" -/sdd:plan +/plan-task # /clear (or re-open Claude Code) -/sdd:implement +/implement-task ``` -Re-running `/implement --refine` on large changes is less reliable than a fresh planning cycle. A new task produces a clean specification, proper architecture analysis, and accurate implementation steps. +Re-running `/implement-task --refine` on large changes is less reliable than a fresh planning cycle. A new task produces a clean specification, proper architecture analysis, and accurate implementation steps. **Examples of changes that warrant a new task:** @@ -121,23 +121,23 @@ A realistic sequence showing how refinement fits into the workflow: ```bash # 1. Create and plan the task /sdd:add-task "Add JWT authentication middleware" -/sdd:plan +/plan-task # 2. Review the spec — agent chose HS256, but you need RS256 -/plan --refine Use RS256 with rotating key pairs instead of HS256 +/plan-task --refine Use RS256 with rotating key pairs instead of HS256 # 3. Clear context, then implement /clear -/sdd:implement +/implement-task # 4. Review the code — token expiry is 1 hour, you want 15 minutes vi src/config/auth.ts # change TOKEN_EXPIRY to 900 -/implement --refine # agent updates tests and documentation to match +/implement-task --refine # agent updates tests and documentation to match # 5. Product feedback: "Add refresh tokens" # This is a significant scope addition — create a new task /sdd:add-task "Add refresh token rotation for JWT auth" -/sdd:plan +/plan-task /clear -/sdd:implement +/implement-task ``` diff --git a/docs/plugins/sdd/usage-examples.md b/docs/plugins/sdd/usage-examples.md index f8bd074..3bdb596 100644 --- a/docs/plugins/sdd/usage-examples.md +++ b/docs/plugins/sdd/usage-examples.md @@ -10,25 +10,25 @@ Real-world scenarios demonstrating the effective use of the Spec-Driven Developm ```bash # Step 1: Create draft task -/sdd:add-task "Add user profile view and edit functionality with name, email, and avatar" +/add-task "Add user profile view and edit functionality with name, email, and avatar" # Step 2: Plan — research, analyze, decompose, parallelize, verify -/sdd:plan @.specs/tasks/draft/add-user-profile.feature.md +/plan-task @.specs/tasks/draft/add-user-profile.feature.md # Step 3: Review specification (optional but recommended) # Edit .specs/tasks/todo/add-user-profile.feature.md if needed # Re-run planning for only affected sections: -/sdd:plan @.specs/tasks/todo/add-user-profile.feature.md --refine +/plan-task @.specs/tasks/todo/add-user-profile.feature.md --refine # Step 4: Implement -/sdd:implement @.specs/tasks/todo/add-user-profile.feature.md +/implement-task @.specs/tasks/todo/add-user-profile.feature.md # Step 5: Commit and create PR -/git:commit -/git:create-pr +/commit +/create-pr ``` -**What happens during `/sdd:plan`**: +**What happens during `/plan-task`**: 1. `researcher` agent gathers relevant resources and creates a skill file 2. `code-explorer` agent identifies affected files and integration points @@ -39,7 +39,7 @@ Real-world scenarios demonstrating the effective use of the Spec-Driven Developm 7. `qa-engineer` agent defines verification rubrics for each step 8. Task file moved from `draft/` to `todo/` -**What happens during `/sdd:implement`**: +**What happens during `/implement-task`**: 1. Task moved from `todo/` to `in-progress/` 2. Each step executed by `sdd:developer` agent @@ -55,13 +55,13 @@ Real-world scenarios demonstrating the effective use of the Spec-Driven Developm ```bash # Create the task -/sdd:add-task "Fix null pointer in user service when email is empty" +/add-task "Fix null pointer in user service when email is empty" # Fast planning — only business analysis + decomposition, lower quality bar -/sdd:plan @.specs/tasks/draft/fix-null-pointer-user-service.bug.md --fast +/plan-task @.specs/tasks/draft/fix-null-pointer-user-service.bug.md --fast # Implement without judge verification for speed -/sdd:implement @.specs/tasks/todo/fix-null-pointer-user-service.bug.md --skip-judges +/implement-task @.specs/tasks/todo/fix-null-pointer-user-service.bug.md --skip-judges ``` The `--fast` flag sets `--target-quality 3.0 --max-iterations 1 --included-stages "business analysis,decomposition,verifications"`, skipping research, codebase analysis, architecture synthesis, and parallelization. @@ -74,13 +74,13 @@ The `--fast` flag sets `--target-quality 3.0 --max-iterations 1 --included-stage ```bash # Brainstorm the approach first -/sdd:brainstorm We need to add billing capabilities for our B2B SaaS. Organizations should have subscription plans, usage tracking, and invoice generation. +/brainstorm We need to add billing capabilities for our B2B SaaS. Organizations should have subscription plans, usage tracking, and invoice generation. # Create the task with clear scope -/sdd:add-task "Implement multi-tenant billing with hybrid pricing and Stripe integration" +/add-task "Implement multi-tenant billing with hybrid pricing and Stripe integration" # High-quality planning with human review at each phase -/sdd:plan @.specs/tasks/draft/implement-billing-stripe.feature.md --target-quality 4.5 --human-in-the-loop 2,3,4,5,6 +/plan-task @.specs/tasks/draft/implement-billing-stripe.feature.md --target-quality 4.5 --human-in-the-loop 2,3,4,5,6 ``` **Expected planning flow with human-in-the-loop**: @@ -108,7 +108,7 @@ After reviewing and refining the specification: ```bash # Implement with stricter thresholds and human review on critical steps -/sdd:implement @.specs/tasks/todo/implement-billing-stripe.feature.md --target-quality 4.5 --human-in-the-loop 2,4,6 +/implement-task @.specs/tasks/todo/implement-billing-stripe.feature.md --target-quality 4.5 --human-in-the-loop 2,4,6 ``` --- @@ -119,7 +119,7 @@ After reviewing and refining the specification: ```bash # Initial planning -/sdd:plan @.specs/tasks/draft/add-notification-system.feature.md +/plan-task @.specs/tasks/draft/add-notification-system.feature.md # Review the generated specification # Edit .specs/tasks/todo/add-notification-system.feature.md: @@ -127,7 +127,7 @@ After reviewing and refining the specification: # - Add // comment: "should support both email and push notifications" # Re-run only affected stages (architecture and below) -/sdd:plan @.specs/tasks/todo/add-notification-system.feature.md --refine +/plan-task @.specs/tasks/todo/add-notification-system.feature.md --refine # Detects: Architecture Overview section changed # Skips: research, codebase analysis, business analysis @@ -144,12 +144,12 @@ The `--refine` flag uses git diff to detect which sections were modified and onl ```bash # Initial implementation starts -/sdd:implement @.specs/tasks/todo/add-validation.feature.md +/implement-task @.specs/tasks/todo/add-validation.feature.md # ... interrupted after Step 3 ... # Resume from where it left off -/sdd:implement add-validation.feature.md --continue +/implement-task add-validation.feature.md --continue # Output: # Found: Step 1 [DONE], Step 2 [DONE], Step 3 [DONE] @@ -168,7 +168,7 @@ The `--refine` flag uses git diff to detect which sections were modified and onl # Manually edit src/validation/validation.service.ts # Re-verify from the affected step onward -/sdd:implement add-validation.feature.md --refine +/implement-task add-validation.feature.md --refine # Output: # Detecting changed project files... @@ -188,23 +188,23 @@ The `--refine` flag uses git diff to detect which sections were modified and onl ```bash # Create tasks with dependencies -/sdd:add-task "Implement user authentication service" +/add-task "Implement user authentication service" # Created: .specs/tasks/draft/implement-user-auth-service.feature.md -/sdd:add-task "Add role-based access control" @.specs/tasks/draft/implement-user-auth-service.feature.md +/add-task "Add role-based access control" @.specs/tasks/draft/implement-user-auth-service.feature.md # Created: .specs/tasks/draft/add-role-based-access-control.feature.md # Depends on: implement-user-auth-service.feature.md # Plan and implement in order -/sdd:plan @.specs/tasks/draft/implement-user-auth-service.feature.md -/sdd:implement -/git:commit +/plan-task @.specs/tasks/draft/implement-user-auth-service.feature.md +/implement-task +/commit -/sdd:plan @.specs/tasks/draft/add-role-based-access-control.feature.md -/sdd:implement -/git:commit +/plan-task @.specs/tasks/draft/add-role-based-access-control.feature.md +/implement-task +/commit -/git:create-pr +/create-pr ``` --- @@ -215,18 +215,18 @@ The `--refine` flag uses git diff to detect which sections were modified and onl ```bash # Quick diverse idea generation -/sdd:create-ideas "caching strategies for a real-time product catalog" +/create-ideas "caching strategies for a real-time product catalog" # Output: 5 diverse ideas with probability scores # Pick the most promising approach # Deeper exploration with collaborative dialogue -/sdd:brainstorm "We need real-time features but are not sure about WebSockets vs. Server-Sent Events" +/brainstorm "We need real-time features but are not sure about WebSockets vs. Server-Sent Events" # After brainstorm produces a design document: -/sdd:add-task "Implement real-time stock updates using WebSocket connections" -/sdd:plan @.specs/tasks/draft/implement-realtime-stock-updates.feature.md -/sdd:implement +/add-task "Implement real-time stock updates using WebSocket connections" +/plan-task @.specs/tasks/draft/implement-realtime-stock-updates.feature.md +/implement-task ``` --- @@ -237,13 +237,13 @@ The `--refine` flag uses git diff to detect which sections were modified and onl ```bash # Skip research phase — you're familiar with the stack -/sdd:plan @.specs/tasks/draft/add-pagination.feature.md --skip research +/plan-task @.specs/tasks/draft/add-pagination.feature.md --skip research # Skip research and codebase analysis — A small, isolated change -/sdd:plan @.specs/tasks/draft/fix-date-format.bug.md --skip research,"codebase analysis" +/plan-task @.specs/tasks/draft/fix-date-format.bug.md --skip research,"codebase analysis" # Only run business analysis and decomposition -/sdd:plan @.specs/tasks/draft/update-config.chore.md --included-stages "business analysis,decomposition" +/plan-task @.specs/tasks/draft/update-config.chore.md --included-stages "business analysis,decomposition" ``` --- @@ -254,19 +254,19 @@ The `--refine` flag uses git diff to detect which sections were modified and onl ```bash # Critical production API — highest quality -/sdd:plan @.specs/tasks/draft/payment-api.feature.md --target-quality 4.5 --max-iterations 5 -/sdd:implement --target-quality 4.5 --max-iterations unlimited +/plan-task @.specs/tasks/draft/payment-api.feature.md --target-quality 4.5 --max-iterations 5 +/implement-task --target-quality 4.5 --max-iterations unlimited # Internal tool — standard quality -/sdd:plan @.specs/tasks/draft/admin-dashboard.feature.md -/sdd:implement +/plan-task @.specs/tasks/draft/admin-dashboard.feature.md +/implement-task # Quick prototype — minimum viable quality -/sdd:plan @.specs/tasks/draft/poc-feature.feature.md --fast -/sdd:implement --target-quality 3.5 --max-iterations 1 +/plan-task @.specs/tasks/draft/poc-feature.feature.md --fast +/implement-task --target-quality 3.5 --max-iterations 1 # Different thresholds for standard vs critical components -/sdd:implement --target-quality 3.5,4.5 +/implement-task --target-quality 3.5,4.5 # Standard components verified at 3.5, critical at 4.5 ``` @@ -278,35 +278,35 @@ The `--refine` flag uses git diff to detect which sections were modified and onl ```bash # 1. Create and plan the task -/sdd:add-task "Add user notification preferences with email digest settings" -/sdd:plan @.specs/tasks/draft/add-notification-preferences.feature.md +/add-task "Add user notification preferences with email digest settings" +/plan-task @.specs/tasks/draft/add-notification-preferences.feature.md # 2. Review specification, make edits if needed # 3. Re-plan if you made edits -/sdd:plan @.specs/tasks/todo/add-notification-preferences.feature.md --refine +/plan-task @.specs/tasks/todo/add-notification-preferences.feature.md --refine # 4. Implement -/sdd:implement +/implement-task # 5. Commit and create PR -/git:commit -/git:create-pr +/commit +/create-pr ``` ### Research-Heavy Features ```bash # For unfamiliar technology — brainstorm first -/sdd:brainstorm "We need real-time features, but I'm not sure about WebSockets vs. Server-Sent Events" +/brainstorm "We need real-time features, but I'm not sure about WebSockets vs. Server-Sent Events" -# The research phase in /sdd:plan will: +# The research phase in /plan-task will: # - Launch researcher agent to compare libraries # - Analyze browser support and scalability # - Check existing codebase patterns # - Create a reusable skill document -/sdd:add-task "Add real-time collaboration with WebSocket support" -/sdd:plan @.specs/tasks/draft/add-realtime-collaboration.feature.md +/add-task "Add real-time collaboration with WebSocket support" +/plan-task @.specs/tasks/draft/add-realtime-collaboration.feature.md ``` --- @@ -329,9 +329,9 @@ The `--refine` flag uses git diff to detect which sections were modified and onl ### Common Patterns -1. **Brainstorm before task creation** — Use `/sdd:brainstorm` for vague requirements, `/sdd:create-ideas` for quick diverse options +1. **Brainstorm before task creation** — Use `/brainstorm` for vague requirements, `/create-ideas` for quick diverse options 2. **Review specifications** — Edit the task file and use `--refine` to propagate changes -3. **Decompose large tasks** — Create multiple tasks with dependencies using `/sdd:add-task` +3. **Decompose large tasks** — Create multiple tasks with dependencies using `/add-task` 4. **Use human-in-the-loop for critical decisions** — Architecture and decomposition phases benefit most from human review 5. **Continue interrupted work** — Use `--continue` to resume implementation, `--refine` after manual fixes diff --git a/docs/plugins/tdd/README.md b/docs/plugins/tdd/README.md index 6e3e246..f227356 100644 --- a/docs/plugins/tdd/README.md +++ b/docs/plugins/tdd/README.md @@ -33,7 +33,7 @@ The plugin is based on foundational works including Kent Beck's *Test-Driven Dev # Manually make some changes that cause test failures # Fix failing tests -> /tdd:fix-tests +> /fix-tests ``` ### After Implementation @@ -44,7 +44,7 @@ If you implemented a new feature but have not written tests, you can use the `wr > claude "implement email validation for user registration" # Write tests after you made changes -> /tdd:write-tests +> /write-tests ``` [Usage Examples](./usage-examples.md) diff --git a/docs/plugins/tdd/fix-tests.md b/docs/plugins/tdd/fix-tests.md index c85c94a..a6f8154 100644 --- a/docs/plugins/tdd/fix-tests.md +++ b/docs/plugins/tdd/fix-tests.md @@ -1,4 +1,4 @@ -# /tdd:fix-tests - Fix Failing Tests +# /fix-tests - Fix Failing Tests Systematically fix all failing tests after business logic changes or refactoring using orchestrated agents. @@ -6,7 +6,7 @@ Systematically fix all failing tests after business logic changes or refactoring - Output - Fixed tests that pass while preserving test intent ```bash -/tdd:fix-tests ["focus area or modules"] +/fix-tests ["focus area or modules"] ``` ## Arguments @@ -47,16 +47,16 @@ Optional specification of which tests or modules to focus on. Defaults to all fa ```bash # Fix all failing tests -> /tdd:fix-tests +> /fix-tests # Focus on specific test files -> /tdd:fix-tests user authentication tests +> /fix-tests user authentication tests # Fix tests in specific module -> /tdd:fix-tests payment module tests +> /fix-tests payment module tests # Focus on integration tests -> /tdd:fix-tests integration tests only +> /fix-tests integration tests only ``` ## Best practices diff --git a/docs/plugins/tdd/usage-examples.md b/docs/plugins/tdd/usage-examples.md index 54961f6..41d88a3 100644 --- a/docs/plugins/tdd/usage-examples.md +++ b/docs/plugins/tdd/usage-examples.md @@ -13,7 +13,7 @@ Real-world scenarios demonstrating effective use of the TDD plugin for test-firs > claude "create a function to validate email addresses with proper regex" # Add test coverage -> /tdd:write-tests +> /write-tests ``` **Expected Flow**: @@ -59,7 +59,7 @@ describe('validateEmail', () => { > claude "implement Stripe payment processing with subscription support, webhooks, and retry logic" # Generate comprehensive tests using agents -> /tdd:write-tests Focus on payment flows and error handling +> /write-tests Focus on payment flows and error handling ``` **Expected Flow**: @@ -98,7 +98,7 @@ Webhook Handler (webhook-handler.ts): > claude "refactor user authentication from sessions to JWT tokens" # Fix all failing tests -> /tdd:fix-tests +> /fix-tests ``` **Expected Flow**: @@ -162,7 +162,7 @@ All 5 tests in auth.test.ts now passing ✅ > claude "fix the validation to reject empty usernames" # Verify and add edge case tests -> /tdd:write-tests Focus on username validation edge cases +> /write-tests Focus on username validation edge cases ``` **Expected Flow**: @@ -180,7 +180,7 @@ test('rejects empty username during registration', () => { 2. Test fails (RED phase confirmed) 3. Fix implemented 4. Test passes (GREEN) -5. `/tdd:write-tests` adds comprehensive edge cases: +5. `/write-tests` adds comprehensive edge cases: ```typescript describe('username validation', () => { @@ -199,13 +199,13 @@ describe('username validation', () => { ```bash # Review existing coverage -> /tdd:write-tests Focus on financial calculations - ensure all edge cases covered +> /write-tests Focus on financial calculations - ensure all edge cases covered # Run coverage report > npm run test:coverage # Address any gaps identified -> /tdd:write-tests Cover the remaining uncovered branches +> /write-tests Cover the remaining uncovered branches ``` **Expected Coverage Review Output**: @@ -252,7 +252,7 @@ Tests Added: > npm test # Fix tests for new API -> /tdd:fix-tests React 18 API changes - focus on rendering and act() warnings +> /fix-tests React 18 API changes - focus on rendering and act() warnings ``` **Expected Agent Analysis**: @@ -285,7 +285,7 @@ All 9 previously failing tests now pass ✅ > claude "implement user service with CRUD operations, authentication, and notifications" # Generate tests for entire service -> /tdd:write-tests Cover all critical business logic across the service +> /write-tests Cover all critical business logic across the service ``` **Expected Multi-Agent Orchestration**: @@ -329,7 +329,7 @@ Final Results: > /reflexion:reflect # Ensure test coverage -> /tdd:write-tests +> /write-tests # Save testing insights > /reflexion:memorize "Rate limiting test patterns" @@ -352,13 +352,13 @@ Final Results: ```bash # Write tests for changes -> /tdd:write-tests +> /write-tests # Get multi-agent code review -> /code-review:review-local-changes +> /review-local-changes # Fix any test issues identified -> /tdd:fix-tests address code review findings +> /fix-tests address code review findings ``` **Code Review Output**: @@ -387,8 +387,8 @@ Recommendations: > /sdd:04-implement # Implementation phase # TDD for implementation -> /tdd:write-tests # Cover all implemented logic -> /tdd:fix-tests # Fix any issues +> /write-tests # Cover all implemented logic +> /fix-tests # Fix any issues # Continue SDD workflow > /sdd:05-document @@ -401,13 +401,13 @@ Recommendations: > claude "add password strength validation" # Ensure test coverage -> /tdd:write-tests +> /write-tests # Fix any failing tests -> /tdd:fix-tests +> /fix-tests # Review all changes -> /code-review:review-local-changes +> /review-local-changes # Commit with confidence > /git:commit @@ -420,7 +420,7 @@ Recommendations: **Scenario**: Test is asserting on mock existence rather than behavior. ```bash -> /tdd:write-tests +> /write-tests ``` **Plugin Detection**: @@ -444,7 +444,7 @@ Fix Applied: **Scenario**: Production class contains methods only used in tests. ```bash -> /tdd:fix-tests +> /fix-tests ``` **Plugin Detection**: @@ -468,7 +468,7 @@ Recommendation: **Scenario**: Mock is missing fields that downstream code depends on. ```bash -> /tdd:write-tests +> /write-tests ``` **Plugin Warning**: @@ -492,10 +492,10 @@ Fix Applied: | Scenario | Command | |----------|---------| -| Cover all local changes | `/tdd:write-tests` | -| Cover specific module | `/tdd:write-tests authentication module` | -| Focus on edge cases | `/tdd:write-tests Focus on edge cases and error handling` | -| Fix all failing tests | `/tdd:fix-tests` | -| Fix specific test files | `/tdd:fix-tests payment tests` | -| Fix after refactoring | `/tdd:fix-tests after API refactoring` | -| Fix after dependency update | `/tdd:fix-tests React 18 migration` | +| Cover all local changes | `/write-tests` | +| Cover specific module | `/write-tests authentication module` | +| Focus on edge cases | `/write-tests Focus on edge cases and error handling` | +| Fix all failing tests | `/fix-tests` | +| Fix specific test files | `/fix-tests payment tests` | +| Fix after refactoring | `/fix-tests after API refactoring` | +| Fix after dependency update | `/fix-tests React 18 migration` | diff --git a/docs/plugins/tdd/write-tests.md b/docs/plugins/tdd/write-tests.md index 9e69820..be96c0e 100644 --- a/docs/plugins/tdd/write-tests.md +++ b/docs/plugins/tdd/write-tests.md @@ -1,4 +1,4 @@ -# /tdd:write-tests - Cover Local Changes with Tests +# /write-tests - Cover Local Changes with Tests Systematically add test coverage for all local code changes using specialized review and development agents. @@ -6,7 +6,7 @@ Systematically add test coverage for all local code changes using specialized re - Output - New test files covering all critical business logic ```bash -/tdd:write-tests ["focus area or modules"] +/write-tests ["focus area or modules"] ``` ## Arguments @@ -46,16 +46,16 @@ Optional focus area specification. Defaults to all uncommitted changes. If every ```bash # Cover all uncommitted changes -> /tdd:write-tests +> /write-tests # Focus on specific module -> /tdd:write-tests Focus on payment processing edge cases +> /write-tests Focus on payment processing edge cases # Cover authentication changes -> /tdd:write-tests authentication module +> /write-tests authentication module # Focus on error handling -> /tdd:write-tests Focus on error paths and validations +> /write-tests Focus on error paths and validations ``` ## Best practices diff --git a/docs/plugins/tech-stack/README.md b/docs/plugins/tech-stack/README.md index 533acd9..9b0019a 100644 --- a/docs/plugins/tech-stack/README.md +++ b/docs/plugins/tech-stack/README.md @@ -1,17 +1,16 @@ # Tech Stack Plugin -Language and framework-specific best practices plugin that configures your CLAUDE.md with standardized coding standards, ensuring consistent code quality across all AI-assisted development. +Language and framework-specific best practices plugin that provides rules automatically loaded into agent context when working with matching file types, ensuring consistent code quality across all AI-assisted development. Focused on: -- **Standardized Guidelines** - Pre-defined best practices for specific languages and frameworks -- **Initial context building** - Updates of CLAUDE.md, so it will be loaded during every claude code session +- **Automatic Rules** - Best practices loaded into context based on file types being worked on +- **Zero Configuration** - Rules activate automatically when agent reads or writes matching files ## Overview -The Tech Stack plugin provides commands for setting up language and framework-specific best practices in your CLAUDE.md file. Instead of manually defining coding standards, this plugin provides curated, production-tested guidelines that can be applied with a single command. +The Tech Stack plugin provides rules for language and framework-specific best practices. Rules are automatically loaded into the agent's context when working with matching file types (e.g., `**/*.ts` for TypeScript). No manual invocation is needed -- once the plugin is installed, the agent receives relevant coding standards whenever it reads or writes files of that type. -When Claude operates with explicit coding standards in CLAUDE.md, it produces more consistent and higher-quality code. The Tech Stack plugin bridges the gap between starting a new project and having well-defined development standards. ## Quick Start @@ -19,26 +18,25 @@ When Claude operates with explicit coding standards in CLAUDE.md, it produces mo # Install the plugin /plugin install tech-stack@NeoLabHQ/context-engineering-kit -# Add TypeScript best practices to your project -/tech-stack:add-typescript-best-practices +# Rules activate automatically when working on TypeScript files +# No additional setup needed -# Review the updated CLAUDE.md -cat CLAUDE.md +Refactor @src/main.ts to use generics +-> TypeScript Best Practices automatically loaded and applied ``` -[Usage Examples](./usage-examples.md) +## Rules +Rules are context files that are automatically loaded when the agent works on files matching specific glob patterns. Unlike skills (which require manual invocation), rules apply transparently based on the file types being edited. -### Why CLAUDE.md Matters +| Rule | File Pattern | Description | +|------|-------------|-------------| +| [TypeScript Best Practices](typescript-best-practices.md) | `**/*.ts` | Type system guidelines, code style, async patterns, utility types, and code quality standards | -CLAUDE.md is read by Claude at the start of every conversation. By placing coding standards here: - -1. **Persistent Context** - Guidelines are always available to Claude -2. **Project-Specific Rules** - Different projects can have different standards -3. **Team Synchronization** - All team members share the same AI configuration -4. **Version Control** - Guidelines are tracked alongside your code - -## Commands - -- [/tech-stack:add-typescript-best-practices](./add-typescript-best-practices.md) - Sets up TypeScript best practices and code style rules in your CLAUDE.md file, providing Claude with explicit guidelines for generating consistent, type-safe code. +### What TypeScript Best Practices Covers +- **Code Style** - Strict typing, interfaces over types, enum usage, type guards +- **Type System** - Inference, generics, conditional types, mapped types, opaque types +- **Async Patterns** - async/await, Promise-based APIs, concurrent operations +- **Code Quality** - Destructuring, naming conventions, library-first approach +- **Utility Types** - Practical usage of Record, Partial, Omit, Pick, and more diff --git a/docs/plugins/tech-stack/add-typescript-best-practices.md b/docs/plugins/tech-stack/add-typescript-best-practices.md deleted file mode 100644 index f4745a4..0000000 --- a/docs/plugins/tech-stack/add-typescript-best-practices.md +++ /dev/null @@ -1,26 +0,0 @@ -# /tech-stack:add-typescript-best-practices - TypeScript Configuration - -Sets up TypeScript best practices and code style rules in your CLAUDE.md file, providing Claude with explicit guidelines for generating consistent, type-safe code. - -- Purpose - Configure TypeScript coding standards -- Output - Updated CLAUDE.md with TypeScript guidelines - -```bash -/tech-stack:add-typescript-best-practices -``` - -## Arguments - -Optional argument which practices to add or avoid. - -## How It Works - -1. **File Detection**: Locates or creates CLAUDE.md in your project root - -2. **Content Injection**: Adds the following standardized sections: - - **Code Style Rules** - General principles for TypeScript development - - **Type System Guidelines** - Interface vs type preferences, enum usage - - **Library-First Approach** - Recommended libraries for common tasks - - **Code Quality Patterns** - Destructuring, time handling, and more - -3. **Non-Destructive Update**: Preserves existing CLAUDE.md content while adding new guidelines diff --git a/docs/plugins/tech-stack/typescript-best-practices.md b/docs/plugins/tech-stack/typescript-best-practices.md new file mode 100644 index 0000000..5c26703 --- /dev/null +++ b/docs/plugins/tech-stack/typescript-best-practices.md @@ -0,0 +1,92 @@ +# TypeScript Best Practices Rule + +Auto-applied rule that enforces TypeScript coding standards whenever the agent reads or writes TypeScript files. Covers type system guidelines, code style patterns, async best practices, and utility type usage. + +- Activation - Automatically when working on files matching `**/*.ts` +- Impact - Applied to all TypeScript file operations (read and write) + +## What It Enforces + +The rule provides comprehensive TypeScript guidelines organized into seven categories. When plugin is active, the agent receives these standards as context on first read or write of a TypeScript file. + +### Categories + +| Category | Key Guidelines | +|----------|---------------| +| **Code Style** | Strict typing, interfaces over types for object shapes, enums for constants, type guards over assertions | +| **Type System** | Prefer inference, avoid `any`, use `Record` over `object`, prefer `@ts-expect-error` over `@ts-ignore` | +| **Async Patterns** | `async`/`await` over callbacks, async APIs over sync, `Promise.all` for concurrency | +| **Code Structure** | Object destructuring, descriptive naming, named constants over magic values | +| **Type Narrowing** | typeof guards, instanceof guards, truthiness/equality narrowing, `in` operator, custom type guards (type predicates, generics, property checks), assertion functions | +| **TypeScript Utility Types** | Parameters, ReturnType, Awaited, Record, Partial, Required, Omit, Pick, Exclude, Extract, NonNullable, plus reusable wrapper type patterns | +| **Performance** | `for...of` over index loops, reuse existing functions and packages | +| **Logging** | Never log private data, always log errors in `.catch()` callbacks | +| **Time Consistency** | Assign `Date.now()` once and reuse, use `ms` package for durations | + +### Type System Guidelines + +The rule emphasizes strict type safety with specific preferences: + +- **Interfaces for objects, types for unions** - Use `interface` for object shapes (e.g., React props); use `type` for unions and intersections +- **Const assertions** - Prefer `as const satisfies XyzInterface` over plain `as const` +- **Module augmentation** - Prefer `declare module` over `namespace`-based extension patterns +- **Extensibility** - Define metadata fields next to the processor/plugin that reads or writes them + +### Library-First Approach + +The rule recommends established libraries over custom implementations: + +| Domain | Recommended Libraries | +|--------|----------------------| +| Date/time | date-fns, dayjs | +| Validation | joi, yup, zod | +| HTTP | axios, got | +| State management | Redux, MobX, Zustand | +| Utilities | lodash, ramda | + +### Type Narrowing + +The rule covers TypeScript's ability to refine types based on control flow analysis. When the agent writes conditional logic, it applies these narrowing techniques: + +| Technique | Description | +|-----------|-------------| +| `typeof` guards | Narrow primitives (`string`, `number`, `boolean`, etc.) | +| `instanceof` guards | Narrow class instances (e.g., `Error`, custom classes) | +| Truthiness narrowing | Eliminate `null`/`undefined` via truthy checks | +| Equality narrowing | Refine types when two values are compared with `===` | +| `in` operator | Discriminate union members by checking for a property | +| Custom type guards | User-defined `value is Type` predicate functions | +| Generic type guards | Reusable guards like `isNotNull` for filtering arrays | +| Object property checks | `hasProperty` guards for safe dynamic property access | +| Assertion functions | `asserts value is Type` functions that throw on invalid input | + +### TypeScript Utility Types + +The rule provides practical usage patterns and before/after examples for built-in utility types. The agent uses these when generating or refactoring type definitions: + +| Utility Type | Use Case | +|-------------|----------| +| `Parameters` | Wrapping functions, creating function variants | +| `ReturnType` | Extracting return types when not explicitly exported | +| `Awaited` | Unwrapping Promise types, especially with async functions | +| `Record` | Creating object types with dynamic or union keys | +| `Partial` | Update/patch operations where not all fields are required | +| `Required` | Ensuring all config options are provided | +| `Omit` | Removing sensitive or internal fields from types | +| `Pick` | Creating focused subsets of larger types | +| `Exclude` | Filtering members out of union types | +| `Extract` | Selecting specific members from union types | +| `NonNullable` | Removing `null`/`undefined` after validation | + +Also includes patterns for combining utilities (e.g., `Awaited>`) and creating reusable wrapper types. + +### Code Examples Included + +The rule contains before/after examples for common TypeScript patterns: + +- Eliminating `any` with generics +- Narrowing unknown API responses with type guards +- `as const` assertions and literal types +- Conditional types and `infer` keyword +- Mapped types and opaque (brand) types +- Template literal types diff --git a/docs/plugins/tech-stack/usage-examples.md b/docs/plugins/tech-stack/usage-examples.md deleted file mode 100644 index 6ecf59f..0000000 --- a/docs/plugins/tech-stack/usage-examples.md +++ /dev/null @@ -1,373 +0,0 @@ -# Tech Stack Plugin - Usage Examples - -Real-world scenarios demonstrating effective use of the Tech Stack plugin for establishing coding standards. - -## Examples - -### New TypeScript Project Setup - -**Scenario**: You're starting a new TypeScript API project and want to establish coding standards from the beginning. - -```bash -# Initialize Claude configuration -claude /init - -# Create project constitution -/sdd:00-setup TypeScript REST API with Express and PostgreSQL - -# Add TypeScript best practices -/tech-stack:add-typescript-best-practices - -# Verify the configuration -cat CLAUDE.md -``` - -**Expected Flow**: - -1. Claude creates initial CLAUDE.md with project basics -2. SDD establishes architectural principles in specs/constitution.md -3. Tech Stack adds TypeScript-specific coding standards to CLAUDE.md -4. Your project now has comprehensive development guidelines - -**Result in CLAUDE.md**: -```markdown -## Code Style Rules - -### General Principles - -- **TypeScript**: All code must be strictly typed, leverage TypeScript's type safety features - -### Code style rules - -- Interfaces over types - use interfaces for object types -- Use enum for constant values, prefer them over string literals -- Export all types by default -- Use type guards instead of type assertions -``` - -### Onboarding Existing Project - -**Scenario**: You have an existing TypeScript codebase that needs standardized coding guidelines for the team. - -```bash -# Add TypeScript best practices to existing project -/tech-stack:add-typescript-best-practices - -# Review what was added -cat CLAUDE.md - -# Optionally, customize for your project's specific needs -> claude "add a section about our REST API naming conventions to CLAUDE.md" -``` - -**Expected Flow**: - -1. Tech Stack adds standardized TypeScript guidelines -2. Existing CLAUDE.md content is preserved -3. You can customize the added guidelines to match your project - -**When to Customize**: - -Your team may have different preferences. After running the command, consider: - -- Removing library recommendations that don't match your stack -- Adding project-specific type naming conventions -- Including framework-specific patterns (NestJS, Next.js, etc.) - -### Team Standardization - -**Scenario**: Your team wants consistent AI-generated code across all developers. - -```bash -# Lead developer sets up standards -/tech-stack:add-typescript-best-practices - -# Commit CLAUDE.md to version control -git add CLAUDE.md -git commit -m "Add TypeScript coding standards for AI assistance" - -# All team members get the same guidelines when they pull -git pull -``` - -**Benefits**: - -- All team members' Claude instances follow the same rules -- Code reviews have consistent standards to reference -- New team members immediately work with established patterns -- AI-generated code matches team conventions - -### Combined with Code Formatting - -**Scenario**: You want both language best practices and code formatting standards. - -```bash -# Add TypeScript best practices -/tech-stack:add-typescript-best-practices - -# Add code formatting and architecture rules -/ddd:setup-code-formating - -# Your CLAUDE.md now has comprehensive standards -cat CLAUDE.md -``` - -**Result**: - -Your CLAUDE.md will contain: - -1. **TypeScript Best Practices** (from Tech Stack) - - Type system guidelines - - Library recommendations - - Code quality patterns - -2. **Code Formatting Rules** (from DDD) - - Clean Architecture principles - - SOLID patterns - - Formatting standards - -### Feature Development with Standards - -**Scenario**: Implementing a new feature while ensuring it follows established TypeScript practices. - -```bash -# Ensure standards are in place -/tech-stack:add-typescript-best-practices - -# Implement a feature -> claude "create a user authentication service with JWT tokens" -``` - -**Claude's Implementation Will Follow**: - -- Use interfaces for user and token types -- Use enums for authentication states -- Apply type guards for token validation -- Use established libraries (e.g., jsonwebtoken) -- Apply destructuring patterns - -**Example Generated Code**: - -```typescript -// Interfaces over types (from guidelines) -interface User { - id: string; - email: string; - role: UserRole; -} - -// Enum for constants (from guidelines) -enum UserRole { - Admin = 'ADMIN', - User = 'USER', - Guest = 'GUEST' -} - -// Type guards instead of assertions (from guidelines) -function isValidUser(data: unknown): data is User { - return ( - typeof data === 'object' && - data !== null && - 'id' in data && - 'email' in data - ); -} - -// Destructuring (from guidelines) -async function authenticateUser(credentials: Credentials): Promise { - const { email, password } = credentials; - const { data: user } = await userRepository.findByEmail(email); - // ... -} -``` - -### Quality Assurance Workflow - -**Scenario**: After implementing a feature, verify it follows the established standards. - -```bash -# Setup standards first -/tech-stack:add-typescript-best-practices - -# Implement feature -> claude "create a payment processing module" - -# Reflect on the implementation -/reflexion:reflect "verify TypeScript best practices are followed" -``` - -**Reflection Output Example**: -``` -Reflection Analysis: -- All interfaces properly defined for PaymentRequest, PaymentResponse -- Enum used for PaymentStatus (PENDING, COMPLETED, FAILED) -- Type guards implemented for external API responses -- Destructuring applied consistently - -Improvements Suggested: -- Consider using date-fns for date formatting (library-first principle) -- Add explicit return types to all functions -``` - -```bash -# Apply improvements -> claude "apply the suggested improvements from reflection" - -# Save insights for future reference -/reflexion:memorize -``` - -### Gradual Standards Adoption - -**Scenario**: Introducing TypeScript best practices incrementally to a large codebase. - -```bash -# Start with basic standards -/tech-stack:add-typescript-best-practices - -# Review a specific module against new standards -/reflexion:critique src/users/*.ts - -# Address findings in that module -> claude "refactor the users module to follow TypeScript best practices" - -# Move to next module -/reflexion:critique src/payments/*.ts -``` - -**Benefits of Gradual Adoption**: - -1. Avoid massive refactoring PRs -2. Learn patterns as you apply them -3. Team can adapt to new standards progressively -4. Easier to track and review changes - -## Integration with Other Plugins - -### With SDD (Full Project Setup) - -```bash -# Complete project initialization -/sdd:00-setup TypeScript microservice with NestJS - -# Add language standards -/tech-stack:add-typescript-best-practices - -# Add formatting standards -/ddd:setup-code-formating - -# Start feature development -/sdd:01-research "user authentication feature" -``` - -### With Reflexion (Quality Loop) - -```bash -# Establish standards -/tech-stack:add-typescript-best-practices - -# Implement feature -> claude "create REST API for product catalog" - -# Review against standards -/reflexion:critique - -# Memorize project-specific patterns -/reflexion:memorize --section="TypeScript Patterns" -``` - -### With Code Review - -```bash -# Standards in place -/tech-stack:add-typescript-best-practices - -# Make changes -> claude "add pagination to product listing endpoint" - -# Review against CLAUDE.md standards -/code-review:review-local-changes - -# Standards violations will be flagged in review -``` - -### With MCP Tools - -```bash -# Setup TypeScript standards -/tech-stack:add-typescript-best-practices - -# Add documentation retrieval -/mcp:setup-context7-mcp - -# Now when implementing features, Claude can: -# - Follow your TypeScript standards (from CLAUDE.md) -# - Look up library documentation (from Context7) -> claude "implement form validation using zod" -``` - -## Common Patterns - -### Before Starting Any TypeScript Project - -```bash -claude /init -/sdd:00-setup [your tech stack description] -/tech-stack:add-typescript-best-practices -/ddd:setup-code-formating -``` - -### Before Major Feature Implementation - -```bash -# Ensure standards are current -cat CLAUDE.md | grep "Code Style" - -# If missing, add them -/tech-stack:add-typescript-best-practices -``` - -### During Code Review Preparation - -```bash -# Self-review against standards -/reflexion:reflect "check TypeScript best practices compliance" - -# Fix any issues before submitting PR -> claude "address the TypeScript issues identified" -``` - -### When Onboarding New Team Member - -Share with new team members: - -1. Pull the repository (includes CLAUDE.md) -2. Review CLAUDE.md for coding standards -3. Standards automatically apply to their Claude sessions - -## Troubleshooting - -### Standards Not Being Followed - -If Claude isn't following the established standards: - -1. Verify CLAUDE.md exists and contains the standards -2. Check if CLAUDE.md is in the project root -3. Re-run `/tech-stack:add-typescript-best-practices` if needed -4. Explicitly reference standards: "follow the TypeScript guidelines in CLAUDE.md" - -### Conflicting Guidelines - -If your project has specific requirements that conflict with default guidelines: - -1. Run the command to get the base guidelines -2. Modify CLAUDE.md to reflect your project's actual standards -3. Commit the customized CLAUDE.md - -### Need More Language Support - -Currently, the plugin supports TypeScript. For other languages: - -1. Use the TypeScript command as a template -2. Manually add similar sections for your language to CLAUDE.md -3. Watch for future plugin updates with additional language support diff --git a/docs/reference/agents.md b/docs/reference/agents.md index 20d3e4d..84fa035 100644 --- a/docs/reference/agents.md +++ b/docs/reference/agents.md @@ -6,7 +6,7 @@ Complete alphabetical index of all specialized agents available across Context E ### Code Review -Specialized agents for comprehensive code quality analysis. [More info](../plugins/code-review/README.md). +Specialized agents for comprehensive code quality analysis. [More info](../plugins/review/README.md). - `bug-hunter` - Identifies potential bugs, edge cases, and error-prone patterns. - `code-quality-reviewer` - Evaluates code structure, readability, and maintainability. diff --git a/docs/reference/commands.md b/docs/reference/commands.md index d36cc43..5d9703d 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -15,65 +15,59 @@ Reflection and self-improvement commands based on Self-Refine and Reflexion pape ### Code Review -Comprehensive code review commands using specialized agents. [More info](../plugins/code-review/README.md). +Comprehensive code review commands using specialized agents. [More info](../plugins/review/README.md). -- `/code-review:review-local-changes` - Comprehensive review of local uncommitted changes using specialized agents with code improvement suggestions. -- `/code-review:review-pr` - Comprehensive pull request review using specialized agents. +- `/review-local-changes` - Comprehensive review of local uncommitted changes using specialized agents with code improvement suggestions. +- `/review-pr` - Comprehensive pull request review using specialized agents. ### Git Commands for Git operations including commits, pull requests, and worktree management. [More info](../plugins/git/README.md). -- `/git:commit` - Create well-formatted commits with conventional commit messages and emoji. -- `/git:create-pr` - Create pull requests using GitHub CLI with proper templates and formatting. -- `/git:analyze-issue` - Analyze a GitHub issue and create a detailed technical specification. -- `/git:load-issues` - Load all open issues from GitHub and save them as markdown files. -- `/git:create-worktree` - Create git worktrees for parallel development with automatic dependency installation. -- `/git:compare-worktrees` - Compare files and directories between git worktrees. -- `/git:merge-worktree` - Merge changes from worktrees with selective checkout, cherry-picking, or patch selection. +- `/commit` - Create well-formatted commits with conventional commit messages and emoji. +- `/create-pr` - Create pull requests using GitHub CLI with proper templates and formatting. +- `/analyze-issue` - Analyze a GitHub issue and create a detailed technical specification. +- `/load-issues` - Load all open issues from GitHub and save them as markdown files. ### Spec-Driven Development (SDD) Complete Spec-Driven Development workflow commands. [More info](../plugins/sdd/README.md). -- `/sdd:00-setup` - Create or update the project constitution from interactive or provided principle inputs. -- `/sdd:01-specify` - Create or update the feature specification from a natural language feature description. -- `/sdd:02-plan` - Plan the feature development based on the feature specification. -- `/sdd:03-tasks` - Create detailed implementation tasks from feature plans with complexity analysis. -- `/sdd:04-implement` - Execute feature implementation following task list with TDD approach and quality review. -- `/sdd:05-document` - Document completed feature implementation with API guides, architecture updates, and lessons learned. -- `/sdd:brainstorm` - Refines rough ideas into fully-formed designs through collaborative questioning and exploration. +- `/brainstorm` - Refines rough ideas into fully-formed designs through collaborative questioning and exploration +- `/add-task` - Create task template file with initial prompt +- `/plan-task` - Analyze prompt, generate required skills and refine task specification +- `/implement-task` - Execute feature implementation following task list with TDD approach and quality review ### Kaizen Continuous improvement and problem analysis commands. [More info](../plugins/kaizen/README.md). -- `/kaizen:analyze` - Auto-selects best Kaizen method (Gemba Walk, Value Stream, or Muda) for target analysis. -- `/kaizen:analyze-problem` - Comprehensive A3 one-page problem analysis with root cause and action plan. -- `/kaizen:why` - Iterative Five Whys root cause analysis drilling from symptoms to fundamentals. -- `/kaizen:root-cause-tracing` - Systematically traces bugs backward through call stack to identify source of invalid data or incorrect behavior. -- `/kaizen:cause-and-effect` - Systematic Fishbone analysis exploring problem causes across six categories. -- `/kaizen:plan-do-check-act` - Iterative PDCA cycle for systematic experimentation and continuous improvement. +- `/analyse` - Auto-selects best Kaizen method (Gemba Walk, Value Stream, or Muda) for target analysis. +- `/analyse-problem` - Comprehensive A3 one-page problem analysis with root cause and action plan. +- `/why` - Iterative Five Whys root cause analysis drilling from symptoms to fundamentals. +- `/root-cause-tracing` - Systematically traces bugs backward through call stack to identify source of invalid data or incorrect behavior. +- `/cause-and-effect` - Systematic Fishbone analysis exploring problem causes across six categories. +- `/plan-do-check-act` - Iterative PDCA cycle for systematic experimentation and continuous improvement. ### Customaize Agent Commands for creating and testing custom Claude Code extensions. [More info](../plugins/customaize-agent/README.md). -- `/customaize-agent:create-agent` - Comprehensive guide for creating Claude Code agents with proper structure, triggering conditions, system prompts, and validation -- `/customaize-agent:create-command` - Interactive assistant for creating new Claude commands with proper structure and patterns -- `/customaize-agent:create-workflow-command` - Create workflow commands that orchestrate multi-step execution through sub-agents with file-based task prompts -- `/customaize-agent:create-skill` - Guide for creating effective skills with test-driven approach -- `/customaize-agent:create-hook` - Create and configure git hooks with intelligent project analysis and automated testing -- `/customaize-agent:test-skill` - Verify skills work under pressure and resist rationalization using RED-GREEN-REFACTOR cycle -- `/customaize-agent:test-prompt` - Test any prompt (commands, hooks, skills, subagent instructions) using RED-GREEN-REFACTOR cycle with subagents -- `/customaize-agent:apply-anthropic-skill-best-practices` - Comprehensive guide for skill development based on Anthropic's official best practices +- `/create-agent` - Comprehensive guide for creating Claude Code agents with proper structure, triggering conditions, system prompts, and validation +- `/create-command` - Interactive assistant for creating new Claude commands with proper structure and patterns +- `/create-workflow-command` - Create workflow commands that orchestrate multi-step execution through sub-agents with file-based task prompts +- `/create-skill` - Guide for creating effective skills with test-driven approach +- `/create-hook` - Create and configure git hooks with intelligent project analysis and automated testing +- `/test-skill` - Verify skills work under pressure and resist rationalization using RED-GREEN-REFACTOR cycle +- `/test-prompt` - Test any prompt (commands, hooks, skills, subagent instructions) using RED-GREEN-REFACTOR cycle with subagents +- `/apply-anthropic-skill-best-practices` - Comprehensive guide for skill development based on Anthropic's official best practices ### Test-Driven Development (TDD) Test-first development methodology with agent-orchestrated coverage. [More info](../plugins/tdd/README.md). -- `/tdd:write-tests` - Systematically add test coverage for local code changes using specialized review and development agents -- `/tdd:fix-tests` - Fix failing tests after business logic changes or refactoring using orchestrated agents +- `/write-tests` - Systematically add test coverage for local code changes using specialized review and development agents +- `/fix-tests` - Fix failing tests after business logic changes or refactoring using orchestrated agents ### Subagent-Driven Development (SADD) @@ -81,43 +75,35 @@ Execution framework for parallel/sequential task dispatch, competitive generatio #### Execution Commands -- `/sadd:launch-sub-agent` - Launch focused sub-agents with intelligent model selection, Zero-shot CoT reasoning, and self-critique verification -- `/sadd:do-and-judge` - Execute a single task with implementation sub-agent, independent judge verification, and automatic retry loop until passing -- `/sadd:do-in-parallel` - Execute the same task across multiple independent targets in parallel with context isolation -- `/sadd:do-in-steps` - Execute complex tasks through sequential sub-agent orchestration with automatic decomposition and context passing -- `/sadd:do-competitively` - Execute tasks through competitive generation, multi-judge evaluation, and evidence-based synthesis to produce superior results -- `/sadd:tree-of-thoughts` - Execute complex reasoning through systematic exploration of solution space, pruning unpromising branches, and synthesizing the best solution +- `/launch-sub-agent` - Launch focused sub-agents with intelligent model selection, Zero-shot CoT reasoning, and self-critique verification +- `/do-and-judge` - Execute a single task with implementation sub-agent, independent judge verification, and automatic retry loop until passing +- `/do-in-parallel` - Execute the same task across multiple independent targets in parallel with context isolation +- `/do-in-steps` - Execute complex tasks through sequential sub-agent orchestration with automatic decomposition and context passing +- `/do-competitively` - Execute tasks through competitive generation, multi-judge evaluation, and evidence-based synthesis to produce superior results +- `/tree-of-thoughts` - Execute complex reasoning through systematic exploration of solution space, pruning unpromising branches, and synthesizing the best solution #### Evaluation Commands -- `/sadd:judge-with-debate` - Evaluate solutions through iterative multi-judge debate with consensus building or disagreement reporting -- `/sadd:judge` - Evaluate completed work using LLM-as-Judge with structured rubrics and evidence-based scoring +- `/judge-with-debate` - Evaluate solutions through iterative multi-judge debate with consensus building or disagreement reporting +- `/judge` - Evaluate completed work using LLM-as-Judge with structured rubrics and evidence-based scoring ### Docs Documentation management commands. [More info](../plugins/docs/README.md). -- `/docs:update-docs` - Update implementation documentation after completing development phases +- `/update-docs` - Update implementation documentation after completing development phases +- `/write-concisely` - Apply *The Elements of Style* principles to make documentation clearer and more professional -### Domain-Driven Development (DDD) -Commands for setting up domain-driven development practices. [More info](../plugins/ddd/README.md). -- `/ddd:setup-code-formating` - Sets up code formatting rules and style guidelines in CLAUDE.md - -### Tech Stack - -Commands for language and framework-specific best practices. [More info](../plugins/tech-stack/README.md). - -- `/tech-stack:add-typescript-best-practices` - Setup TypeScript best practices and code style rules in CLAUDE.md ### MCP Commands for integrating Model Context Protocol servers. [More info](../plugins/mcp/README.md). -- `/mcp:setup-context7-mcp` - Guide for setting up the Context7 MCP server to load documentation for specific technologies. -- `/mcp:setup-serena-mcp` - Guide for setting up the Serena MCP server for semantic code retrieval and editing capabilities. -- `/mcp:build-mcp` - Guide for creating high-quality MCP servers that enable LLMs to interact with external services. +- `/setup-context7-mcp` - Guide for setting up the Context7 MCP server to load documentation for specific technologies. +- `/setup-serena-mcp` - Guide for setting up the Serena MCP server for semantic code retrieval and editing capabilities. +- `/build-mcp` - Guide for creating high-quality MCP servers that enable LLMs to interact with external services. ### First Principles Framework (FPF) @@ -125,12 +111,12 @@ Structured reasoning with ADI (Abduction-Deduction-Induction) cycle for auditabl #### Workflow Command -- `/fpf:propose-hypotheses` - Execute complete FPF reasoning cycle from hypothesis generation to decision. Orchestrates the full ADI cycle: initialize context, generate hypotheses, verify logic, validate evidence, audit trust, and produce a Design Rationale Record (DRR). +- `/propose-hypotheses` - Execute complete FPF reasoning cycle from hypothesis generation to decision. Orchestrates the full ADI cycle: initialize context, generate hypotheses, verify logic, validate evidence, audit trust, and produce a Design Rationale Record (DRR). #### Utility Commands -- `/fpf:status` - Show current FPF phase and hypothesis counts across knowledge layers (L0/L1/L2). -- `/fpf:query` - Search the FPF knowledge base and display hypothesis details with assurance information. -- `/fpf:decay` - Manage evidence freshness: refresh stale evidence, deprecate obsolete decisions, or waive with documented rationale. -- `/fpf:actualize` - Reconcile the FPF knowledge base with codebase changes, detecting context drift and stale evidence. -- `/fpf:reset` - Archive current session and reset the FPF cycle for a fresh start. +- `/status` - Show current FPF phase and hypothesis counts across knowledge layers (L0/L1/L2). +- `/query` - Search the FPF knowledge base and display hypothesis details with assurance information. +- `/decay` - Manage evidence freshness: refresh stale evidence, deprecate obsolete decisions, or waive with documented rationale. +- `/actualize` - Reconcile the FPF knowledge base with codebase changes, detecting context drift and stale evidence. +- `/reset` - Archive current session and reset the FPF cycle for a fresh start. diff --git a/docs/resources/papers.md b/docs/resources/papers.md index 918c99a..f81719b 100644 --- a/docs/resources/papers.md +++ b/docs/resources/papers.md @@ -354,11 +354,11 @@ Key components: - Plug-and-play module enables practical self-evolution during test-time inference **Relevance to CEK**: -Directly informs the `/sadd:judge` command's approach to work evaluation. The rubric-based verification and iterative feedback refinement patterns align with the command's structured evaluation rubrics and self-verification loops. +Directly informs the `/judge` command's approach to work evaluation. The rubric-based verification and iterative feedback refinement patterns align with the command's structured evaluation rubrics and self-verification loops. **Used By Plugins**: -- SADD (`/sadd:judge` - rubric-guided evaluation with iterative improvement) +- SADD (`/judge` - rubric-guided evaluation with iterative improvement) **Technical Notes**: @@ -391,12 +391,12 @@ Key components: - Enables continuous improvement of judge prompts and configurations **Relevance to CEK**: -Informs the design of multi-layer evaluation systems where judges are themselves evaluated. Supports the `/sadd:judge-with-debate` command's approach to reaching consensus through multiple judge perspectives. +Informs the design of multi-layer evaluation systems where judges are themselves evaluated. Supports the `/judge-with-debate` command's approach to reaching consensus through multiple judge perspectives. **Used By Plugins**: -- SADD (`/sadd:judge-with-debate` - multi-judge consensus with meta-evaluation) -- SADD (`/sadd:judge` - quality validation of judge outputs) +- SADD (`/judge-with-debate` - multi-judge consensus with meta-evaluation) +- SADD (`/judge` - quality validation of judge outputs) **Technical Notes**: @@ -428,12 +428,12 @@ Key components: - Effective across diverse open-ended tasks including creative writing and code generation **Relevance to CEK**: -Directly informs the rubric-based evaluation patterns in SADD plugin commands. The automatic rubric generation approach enables `/sadd:judge` to create task-specific evaluation criteria dynamically. +Directly informs the rubric-based evaluation patterns in SADD plugin commands. The automatic rubric generation approach enables `/judge` to create task-specific evaluation criteria dynamically. **Used By Plugins**: -- SADD (`/sadd:judge` - dynamic rubric generation for task-specific evaluation) -- SADD (`/sadd:do-and-judge` - rubric-guided verification loops) +- SADD (`/judge` - dynamic rubric generation for task-specific evaluation) +- SADD (`/do-and-judge` - rubric-guided verification loops) **Technical Notes**: @@ -465,12 +465,12 @@ Key components: - Effective rubrics balance comprehensiveness with clarity **Relevance to CEK**: -Provides methodology for designing evaluation rubrics used across SADD plugin commands. Supports the principle-based evaluation approach in `/sadd:judge` and related commands. +Provides methodology for designing evaluation rubrics used across SADD plugin commands. Supports the principle-based evaluation approach in `/judge` and related commands. **Used By Plugins**: -- SADD (`/sadd:judge` - structured rubric design) -- SADD (`/sadd:judge-with-debate` - rubric-based multi-judge evaluation) +- SADD (`/judge` - structured rubric design) +- SADD (`/judge-with-debate` - rubric-based multi-judge evaluation) - Code Review (principle-based evaluation criteria) **Technical Notes**: @@ -576,7 +576,7 @@ Core technique for the SADD meta-judge's checklist generation. The meta-judge pr **Used By Plugins**: -- SADD (`/sadd:judge` - checklist-based evaluation, `/sadd:do-and-judge` - verification checklists) +- SADD (`/judge` - checklist-based evaluation, `/do-and-judge` - verification checklists) **Technical Notes**: @@ -605,7 +605,7 @@ Informs the SADD judge's checklist evaluation approach. The decomposition of rub **Used By Plugins**: -- SADD (`/sadd:judge` - boolean checklist evaluation) +- SADD (`/judge` - boolean checklist evaluation) **Technical Notes**: @@ -634,7 +634,7 @@ Validates the SADD architecture where meta-judge (strong model) generates criter **Used By Plugins**: -- SADD (`/sadd:judge` - checklist-guided grading, meta-judge separation) +- SADD (`/judge` - checklist-guided grading, meta-judge separation) **Technical Notes**: @@ -663,7 +663,7 @@ Complements the SADD judge's approach to evaluation by treating each checklist i **Used By Plugins**: -- SADD (`/sadd:judge` - assertion-style evaluation criteria) +- SADD (`/judge` - assertion-style evaluation criteria) **Technical Notes**: @@ -896,7 +896,7 @@ Supports the SADD judge's approach to adaptive evaluation, where scoring criteri **Used By Plugins**: -- SADD (`/sadd:judge` - adaptive rubric application) +- SADD (`/judge` - adaptive rubric application) **Technical Notes**: @@ -954,8 +954,8 @@ Informs the SADD judge's approach to evaluating complex implementations by asses **Used By Plugins**: -- SADD (`/sadd:judge` - decomposed evaluation) -- SADD (`/sadd:judge-with-debate` - independent judge assessments) +- SADD (`/judge` - decomposed evaluation) +- SADD (`/judge-with-debate` - independent judge assessments) **Technical Notes**: @@ -1272,11 +1272,11 @@ Core principles: - Adopted by universities, publishers, and style guides worldwide **Relevance to CEK**: -Directly informs the `/docs:write-concisely` command. The skill applies Strunk's rules to automatically improve documentation clarity and reduce word count while maintaining meaning. +Directly informs the `/write-concisely` command. The skill applies Strunk's rules to automatically improve documentation clarity and reduce word count while maintaining meaning. **Used By Plugins**: -- Docs (`/docs:write-concisely`, `/docs:update-docs`) +- Docs (`/write-concisely`, `/update-docs`) **Technical Notes**: diff --git a/docs/resources/related-projects.md b/docs/resources/related-projects.md index 9d3690b..caf2f0c 100644 --- a/docs/resources/related-projects.md +++ b/docs/resources/related-projects.md @@ -36,8 +36,8 @@ CEK's FPF plugin implements structured reasoning methodology from: The FPF plugin adapts the quint-code approach into a workflow-based architecture: -- **Workflow command** (`/fpf:propose-hypotheses`) - Orchestrates the complete ADI cycle using sub-agents -- **Utility commands** (`/fpf:status`, `/fpf:query`, `/fpf:decay`, `/fpf:actualize`, `/fpf:reset`) - Manage knowledge base state and maintenance +- **Workflow command** (`/propose-hypotheses`) - Orchestrates the complete ADI cycle using sub-agents +- **Utility commands** (`/status`, `/query`, `/decay`, `/actualize`, `/reset`) - Manage knowledge base state and maintenance --- diff --git a/justfile b/justfile index 9842da6..ab095ce 100644 --- a/justfile +++ b/justfile @@ -1,6 +1,6 @@ # Plugin management commands -plugins := "code-review customaize-agent ddd docs git kaizen mcp reflexion sadd sdd tdd tech-stack fpf" +plugins := "review customaize-agent ddd docs git kaizen mcp reflexion sadd sdd tdd tech-stack fpf" marketplace := ".claude-plugin/marketplace.json" # Show all commands @@ -74,17 +74,33 @@ list-plugins: done -# Get the running devcontainer ID (empty if not running) +[doc("Get the running devcontainer ID (empty if not running)")] _sandbox-id: @docker ps --filter "label=devcontainer.local_folder={{justfile_directory()}}" --format "{{{{.ID}}" | head -n1 -# Start devcontainer and open an interactive shell +[doc(""" + Start devcontainer and open an interactive shell. + + Description: + Starts the development container using devcontainer CLI and attaches to an + interactive zsh shell. First run may take time to build the image. + + Steps: + 1. Runs `devcontainer up` to start the container + 2. Extracts container ID, workspace folder, and user from output + 3. Attaches to the container with docker exec + + Usage: + just sandbox +""")] sandbox: #!/usr/bin/env bash set -euo pipefail echo "Starting devcontainer... First run can take long time to build the image" - output=$(devcontainer up --workspace-folder .) # TODO: print output during the process - echo "$output" + tmpfile=$(mktemp) + devcontainer up --workspace-folder . 2>&1 | tee "$tmpfile" + output=$(cat "$tmpfile") + rm "$tmpfile" container_id=$(echo "$output" | grep -oP '"containerId"\s*:\s*"\K[^"]+') workspace=$(echo "$output" | grep -oP '"remoteWorkspaceFolder"\s*:\s*"\K[^"]+') user=$(echo "$output" | grep -oP '"remoteUser"\s*:\s*"\K[^"]+') @@ -95,7 +111,21 @@ sandbox: echo "Attaching to container $container_id as ${user:-root} at $workspace..." docker exec -it -u "${user:-root}" -w "${workspace:-/}" "$container_id" zsh -# Attach to a running devcontainer +[doc(""" + Attach to a running devcontainer. + + Description: + Connects to an already running devcontainer shell. Requires that + the devcontainer was started with `just sandbox` first. + + Steps: + 1. Gets the container ID using _sandbox-id + 2. Inspects container to find workspace and user + 3. Attaches with docker exec + + Usage: + just attach-sandbox +""")] attach-sandbox: #!/usr/bin/env bash set -euo pipefail @@ -117,7 +147,21 @@ attach-sandbox: echo "Attaching to container $container_id as $user at $workspace..." docker exec -it -u "$user" -w "$workspace" "$container_id" zsh -# Stop and remove the devcontainer +[doc(""" + Stop and remove the devcontainer. + + Description: + Gracefully stops and removes the running development container. + Safe to run even if no container is running. + + Steps: + 1. Gets container ID (if any) + 2. Stops the container with docker stop + 3. Removes the container with docker rm + + Usage: + just stop-sandbox +""")] stop-sandbox: #!/usr/bin/env bash set -euo pipefail @@ -130,6 +174,19 @@ stop-sandbox: docker stop "$container_id" && docker rm "$container_id" echo "Done." +[doc(""" + Tear down the devcontainer docker-compose resources. + + Description: + Runs docker compose down for the devcontainer configuration. + Use this to completely clean up devcontainer networking and volumes. + + Usage: + just down-devcontainer +""")] +down-devcontainer: + docker compose --project-name decision-engine_devcontainer -f .devcontainer/docker-compose.yaml down + # Run claude with a prompt and stream plain text output [no-exit-message] @@ -181,6 +238,3 @@ claude-plan-and-implement task-filename: echo "" echo "==> Implementing: $todo" just claude "/sdd:implement @$todo" - -down-devcontainer: - docker compose --project-name decision-engine_devcontainer -f .devcontainer/docker-compose.yaml down \ No newline at end of file diff --git a/plugins/customaize-agent/.claude-plugin/plugin.json b/plugins/customaize-agent/.claude-plugin/plugin.json index 04bcb95..d192423 100644 --- a/plugins/customaize-agent/.claude-plugin/plugin.json +++ b/plugins/customaize-agent/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "customaize-agent", - "version": "1.4.0", + "version": "3.0.0", "description": "Commands and skills for writing and refining commands, hooks, skills for Claude Code, includes Anthropic Best Practices and Agent Persuasion Principles that can be useful for sub-agent workflows.", "author": { "name": "Vlad Goncharov", diff --git a/plugins/customaize-agent/README.md b/plugins/customaize-agent/README.md index 68af7e8..49d94a6 100644 --- a/plugins/customaize-agent/README.md +++ b/plugins/customaize-agent/README.md @@ -58,9 +58,9 @@ The plugin is built on Anthropic's official skill authoring best practices and r ## Skills -- [customaize-agent:prompt-engineering](./prompt-engineering.md) - Advanced prompt engineering techniques including Anthropic's official best practices and research-backed persuasion principles. -- [customaize-agent:context-engineering](./context-engineering.md) - Use when writing, editing, or optimizing commands, skills, or sub-agent prompts. Provides deep understanding of context mechanics in agent systems. -- [customaize-agent:agent-evaluation](./agent-evaluation.md) - Use when testing prompt effectiveness, validating context engineering choices, or measuring agent improvement quality. +- [prompt-engineering](./prompt-engineering.md) - Advanced prompt engineering techniques including Anthropic's official best practices and research-backed persuasion principles. +- [context-engineering](./context-engineering.md) - Use when writing, editing, or optimizing commands, skills, or sub-agent prompts. Provides deep understanding of context mechanics in agent systems. +- [agent-evaluation](./agent-evaluation.md) - Use when testing prompt effectiveness, validating context engineering choices, or measuring agent improvement quality. ## Theoretical Foundation diff --git a/plugins/customaize-agent/skills/agent-evaluation/SKILL.md b/plugins/customaize-agent/skills/agent-evaluation/SKILL.md index 9c96e3b..30b4007 100644 --- a/plugins/customaize-agent/skills/agent-evaluation/SKILL.md +++ b/plugins/customaize-agent/skills/agent-evaluation/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:agent-evaluation +name: agent-evaluation description: Evaluate and improve Claude Code commands, skills, and agents. Use when testing prompt effectiveness, validating context engineering choices, or measuring improvement quality. --- diff --git a/plugins/customaize-agent/skills/apply-anthropic-skill-best-practices/SKILL.md b/plugins/customaize-agent/skills/apply-anthropic-skill-best-practices/SKILL.md index 69c949d..b481142 100644 --- a/plugins/customaize-agent/skills/apply-anthropic-skill-best-practices/SKILL.md +++ b/plugins/customaize-agent/skills/apply-anthropic-skill-best-practices/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:apply-anthropic-skill-best-practices +name: apply-anthropic-skill-best-practices description: Comprehensive guide for skill development based on Anthropic's official best practices - use for complex skills requiring detailed structure argument-hint: Optional skill name or path to skill being reviewed --- diff --git a/plugins/customaize-agent/skills/context-engineering/SKILL.md b/plugins/customaize-agent/skills/context-engineering/SKILL.md index e6faf9b..4c4b424 100644 --- a/plugins/customaize-agent/skills/context-engineering/SKILL.md +++ b/plugins/customaize-agent/skills/context-engineering/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:context-engineering +name: context-engineering description: Understand the components, mechanics, and constraints of context in agent systems. Use when writing, editing, or optimizing commands, skills, or sub-agents prompts. --- diff --git a/plugins/customaize-agent/skills/create-agent/SKILL.md b/plugins/customaize-agent/skills/create-agent/SKILL.md index d306b65..97eb821 100644 --- a/plugins/customaize-agent/skills/create-agent/SKILL.md +++ b/plugins/customaize-agent/skills/create-agent/SKILL.md @@ -1,7 +1,7 @@ --- -name: customaize-agent:create-agent +name: create-agent description: Comprehensive guide for creating Claude Code agents with proper structure, triggering conditions, system prompts, and validation - combines official Anthropic best practices with proven patterns -argument-hint: [agent-name] [optional description of agent purpose] +argument-hint: "[agent-name] [optional description of agent purpose]" allowed-tools: Read, Write, Glob, Grep, Bash(mkdir:*), Task --- diff --git a/plugins/customaize-agent/skills/create-command/SKILL.md b/plugins/customaize-agent/skills/create-command/SKILL.md index 0878de2..9010274 100644 --- a/plugins/customaize-agent/skills/create-command/SKILL.md +++ b/plugins/customaize-agent/skills/create-command/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:create-command +name: create-command description: Interactive assistant for creating new Claude commands with proper structure, patterns, and MCP tool integration argument-hint: Optional command name or description of command purpose --- diff --git a/plugins/customaize-agent/skills/create-hook/SKILL.md b/plugins/customaize-agent/skills/create-hook/SKILL.md index d721622..db139d9 100644 --- a/plugins/customaize-agent/skills/create-hook/SKILL.md +++ b/plugins/customaize-agent/skills/create-hook/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:create-hook +name: create-hook description: Create and configure git hooks with intelligent project analysis, suggestions, and automated testing argument-hint: Optional hook type or description of desired behavior --- diff --git a/plugins/customaize-agent/skills/create-rule/SKILL.md b/plugins/customaize-agent/skills/create-rule/SKILL.md index f281d46..3d93048 100644 --- a/plugins/customaize-agent/skills/create-rule/SKILL.md +++ b/plugins/customaize-agent/skills/create-rule/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:create-rule +name: create-rule description: Use when found gap or repetative issue, that produced by you or implemenataion agent. Esentially use it each time when you say "You absolutly right, I should have done it differently." -> need create rule for this issue so it not appears again. --- diff --git a/plugins/customaize-agent/skills/create-skill/SKILL.md b/plugins/customaize-agent/skills/create-skill/SKILL.md index c183893..8f79437 100644 --- a/plugins/customaize-agent/skills/create-skill/SKILL.md +++ b/plugins/customaize-agent/skills/create-skill/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:create-skill +name: create-skill description: Guide for creating effective skills. This command should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations. Use when creating new skills, editing existing skills, or verifying skills work before deployment - applies TDD to process documentation by testing with subagents before writing, iterating until bulletproof against rationalization --- @@ -20,7 +20,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel **REQUIRED BACKGROUND:** You MUST understand Test-Driven Development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation. -**Official guidance:** The Anthropic's official skill authoring best practices provided at the `/customaize-agent:apply-anthropic-skill-best-practices` command, they enhance `customize-agent:prompt-engineering` skill. Use skill and the document, as they not copy but add to each other. These document provides additional patterns and guidelines that complement the TDD-focused approach in this skill. +**Official guidance:** The Anthropic's official skill authoring best practices provided at the `/apply-anthropic-skill-best-practices` command, they enhance `prompt-engineering` skill. Use skill and the document, as they not copy but add to each other. These document provides additional patterns and guidelines that complement the TDD-focused approach in this skill. ## About Skills diff --git a/plugins/customaize-agent/skills/create-workflow-command/SKILL.md b/plugins/customaize-agent/skills/create-workflow-command/SKILL.md index cf1ce6e..d611f37 100644 --- a/plugins/customaize-agent/skills/create-workflow-command/SKILL.md +++ b/plugins/customaize-agent/skills/create-workflow-command/SKILL.md @@ -1,7 +1,7 @@ --- -name: customaize-agent:create-workflow-command +name: create-workflow-command description: Create a workflow command that orchestrates multi-step execution through sub-agents with file-based task prompts -argument-hint: [workflow-name] [description] +argument-hint: "[workflow-name] [description]" allowed-tools: Read, Write, Glob, Grep, Bash(mkdir:*) --- diff --git a/plugins/customaize-agent/skills/prompt-engineering/SKILL.md b/plugins/customaize-agent/skills/prompt-engineering/SKILL.md index 03ef45e..dc3b1b7 100644 --- a/plugins/customaize-agent/skills/prompt-engineering/SKILL.md +++ b/plugins/customaize-agent/skills/prompt-engineering/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:prompt-engineering +name: prompt-engineering description: Use this skill when you writing commands, hooks, skills for Agent, or prompts for sub agents or any other LLM interaction, including optimizing prompts, improving LLM outputs, or designing production prompt templates. --- diff --git a/plugins/customaize-agent/skills/test-prompt/SKILL.md b/plugins/customaize-agent/skills/test-prompt/SKILL.md index 0f9598b..5751942 100644 --- a/plugins/customaize-agent/skills/test-prompt/SKILL.md +++ b/plugins/customaize-agent/skills/test-prompt/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:test-prompt +name: test-prompt description: Use when creating or editing any prompt (commands, hooks, skills, subagent instructions) to verify it produces desired behavior - applies RED-GREEN-REFACTOR cycle to prompt engineering using subagents for isolated testing --- diff --git a/plugins/customaize-agent/skills/test-skill/SKILL.md b/plugins/customaize-agent/skills/test-skill/SKILL.md index 59f6d9f..13147fb 100644 --- a/plugins/customaize-agent/skills/test-skill/SKILL.md +++ b/plugins/customaize-agent/skills/test-skill/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:test-skill +name: test-skill description: Use when creating or editing skills, before deployment, to verify they work under pressure and resist rationalization - applies RED-GREEN-REFACTOR cycle to process documentation by running baseline without skill, writing to address failures, iterating to close loopholes --- diff --git a/plugins/customaize-agent/skills/thought-based-reasoning/SKILL.md b/plugins/customaize-agent/skills/thought-based-reasoning/SKILL.md index 7cb4dc1..12488fe 100644 --- a/plugins/customaize-agent/skills/thought-based-reasoning/SKILL.md +++ b/plugins/customaize-agent/skills/thought-based-reasoning/SKILL.md @@ -1,5 +1,5 @@ --- -name: customaize-agent:thought-based-reasoning +name: thought-based-reasoning description: Use when tackling complex reasoning tasks requiring step-by-step logic, multi-step arithmetic, commonsense reasoning, symbolic manipulation, or problems where simple prompting fails - provides comprehensive guide to Chain-of-Thought and related prompting techniques (Zero-shot CoT, Self-Consistency, Tree of Thoughts, Least-to-Most, ReAct, PAL, Reflexion) with templates, decision matrices, and research-backed patterns --- diff --git a/plugins/ddd/.claude-plugin/plugin.json b/plugins/ddd/.claude-plugin/plugin.json index 5e14f07..ebc6c20 100644 --- a/plugins/ddd/.claude-plugin/plugin.json +++ b/plugins/ddd/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "ddd", - "version": "2.0.0", + "version": "3.0.0", "description": "Introduces command to update CLAUDE.md with best practices for domain-driven development, focused on quality of code, includes Clean Architecture, SOLID principles, and other design patterns.", "author": { "name": "Vlad Goncharov", diff --git a/plugins/ddd/README.md b/plugins/ddd/README.md index 6ed2c22..4b9d124 100644 --- a/plugins/ddd/README.md +++ b/plugins/ddd/README.md @@ -11,7 +11,7 @@ Focused on: ## Overview -The DDD plugin implements battle-tested software architecture principles that have proven essential for building maintainable, scalable systems. It provides commands to configure AI-assisted development with established best practices, and rules that guide code generation toward high-quality patterns. +The DDD plugin implements battle-tested software architecture principles that have proven essential for building maintainable, scalable systems. All principles encoded as rules that include correct and incorrect code examples and added to agent context, during code writing. To add rules to your agent, simply enable plugin The plugin is based on foundational works including Eric Evans' "Domain-Driven Design" (2003), Robert C. Martin's "Clean Architecture" (2017), and the SOLID principles that have become industry standards for object-oriented design. @@ -23,9 +23,6 @@ These principles address the core challenge of software development: **managing # Install the plugin /plugin install ddd@NeoLabHQ/context-engineering-kit -# Set up code formatting standards in CLAUDE.md -/ddd:setup-code-formating - # Rules activate automatically when writing or reviewing code # Alternatively, you can ask Claude to use DDD directly > claude "Use DDD rules to implement user authentication" @@ -33,12 +30,6 @@ These principles address the core challenge of software development: **managing [Usage Examples](./usage-examples.md) -## setup-code-formating command - -Establishes consistent code formatting rules and style guidelines by updating your project's CLAUDE.md file with enforced standards. - -See [setup-code-formating.md](./setup-code-formating.md) for detailed command documentation. - ## Rules The DDD plugin includes 14 rules organized into four categories that activate automatically when writing or reviewing code. Each rule targets specific file patterns and has an assigned impact level. diff --git a/plugins/ddd/skills/setup-code-formating/SKILL.md b/plugins/ddd/skills/setup-code-formating/SKILL.md deleted file mode 100644 index f52ef68..0000000 --- a/plugins/ddd/skills/setup-code-formating/SKILL.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: ddd:setup-code-formating -description: Sets up code formatting rules and style guidelines in CLAUDE.md -argument-hint: None required - creates standard formatting configuration ---- - -# Setup Architecture Memory - -Create or update CLAUDE.md in with following content, write it strictly as it is, do not summaraise or introduce and new additional information: - -```markdown -## Code Style Rules - -### Code Formatting - -- No semicolons (enforced) -- Single quotes (enforced) -- No unnecessary curly braces (enforced) -- 2-space indentation -- Import order: external → internal → types -``` diff --git a/plugins/docs/.claude-plugin/plugin.json b/plugins/docs/.claude-plugin/plugin.json index 050fdb8..c615ffa 100644 --- a/plugins/docs/.claude-plugin/plugin.json +++ b/plugins/docs/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "docs", - "version": "1.2.0", + "version": "3.0.0", "description": "Commands for analysing project, writing and refining documentation.", "author": { "name": "Vlad Goncharov", diff --git a/plugins/docs/README.md b/plugins/docs/README.md index aa26496..263a6d7 100644 --- a/plugins/docs/README.md +++ b/plugins/docs/README.md @@ -35,13 +35,13 @@ The plugin guides you through: # Update project documentation after implementing features > claude "implement user profile settings page" -> /docs:update-docs +> /update-docs # Focus on specific documentation type -> /docs:update-docs api +> /update-docs api # Target specific directory -> /docs:update-docs src/payments/ +> /update-docs src/payments/ ``` [Usage Examples](./usage-examples.md) diff --git a/plugins/docs/skills/update-docs/SKILL.md b/plugins/docs/skills/update-docs/SKILL.md index 6571be7..6f12ac4 100644 --- a/plugins/docs/skills/update-docs/SKILL.md +++ b/plugins/docs/skills/update-docs/SKILL.md @@ -1,5 +1,5 @@ --- -name: docs:update-docs +name: update-docs description: Update and maintain project documentation for local code changes using multi-agent workflow with tech-writer agents. Covers docs/, READMEs, JSDoc, and API documentation. argument-hint: Optional target directory, documentation type (api, guides, readme, jsdoc), or specific focus area --- diff --git a/plugins/docs/skills/write-concisely/SKILL.md b/plugins/docs/skills/write-concisely/SKILL.md index 6b3e79f..f20e2da 100644 --- a/plugins/docs/skills/write-concisely/SKILL.md +++ b/plugins/docs/skills/write-concisely/SKILL.md @@ -1,5 +1,5 @@ --- -name: docs:write-concisely +name: write-concisely description: Apply writing rules to any documentation that humans will read. Makes your writing clearer, stronger, and more professional. --- diff --git a/plugins/fpf/.claude-plugin/plugin.json b/plugins/fpf/.claude-plugin/plugin.json index 0f847c4..6eb666e 100644 --- a/plugins/fpf/.claude-plugin/plugin.json +++ b/plugins/fpf/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fpf", - "version": "1.1.1", + "version": "3.0.0", "description": "First Principles Framework (FPF) for structured reasoning using workflow command pattern. Implements ADI (Abduction-Deduction-Induction) cycle via propose-hypotheses workflow with fpf-agent for hypothesis generation, logical verification, empirical validation, and auditable decision-making. Includes utility commands for status, query, decay, actualize, and reset.", "author": { "name": "Vlad Goncharov", diff --git a/plugins/fpf/README.md b/plugins/fpf/README.md index c617950..d8c1978 100644 --- a/plugins/fpf/README.md +++ b/plugins/fpf/README.md @@ -41,7 +41,7 @@ Implementation based on [quint-code](https://github.com/m0n0x41d/quint-code) by /plugin install fpf@NeoLabHQ/context-engineering-kit # Start a decision process -/fpf:propose-hypotheses What caching strategy should we use? +/propose-hypotheses What caching strategy should we use? # Commad will perform majority of orcestration and launch subagents to perform the work. # Additionaly you will be asked to add your own hypotheses and review the results. @@ -52,7 +52,7 @@ Implementation based on [quint-code](https://github.com/m0n0x41d/quint-code) by ``` ┌─────────────────────────────────────────────────────────────────┐ │ 1. Initialize Context │ -│ /fpf:propose-hypotheses │ +│ /propose-hypotheses │ │ (create .fpf/ directory structure) │ └────────────────────────┬────────────────────────────────────────┘ │ @@ -108,7 +108,7 @@ Implementation based on [quint-code](https://github.com/m0n0x41d/quint-code) by ## Commands Overview -### /fpf:propose-hypotheses - Decision Cycle +### /propose-hypotheses - Decision Cycle Execute the complete FPF cycle from hypothesis generation through evidence validation to decision. @@ -116,7 +116,7 @@ Execute the complete FPF cycle from hypothesis generation through evidence valid - Output - `.fpf/decisions/DRR--.md` with winner and rationale ```bash -/fpf:propose-hypotheses [problem or decision to make] +/propose-hypotheses [problem or decision to make] ``` #### Arguments @@ -182,16 +182,16 @@ The workflow follows three inference modes: ```bash # Caching strategy decision -/fpf:propose-hypotheses What caching strategy should we use? +/propose-hypotheses What caching strategy should we use? # Deployment approach -/fpf:propose-hypotheses How should we deploy our application? +/propose-hypotheses How should we deploy our application? # Architecture decision -/fpf:propose-hypotheses Should we use microservices or monolith? +/propose-hypotheses Should we use microservices or monolith? # Technology selection -/fpf:propose-hypotheses Which database should we use for high-write workloads? +/propose-hypotheses Which database should we use for high-write workloads? ``` #### When to Use @@ -218,7 +218,7 @@ Time-critical situations where the overhead isn't justified --- -### /fpf:status - Check Progress +### /status - Check Progress Show current FPF phase, hypothesis counts, and any warnings about stale evidence. @@ -226,7 +226,7 @@ Show current FPF phase, hypothesis counts, and any warnings about stale evidence - Output - Status table with phase, counts, and warnings ```bash -/fpf:status +/status ``` #### Arguments @@ -247,7 +247,7 @@ None required. ```bash # Check current status -/fpf:status +/status ``` **Example Output:** @@ -286,7 +286,7 @@ All systems nominal. --- -### /fpf:query - Search Knowledge Base +### /query - Search Knowledge Base Search the FPF knowledge base for hypotheses, evidence, or decisions with assurance information. @@ -294,7 +294,7 @@ Search the FPF knowledge base for hypotheses, evidence, or decisions with assura - Output - Search results with layer, R_eff, and evidence counts ```bash -/fpf:query [keyword or hypothesis name] +/query [keyword or hypothesis name] ``` #### Arguments @@ -313,13 +313,13 @@ Keyword to search for, specific hypothesis name, or "DRR" to list decisions. ```bash # Search by keyword -/fpf:query caching +/query caching # Query specific hypothesis -/fpf:query redis-caching +/query redis-caching # List all decisions -/fpf:query DRR +/query DRR ``` **Example Output (keyword search):** @@ -363,21 +363,21 @@ Evidence: 2 files --- -### /fpf:decay - Manage Evidence Freshness +### /decay - Manage Evidence Freshness Check for stale evidence and choose how to handle it: refresh, deprecate, or waive. - Purpose - Maintain evidence validity over time - Output - Updated evidence status and trust scores -Evidence expires. A benchmark from six months ago might not reflect current performance. `/fpf:decay` shows you what's stale and gives you three options: +Evidence expires. A benchmark from six months ago might not reflect current performance. `/decay` shows you what's stale and gives you three options: - Refresh — Re-run tests to get fresh evidence - Deprecate — Downgrade the hypothesis if the decision needs rethinking - Waive — Accept the risk temporarily with documented rationale ```bash -/fpf:decay waive the benchmark until February, we'll re-test after launch +/decay waive the benchmark until February, we'll re-test after launch ``` #### Arguments @@ -399,7 +399,7 @@ None required. Command is interactive. ```bash # Check for stale evidence -/fpf:decay +/decay # Natural language waiver # User: Waive the benchmark until February, we'll re-run after migration. @@ -419,7 +419,7 @@ None required. Command is interactive. --- -### /fpf:actualize - Reconcile with Codebase +### /actualize - Reconcile with Codebase Update the knowledge base to reflect codebase changes that may affect existing hypotheses. @@ -433,7 +433,7 @@ This command serves as the Observe phase of the FPF's Canonical Evolution Loop ( - Flagging Outdated Decisions: Identifies decisions whose underlying evidence chain has been impacted by recent code changes. ```bash -/fpf:actualize +/actualize ``` #### How It Works @@ -447,10 +447,10 @@ This command serves as the Observe phase of the FPF's Canonical Evolution Loop ( ```bash # After major refactoring -/fpf:actualize +/actualize # After dependency updates -/fpf:actualize +/actualize ``` #### Best practices @@ -461,7 +461,7 @@ This command serves as the Observe phase of the FPF's Canonical Evolution Loop ( --- -### /fpf:reset - Start Fresh +### /reset - Start Fresh Archive the current session and return to IDLE state for a new reasoning cycle. @@ -469,7 +469,7 @@ Archive the current session and return to IDLE state for a new reasoning cycle. - Output - Archived session in `.fpf/sessions/` ```bash -/fpf:reset +/reset ``` #### Arguments @@ -490,7 +490,7 @@ None required. Command is interactive. #### Usage Examples ```bash -/fpf:reset +/reset # Agent: What type of reset would you like? # 1. Soft Reset - Archive current session, start fresh diff --git a/plugins/fpf/skills/actualize/SKILL.md b/plugins/fpf/skills/actualize/SKILL.md index 19dc2aa..a663e28 100644 --- a/plugins/fpf/skills/actualize/SKILL.md +++ b/plugins/fpf/skills/actualize/SKILL.md @@ -1,5 +1,5 @@ --- -name: fpf:actualize +name: actualize description: "Reconcile the project's FPF state with recent repository changes" --- diff --git a/plugins/fpf/skills/decay/SKILL.md b/plugins/fpf/skills/decay/SKILL.md index 74e15f3..3b1e94e 100644 --- a/plugins/fpf/skills/decay/SKILL.md +++ b/plugins/fpf/skills/decay/SKILL.md @@ -1,5 +1,5 @@ --- -name: fpf:decay +name: decay description: "Manage evidence freshness by identifying stale decisions and providing governance actions" --- diff --git a/plugins/fpf/skills/propose-hypotheses/SKILL.md b/plugins/fpf/skills/propose-hypotheses/SKILL.md index d5492f1..563c5b7 100644 --- a/plugins/fpf/skills/propose-hypotheses/SKILL.md +++ b/plugins/fpf/skills/propose-hypotheses/SKILL.md @@ -1,5 +1,5 @@ --- -name: fpf:propose-hypotheses +name: propose-hypotheses description: Execute complete FPF cycle from hypothesis generation to decision argument-hint: "[problem-statement]" allowed-tools: Task, Read, Write, Bash, AskUserQuestion diff --git a/plugins/fpf/skills/query/SKILL.md b/plugins/fpf/skills/query/SKILL.md index 952b5ca..c02f644 100644 --- a/plugins/fpf/skills/query/SKILL.md +++ b/plugins/fpf/skills/query/SKILL.md @@ -1,5 +1,5 @@ --- -name: fpf:query +name: query description: "Search the FPF knowledge base and display hypothesis details with assurance information" --- diff --git a/plugins/fpf/skills/reset/SKILL.md b/plugins/fpf/skills/reset/SKILL.md index bd9e9df..45720d7 100644 --- a/plugins/fpf/skills/reset/SKILL.md +++ b/plugins/fpf/skills/reset/SKILL.md @@ -1,5 +1,5 @@ --- -name: fpf:reset +name: reset description: "Reset the FPF reasoning cycle to start fresh" --- diff --git a/plugins/fpf/skills/status/SKILL.md b/plugins/fpf/skills/status/SKILL.md index 200e39b..d515da9 100644 --- a/plugins/fpf/skills/status/SKILL.md +++ b/plugins/fpf/skills/status/SKILL.md @@ -1,5 +1,5 @@ --- -name: fpf:status +name: status description: "Display the current state of the FPF knowledge base" --- diff --git a/plugins/git/.claude-plugin/plugin.json b/plugins/git/.claude-plugin/plugin.json index f4fd527..b99cc42 100644 --- a/plugins/git/.claude-plugin/plugin.json +++ b/plugins/git/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "git", - "version": "1.2.0", + "version": "3.0.0", "description": "Introduces commands for commit and PRs creation, plus skills for git worktrees and notes.", "author": { "name": "Vlad Goncharov", diff --git a/plugins/git/README.md b/plugins/git/README.md index a0cf862..2427fcc 100644 --- a/plugins/git/README.md +++ b/plugins/git/README.md @@ -22,37 +22,34 @@ Most commands require GitHub CLI (`gh`) for full functionality including creatin /plugin install git@NeoLabHQ/context-engineering-kit # Create a well-formatted commit -> /git:commit +> /commit # Create a pull request -> /git:create-pr +> /create-pr ``` #### Analyze Open GitHub issues ```bash # Load all open issues -> /git:load-issues +> /load-issues # Analyze a GitHub issue -> /git:analyze-issue 123 +> /analyze-issue 123 ``` [Usage Examples](./usage-examples.md) ## Commands -- [/git:commit](./commit.md) - Create well-formatted commits with conventional commit messages and emoji. -- [/git:create-pr](./create-pr.md) - Create pull requests using GitHub CLI with proper templates and formatting. -- [/git:analyze-issue](./analyze-issue.md) - Analyze a GitHub issue and create a detailed technical specification. -- [/git:load-issues](./load-issues.md) - Load all open issues from GitHub and save them as markdown files. -- [/git:attach-review-to-pr](./attach-review-to-pr.md) - Add line-specific review comments to pull requests using GitHub CLI API. -- [/git:create-worktree](./create-worktree.md) - Create and setup git worktrees for parallel development with automatic dependency installation. -- [/git:compare-worktrees](./compare-worktrees.md) - Compare files and directories between git worktrees or worktree and current branch. -- [/git:merge-worktree](./merge-worktree.md) - Merge changes from worktrees into current branch with selective file checkout, cherry-picking, interactive patch selection, or manual merge. +- [/commit](./commit.md) - Create well-formatted commits with conventional commit messages and emoji. +- [/create-pr](./create-pr.md) - Create pull requests using GitHub CLI with proper templates and formatting. +- [/analyze-issue](./analyze-issue.md) - Analyze a GitHub issue and create a detailed technical specification. +- [/load-issues](./load-issues.md) - Load all open issues from GitHub and save them as markdown files. +- [/attach-review-to-pr](./attach-review-to-pr.md) - Add line-specific review comments to pull requests using GitHub CLI API. +- [/worktrees](./git-worktrees.md) - Create, compare, and merge git worktrees for parallel development with automatic dependency installation ## Skills -- [worktrees](./worktrees.md) - Skill for Parallel Branch Development in same file system using git worktrees. -- [notes](./notes.md) - Skill about using git notes to add metadata to commits without changing history. +- [notes](./git-notes.md) - Skill about using git notes to add metadata to commits without changing history. diff --git a/plugins/git/skills/analyze-issue/SKILL.md b/plugins/git/skills/analyze-issue/SKILL.md index 706a392..6c3beec 100644 --- a/plugins/git/skills/analyze-issue/SKILL.md +++ b/plugins/git/skills/analyze-issue/SKILL.md @@ -1,5 +1,5 @@ --- -name: git:analyze-issue +name: analyze-issue description: Analyze a GitHub issue and create a detailed technical specification argument-hint: Issue number (e.g., 42) allowed-tools: Bash(gh issue:*), Read, Write, Glob, Grep diff --git a/plugins/git/skills/attach-review-to-pr/SKILL.md b/plugins/git/skills/attach-review-to-pr/SKILL.md index eefc49c..9c8bb58 100644 --- a/plugins/git/skills/attach-review-to-pr/SKILL.md +++ b/plugins/git/skills/attach-review-to-pr/SKILL.md @@ -1,5 +1,5 @@ --- -name: git:attach-review-to-pr +name: attach-review-to-pr description: Add line-specific review comments to pull requests using GitHub CLI API argument-hint: PR number or URL (optional - can work with current branch) allowed-tools: Bash(gh api:*), Bash(gh auth:*), Bash(gh pr:*), mcp__github_inline_comment__create_inline_comment diff --git a/plugins/git/skills/commit/SKILL.md b/plugins/git/skills/commit/SKILL.md index 94b9b87..531b6e9 100644 --- a/plugins/git/skills/commit/SKILL.md +++ b/plugins/git/skills/commit/SKILL.md @@ -1,5 +1,5 @@ --- -name: git:commit +name: commit description: Create well-formatted commits with conventional commit messages and emoji argument-hint: Optional flags like --no-verify to skip pre-commit checks model: haiku diff --git a/plugins/git/skills/compare-worktrees/SKILL.md b/plugins/git/skills/compare-worktrees/SKILL.md deleted file mode 100644 index ab9b446..0000000 --- a/plugins/git/skills/compare-worktrees/SKILL.md +++ /dev/null @@ -1,285 +0,0 @@ ---- -name: git:compare-worktrees -description: Compare files and directories between git worktrees or worktree and current branch -argument-hint: Path(s) to compare, worktree paths, branch names, or --stat for summary -model: opus -allowed-tools: Bash(git worktree:*), Bash(git diff:*), Bash(git branch:*), Bash(git status:*), Bash(diff:*), Bash(ls:*), Bash(pwd:*), Bash(find:*) ---- - -# Claude Command: Compare Worktrees - -Your job is to compare files and directories between git worktrees, helping users understand differences in code across branches or worktrees. - -## Instructions - -CRITICAL: Perform the following steps exactly as described: - -1. **Current state check**: Run `git worktree list` to show all existing worktrees and their locations - -2. **Parse user input**: Classify each provided argument: - - **No arguments**: Interactive mode - ask user what to compare - - **`--stat`**: Show summary statistics of differences (files changed, insertions, deletions) - - **Worktree path**: A path that matches one of the worktree roots from `git worktree list` - - **Branch name**: A name that matches a branch in one of the worktrees - - **File/directory path**: A path within the current worktree to compare - -3. **Determine comparison targets** (worktrees to compare): - a. If user provided worktree paths: Use those as comparison targets - b. If user specified branch names: Find the worktrees for those branches from `git worktree list` - c. If only one worktree exists besides current: Use current and that one as comparison targets - d. If multiple worktrees exist and none specified: Present list and ask user which to compare - e. If no other worktrees exist: Offer to compare with a branch using `git diff` - -4. **Determine what to compare** (files/directories within worktrees): - a. If user specified file(s) or directory(ies) paths: Compare ALL of them - b. If no specific paths given: Ask user: - - "Compare entire worktree?" or - - "Compare specific files/directories? (enter paths)" - -5. **Execute comparison**: - - **For specific files between worktrees:** - - ```bash - diff / / - # Or for unified diff format: - diff -u / / - ``` - - **For directories between worktrees:** - - ```bash - diff -r / / - # Or for summary only: - diff -rq / / - ``` - - **For branch-level comparison (using git diff):** - - ```bash - git diff .. -- - # Or for stat summary: - git diff --stat .. - ``` - - **For comparing with current working directory:** - - ```bash - diff / - ``` - -6. **Format and present results**: - - Show clear header indicating what's being compared - - For large diffs, offer to show summary first - - Highlight significant changes (new files, deleted files, renamed files) - - Provide context about the branches each worktree contains - -## Comparison Modes - -| Mode | Description | Command Pattern | -|------|-------------|-----------------| -| **File diff** | Compare single file between worktrees | `diff -u /file /file` | -| **Directory diff** | Compare directories recursively | `diff -r /dir /dir` | -| **Summary only** | Show which files differ (no content) | `diff -rq / /` | -| **Git diff** | Use git's diff (branch-based) | `git diff branch1..branch2 -- path` | -| **Stat view** | Show change statistics | `git diff --stat branch1..branch2` | - -## Worktree Detection - -The command finds worktrees using `git worktree list`: - -``` -/home/user/project abc1234 [main] -/home/user/project-feature def5678 [feature-x] -/home/user/project-hotfix ghi9012 [hotfix-123] -``` - -From this output, the command extracts: - -- **Path**: The absolute path to the worktree directory -- **Branch**: The branch name in brackets (used when user specifies branch name) - -## Examples - -**Compare specific file between worktrees:** - -```bash -> /git:compare-worktrees src/app.js -# Prompts to select which worktree to compare with -# Shows diff of src/app.js between current and selected worktree -``` - -**Compare between two specific worktrees:** - -```bash -> /git:compare-worktrees ../project-main ../project-feature src/module.js -# Compares src/module.js between the two specified worktrees -``` - -**Compare multiple files/directories:** - -```bash -> /git:compare-worktrees src/app.js src/utils/ package.json -# Shows diffs for all three paths between worktrees -``` - -**Compare entire directories:** - -```bash -> /git:compare-worktrees src/ -# Shows all differences in src/ directory between worktrees -``` - -**Get summary statistics:** - -```bash -> /git:compare-worktrees --stat -# Shows which files differ and line counts -``` - -**Interactive mode:** - -```bash -> /git:compare-worktrees -# Lists available worktrees -# Asks which to compare -# Asks for specific paths or entire worktree -``` - -**Compare with branch worktree by branch name:** - -```bash -> /git:compare-worktrees feature-x -# Finds worktree for feature-x branch and compares -``` - -**Compare specific paths between branch worktrees:** - -```bash -> /git:compare-worktrees main feature-x src/ tests/ -# Compares src/ and tests/ directories between main and feature-x worktrees -``` - -## Output Format - -**File Comparison Header:** - -``` -Comparing: src/app.js - From: /home/user/project (main) - To: /home/user/project-feature (feature-x) ---- -[diff output] -``` - -**Summary Output:** - -``` -Worktree Comparison Summary -=========================== -From: /home/user/project (main) -To: /home/user/project-feature (feature-x) - -Files only in main: - - src/deprecated.js - -Files only in feature-x: - + src/new-feature.js - + src/new-feature.test.js - -Files that differ: - ~ src/app.js - ~ src/utils/helpers.js - ~ package.json - -Statistics: - 3 files changed - 2 files added - 1 file removed -``` - -## Common Workflows - -### Review Feature Changes - -```bash -# See what changed in a feature branch -> /git:compare-worktrees --stat -> /git:compare-worktrees src/components/ -``` - -### Compare Implementations - -```bash -# Compare how two features implemented similar functionality -> /git:compare-worktrees ../project-feature-1 ../project-feature-2 src/auth/ -``` - -### Quick File Check - -```bash -# Check if a specific file differs -> /git:compare-worktrees package.json -``` - -### Pre-Merge Review - -```bash -# Review all changes before merging (compare src and tests together) -> /git:compare-worktrees --stat -> /git:compare-worktrees src/ tests/ -# Both src/ and tests/ directories will be compared -``` - -## Important Notes - -- **Argument detection**: The command auto-detects argument types by comparing them against `git worktree list` output: - - Paths matching worktree roots → treated as worktrees to compare - - Names matching branches in worktrees → treated as worktrees to compare - - Other paths → treated as files/directories to compare within worktrees - -- **Multiple paths**: When multiple file/directory paths are provided, ALL of them are compared between the selected worktrees (not just the first one). - -- **Worktree paths**: When specifying worktrees, use the full path or relative path from current directory (e.g., `../project-feature`) - -- **Branch vs Worktree**: If you specify a branch name, the command looks for a worktree with that branch checked out. If no worktree exists for that branch, it suggests using `git diff` instead. - -- **Large diffs**: For large directories, the command will offer to show a summary first before displaying full diff output. - -- **Binary files**: Binary files are detected and reported as "Binary files differ" without showing actual diff. - -- **File permissions**: The diff will also show changes in file permissions if they differ. - -- **No worktrees**: If no other worktrees exist, the command will explain how to create one and offer to use `git diff` for branch comparison instead. - -## Integration with Create Worktree - -Use `/git:create-worktree` first to set up worktrees for comparison: - -```bash -# Create worktrees for comparison -> /git:create-worktree feature-x, main -# Created: ../project-feature-x and ../project-main - -# Now compare -> /git:compare-worktrees src/ -``` - -## Troubleshooting - -**"No other worktrees found"** - -- Create a worktree first with `/git:create-worktree ` -- Or use `git diff` for branch-only comparison without worktrees - -**"Worktree for branch not found"** - -- The branch may not have a worktree created -- Run `git worktree list` to see available worktrees -- Create the worktree with `/git:create-worktree ` - -**"Path does not exist in worktree"** - -- The specified file/directory may not exist in one of the worktrees -- This could indicate the file was added/deleted in one branch -- The command will report this in the comparison output diff --git a/plugins/git/skills/create-pr/SKILL.md b/plugins/git/skills/create-pr/SKILL.md index dfc2a47..75a75b6 100644 --- a/plugins/git/skills/create-pr/SKILL.md +++ b/plugins/git/skills/create-pr/SKILL.md @@ -1,5 +1,5 @@ --- -name: git:create-pr +name: create-pr description: Create pull requests using GitHub CLI with proper templates and formatting argument-hint: None required - interactive guide for PR creation allowed-tools: Bash(gh pr:*), Bash(gh auth:*), Bash(git status:*), Bash(git push:*), Bash(git branch:*), Skill(git:commit) @@ -38,9 +38,9 @@ Check if `gh` is installed, if not follow this instruction to install it: Before creating a PR, check for uncommitted changes: 1. Run `git status` to check for uncommitted changes (staged, unstaged, or untracked files) -2. If uncommitted changes exist, use the Skill tool to run the `git:commit` command first: +2. If uncommitted changes exist, use the Skill tool to run the `commit` skill first: ``` - Skill: git:commit + Skill: commit ``` 3. This ensures all your work is committed before creating the PR diff --git a/plugins/git/skills/create-worktree/SKILL.md b/plugins/git/skills/create-worktree/SKILL.md deleted file mode 100644 index 82daf0e..0000000 --- a/plugins/git/skills/create-worktree/SKILL.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -name: git:create-worktree -description: Create and setup git worktrees for parallel development with automatic dependency installation -argument-hint: (e.g., "refactor auth system" or "fix login") or --list to show existing worktrees -model: opus -allowed-tools: Bash(git worktree:*), Bash(git branch:*), Bash(git fetch:*), Bash(git status:*), Bash(ls:*), Bash(pwd:*), Bash(npm install:*), Bash(npm i:*), Bash(yarn install:*), Bash(yarn:*), Bash(pnpm install:*), Bash(pnpm i:*), Bash(bun install:*), Bash(pip install:*), Bash(poetry install:*), Bash(cargo build:*), Bash(go mod download:*) ---- - -# Claude Command: Create Worktree - -Your job is to create and setup git worktrees for parallel development, with automatic detection and installation of project dependencies. - -## Instructions - -CRITICAL: Perform the following steps exactly as described: - -1. **Current state check**: Run `git worktree list` to show existing worktrees and `git status` to verify the repository state is clean (no uncommitted changes that might cause issues) - -2. **Fetch latest remote branches**: Run `git fetch --all` to ensure local has knowledge of all remote branches - -3. **Parse user input**: Determine what the user wants to create: - - ``: Create worktree with auto-detected type prefix - - `--list`: Just show existing worktrees and exit - - No input: Ask user interactively for the name - -4. **Auto-detect branch type from name**: Check if the first word is a known branch type. If yes, use it as the prefix and the rest as the name. If no, default to `feature/`. - - **Known types:** `feature`, `feat`, `fix`, `bug`, `bugfix`, `hotfix`, `release`, `docs`, `test`, `refactor`, `chore`, `spike`, `experiment`, `review` - - **Examples:** - - `refactor auth system` → `refactor/auth-system` - - `fix login bug` → `fix/login-bug` - - `auth system` → `feature/auth-system` (default) - - `hotfix critical error` → `hotfix/critical-error` - - **Name normalization:** Convert spaces to dashes, lowercase, remove special characters except dashes/underscores - -5. **For each worktree to create**: - a. **Branch name construction**: Build full branch name from detected type and normalized name: - - `/` (e.g., `feature/auth-system`) - - b. **Branch resolution**: Determine if the branch exists locally, remotely, or needs to be created: - - If branch exists locally: `git worktree add ../- ` - - If branch exists remotely (origin/): `git worktree add --track -b ../- origin/` - - If branch doesn't exist: Ask user for base branch (default: current branch or main/master), then `git worktree add -b ../- ` - - c. **Path convention**: Use sibling directory with pattern `../-` - - Extract project name from current directory - - Use the normalized name (NOT the full branch with prefix) - - Example: `feature/auth-system` → `../myproject-auth-system` - - d. **Create the worktree**: Execute the appropriate git worktree add command - - e. **Dependency detection**: Check the new worktree for dependency files and determine if setup is needed: - - `package.json` -> Node.js project (npm/yarn/pnpm/bun) - - `requirements.txt` or `pyproject.toml` or `setup.py` -> Python project - - `Cargo.toml` -> Rust project - - `go.mod` -> Go project - - `Gemfile` -> Ruby project - - `composer.json` -> PHP project - - f. **Package manager detection** (for Node.js projects): - - `bun.lockb` -> Use `bun install` - - `pnpm-lock.yaml` -> Use `pnpm install` - - `yarn.lock` -> Use `yarn install` - - `package-lock.json` or default -> Use `npm install` - - g. **Automatic setup**: Automatically run dependency installation: - - cd to worktree and run the detected install command - - Report progress: "Installing dependencies with [package manager]..." - - If installation fails, report the error but continue with worktree creation summary - -6. **Summary**: Display summary of created worktrees: - - Worktree path - - Branch name (full name with prefix) - - Setup status (dependencies installed or failed) - - Quick navigation command: `cd ` - -## Worktree Path Convention - -Worktrees are created as sibling directories to maintain organization: - -``` -~/projects/ - myproject/ # Main worktree (current directory) - myproject-add-auth/ # Feature branch worktree (feature/add-auth) - myproject-critical-bug/ # Hotfix worktree (hotfix/critical-bug) - myproject-pr-456/ # PR review worktree (review/pr-456) -``` - -**Naming rules:** - -- Pattern: `-` (uses the name part, NOT the full branch) -- Branch name: `/` (e.g., `feature/add-auth`) -- Directory name uses only the `` portion for brevity - -## Examples - -**Feature worktree (default):** - -```bash -> /git:create-worktree auth system -# Branch: feature/auth-system -# Creates: ../myproject-auth-system -``` - -**Fix worktree:** - -```bash -> /git:create-worktree fix login error -# Branch: fix/login-error -# Creates: ../myproject-login-error -``` - -**Refactor worktree:** - -```bash -> /git:create-worktree refactor api layer -# Branch: refactor/api-layer -# Creates: ../myproject-api-layer -``` - -**Hotfix worktree:** - -```bash -> /git:create-worktree hotfix critical bug -# Branch: hotfix/critical-bug -# Creates: ../myproject-critical-bug -``` - -**List existing worktrees:** - -```bash -> /git:create-worktree --list -# Shows: git worktree list output -``` - -## Setup Detection Examples - -**Node.js project with pnpm:** - -``` -Detected Node.js project with pnpm-lock.yaml -Installing dependencies with pnpm... -✓ Dependencies installed successfully -``` - -**Python project:** - -``` -Detected Python project with requirements.txt -Installing dependencies with pip... -✓ Dependencies installed successfully -``` - -**Rust project:** - -``` -Detected Rust project with Cargo.toml -Building project with cargo... -✓ Project built successfully -``` - -## Common Workflows - -### Quick Feature Branch - -```bash -> /git:create-worktree new dashboard -# Branch: feature/new-dashboard -# Creates worktree, installs dependencies, ready to code -``` - -### Hotfix While Feature In Progress - -```bash -# In main worktree, working on feature -> /git:create-worktree hotfix critical bug -# Branch: hotfix/critical-bug -# Creates separate worktree from main/master -# Fix bug in hotfix worktree -# Return to feature work when done -``` - -### PR Review Without Stashing - -```bash -> /git:create-worktree review pr 123 -# Branch: review/pr-123 -# Creates worktree for reviewing PR -# Can run tests, inspect code -# Delete when review complete -``` - -### Experiment or Spike - -```bash -> /git:create-worktree spike new architecture -# Branch: spike/new-architecture -# Creates isolated worktree for experimentation -# Discard or merge based on results -``` - -## Important Notes - -- **Branch lock**: Each branch can only be checked out in one worktree at a time. If a branch is already checked out, the command will inform you which worktree has it. - -- **Shared .git**: All worktrees share the same Git object database. Changes committed in any worktree are visible to all others. - -- **Clean working directory**: The command checks for uncommitted changes and warns if present, as creating worktrees is safest with a clean state. - -- **Sibling directories**: Worktrees are always created as sibling directories (using `../`) to keep the workspace organized. Never create worktrees inside the main repository. - -- **Automatic dependency installation**: The command automatically detects the project type and package manager, then runs the appropriate install command without prompting. - -- **Remote tracking**: For remote branches, worktrees are created with proper tracking setup (`--track` flag) so pulls/pushes work correctly. - -## Cleanup - -When done with a worktree, use the proper removal command: - -```bash -git worktree remove ../myproject-add-auth -``` - -Or for a worktree with uncommitted changes: - -```bash -git worktree remove --force ../myproject-add-auth -``` - -Never use `rm -rf` to delete worktrees - always use `git worktree remove`. - -## Troubleshooting - -**"Branch is already checked out"** - -- Run `git worktree list` to see where the branch is checked out -- Either work in that worktree or remove it first - -**"Cannot create worktree - path already exists"** - -- The target directory already exists -- Either remove it or choose a different worktree path - -**"Dependency installation failed"** - -- Navigate to the worktree manually: `cd ../myproject-` -- Run the install command directly to see full error output -- Common causes: missing system dependencies, network issues, corrupted lockfile - -**"Wrong type detected"** - -- The first word is used as the branch type if it's a known type -- To force a specific type, start with: `fix`, `hotfix`, `docs`, `test`, `refactor`, `chore`, `spike`, `review` -- Default type is `feature/` when first word isn't a known type diff --git a/plugins/git/skills/notes/SKILL.md b/plugins/git/skills/git-notes/SKILL.md similarity index 99% rename from plugins/git/skills/notes/SKILL.md rename to plugins/git/skills/git-notes/SKILL.md index a1fe2ac..80819d1 100644 --- a/plugins/git/skills/notes/SKILL.md +++ b/plugins/git/skills/git-notes/SKILL.md @@ -1,5 +1,5 @@ --- -name: git:notes +name: git-notes description: Use when adding metadata to commits without changing history, tracking review status, test results, code quality annotations, or supplementing commit messages post-hoc - provides git notes commands and patterns for attaching non-invasive metadata to Git objects. --- diff --git a/plugins/git/skills/git-worktrees/SKILL.md b/plugins/git/skills/git-worktrees/SKILL.md new file mode 100644 index 0000000..1a9398d --- /dev/null +++ b/plugins/git/skills/git-worktrees/SKILL.md @@ -0,0 +1,1362 @@ +--- +name: git-worktrees +description: Use when working on multiple branches simultaneously, context switching without stashing, reviewing PRs while developing, testing in isolation, or comparing implementations across branches - provides git worktree commands and workflow patterns for parallel development with multiple working directories. +--- + +# Git Worktrees + +## Overview + +Git worktrees enable checking out multiple branches simultaneously in separate directories, all sharing the same repository. Create a worktree instead of stashing changes or cloning separately. + +**Core principle:** One worktree per active branch. Switch contexts by changing directories, not branches. + +## Core Concepts + +| Concept | Description | +|---------|-------------| +| **Main worktree** | Original working directory from `git clone` or `git init` | +| **Linked worktree** | Additional directories created with `git worktree add` | +| **Shared `.git`** | All worktrees share same Git object database (no duplication) | +| **Branch lock** | Each branch can only be checked out in ONE worktree at a time | +| **Worktree metadata** | Administrative files in `.git/worktrees/` tracking linked worktrees | + +## Quick Reference + +| Task | Command | +|------|---------| +| Create worktree (existing branch) | `git worktree add ` | +| Create worktree (new branch) | `git worktree add -b ` | +| Create worktree (new branch from ref) | `git worktree add -b ` | +| Create detached worktree | `git worktree add --detach ` | +| List all worktrees | `git worktree list` | +| Remove worktree | `git worktree remove ` | +| Force remove worktree | `git worktree remove --force ` | +| Move worktree | `git worktree move ` | +| Lock worktree | `git worktree lock ` | +| Unlock worktree | `git worktree unlock ` | +| Prune stale worktrees | `git worktree prune` | +| Repair worktree links | `git worktree repair` | +| Compare files between worktrees | `diff ../worktree-a/file ../worktree-b/file` | +| Get one file from another branch | `git checkout -- ` | +| Get partial file changes | `git checkout -p -- ` | +| Cherry-pick a commit | `git cherry-pick ` | +| Cherry-pick without committing | `git cherry-pick --no-commit ` | +| Merge without auto-commit | `git merge --no-commit ` | + +## Essential Commands + +### Create a Worktree + +```bash +# Create worktree with existing branch +git worktree add ../feature-x feature-x + +# Create worktree with new branch from current HEAD +git worktree add -b new-feature ../new-feature + +# Create worktree with new branch from specific commit +git worktree add -b hotfix-123 ../hotfix origin/main + +# Create worktree tracking remote branch +git worktree add --track -b feature ../feature origin/feature + +# Create worktree with detached HEAD (for experiments) +git worktree add --detach ../experiment HEAD~5 +``` + +### List Worktrees + +```bash +# Simple list +git worktree list + +# Verbose output with additional details +git worktree list -v + +# Machine-readable format (for scripting) +git worktree list --porcelain +``` + +**Example output:** + +``` +/home/user/project abc1234 [main] +/home/user/project-feature def5678 [feature-x] +/home/user/project-hotfix ghi9012 [hotfix-123] +``` + +### Remove a Worktree + +```bash +# Remove worktree (working directory must be clean) +git worktree remove ../feature-x + +# Force remove (discards uncommitted changes) +git worktree remove --force ../feature-x +``` + +### Move a Worktree + +```bash +# Relocate worktree to new path +git worktree move ../old-path ../new-path +``` + +### Lock/Unlock Worktrees + +```bash +# Lock worktree (prevents pruning if on removable storage) +git worktree lock ../feature-x +git worktree lock --reason "On USB drive" ../feature-x + +# Unlock worktree +git worktree unlock ../feature-x +``` + +### Prune Stale Worktrees + +```bash +# Remove stale worktree metadata (after manual directory deletion) +git worktree prune + +# Dry-run to see what would be pruned +git worktree prune --dry-run + +# Verbose output +git worktree prune -v +``` + +### Repair Worktrees + +```bash +# Repair worktree links after moving directories manually +git worktree repair + +# Repair specific worktree +git worktree repair ../feature-x +``` + +## Workflow Patterns + +### Pattern 1: Feature + Hotfix in Parallel + +To fix a bug while feature work is in progress: + +```bash +# Create worktree for hotfix from main +git worktree add -b hotfix-456 ../project-hotfix origin/main + +# Switch to hotfix directory, fix, commit, push +cd ../project-hotfix +git add . && git commit -m "fix: resolve critical bug #456" +git push origin hotfix-456 + +# Return to feature work +cd ../project + +# Clean up when done +git worktree remove ../project-hotfix +``` + +### Pattern 2: PR Review While Working + +To review a PR without affecting current work: + +```bash +# Fetch PR branch and create worktree +git fetch origin pull/123/head:pr-123 +git worktree add ../project-review pr-123 + +# Review: run tests, inspect code +cd ../project-review + +# Return to work, then clean up +cd ../project +git worktree remove ../project-review +git branch -d pr-123 +``` + +### Pattern 3: Compare Implementations + +To compare code across branches side-by-side: + +```bash +# Create worktrees for different versions +git worktree add ../project-v1 v1.0.0 +git worktree add ../project-v2 v2.0.0 + +# Diff, compare, or run both simultaneously +diff ../project-v1/src/module.js ../project-v2/src/module.js + +# Clean up +git worktree remove ../project-v1 +git worktree remove ../project-v2 +``` + +### Pattern 4: Long-Running Tasks + +To run tests/builds in isolation while continuing development: + +```bash +# Create worktree for CI-like testing +git worktree add ../project-test main + +# Start long-running tests in background +cd ../project-test && npm test & + +# Continue development in main worktree +cd ../project +``` + +### Pattern 5: Stable Reference + +To maintain a clean main checkout for reference: + +```bash +# Create permanent worktree for main branch +git worktree add ../project-main main + +# Lock to prevent accidental removal +git worktree lock --reason "Reference checkout" ../project-main +``` + +### Pattern 6: Selective Merging from Multiple Features + +To combine specific changes from multiple feature branches: + +```bash +# Create worktrees for each feature to review +git worktree add ../project-feature-1 feature-1 +git worktree add ../project-feature-2 feature-2 + +# Review changes in each worktree +diff ../project/src/module.js ../project-feature-1/src/module.js +diff ../project/src/module.js ../project-feature-2/src/module.js + +# From main worktree, selectively take changes +cd ../project +git checkout feature-1 -- src/moduleA.js src/utils.js +git checkout feature-2 -- src/moduleB.js +git commit -m "feat: combine selected changes from feature branches" + +# Or cherry-pick specific commits +git cherry-pick abc1234 # from feature-1 +git cherry-pick def5678 # from feature-2 + +# Clean up +git worktree remove ../project-feature-1 +git worktree remove ../project-feature-2 +``` + +## Comparing and Merging Changes Between Worktrees + +Since all worktrees share the same Git repository, you can compare files, cherry-pick commits, and selectively merge changes between them. + +### Compare and Review File Changes + +Since worktrees are just directories, you can compare files directly: + +```bash +# Compare specific file between worktrees +diff ../project-main/src/app.js ../project-feature/src/app.js + +# Use git diff to compare branches (works from any worktree) +git diff main..feature-branch -- src/app.js + +# Visual diff with your preferred tool +code --diff ../project-main/src/app.js ../project-feature/src/app.js + +# Compare entire directories +diff -r ../project-v1/src ../project-v2/src +``` + +### Merge Only One File from a Worktree + +You can selectively bring a single file from another branch using `git checkout`: + +```bash +# In your current branch, get a specific file from another branch +git checkout feature-branch -- path/to/file.js + +# Or get it from a specific commit +git checkout abc1234 -- path/to/file.js + +# Get multiple specific files +git checkout feature-branch -- src/module.js src/utils.js +``` + +For **partial file changes** (specific hunks/lines only): + +```bash +# Interactive patch mode - select which changes to take +git checkout -p feature-branch -- path/to/file.js +``` + +This prompts you to accept/reject each change hunk individually with options: +- `y` - apply this hunk +- `n` - skip this hunk +- `s` - split into smaller hunks +- `e` - manually edit the hunk + +### Cherry-Pick Commits from Worktrees + +Cherry-picking works at the commit level. Since all worktrees share the same repository, you can cherry-pick any commit: + +```bash +# Find the commit hash (from any worktree or git log) +git log feature-branch --oneline + +# Cherry-pick specific commit into your current branch +git cherry-pick abc1234 + +# Cherry-pick multiple commits +git cherry-pick abc1234 def5678 + +# Cherry-pick a range of commits +git cherry-pick abc1234^..def5678 + +# Cherry-pick without committing (stage changes only) +git cherry-pick --no-commit abc1234 +``` + +### Merge Changes from Multiple Worktrees + +You can merge or cherry-pick from multiple branches: + +```bash +# Merge multiple branches sequentially +git merge feature-1 +git merge feature-2 + +# Or use octopus merge for multiple branches at once +git merge feature-1 feature-2 feature-3 + +# Cherry-pick commits from multiple branches +git cherry-pick abc1234 # from feature-1 +git cherry-pick def5678 # from feature-2 +``` + +### Selective Merging - Pick Which Changes to Include + +#### Option 1: Selective File Checkout + +```bash +# Get specific files from different branches +git checkout feature-1 -- src/moduleA.js +git checkout feature-2 -- src/moduleB.js +git commit -m "Merge selected files from feature branches" +``` + +#### Option 2: Interactive Patch Selection + +```bash +# Select specific hunks from a file +git checkout -p feature-1 -- src/shared.js +``` + +#### Option 3: Cherry-Pick with Selective Staging + +```bash +# Apply changes without committing +git cherry-pick --no-commit abc1234 + +# Unstage what you don't want +git reset HEAD -- unwanted-file.js +git checkout -- unwanted-file.js + +# Commit only what you kept +git commit -m "Selected changes from feature-1" +``` + +#### Option 4: Merge with Manual Selection + +```bash +# Start merge but don't auto-commit +git merge --no-commit feature-1 + +# Review and modify staged changes +git status +git reset HEAD -- file-to-exclude.js +git checkout -- file-to-exclude.js + +# Commit your selection +git commit -m "Merge selected changes from feature-1" +``` + +#### Option 5: Using git restore (Git 2.23+) + +```bash +# Restore specific file from another branch +git restore --source=feature-branch -- path/to/file.js + +# Interactive restore with patch selection +git restore -p --source=feature-branch -- path/to/file.js +``` + +## Directory Structure Conventions + +Organize worktrees predictably: + +``` +~/projects/ + myproject/ # Main worktree (main/master branch) + myproject-feature-x/ # Feature branch worktree + myproject-hotfix/ # Hotfix worktree + myproject-review/ # Temporary PR review worktree +``` + +**Naming convention:** `-` or `-` + +## Best Practices + +| Practice | Rationale | +|----------|-----------| +| **Use sibling directories** | Keep worktrees at same level as main project for easy navigation | +| **Name by purpose** | `project-review` is clearer than `project-pr-123` | +| **Clean up promptly** | Remove worktrees when done to avoid confusion | +| **Lock remote worktrees** | Prevent pruning if worktree is on network/USB storage | +| **Use `--detach` for experiments** | Avoid creating throwaway branches | +| **Commit before removing** | Always commit or stash before `git worktree remove` | + +## Common Issues and Solutions + +### Issue: "Branch is already checked out" + +**Cause:** Attempting to checkout a branch that's active in another worktree. + +**Solution:** + +```bash +# Find where the branch is checked out +git worktree list + +# Either work in that worktree or remove it first +git worktree remove ../other-worktree +``` + +### Issue: Stale worktree after manual deletion + +**Cause:** Deleted worktree directory without using `git worktree remove`. + +**Solution:** + +```bash +# Clean up stale metadata +git worktree prune +``` + +### Issue: Worktree moved manually + +**Cause:** Moved worktree directory without using `git worktree move`. + +**Solution:** + +```bash +# Repair the worktree links +git worktree repair +# Or specify the new path +git worktree repair /new/path/to/worktree +``` + +### Issue: Worktree on removed drive + +**Cause:** Worktree was on removable storage that's no longer connected. + +**Solution:** + +```bash +# If temporary, lock it to prevent pruning +git worktree lock ../usb-worktree + +# If permanent, prune it +git worktree prune +``` + +## Common Mistakes + +| Mistake | Fix | +|---------|-----| +| Using `rm -rf` to delete worktree | Always use `git worktree remove`, then `git worktree prune` if needed | +| Forgetting branch is locked to worktree | Run `git worktree list` before checkout errors | +| Not cleaning up temporary worktrees | Remove worktrees immediately after task completion | +| Creating worktrees in nested locations | Use sibling directories (`../project-feature`) not subdirs | +| Moving worktree directory manually | Use `git worktree move` or run `git worktree repair` after | + +## Agent Workflow Integration + +To isolate parallel agent tasks: + +```bash +# Create worktree for isolated task +git worktree add -b task-123 ../project-task-123 +cd ../project-task-123 +# Make changes, run tests, return +cd ../project +``` + +To experiment safely with detached HEAD: + +```bash +# Create detached worktree (no branch to clean up) +git worktree add --detach ../project-experiment +cd ../project-experiment +# Experiment, then discard or commit to new branch +git worktree remove --force ../project-experiment +``` + +## Verification Checklist + +Before using worktrees: + +- [ ] Understand that branches can only be checked out in one worktree +- [ ] Know where worktrees will be created (use sibling directories) +- [ ] Plan cleanup strategy for temporary worktrees + +When creating worktrees: + +- [ ] Use descriptive directory names +- [ ] Verify branch is not already checked out elsewhere +- [ ] Consider using `--detach` for experiments + +When removing worktrees: + +- [ ] Commit or stash any uncommitted changes +- [ ] Use `git worktree remove`, not `rm -rf` +- [ ] Run `git worktree prune` if directory was deleted manually + +--- + +# How to Compare Worktrees + +Workflow to compare files and directories between git worktrees, helping users understand differences in code across branches or worktrees. + +## Instructions + +CRITICAL: Perform the following steps exactly as described: + +1. **Current state check**: Run `git worktree list` to show all existing worktrees and their locations + +2. **Parse user input**: Classify each provided argument: + - **No arguments**: Interactive mode - ask user what to compare + - **`--stat`**: Show summary statistics of differences (files changed, insertions, deletions) + - **Worktree path**: A path that matches one of the worktree roots from `git worktree list` + - **Branch name**: A name that matches a branch in one of the worktrees + - **File/directory path**: A path within the current worktree to compare + +3. **Determine comparison targets** (worktrees to compare): + a. If user provided worktree paths: Use those as comparison targets + b. If user specified branch names: Find the worktrees for those branches from `git worktree list` + c. If only one worktree exists besides current: Use current and that one as comparison targets + d. If multiple worktrees exist and none specified: Present list and ask user which to compare + e. If no other worktrees exist: Offer to compare with a branch using `git diff` + +4. **Determine what to compare** (files/directories within worktrees): + a. If user specified file(s) or directory(ies) paths: Compare ALL of them + b. If no specific paths given: Ask user: + - "Compare entire worktree?" or + - "Compare specific files/directories? (enter paths)" + +5. **Execute comparison**: + + **For specific files between worktrees:** + + ```bash + diff / / + # Or for unified diff format: + diff -u / / + ``` + + **For directories between worktrees:** + + ```bash + diff -r / / + # Or for summary only: + diff -rq / / + ``` + + **For branch-level comparison (using git diff):** + + ```bash + git diff .. -- + # Or for stat summary: + git diff --stat .. + ``` + + **For comparing with current working directory:** + + ```bash + diff / + ``` + +6. **Format and present results**: + - Show clear header indicating what's being compared + - For large diffs, offer to show summary first + - Highlight significant changes (new files, deleted files, renamed files) + - Provide context about the branches each worktree contains + +## Comparison Modes + +| Mode | Description | Command Pattern | +|------|-------------|-----------------| +| **File diff** | Compare single file between worktrees | `diff -u /file /file` | +| **Directory diff** | Compare directories recursively | `diff -r /dir /dir` | +| **Summary only** | Show which files differ (no content) | `diff -rq / /` | +| **Git diff** | Use git's diff (branch-based) | `git diff branch1..branch2 -- path` | +| **Stat view** | Show change statistics | `git diff --stat branch1..branch2` | + +## Worktree Detection + +The command finds worktrees using `git worktree list`: + +``` +/home/user/project abc1234 [main] +/home/user/project-feature def5678 [feature-x] +/home/user/project-hotfix ghi9012 [hotfix-123] +``` + +From this output, the command extracts: + +- **Path**: The absolute path to the worktree directory +- **Branch**: The branch name in brackets (used when user specifies branch name) + +## Examples + +**Compare specific file between worktrees:** + +```bash +> /worktrees compare src/app.js +# Prompts to select which worktree to compare with +# Shows diff of src/app.js between current and selected worktree +``` + +**Compare between two specific worktrees:** + +```bash +> /worktrees compare ../project-main ../project-feature src/module.js +# Compares src/module.js between the two specified worktrees +``` + +**Compare multiple files/directories:** + +```bash +> /worktrees compare src/app.js src/utils/ package.json +# Shows diffs for all three paths between worktrees +``` + +**Compare entire directories:** + +```bash +> /worktrees compare src/ +# Shows all differences in src/ directory between worktrees +``` + +**Get summary statistics:** + +```bash +> /worktrees compare --stat +# Shows which files differ and line counts +``` + +**Interactive mode:** + +```bash +> /worktrees compare +# Lists available worktrees +# Asks which to compare +# Asks for specific paths or entire worktree +``` + +**Compare with branch worktree by branch name:** + +```bash +> /worktrees compare feature-x +# Finds worktree for feature-x branch and compares +``` + +**Compare specific paths between branch worktrees:** + +```bash +> /worktrees compare main feature-x src/ tests/ +# Compares src/ and tests/ directories between main and feature-x worktrees +``` + +## Output Format + +**File Comparison Header:** + +``` +Comparing: src/app.js + From: /home/user/project (main) + To: /home/user/project-feature (feature-x) +--- +[diff output] +``` + +**Summary Output:** + +``` +Worktree Comparison Summary +=========================== +From: /home/user/project (main) +To: /home/user/project-feature (feature-x) + +Files only in main: + - src/deprecated.js + +Files only in feature-x: + + src/new-feature.js + + src/new-feature.test.js + +Files that differ: + ~ src/app.js + ~ src/utils/helpers.js + ~ package.json + +Statistics: + 3 files changed + 2 files added + 1 file removed +``` + +## Common Workflows + +### Review Feature Changes + +```bash +# See what changed in a feature branch +> /worktrees compare --stat +> /worktrees compare src/components/ +``` + +### Compare Implementations + +```bash +# Compare how two features implemented similar functionality +> /worktrees compare ../project-feature-1 ../project-feature-2 src/auth/ +``` + +### Quick File Check + +```bash +# Check if a specific file differs +> /worktrees compare package.json +``` + +### Pre-Merge Review + +```bash +# Review all changes before merging (compare src and tests together) +> /worktrees compare --stat +> /worktrees compare src/ tests/ +# Both src/ and tests/ directories will be compared +``` + +## Important Notes + +- **Argument detection**: The command auto-detects argument types by comparing them against `git worktree list` output: + - Paths matching worktree roots → treated as worktrees to compare + - Names matching branches in worktrees → treated as worktrees to compare + - Other paths → treated as files/directories to compare within worktrees + +- **Multiple paths**: When multiple file/directory paths are provided, ALL of them are compared between the selected worktrees (not just the first one). + +- **Worktree paths**: When specifying worktrees, use the full path or relative path from current directory (e.g., `../project-feature`) + +- **Branch vs Worktree**: If you specify a branch name, the command looks for a worktree with that branch checked out. If no worktree exists for that branch, it suggests using `git diff` instead. + +- **Large diffs**: For large directories, the command will offer to show a summary first before displaying full diff output. + +- **Binary files**: Binary files are detected and reported as "Binary files differ" without showing actual diff. + +- **File permissions**: The diff will also show changes in file permissions if they differ. + +- **No worktrees**: If no other worktrees exist, the command will explain how to create one and offer to use `git diff` for branch comparison instead. + +## Integration with Create Worktree + +Use `/worktrees create` first to set up worktrees for comparison: + +```bash +# Create worktrees for comparison +> /worktrees create feature-x, main +# Created: ../project-feature-x and ../project-main + +# Now compare +> /worktrees compare src/ +``` + +## Troubleshooting + +**"No other worktrees found"** + +- Create a worktree first with `/worktrees create ` +- Or use `git diff` for branch-only comparison without worktrees + +**"Worktree for branch not found"** + +- The branch may not have a worktree created +- Run `git worktree list` to see available worktrees +- Create the worktree with `/worktrees create ` + +**"Path does not exist in worktree"** + +- The specified file/directory may not exist in one of the worktrees +- This could indicate the file was added/deleted in one branch +- The command will report this in the comparison output + +--- + +# How to Create Worktree + +Workflow to create and setup git worktrees for parallel development, with automatic detection and installation of project dependencies. + +## Instructions + +CRITICAL: Perform the following steps exactly as described: + +1. **Current state check**: Run `git worktree list` to show existing worktrees and `git status` to verify the repository state is clean (no uncommitted changes that might cause issues) + +2. **Fetch latest remote branches**: Run `git fetch --all` to ensure local has knowledge of all remote branches + +3. **Parse user input**: Determine what the user wants to create: + - ``: Create worktree with auto-detected type prefix + - `--list`: Just show existing worktrees and exit + - No input: Ask user interactively for the name + +4. **Auto-detect branch type from name**: Check if the first word is a known branch type. If yes, use it as the prefix and the rest as the name. If no, default to `feature/`. + + **Known types:** `feature`, `feat`, `fix`, `bug`, `bugfix`, `hotfix`, `release`, `docs`, `test`, `refactor`, `chore`, `spike`, `experiment`, `review` + + **Examples:** + - `refactor auth system` → `refactor/auth-system` + - `fix login bug` → `fix/login-bug` + - `auth system` → `feature/auth-system` (default) + - `hotfix critical error` → `hotfix/critical-error` + + **Name normalization:** Convert spaces to dashes, lowercase, remove special characters except dashes/underscores + +5. **For each worktree to create**: + a. **Branch name construction**: Build full branch name from detected type and normalized name: + - `/` (e.g., `feature/auth-system`) + + b. **Branch resolution**: Determine if the branch exists locally, remotely, or needs to be created: + - If branch exists locally: `git worktree add ../- ` + - If branch exists remotely (origin/): `git worktree add --track -b ../- origin/` + - If branch doesn't exist: Ask user for base branch (default: current branch or main/master), then `git worktree add -b ../- ` + + c. **Path convention**: Use sibling directory with pattern `../-` + - Extract project name from current directory + - Use the normalized name (NOT the full branch with prefix) + - Example: `feature/auth-system` → `../myproject-auth-system` + + d. **Create the worktree**: Execute the appropriate git worktree add command + + e. **Dependency detection**: Check the new worktree for dependency files and determine if setup is needed: + - `package.json` -> Node.js project (npm/yarn/pnpm/bun) + - `requirements.txt` or `pyproject.toml` or `setup.py` -> Python project + - `Cargo.toml` -> Rust project + - `go.mod` -> Go project + - `Gemfile` -> Ruby project + - `composer.json` -> PHP project + + f. **Package manager detection** (for Node.js projects): + - `bun.lockb` -> Use `bun install` + - `pnpm-lock.yaml` -> Use `pnpm install` + - `yarn.lock` -> Use `yarn install` + - `package-lock.json` or default -> Use `npm install` + + g. **Automatic setup**: Automatically run dependency installation: + - cd to worktree and run the detected install command + - Report progress: "Installing dependencies with [package manager]..." + - If installation fails, report the error but continue with worktree creation summary + +6. **Summary**: Display summary of created worktrees: + - Worktree path + - Branch name (full name with prefix) + - Setup status (dependencies installed or failed) + - Quick navigation command: `cd ` + +## Worktree Path Convention + +Worktrees are created as sibling directories to maintain organization: + +``` +~/projects/ + myproject/ # Main worktree (current directory) + myproject-add-auth/ # Feature branch worktree (feature/add-auth) + myproject-critical-bug/ # Hotfix worktree (hotfix/critical-bug) + myproject-pr-456/ # PR review worktree (review/pr-456) +``` + +**Naming rules:** + +- Pattern: `-` (uses the name part, NOT the full branch) +- Branch name: `/` (e.g., `feature/add-auth`) +- Directory name uses only the `` portion for brevity + +## Examples + +**Feature worktree (default):** + +```bash +> /worktrees create auth system +# Branch: feature/auth-system +# Creates: ../myproject-auth-system +``` + +**Fix worktree:** + +```bash +> /worktrees create fix login error +# Branch: fix/login-error +# Creates: ../myproject-login-error +``` + +**Refactor worktree:** + +```bash +> /worktrees create refactor api layer +# Branch: refactor/api-layer +# Creates: ../myproject-api-layer +``` + +**Hotfix worktree:** + +```bash +> /worktrees create hotfix critical bug +# Branch: hotfix/critical-bug +# Creates: ../myproject-critical-bug +``` + +**List existing worktrees:** + +```bash +> /worktrees list +# Shows: git worktree list output +``` + +## Setup Detection Examples + +**Node.js project with pnpm:** + +``` +Detected Node.js project with pnpm-lock.yaml +Installing dependencies with pnpm... +✓ Dependencies installed successfully +``` + +**Python project:** + +``` +Detected Python project with requirements.txt +Installing dependencies with pip... +✓ Dependencies installed successfully +``` + +**Rust project:** + +``` +Detected Rust project with Cargo.toml +Building project with cargo... +✓ Project built successfully +``` + +## Common Workflows + +### Quick Feature Branch + +```bash +> /worktrees create new dashboard +# Branch: feature/new-dashboard +# Creates worktree, installs dependencies, ready to code +``` + +### Hotfix While Feature In Progress + +```bash +# In main worktree, working on feature +> /worktrees create hotfix critical bug +# Branch: hotfix/critical-bug +# Creates separate worktree from main/master +# Fix bug in hotfix worktree +# Return to feature work when done +``` + +### PR Review Without Stashing + +```bash +> /worktrees create review pr 123 +# Branch: review/pr-123 +# Creates worktree for reviewing PR +# Can run tests, inspect code +# Delete when review complete +``` + +### Experiment or Spike + +```bash +> /worktrees create spike new architecture +# Branch: spike/new-architecture +# Creates isolated worktree for experimentation +# Discard or merge based on results +``` + +## Important Notes + +- **Branch lock**: Each branch can only be checked out in one worktree at a time. If a branch is already checked out, the command will inform you which worktree has it. + +- **Shared .git**: All worktrees share the same Git object database. Changes committed in any worktree are visible to all others. + +- **Clean working directory**: The command checks for uncommitted changes and warns if present, as creating worktrees is safest with a clean state. + +- **Sibling directories**: Worktrees are always created as sibling directories (using `../`) to keep the workspace organized. Never create worktrees inside the main repository. + +- **Automatic dependency installation**: The command automatically detects the project type and package manager, then runs the appropriate install command without prompting. + +- **Remote tracking**: For remote branches, worktrees are created with proper tracking setup (`--track` flag) so pulls/pushes work correctly. + +## Cleanup + +When done with a worktree, use the proper removal command: + +```bash +git worktree remove ../myproject-add-auth +``` + +Or for a worktree with uncommitted changes: + +```bash +git worktree remove --force ../myproject-add-auth +``` + +Never use `rm -rf` to delete worktrees - always use `git worktree remove`. + +## Troubleshooting + +**"Branch is already checked out"** + +- Run `git worktree list` to see where the branch is checked out +- Either work in that worktree or remove it first + +**"Cannot create worktree - path already exists"** + +- The target directory already exists +- Either remove it or choose a different worktree path + +**"Dependency installation failed"** + +- Navigate to the worktree manually: `cd ../myproject-` +- Run the install command directly to see full error output +- Common causes: missing system dependencies, network issues, corrupted lockfile + +**"Wrong type detected"** + +- The first word is used as the branch type if it's a known type +- To force a specific type, start with: `fix`, `hotfix`, `docs`, `test`, `refactor`, `chore`, `spike`, `review` +- Default type is `feature/` when first word isn't a known type + +--- + +# How to Merge Worktree + +Workflow to help users merge changes from git worktrees into their current branch, supporting multiple merge strategies from simple file checkout to selective cherry-picking. + +## Instructions + +CRITICAL: Perform the following steps exactly as described: + +1. **Current state check**: Run `git worktree list` to show all existing worktrees and `git status` to verify working directory state + +2. **Parse user input**: Determine what merge operation the user wants: + - **`--interactive` or no arguments**: Guided interactive mode + - **File/directory path**: Merge specific file(s) or directory from a worktree + - **Commit name**: Cherry-pick a specific commit + - **Branch name**: Merge from that branch's worktree + - **`--from `**: Specify source worktree explicitly + - **`--patch` or `-p`**: Use interactive patch selection mode + +3. **Determine source worktree/branch**: + a. If user specified `--from `: Use that worktree path directly + b. If user specified a branch name: Find worktree for that branch from `git worktree list` + c. If only one other worktree exists: Ask to confirm using it as source + d. If multiple worktrees exist: Present list and ask user which to merge from + e. If no other worktrees exist: Explain and offer to use branch-based merge instead + +4. **Determine merge strategy**: Present options based on user's needs: + + **Strategy A: Selective File Checkout** (for specific files/directories) + - Best for: Getting complete file(s) from another branch + - Command: `git checkout -- ` + + **Strategy B: Interactive Patch Selection** (for partial file changes) + - Best for: Selecting specific hunks/lines from a file + - Command: `git checkout -p -- ` + - Prompts user for each hunk: y (apply), n (skip), s (split), e (edit) + + **Strategy C: Cherry-Pick with Selective Staging** (for specific commits) + - Best for: Applying a commit but excluding some changes + - Steps: + 1. `git cherry-pick --no-commit ` + 2. Review staged changes + 3. `git reset HEAD -- ` to unstage + 4. `git checkout -- ` to discard + 5. `git commit -m "message"` + + **Strategy D: Manual Merge with Conflicts** (for complex merges) + - Best for: Full branch merge with control over resolution + - Steps: + 1. `git merge --no-commit ` + 2. Review all changes + 3. Selectively stage/unstage files + 4. Resolve conflicts if any + 5. `git commit -m "message"` + + **Strategy E: Multi-Worktree Selective Merge** (combining from multiple sources) + - Best for: Taking different files from different worktrees + - Steps: + 1. `git checkout -- ` + 2. `git checkout -- ` + 3. `git commit -m "Merge selected files from multiple branches"` + +5. **Execute the selected strategy**: + - Run pre-merge comparison if user wants to review (suggest `/worktrees compare` first) + - Execute git commands for the chosen strategy + - Handle any conflicts that arise + - Confirm changes before final commit + +6. **Post-merge summary**: Display what was merged: + - Files changed/added/removed + - Source worktree/branch + - Merge strategy used + +7. **Cleanup prompt**: After successful merge, ask: + - "Would you like to remove any worktrees to clean up local state?" + - If yes: List worktrees and ask which to remove + - Execute `git worktree remove ` for selected worktrees + - Remind about `git worktree prune` if needed + +## Merge Strategies Reference + +| Strategy | Use When | Command Pattern | +|----------|----------|-----------------| +| **Selective File** | Need complete file(s) from another branch | `git checkout -- ` | +| **Interactive Patch** | Need specific changes within a file | `git checkout -p -- ` | +| **Cherry-Pick Selective** | Need a commit but not all its changes | `git cherry-pick --no-commit` + selective staging | +| **Manual Merge** | Full branch merge with control | `git merge --no-commit` + selective staging | +| **Multi-Source** | Combining files from multiple branches | Multiple `git checkout -- ` | + +## Examples + +**Merge single file from worktree:** +```bash +> /worktrees merge src/app.js --from ../project-feature +# Prompts for merge strategy +# Executes: git checkout feature-branch -- src/app.js +``` + +**Interactive patch selection:** +```bash +> /worktrees merge src/utils.js --patch +# Lists available worktrees to select from +# Runs: git checkout -p feature-branch -- src/utils.js +# User selects hunks interactively (y/n/s/e) +``` + +**Cherry-pick specific commit:** +```bash +> /worktrees merge abc1234 +# Detects commit hash +# Asks: Apply entire commit or selective? +# If selective: git cherry-pick --no-commit abc1234 +# Then guides through unstaging unwanted changes +``` + +**Full guided mode:** +```bash +> /worktrees merge +# Lists all worktrees +# Asks what to merge (files, commits, or branches) +# Guides through appropriate strategy +# Offers cleanup at end +``` + +**Directory merge with conflicts:** +```bash +> /worktrees merge src/components/ --from ../project-refactor +# Strategy D: Manual merge with conflicts +# git merge --no-commit refactor-branch +# Helps resolve any conflicts +# Reviews and commits selected changes +``` + +## Interactive Patch Mode Guide + +When using `--patch` or Strategy B, the user sees prompts for each change hunk: + +``` +@@ -10,6 +10,8 @@ function processData(input) { + const result = transform(input); ++ // Added validation ++ if (!isValid(result)) throw new Error('Invalid'); + return result; + } +Apply this hunk? [y,n,q,a,d,s,e,?] +``` + +| Key | Action | +|-----|--------| +| `y` | Apply this hunk | +| `n` | Skip this hunk | +| `q` | Quit (don't apply this or remaining hunks) | +| `a` | Apply this and all remaining hunks | +| `d` | Don't apply this or remaining hunks in this file | +| `s` | Split into smaller hunks | +| `e` | Manually edit the hunk | +| `?` | Show help | + +## Cherry-Pick Selective Workflow + +For Strategy C (cherry-picking with selective staging): + +```bash +# 1. Apply commit without committing +git cherry-pick --no-commit abc1234 + +# 2. Check what was staged +git status + +# 3. Unstage files you don't want +git reset HEAD -- path/to/unwanted.js + +# 4. Discard changes to those files +git checkout -- path/to/unwanted.js + +# 5. Commit the remaining changes +git commit -m "Cherry-pick selected changes from abc1234" +``` + +## Multi-Worktree Merge Workflow + +For Strategy E (merging from multiple worktrees): + +```bash +# Get files from different branches +git checkout feature-auth -- src/auth/login.js src/auth/session.js +git checkout feature-api -- src/api/endpoints.js +git checkout feature-ui -- src/components/Header.js + +# Review all changes +git status +git diff --cached + +# Commit combined changes +git commit -m "feat: combine auth, API, and UI improvements from feature branches" +``` + +## Common Workflows + +### Take a Feature File Without Full Merge +```bash +> /worktrees merge src/new-feature.js --from ../project-feature +# Gets just the file, not the entire branch +``` + +### Partial Bugfix from Hotfix Branch +```bash +> /worktrees merge --patch src/utils.js --from ../project-hotfix +# Select only the specific bug fix hunks, not all changes +``` + +### Combine Multiple PRs' Changes +```bash +> /worktrees merge --interactive +# Select specific files from PR-1 worktree +# Select other files from PR-2 worktree +# Combine into single coherent commit +``` + +### Pre-Merge Review +```bash +# First review what will be merged +> /worktrees compare src/module.js +# Then merge with confidence +> /worktrees merge src/module.js --from ../project-feature +``` + +## Important Notes + +- **Working directory state**: Always ensure your working directory is clean before merging. Uncommitted changes can cause conflicts. + +- **Pre-merge review**: Consider using `/worktrees compare` before merging to understand what changes will be applied. + +- **Conflict resolution**: If conflicts occur during merge, the command will help identify and resolve them before committing. + +- **No-commit flag**: Most strategies use `--no-commit` to give you control over the final commit message and what gets included. + +- **Shared repository**: All worktrees share the same Git object database, so commits made in any worktree are immediately visible to cherry-pick from any other. + +- **Branch locks**: Remember that branches can only be checked out in one worktree at a time. Use branch names for merge operations rather than creating duplicate worktrees. + +## Cleanup After Merge + +After merging, consider cleaning up worktrees that are no longer needed: + +```bash +# List worktrees +git worktree list + +# Remove specific worktree (clean state required) +git worktree remove ../project-feature + +# Force remove (discards uncommitted changes) +git worktree remove --force ../project-feature + +# Clean up stale worktree references +git worktree prune +``` + +The command will prompt you about cleanup after each successful merge to help maintain a tidy workspace. + +## Troubleshooting + +**"Cannot merge: working directory has uncommitted changes"** +- Commit or stash your current changes first +- Or use `git stash` before merge, `git stash pop` after + +**"Merge conflict in "** +- The command will show conflicted files +- Open files and resolve conflicts (look for `<<<<<<<` markers) +- Stage resolved files with `git add ` +- Continue with `git commit` + +**"Commit not found" when cherry-picking** +- Ensure the commit hash is correct +- Run `git log ` in any worktree to find commits +- Commits are shared across all worktrees + +**"Cannot checkout: file exists in working tree"** +- File has local modifications +- Either commit, stash, or discard local changes first +- Then retry the merge operation + +**"Branch not found for worktree"** +- The specified worktree may have been removed +- Run `git worktree list` to see current worktrees +- Use `git worktree prune` to clean up stale references + +## Integration with Other Commands + +**Pre-merge review:** +```bash +> /worktrees compare src/ +> /worktrees merge src/specific-file.js +``` + +**Create worktree, merge, cleanup:** +```bash +> /worktrees create feature-branch +> /worktrees compare src/ +> /worktrees merge src/module.js --from ../project-feature-branch +# After merge, cleanup is offered automatically +``` diff --git a/plugins/git/skills/load-issues/SKILL.md b/plugins/git/skills/load-issues/SKILL.md index e616056..3a15bdf 100644 --- a/plugins/git/skills/load-issues/SKILL.md +++ b/plugins/git/skills/load-issues/SKILL.md @@ -1,5 +1,5 @@ --- -name: git:load-issues +name: load-issues description: Load all open issues from GitHub and save them as markdown files argument-hint: None required - loads all open issues automatically allowed-tools: Bash(gh issue:*), Bash(mkdir:*), Write diff --git a/plugins/git/skills/merge-worktree/SKILL.md b/plugins/git/skills/merge-worktree/SKILL.md deleted file mode 100644 index 3c9e851..0000000 --- a/plugins/git/skills/merge-worktree/SKILL.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -name: git:merge-worktree -description: Merge changes from worktrees into current branch with selective file checkout, cherry-picking, interactive patch selection, or manual merge -argument-hint: file/directory path, commit name, branch name, or --interactive for guided mode -model: opus -allowed-tools: Bash(git worktree:*), Bash(git branch:*), Bash(git diff:*), Bash(git status:*), Bash(git checkout:*), Bash(git cherry-pick:*), Bash(git merge:*), Bash(git reset:*), Bash(git log:*), Bash(git restore:*), Bash(git add:*), Bash(ls:*), Bash(pwd:*), Bash(diff:*) ---- - -# Claude Command: Merge Worktree - -Your job is to help users merge changes from git worktrees into their current branch, supporting multiple merge strategies from simple file checkout to selective cherry-picking. - -## Instructions - -CRITICAL: Perform the following steps exactly as described: - -1. **Current state check**: Run `git worktree list` to show all existing worktrees and `git status` to verify working directory state - -2. **Parse user input**: Determine what merge operation the user wants: - - **`--interactive` or no arguments**: Guided interactive mode - - **File/directory path**: Merge specific file(s) or directory from a worktree - - **Commit name**: Cherry-pick a specific commit - - **Branch name**: Merge from that branch's worktree - - **`--from `**: Specify source worktree explicitly - - **`--patch` or `-p`**: Use interactive patch selection mode - -3. **Determine source worktree/branch**: - a. If user specified `--from `: Use that worktree path directly - b. If user specified a branch name: Find worktree for that branch from `git worktree list` - c. If only one other worktree exists: Ask to confirm using it as source - d. If multiple worktrees exist: Present list and ask user which to merge from - e. If no other worktrees exist: Explain and offer to use branch-based merge instead - -4. **Determine merge strategy**: Present options based on user's needs: - - **Strategy A: Selective File Checkout** (for specific files/directories) - - Best for: Getting complete file(s) from another branch - - Command: `git checkout -- ` - - **Strategy B: Interactive Patch Selection** (for partial file changes) - - Best for: Selecting specific hunks/lines from a file - - Command: `git checkout -p -- ` - - Prompts user for each hunk: y (apply), n (skip), s (split), e (edit) - - **Strategy C: Cherry-Pick with Selective Staging** (for specific commits) - - Best for: Applying a commit but excluding some changes - - Steps: - 1. `git cherry-pick --no-commit ` - 2. Review staged changes - 3. `git reset HEAD -- ` to unstage - 4. `git checkout -- ` to discard - 5. `git commit -m "message"` - - **Strategy D: Manual Merge with Conflicts** (for complex merges) - - Best for: Full branch merge with control over resolution - - Steps: - 1. `git merge --no-commit ` - 2. Review all changes - 3. Selectively stage/unstage files - 4. Resolve conflicts if any - 5. `git commit -m "message"` - - **Strategy E: Multi-Worktree Selective Merge** (combining from multiple sources) - - Best for: Taking different files from different worktrees - - Steps: - 1. `git checkout -- ` - 2. `git checkout -- ` - 3. `git commit -m "Merge selected files from multiple branches"` - -5. **Execute the selected strategy**: - - Run pre-merge comparison if user wants to review (suggest `/git:compare-worktrees` first) - - Execute git commands for the chosen strategy - - Handle any conflicts that arise - - Confirm changes before final commit - -6. **Post-merge summary**: Display what was merged: - - Files changed/added/removed - - Source worktree/branch - - Merge strategy used - -7. **Cleanup prompt**: After successful merge, ask: - - "Would you like to remove any worktrees to clean up local state?" - - If yes: List worktrees and ask which to remove - - Execute `git worktree remove ` for selected worktrees - - Remind about `git worktree prune` if needed - -## Merge Strategies Reference - -| Strategy | Use When | Command Pattern | -|----------|----------|-----------------| -| **Selective File** | Need complete file(s) from another branch | `git checkout -- ` | -| **Interactive Patch** | Need specific changes within a file | `git checkout -p -- ` | -| **Cherry-Pick Selective** | Need a commit but not all its changes | `git cherry-pick --no-commit` + selective staging | -| **Manual Merge** | Full branch merge with control | `git merge --no-commit` + selective staging | -| **Multi-Source** | Combining files from multiple branches | Multiple `git checkout -- ` | - -## Examples - -**Merge single file from worktree:** -```bash -> /git:merge-worktree src/app.js --from ../project-feature -# Prompts for merge strategy -# Executes: git checkout feature-branch -- src/app.js -``` - -**Interactive patch selection:** -```bash -> /git:merge-worktree src/utils.js --patch -# Lists available worktrees to select from -# Runs: git checkout -p feature-branch -- src/utils.js -# User selects hunks interactively (y/n/s/e) -``` - -**Cherry-pick specific commit:** -```bash -> /git:merge-worktree abc1234 -# Detects commit hash -# Asks: Apply entire commit or selective? -# If selective: git cherry-pick --no-commit abc1234 -# Then guides through unstaging unwanted changes -``` - -**Merge from multiple worktrees:** -```bash -> /git:merge-worktree --interactive -# "Select files to merge from different worktrees:" -# "From feature-1: src/moduleA.js" -# "From feature-2: src/moduleB.js, src/moduleC.js" -# Executes selective checkouts from each -``` - -**Full guided mode:** -```bash -> /git:merge-worktree -# Lists all worktrees -# Asks what to merge (files, commits, or branches) -# Guides through appropriate strategy -# Offers cleanup at end -``` - -**Directory merge with conflicts:** -```bash -> /git:merge-worktree src/components/ --from ../project-refactor -# Strategy D: Manual merge with conflicts -# git merge --no-commit refactor-branch -# Helps resolve any conflicts -# Reviews and commits selected changes -``` - -## Interactive Patch Mode Guide - -When using `--patch` or Strategy B, the user sees prompts for each change hunk: - -``` -@@ -10,6 +10,8 @@ function processData(input) { - const result = transform(input); -+ // Added validation -+ if (!isValid(result)) throw new Error('Invalid'); - return result; - } -Apply this hunk? [y,n,q,a,d,s,e,?] -``` - -| Key | Action | -|-----|--------| -| `y` | Apply this hunk | -| `n` | Skip this hunk | -| `q` | Quit (don't apply this or remaining hunks) | -| `a` | Apply this and all remaining hunks | -| `d` | Don't apply this or remaining hunks in this file | -| `s` | Split into smaller hunks | -| `e` | Manually edit the hunk | -| `?` | Show help | - -## Cherry-Pick Selective Workflow - -For Strategy C (cherry-picking with selective staging): - -```bash -# 1. Apply commit without committing -git cherry-pick --no-commit abc1234 - -# 2. Check what was staged -git status - -# 3. Unstage files you don't want -git reset HEAD -- path/to/unwanted.js - -# 4. Discard changes to those files -git checkout -- path/to/unwanted.js - -# 5. Commit the remaining changes -git commit -m "Cherry-pick selected changes from abc1234" -``` - -## Multi-Worktree Merge Workflow - -For Strategy E (merging from multiple worktrees): - -```bash -# Get files from different branches -git checkout feature-auth -- src/auth/login.js src/auth/session.js -git checkout feature-api -- src/api/endpoints.js -git checkout feature-ui -- src/components/Header.js - -# Review all changes -git status -git diff --cached - -# Commit combined changes -git commit -m "feat: combine auth, API, and UI improvements from feature branches" -``` - -## Common Workflows - -### Take a Feature File Without Full Merge -```bash -> /git:merge-worktree src/new-feature.js --from ../project-feature -# Gets just the file, not the entire branch -``` - -### Partial Bugfix from Hotfix Branch -```bash -> /git:merge-worktree --patch src/utils.js --from ../project-hotfix -# Select only the specific bug fix hunks, not all changes -``` - -### Combine Multiple PRs' Changes -```bash -> /git:merge-worktree --interactive -# Select specific files from PR-1 worktree -# Select other files from PR-2 worktree -# Combine into single coherent commit -``` - -### Pre-Merge Review -```bash -# First review what will be merged -> /git:compare-worktrees src/module.js -# Then merge with confidence -> /git:merge-worktree src/module.js --from ../project-feature -``` - -## Important Notes - -- **Working directory state**: Always ensure your working directory is clean before merging. Uncommitted changes can cause conflicts. - -- **Pre-merge review**: Consider using `/git:compare-worktrees` before merging to understand what changes will be applied. - -- **Conflict resolution**: If conflicts occur during merge, the command will help identify and resolve them before committing. - -- **No-commit flag**: Most strategies use `--no-commit` to give you control over the final commit message and what gets included. - -- **Shared repository**: All worktrees share the same Git object database, so commits made in any worktree are immediately visible to cherry-pick from any other. - -- **Branch locks**: Remember that branches can only be checked out in one worktree at a time. Use branch names for merge operations rather than creating duplicate worktrees. - -## Cleanup After Merge - -After merging, consider cleaning up worktrees that are no longer needed: - -```bash -# List worktrees -git worktree list - -# Remove specific worktree (clean state required) -git worktree remove ../project-feature - -# Force remove (discards uncommitted changes) -git worktree remove --force ../project-feature - -# Clean up stale worktree references -git worktree prune -``` - -The command will prompt you about cleanup after each successful merge to help maintain a tidy workspace. - -## Troubleshooting - -**"Cannot merge: working directory has uncommitted changes"** -- Commit or stash your current changes first -- Or use `git stash` before merge, `git stash pop` after - -**"Merge conflict in "** -- The command will show conflicted files -- Open files and resolve conflicts (look for `<<<<<<<` markers) -- Stage resolved files with `git add ` -- Continue with `git commit` - -**"Commit not found" when cherry-picking** -- Ensure the commit hash is correct -- Run `git log ` in any worktree to find commits -- Commits are shared across all worktrees - -**"Cannot checkout: file exists in working tree"** -- File has local modifications -- Either commit, stash, or discard local changes first -- Then retry the merge operation - -**"Branch not found for worktree"** -- The specified worktree may have been removed -- Run `git worktree list` to see current worktrees -- Use `git worktree prune` to clean up stale references - -## Integration with Other Commands - -**Pre-merge review:** -```bash -> /git:compare-worktrees src/ -> /git:merge-worktree src/specific-file.js -``` - -**Create worktree, merge, cleanup:** -```bash -> /git:create-worktree feature-branch -> /git:compare-worktrees src/ -> /git:merge-worktree src/module.js --from ../project-feature-branch -# After merge, cleanup is offered automatically -``` diff --git a/plugins/git/skills/worktrees/SKILL.md b/plugins/git/skills/worktrees/SKILL.md deleted file mode 100644 index cea08e4..0000000 --- a/plugins/git/skills/worktrees/SKILL.md +++ /dev/null @@ -1,526 +0,0 @@ ---- -name: git:worktrees -description: Use when working on multiple branches simultaneously, context switching without stashing, reviewing PRs while developing, testing in isolation, or comparing implementations across branches - provides git worktree commands and workflow patterns for parallel development with multiple working directories. ---- - -# Git Worktrees - -## Overview - -Git worktrees enable checking out multiple branches simultaneously in separate directories, all sharing the same repository. Create a worktree instead of stashing changes or cloning separately. - -**Core principle:** One worktree per active branch. Switch contexts by changing directories, not branches. - -## Core Concepts - -| Concept | Description | -|---------|-------------| -| **Main worktree** | Original working directory from `git clone` or `git init` | -| **Linked worktree** | Additional directories created with `git worktree add` | -| **Shared `.git`** | All worktrees share same Git object database (no duplication) | -| **Branch lock** | Each branch can only be checked out in ONE worktree at a time | -| **Worktree metadata** | Administrative files in `.git/worktrees/` tracking linked worktrees | - -## Quick Reference - -| Task | Command | -|------|---------| -| Create worktree (existing branch) | `git worktree add ` | -| Create worktree (new branch) | `git worktree add -b ` | -| Create worktree (new branch from ref) | `git worktree add -b ` | -| Create detached worktree | `git worktree add --detach ` | -| List all worktrees | `git worktree list` | -| Remove worktree | `git worktree remove ` | -| Force remove worktree | `git worktree remove --force ` | -| Move worktree | `git worktree move ` | -| Lock worktree | `git worktree lock ` | -| Unlock worktree | `git worktree unlock ` | -| Prune stale worktrees | `git worktree prune` | -| Repair worktree links | `git worktree repair` | -| Compare files between worktrees | `diff ../worktree-a/file ../worktree-b/file` | -| Get one file from another branch | `git checkout -- ` | -| Get partial file changes | `git checkout -p -- ` | -| Cherry-pick a commit | `git cherry-pick ` | -| Cherry-pick without committing | `git cherry-pick --no-commit ` | -| Merge without auto-commit | `git merge --no-commit ` | - -## Essential Commands - -### Create a Worktree - -```bash -# Create worktree with existing branch -git worktree add ../feature-x feature-x - -# Create worktree with new branch from current HEAD -git worktree add -b new-feature ../new-feature - -# Create worktree with new branch from specific commit -git worktree add -b hotfix-123 ../hotfix origin/main - -# Create worktree tracking remote branch -git worktree add --track -b feature ../feature origin/feature - -# Create worktree with detached HEAD (for experiments) -git worktree add --detach ../experiment HEAD~5 -``` - -### List Worktrees - -```bash -# Simple list -git worktree list - -# Verbose output with additional details -git worktree list -v - -# Machine-readable format (for scripting) -git worktree list --porcelain -``` - -**Example output:** - -``` -/home/user/project abc1234 [main] -/home/user/project-feature def5678 [feature-x] -/home/user/project-hotfix ghi9012 [hotfix-123] -``` - -### Remove a Worktree - -```bash -# Remove worktree (working directory must be clean) -git worktree remove ../feature-x - -# Force remove (discards uncommitted changes) -git worktree remove --force ../feature-x -``` - -### Move a Worktree - -```bash -# Relocate worktree to new path -git worktree move ../old-path ../new-path -``` - -### Lock/Unlock Worktrees - -```bash -# Lock worktree (prevents pruning if on removable storage) -git worktree lock ../feature-x -git worktree lock --reason "On USB drive" ../feature-x - -# Unlock worktree -git worktree unlock ../feature-x -``` - -### Prune Stale Worktrees - -```bash -# Remove stale worktree metadata (after manual directory deletion) -git worktree prune - -# Dry-run to see what would be pruned -git worktree prune --dry-run - -# Verbose output -git worktree prune -v -``` - -### Repair Worktrees - -```bash -# Repair worktree links after moving directories manually -git worktree repair - -# Repair specific worktree -git worktree repair ../feature-x -``` - -## Workflow Patterns - -### Pattern 1: Feature + Hotfix in Parallel - -To fix a bug while feature work is in progress: - -```bash -# Create worktree for hotfix from main -git worktree add -b hotfix-456 ../project-hotfix origin/main - -# Switch to hotfix directory, fix, commit, push -cd ../project-hotfix -git add . && git commit -m "fix: resolve critical bug #456" -git push origin hotfix-456 - -# Return to feature work -cd ../project - -# Clean up when done -git worktree remove ../project-hotfix -``` - -### Pattern 2: PR Review While Working - -To review a PR without affecting current work: - -```bash -# Fetch PR branch and create worktree -git fetch origin pull/123/head:pr-123 -git worktree add ../project-review pr-123 - -# Review: run tests, inspect code -cd ../project-review - -# Return to work, then clean up -cd ../project -git worktree remove ../project-review -git branch -d pr-123 -``` - -### Pattern 3: Compare Implementations - -To compare code across branches side-by-side: - -```bash -# Create worktrees for different versions -git worktree add ../project-v1 v1.0.0 -git worktree add ../project-v2 v2.0.0 - -# Diff, compare, or run both simultaneously -diff ../project-v1/src/module.js ../project-v2/src/module.js - -# Clean up -git worktree remove ../project-v1 -git worktree remove ../project-v2 -``` - -### Pattern 4: Long-Running Tasks - -To run tests/builds in isolation while continuing development: - -```bash -# Create worktree for CI-like testing -git worktree add ../project-test main - -# Start long-running tests in background -cd ../project-test && npm test & - -# Continue development in main worktree -cd ../project -``` - -### Pattern 5: Stable Reference - -To maintain a clean main checkout for reference: - -```bash -# Create permanent worktree for main branch -git worktree add ../project-main main - -# Lock to prevent accidental removal -git worktree lock --reason "Reference checkout" ../project-main -``` - -### Pattern 6: Selective Merging from Multiple Features - -To combine specific changes from multiple feature branches: - -```bash -# Create worktrees for each feature to review -git worktree add ../project-feature-1 feature-1 -git worktree add ../project-feature-2 feature-2 - -# Review changes in each worktree -diff ../project/src/module.js ../project-feature-1/src/module.js -diff ../project/src/module.js ../project-feature-2/src/module.js - -# From main worktree, selectively take changes -cd ../project -git checkout feature-1 -- src/moduleA.js src/utils.js -git checkout feature-2 -- src/moduleB.js -git commit -m "feat: combine selected changes from feature branches" - -# Or cherry-pick specific commits -git cherry-pick abc1234 # from feature-1 -git cherry-pick def5678 # from feature-2 - -# Clean up -git worktree remove ../project-feature-1 -git worktree remove ../project-feature-2 -``` - -## Comparing and Merging Changes Between Worktrees - -Since all worktrees share the same Git repository, you can compare files, cherry-pick commits, and selectively merge changes between them. - -### Compare and Review File Changes - -Since worktrees are just directories, you can compare files directly: - -```bash -# Compare specific file between worktrees -diff ../project-main/src/app.js ../project-feature/src/app.js - -# Use git diff to compare branches (works from any worktree) -git diff main..feature-branch -- src/app.js - -# Visual diff with your preferred tool -code --diff ../project-main/src/app.js ../project-feature/src/app.js - -# Compare entire directories -diff -r ../project-v1/src ../project-v2/src -``` - -### Merge Only One File from a Worktree - -You can selectively bring a single file from another branch using `git checkout`: - -```bash -# In your current branch, get a specific file from another branch -git checkout feature-branch -- path/to/file.js - -# Or get it from a specific commit -git checkout abc1234 -- path/to/file.js - -# Get multiple specific files -git checkout feature-branch -- src/module.js src/utils.js -``` - -For **partial file changes** (specific hunks/lines only): - -```bash -# Interactive patch mode - select which changes to take -git checkout -p feature-branch -- path/to/file.js -``` - -This prompts you to accept/reject each change hunk individually with options: -- `y` - apply this hunk -- `n` - skip this hunk -- `s` - split into smaller hunks -- `e` - manually edit the hunk - -### Cherry-Pick Commits from Worktrees - -Cherry-picking works at the commit level. Since all worktrees share the same repository, you can cherry-pick any commit: - -```bash -# Find the commit hash (from any worktree or git log) -git log feature-branch --oneline - -# Cherry-pick specific commit into your current branch -git cherry-pick abc1234 - -# Cherry-pick multiple commits -git cherry-pick abc1234 def5678 - -# Cherry-pick a range of commits -git cherry-pick abc1234^..def5678 - -# Cherry-pick without committing (stage changes only) -git cherry-pick --no-commit abc1234 -``` - -### Merge Changes from Multiple Worktrees - -You can merge or cherry-pick from multiple branches: - -```bash -# Merge multiple branches sequentially -git merge feature-1 -git merge feature-2 - -# Or use octopus merge for multiple branches at once -git merge feature-1 feature-2 feature-3 - -# Cherry-pick commits from multiple branches -git cherry-pick abc1234 # from feature-1 -git cherry-pick def5678 # from feature-2 -``` - -### Selective Merging - Pick Which Changes to Include - -#### Option 1: Selective File Checkout - -```bash -# Get specific files from different branches -git checkout feature-1 -- src/moduleA.js -git checkout feature-2 -- src/moduleB.js -git commit -m "Merge selected files from feature branches" -``` - -#### Option 2: Interactive Patch Selection - -```bash -# Select specific hunks from a file -git checkout -p feature-1 -- src/shared.js -``` - -#### Option 3: Cherry-Pick with Selective Staging - -```bash -# Apply changes without committing -git cherry-pick --no-commit abc1234 - -# Unstage what you don't want -git reset HEAD -- unwanted-file.js -git checkout -- unwanted-file.js - -# Commit only what you kept -git commit -m "Selected changes from feature-1" -``` - -#### Option 4: Merge with Manual Selection - -```bash -# Start merge but don't auto-commit -git merge --no-commit feature-1 - -# Review and modify staged changes -git status -git reset HEAD -- file-to-exclude.js -git checkout -- file-to-exclude.js - -# Commit your selection -git commit -m "Merge selected changes from feature-1" -``` - -#### Option 5: Using git restore (Git 2.23+) - -```bash -# Restore specific file from another branch -git restore --source=feature-branch -- path/to/file.js - -# Interactive restore with patch selection -git restore -p --source=feature-branch -- path/to/file.js -``` - -## Directory Structure Conventions - -Organize worktrees predictably: - -``` -~/projects/ - myproject/ # Main worktree (main/master branch) - myproject-feature-x/ # Feature branch worktree - myproject-hotfix/ # Hotfix worktree - myproject-review/ # Temporary PR review worktree -``` - -**Naming convention:** `-` or `-` - -## Best Practices - -| Practice | Rationale | -|----------|-----------| -| **Use sibling directories** | Keep worktrees at same level as main project for easy navigation | -| **Name by purpose** | `project-review` is clearer than `project-pr-123` | -| **Clean up promptly** | Remove worktrees when done to avoid confusion | -| **Lock remote worktrees** | Prevent pruning if worktree is on network/USB storage | -| **Use `--detach` for experiments** | Avoid creating throwaway branches | -| **Commit before removing** | Always commit or stash before `git worktree remove` | - -## Common Issues and Solutions - -### Issue: "Branch is already checked out" - -**Cause:** Attempting to checkout a branch that's active in another worktree. - -**Solution:** - -```bash -# Find where the branch is checked out -git worktree list - -# Either work in that worktree or remove it first -git worktree remove ../other-worktree -``` - -### Issue: Stale worktree after manual deletion - -**Cause:** Deleted worktree directory without using `git worktree remove`. - -**Solution:** - -```bash -# Clean up stale metadata -git worktree prune -``` - -### Issue: Worktree moved manually - -**Cause:** Moved worktree directory without using `git worktree move`. - -**Solution:** - -```bash -# Repair the worktree links -git worktree repair -# Or specify the new path -git worktree repair /new/path/to/worktree -``` - -### Issue: Worktree on removed drive - -**Cause:** Worktree was on removable storage that's no longer connected. - -**Solution:** - -```bash -# If temporary, lock it to prevent pruning -git worktree lock ../usb-worktree - -# If permanent, prune it -git worktree prune -``` - -## Common Mistakes - -| Mistake | Fix | -|---------|-----| -| Using `rm -rf` to delete worktree | Always use `git worktree remove`, then `git worktree prune` if needed | -| Forgetting branch is locked to worktree | Run `git worktree list` before checkout errors | -| Not cleaning up temporary worktrees | Remove worktrees immediately after task completion | -| Creating worktrees in nested locations | Use sibling directories (`../project-feature`) not subdirs | -| Moving worktree directory manually | Use `git worktree move` or run `git worktree repair` after | - -## Agent Workflow Integration - -To isolate parallel agent tasks: - -```bash -# Create worktree for isolated task -git worktree add -b task-123 ../project-task-123 -cd ../project-task-123 -# Make changes, run tests, return -cd ../project -``` - -To experiment safely with detached HEAD: - -```bash -# Create detached worktree (no branch to clean up) -git worktree add --detach ../project-experiment -cd ../project-experiment -# Experiment, then discard or commit to new branch -git worktree remove --force ../project-experiment -``` - -## Verification Checklist - -Before using worktrees: - -- [ ] Understand that branches can only be checked out in one worktree -- [ ] Know where worktrees will be created (use sibling directories) -- [ ] Plan cleanup strategy for temporary worktrees - -When creating worktrees: - -- [ ] Use descriptive directory names -- [ ] Verify branch is not already checked out elsewhere -- [ ] Consider using `--detach` for experiments - -When removing worktrees: - -- [ ] Commit or stash any uncommitted changes -- [ ] Use `git worktree remove`, not `rm -rf` -- [ ] Run `git worktree prune` if directory was deleted manually diff --git a/plugins/kaizen/.claude-plugin/plugin.json b/plugins/kaizen/.claude-plugin/plugin.json index 6a5b54f..49724b8 100644 --- a/plugins/kaizen/.claude-plugin/plugin.json +++ b/plugins/kaizen/.claude-plugin/plugin.json @@ -1,9 +1,9 @@ { - "name": "kaizen", - "version": "1.0.0", - "description": "Inspired by Japanese continuous improvement philosophy, Agile and Lean development practices. Introduces commands for analysis of root cause of issues and problems, including 5 Whys, Cause and Effect Analysis, and other techniques.", - "author": { - "name": "Vlad Goncharov", - "email": "vlad.goncharov@neolab.finance" - } + "name": "kaizen", + "version": "3.0.0", + "description": "Inspired by Japanese continuous improvement philosophy, Agile and Lean development practices. Introduces commands for analysis of root cause of issues and problems, including 5 Whys, Cause and Effect Analysis, and other techniques.", + "author": { + "name": "Vlad Goncharov", + "email": "vlad.goncharov@neolab.finance" + } } diff --git a/plugins/kaizen/README.md b/plugins/kaizen/README.md index 2372662..f7fb672 100644 --- a/plugins/kaizen/README.md +++ b/plugins/kaizen/README.md @@ -24,25 +24,25 @@ They are based on the idea that most bugs and quality issues are symptoms of dee /plugin install kaizen@NeoLabHQ/context-engineering-kit # Investigate a bug's root cause -> /kaizen:why "API returns 500 error on checkout" +> /why "API returns 500 error on checkout" # Analyze code for improvement opportunities -> /kaizen:analyse src/checkout/ +> /analyse src/checkout/ # Document a complex problem comprehensively -> /kaizen:analyse-problem "Database connection exhaustion during peak traffic" +> /analyse-problem "Database connection exhaustion during peak traffic" ``` [Usage Examples](./usage-examples.md) ## Commands -- [/kaizen:why](./why.md) - Five Whys Root Cause Analysis. Iterative questioning technique that drills from surface symptoms to fundamental root causes by repeatedly asking "why." -- [/kaizen:root-cause-tracing](./root-cause-tracing.md) - Bug Tracing Through Call Stack. Systematically traces bugs backward through the call stack to identify where invalid data or incorrect behavior originates. -- [/kaizen:cause-and-effect](./cause-and-effect.md) - Fishbone Analysis. Systematic exploration of problem causes across six categories using the Ishikawa (Fishbone) diagram approach. -- [/kaizen:analyse-problem](./analyse-problem.md) - A3 Problem Analysis. Comprehensive one-page problem documentation using the A3 format, covering Background, Current Condition, Goal, Root Cause, Countermeasures, Implementation Plan, and Follow-up. -- [/kaizen:analyse](./analyse.md) - Smart Analysis Method Selection. Intelligently selects and applies the most appropriate Kaizen analysis technique based on what you're analyzing: Gemba Walk, Value Stream Mapping, or Muda (Waste) Analysis. -- [/kaizen:plan-do-check-act](./plan-do-check-act.md) - PDCA Improvement Cycle. Four-phase iterative cycle for continuous improvement through systematic experimentation: Plan, Do, Check, Act. +- [/why](./why.md) - Five Whys Root Cause Analysis. Iterative questioning technique that drills from surface symptoms to fundamental root causes by repeatedly asking "why." +- [/root-cause-tracing](./root-cause-tracing.md) - Bug Tracing Through Call Stack. Systematically traces bugs backward through the call stack to identify where invalid data or incorrect behavior originates. +- [/cause-and-effect](./cause-and-effect.md) - Fishbone Analysis. Systematic exploration of problem causes across six categories using the Ishikawa (Fishbone) diagram approach. +- [/analyse-problem](./analyse-problem.md) - A3 Problem Analysis. Comprehensive one-page problem documentation using the A3 format, covering Background, Current Condition, Goal, Root Cause, Countermeasures, Implementation Plan, and Follow-up. +- [/analyse](./analyse.md) - Smart Analysis Method Selection. Intelligently selects and applies the most appropriate Kaizen analysis technique based on what you're analyzing: Gemba Walk, Value Stream Mapping, or Muda (Waste) Analysis. +- [/plan-do-check-act](./plan-do-check-act.md) - PDCA Improvement Cycle. Four-phase iterative cycle for continuous improvement through systematic experimentation: Plan, Do, Check, Act. ## Skills diff --git a/plugins/kaizen/skills/analyse-problem/SKILL.md b/plugins/kaizen/skills/analyse-problem/SKILL.md index 3c699e8..e5520d0 100644 --- a/plugins/kaizen/skills/analyse-problem/SKILL.md +++ b/plugins/kaizen/skills/analyse-problem/SKILL.md @@ -1,5 +1,5 @@ --- -name: kaizen:analyse-problem +name: analyse-problem description: Comprehensive A3 one-page problem analysis with root cause and action plan argument-hint: Optional problem description to document --- diff --git a/plugins/kaizen/skills/analyse/SKILL.md b/plugins/kaizen/skills/analyse/SKILL.md index c1cb4b9..a74e0b8 100644 --- a/plugins/kaizen/skills/analyse/SKILL.md +++ b/plugins/kaizen/skills/analyse/SKILL.md @@ -1,5 +1,5 @@ --- -name: kaizen:analyse +name: analyse description: Auto-selects best Kaizen method (Gemba Walk, Value Stream, or Muda) for target argument-hint: Optional target description (e.g., code, workflow, or inefficiencies) --- diff --git a/plugins/kaizen/skills/cause-and-effect/SKILL.md b/plugins/kaizen/skills/cause-and-effect/SKILL.md index 419a0e1..d10f739 100644 --- a/plugins/kaizen/skills/cause-and-effect/SKILL.md +++ b/plugins/kaizen/skills/cause-and-effect/SKILL.md @@ -1,5 +1,5 @@ --- -name: kaizen:cause-and-effect +name: cause-and-effect description: Systematic Fishbone analysis exploring problem causes across six categories argument-hint: Optional problem description to analyze --- diff --git a/plugins/kaizen/skills/kaizen/SKILL.md b/plugins/kaizen/skills/kaizen/SKILL.md index 8fc3f1b..1696ec2 100644 --- a/plugins/kaizen/skills/kaizen/SKILL.md +++ b/plugins/kaizen/skills/kaizen/SKILL.md @@ -1,5 +1,5 @@ --- -name: kaizen:kaizen +name: kaizen description: Use when Code implementation and refactoring, architecturing or designing systems, process and workflow improvements, error handling and validation. Provide tehniquest to avoid over-engineering and apply iterative improvements. --- diff --git a/plugins/kaizen/skills/plan-do-check-act/SKILL.md b/plugins/kaizen/skills/plan-do-check-act/SKILL.md index fd30d52..f728e92 100644 --- a/plugins/kaizen/skills/plan-do-check-act/SKILL.md +++ b/plugins/kaizen/skills/plan-do-check-act/SKILL.md @@ -1,5 +1,5 @@ --- -name: kaizen:plan-do-check-act +name: plan-do-check-act description: Iterative PDCA cycle for systematic experimentation and continuous improvement argument-hint: Optional improvement goal or problem to address --- diff --git a/plugins/kaizen/skills/root-cause-tracing/SKILL.md b/plugins/kaizen/skills/root-cause-tracing/SKILL.md index 2386850..510fd09 100644 --- a/plugins/kaizen/skills/root-cause-tracing/SKILL.md +++ b/plugins/kaizen/skills/root-cause-tracing/SKILL.md @@ -1,5 +1,5 @@ --- -name: kaizen:root-cause-tracing +name: root-cause-tracing description: Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation when needed, to identify source of invalid data or incorrect behavior --- diff --git a/plugins/kaizen/skills/why/SKILL.md b/plugins/kaizen/skills/why/SKILL.md index de350ac..e45c0bd 100644 --- a/plugins/kaizen/skills/why/SKILL.md +++ b/plugins/kaizen/skills/why/SKILL.md @@ -1,5 +1,5 @@ --- -name: kaizen:why +name: why description: Iterative Five Whys root cause analysis drilling from symptoms to fundamentals argument-hint: Optional issue or symptom description --- diff --git a/plugins/mcp/.claude-plugin/plugin.json b/plugins/mcp/.claude-plugin/plugin.json index aff9a16..f4110c1 100644 --- a/plugins/mcp/.claude-plugin/plugin.json +++ b/plugins/mcp/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "mcp", - "version": "1.2.1", + "version": "3.0.0", "description": "Commands for setup well known MCP server integration if needed and update CLAUDE.md file with requirement to use this MCP server for current project.", "author": { "name": "Vlad Goncharov", diff --git a/plugins/mcp/skills/build-mcp/SKILL.md b/plugins/mcp/skills/build-mcp/SKILL.md index c67b0e2..5a1e6e6 100644 --- a/plugins/mcp/skills/build-mcp/SKILL.md +++ b/plugins/mcp/skills/build-mcp/SKILL.md @@ -1,5 +1,5 @@ --- -name: mcp:build-mcp +name: build-mcp description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). --- diff --git a/plugins/mcp/skills/setup-arxiv-mcp/SKILL.md b/plugins/mcp/skills/setup-arxiv-mcp/SKILL.md index 14bfadf..8282cde 100644 --- a/plugins/mcp/skills/setup-arxiv-mcp/SKILL.md +++ b/plugins/mcp/skills/setup-arxiv-mcp/SKILL.md @@ -1,5 +1,5 @@ --- -name: mcp:setup-arxiv-mcp +name: setup-arxiv-mcp description: Guide for setup arXiv paper search MCP server using Docker MCP argument-hint: Optional - specific research topics or paper sources to configure --- diff --git a/plugins/mcp/skills/setup-codemap-cli/SKILL.md b/plugins/mcp/skills/setup-codemap-cli/SKILL.md index 73e3208..bc85b2f 100644 --- a/plugins/mcp/skills/setup-codemap-cli/SKILL.md +++ b/plugins/mcp/skills/setup-codemap-cli/SKILL.md @@ -1,5 +1,5 @@ --- -name: mcp:setup-codemap-cli +name: setup-codemap-cli description: Guide for setup Codemap CLI for intelligent codebase visualization and navigation argument-hint: Optional - specific configuration preferences or OS type --- diff --git a/plugins/mcp/skills/setup-context7-mcp/SKILL.md b/plugins/mcp/skills/setup-context7-mcp/SKILL.md index 2bd1628..cfdefd0 100644 --- a/plugins/mcp/skills/setup-context7-mcp/SKILL.md +++ b/plugins/mcp/skills/setup-context7-mcp/SKILL.md @@ -1,5 +1,5 @@ --- -name: mcp:setup-context7-mcp +name: setup-context7-mcp description: Guide for setup Context7 MCP server to load documentation for specific technologies. argument-hint: List of languages and frameworks to load documentation for --- diff --git a/plugins/mcp/skills/setup-serena-mcp/SKILL.md b/plugins/mcp/skills/setup-serena-mcp/SKILL.md index a638b14..d1861c5 100644 --- a/plugins/mcp/skills/setup-serena-mcp/SKILL.md +++ b/plugins/mcp/skills/setup-serena-mcp/SKILL.md @@ -1,5 +1,5 @@ --- -name: mcp:setup-serena-mcp +name: setup-serena-mcp description: Guide for setup Serena MCP server for semantic code retrieval and editing capabilities argument-hint: Optional - specific configuration preferences or client type --- diff --git a/plugins/reflexion/.claude-plugin/plugin.json b/plugins/reflexion/.claude-plugin/plugin.json index 468b5d7..f93cc94 100644 --- a/plugins/reflexion/.claude-plugin/plugin.json +++ b/plugins/reflexion/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "reflexion", - "version": "1.1.4", + "version": "3.0.0", "description": "Collection of commands that force LLM to reflect on previous response and output. Based on papers like Self-Refine and Reflexion. These techniques improve the output of large language models by introducing feedback and refinement loops.", "author": { "name": "Vlad Goncharov", diff --git a/plugins/reflexion/README.md b/plugins/reflexion/README.md index 525e49e..4d42e7d 100644 --- a/plugins/reflexion/README.md +++ b/plugins/reflexion/README.md @@ -83,9 +83,9 @@ The plugin includes optional hooks that automatically trigger reflection when yo ## Commands -- [/reflexion:reflect](./reflect.md) - Self-Refinement. Reflect on previous response and output, based on Self-refinement framework for iterative improvement with complexity triage and verification -- [/reflexion:critique](./critique.md) - Multi-Perspective Critique. Memorize insights from reflections and updates CLAUDE.md file with this knowledge. Curates insights from reflections and critiques into CLAUDE.md using Agentic Context Engineering -- [/reflexion:memorize](./memorize.md) - Memorize insights from reflections and updates CLAUDE.md file with this knowledge. Curates insights from reflections and critiques into CLAUDE.md using Agentic Context Engineering +- [/reflect](./reflect.md) - Self-Refinement. Reflect on previous response and output, based on Self-refinement framework for iterative improvement with complexity triage and verification +- [/critique](./critique.md) - Multi-Perspective Critique. Comprehensive multi-perspective review using specialized judges with debate and consensus building +- [/memorize](./memorize.md) - Memory Updates. Curates insights from reflections and critiques into CLAUDE.md using Agentic Context Engineering ## Theoretical Foundation diff --git a/plugins/reflexion/skills/critique/SKILL.md b/plugins/reflexion/skills/critique/SKILL.md index 6df383a..7dac52e 100644 --- a/plugins/reflexion/skills/critique/SKILL.md +++ b/plugins/reflexion/skills/critique/SKILL.md @@ -1,5 +1,5 @@ --- -name: reflexion:critique +name: critique description: Comprehensive multi-perspective review using specialized judges with debate and consensus building argument-hint: Optional file paths, commits, or context to review (defaults to recent changes) --- diff --git a/plugins/reflexion/skills/memorize/SKILL.md b/plugins/reflexion/skills/memorize/SKILL.md index 434fe5d..b0d9870 100644 --- a/plugins/reflexion/skills/memorize/SKILL.md +++ b/plugins/reflexion/skills/memorize/SKILL.md @@ -1,5 +1,5 @@ --- -name: reflexion:memorize +name: memorize description: Curates insights from reflections and critiques into CLAUDE.md using Agentic Context Engineering argument-hint: Optional source specification (last, selection, chat:) or --dry-run for preview --- diff --git a/plugins/reflexion/skills/reflect/SKILL.md b/plugins/reflexion/skills/reflect/SKILL.md index a8438eb..8131b08 100644 --- a/plugins/reflexion/skills/reflect/SKILL.md +++ b/plugins/reflexion/skills/reflect/SKILL.md @@ -1,5 +1,5 @@ --- -name: reflexion:reflect +name: reflect description: Reflect on previus response and output, based on Self-refinement framework for iterative improvement with complexity triage and verification argument-hint: Optional focus area or confidence threshold to use, for example "security" or "deep reflect if less than 90% confidence" --- diff --git a/plugins/code-review/.claude-plugin/plugin.json b/plugins/review/.claude-plugin/plugin.json similarity index 81% rename from plugins/code-review/.claude-plugin/plugin.json rename to plugins/review/.claude-plugin/plugin.json index bc43927..fdeb613 100644 --- a/plugins/code-review/.claude-plugin/plugin.json +++ b/plugins/review/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { - "name": "code-review", - "version": "1.1.1", + "name": "review", + "version": "3.0.0", "description": "Introduce codebase and PR review commands and skills using multiple specialized agents.", "author": { "name": "Vlad Goncharov", diff --git a/docs/plugins/code-review/README.md b/plugins/review/README.md similarity index 82% rename from docs/plugins/code-review/README.md rename to plugins/review/README.md index 2f286cb..97a3ade 100644 --- a/docs/plugins/code-review/README.md +++ b/plugins/review/README.md @@ -1,4 +1,4 @@ -# Code Review Plugin +# Review Plugin Comprehensive multi-agent code review system that examines code from multiple specialized perspectives to catch bugs, security issues, and quality problems before they reach production. @@ -17,10 +17,10 @@ The Code Review plugin implements a multi-agent code review system where special ```bash # Install the plugin -/plugin install code-review@NeoLabHQ/context-engineering-kit +/plugin install review@NeoLabHQ/context-engineering-kit # Review uncommitted local changes -> /code-review:review-local-changes +> /review-local-changes ``` @@ -28,20 +28,20 @@ The Code Review plugin implements a multi-agent code review system where special ```bash # Review with lower impact threshold -> /code-review:review-local-changes --min-impact medium +> /review-local-changes --min-impact medium # Review a pull request -> /code-review:review-pr #123 +> /review-pr #123 # Review PR with only critical issues -> /code-review:review-pr --min-impact critical +> /review-pr --min-impact critical ``` [Usage Examples](./usage-examples.md) ## CI/CD Integration -You can integrate this plugin with your CI/CD pipeline by using Official Anthropics Claude Code Action. See [CI/CD Integration](../../guides/ci-integration.md) for more details. +You can intergreate this plugin with your CI/CD pipeline by using Offical Anthropics Claude Code Action. See [CI/CD Integration](../../guides/ci-integration.md) for more details. ## Agent Architecture @@ -62,8 +62,8 @@ Code Review Command ## Commands -- [/code-review:review-local-changes](./review-local-changes.md) - Local Changes Review with `--min-impact` filtering and `--json` output -- [/code-review:review-pr](./review-pr.md) - Pull Request Review with `--min-impact` filtering for inline comments +- [/review-local-changes](./review-local-changes.md) - Local Changes Review +- [/review-pr](./review-pr.md) - Pull Request Review ## Review Agents @@ -149,7 +149,7 @@ on: pull_request: types: - opened - - synchronize # remove if want to run only, when PR is opened + - synchronize # remove if want to run only when PR is opened - ready_for_review - reopened # Uncomment to limit which files can trigger the workflow @@ -179,7 +179,7 @@ jobs: uses: actions/checkout@v4 with: fetch-depth: 1 - + - name: Run Claude Code Review id: claude-review uses: anthropics/claude-code-action@v1 @@ -189,12 +189,12 @@ jobs: use_sticky_comment: true plugin_marketplaces: https://github.com/NeoLabHQ/context-engineering-kit.git - plugins: "code-review@context-engineering-kit\ngit@context-engineering-kit\ntdd@context-engineering-kit\nsadd@context-engineering-kit\nddd@context-engineering-kit\nsdd@context-engineering-kit\nkaizen@context-engineering-kit" + plugins: "review@context-engineering-kit\ngit@context-engineering-kit\ntdd@context-engineering-kit\nsadd@context-engineering-kit\nddd@context-engineering-kit\nsdd@context-engineering-kit\nkaizen@context-engineering-kit" - prompt: '/code-review:review-pr ${{ github.repository }}/pull/${{ github.event.pull_request.number }} Note: The PR branch is already checked out in the current working directory.' + prompt: '/review-pr ${{ github.repository }}/pull/${{ github.event.pull_request.number }} Note: The PR branch is already checked out in the current working directory.' # Skill and Bash(gh pr comment:*) is required for review, the rest is optional, but recommended for better context and quality of the review. - claude_args: '--allowed-tools "Skill,Bash,Glob,Grep,Read,Task,mcp__github_inline_comment__create_inline_comment,Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr edit:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh api:*)"' + claude_args: '--allowed-tools "Skill,Bash,Glob,Grep,Read,Task,mcp__github_inline_comment__create_inline_comment,Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr edit:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh api:*)" --system-prompt "Follow /review-pr skill EXACTLY!!!"' ``` ## Output Formats diff --git a/plugins/code-review/agents/bug-hunter.md b/plugins/review/agents/bug-hunter.md similarity index 100% rename from plugins/code-review/agents/bug-hunter.md rename to plugins/review/agents/bug-hunter.md diff --git a/plugins/code-review/agents/code-quality-reviewer.md b/plugins/review/agents/code-quality-reviewer.md similarity index 100% rename from plugins/code-review/agents/code-quality-reviewer.md rename to plugins/review/agents/code-quality-reviewer.md diff --git a/plugins/code-review/agents/contracts-reviewer.md b/plugins/review/agents/contracts-reviewer.md similarity index 100% rename from plugins/code-review/agents/contracts-reviewer.md rename to plugins/review/agents/contracts-reviewer.md diff --git a/plugins/code-review/agents/historical-context-reviewer.md b/plugins/review/agents/historical-context-reviewer.md similarity index 100% rename from plugins/code-review/agents/historical-context-reviewer.md rename to plugins/review/agents/historical-context-reviewer.md diff --git a/plugins/code-review/agents/security-auditor.md b/plugins/review/agents/security-auditor.md similarity index 100% rename from plugins/code-review/agents/security-auditor.md rename to plugins/review/agents/security-auditor.md diff --git a/plugins/code-review/agents/test-coverage-reviewer.md b/plugins/review/agents/test-coverage-reviewer.md similarity index 100% rename from plugins/code-review/agents/test-coverage-reviewer.md rename to plugins/review/agents/test-coverage-reviewer.md diff --git a/plugins/code-review/skills/review-local-changes/SKILL.md b/plugins/review/skills/review-local-changes/SKILL.md similarity index 99% rename from plugins/code-review/skills/review-local-changes/SKILL.md rename to plugins/review/skills/review-local-changes/SKILL.md index dbdf99f..5ae3766 100644 --- a/plugins/code-review/skills/review-local-changes/SKILL.md +++ b/plugins/review/skills/review-local-changes/SKILL.md @@ -1,5 +1,5 @@ --- -name: code-review:review-local-changes +name: review-local-changes description: Comprehensive review of local uncommitted changes using specialized agents with code improvement suggestions argument-hint: "[review-aspects] [--min-impact critical|high|medium|medium-low|low] [--json]" --- diff --git a/plugins/code-review/skills/review-pr/SKILL.md b/plugins/review/skills/review-pr/SKILL.md similarity index 99% rename from plugins/code-review/skills/review-pr/SKILL.md rename to plugins/review/skills/review-pr/SKILL.md index 035048e..6555b47 100644 --- a/plugins/code-review/skills/review-pr/SKILL.md +++ b/plugins/review/skills/review-pr/SKILL.md @@ -1,5 +1,5 @@ --- -name: code-review:review-pr +name: review-pr description: Comprehensive pull request review using specialized agents argument-hint: "[review-aspects] [--min-impact critical|high|medium|medium-low|low]" --- diff --git a/plugins/sadd/.claude-plugin/plugin.json b/plugins/sadd/.claude-plugin/plugin.json index 7fab63b..fc3cf63 100644 --- a/plugins/sadd/.claude-plugin/plugin.json +++ b/plugins/sadd/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "sadd", - "version": "1.3.3", + "version": "3.0.0", "description": "Introduces skills for subagent-driven development, dispatches fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates.", "author": { "name": "Vlad Goncharov", diff --git a/plugins/sadd/skills/do-and-judge/SKILL.md b/plugins/sadd/skills/do-and-judge/SKILL.md index 22915ec..6445989 100644 --- a/plugins/sadd/skills/do-and-judge/SKILL.md +++ b/plugins/sadd/skills/do-and-judge/SKILL.md @@ -1,5 +1,5 @@ --- -name: sadd:do-and-judge +name: do-and-judge description: Execute a task with sub-agent implementation and LLM-as-a-judge verification with automatic retry loop argument-hint: Task description (e.g., "Refactor the UserService class to use dependency injection") --- diff --git a/plugins/sadd/skills/do-competitively/SKILL.md b/plugins/sadd/skills/do-competitively/SKILL.md index bd3b69f..d021a7c 100644 --- a/plugins/sadd/skills/do-competitively/SKILL.md +++ b/plugins/sadd/skills/do-competitively/SKILL.md @@ -1,5 +1,5 @@ --- -name: sadd:do-competitively +name: do-competitively description: Execute tasks through competitive multi-agent generation, meta-judge evaluation specification, multi-judge evaluation, and evidence-based synthesis argument-hint: Task description and optional output path/criteria --- diff --git a/plugins/sadd/skills/do-in-parallel/SKILL.md b/plugins/sadd/skills/do-in-parallel/SKILL.md index 70e0132..4e9e542 100644 --- a/plugins/sadd/skills/do-in-parallel/SKILL.md +++ b/plugins/sadd/skills/do-in-parallel/SKILL.md @@ -1,5 +1,5 @@ --- -name: sadd:do-in-parallel +name: do-in-parallel description: Launch multiple sub-agents in parallel to execute tasks across files or targets with intelligent model selection, quality-focused prompting, and meta-judge → LLM-as-a-judge verification argument-hint: Task description [--files "file1.ts,file2.ts,..."] [--targets "target1,target2,..."] [--model opus|sonnet|haiku] [--output ] --- diff --git a/plugins/sadd/skills/do-in-steps/SKILL.md b/plugins/sadd/skills/do-in-steps/SKILL.md index 1ea213d..a372c13 100644 --- a/plugins/sadd/skills/do-in-steps/SKILL.md +++ b/plugins/sadd/skills/do-in-steps/SKILL.md @@ -1,5 +1,5 @@ --- -name: sadd:do-in-steps +name: do-in-steps description: Execute complex tasks through sequential sub-agent orchestration with intelligent model selection, meta-judge → LLM-as-a-judge verification argument-hint: Task description (e.g., "Refactor UserService class and update all consumers") --- diff --git a/plugins/sadd/skills/judge-with-debate/SKILL.md b/plugins/sadd/skills/judge-with-debate/SKILL.md index 370cbda..3b257dc 100644 --- a/plugins/sadd/skills/judge-with-debate/SKILL.md +++ b/plugins/sadd/skills/judge-with-debate/SKILL.md @@ -1,5 +1,5 @@ --- -name: sadd:judge-with-debate +name: judge-with-debate description: Evaluate solutions through multi-round debate between independent judges until consensus argument-hint: Solution path(s) and evaluation criteria --- diff --git a/plugins/sadd/skills/judge/SKILL.md b/plugins/sadd/skills/judge/SKILL.md index 8b3ec36..6bd2ec6 100644 --- a/plugins/sadd/skills/judge/SKILL.md +++ b/plugins/sadd/skills/judge/SKILL.md @@ -1,5 +1,5 @@ --- -name: sadd:judge +name: judge description: Launch a meta-judge then a judge sub-agent to evaluate results produced in the current conversation argument-hint: "[evaluation-focus]" --- diff --git a/plugins/sadd/skills/launch-sub-agent/SKILL.md b/plugins/sadd/skills/launch-sub-agent/SKILL.md index aa36a33..a7bf91d 100644 --- a/plugins/sadd/skills/launch-sub-agent/SKILL.md +++ b/plugins/sadd/skills/launch-sub-agent/SKILL.md @@ -1,5 +1,5 @@ --- -name: sadd:launch-sub-agent +name: launch-sub-agent description: Launch an intelligent sub-agent with automatic model selection based on task complexity, specialized agent matching, Zero-shot CoT reasoning, and mandatory self-critique verification argument-hint: Task description (e.g., "Implement user authentication" or "Research caching strategies") [--model opus|sonnet|haiku] [--agent ] [--output ] --- diff --git a/plugins/sadd/skills/multi-agent-patterns/SKILL.md b/plugins/sadd/skills/multi-agent-patterns/SKILL.md index 00d576a..66f7e37 100644 --- a/plugins/sadd/skills/multi-agent-patterns/SKILL.md +++ b/plugins/sadd/skills/multi-agent-patterns/SKILL.md @@ -1,5 +1,5 @@ --- -name: sadd:multi-agent-patterns +name: multi-agent-patterns description: Design multi-agent architectures for complex tasks. Use when single-agent context limits are exceeded, when tasks decompose naturally into subtasks, or when specializing agents improves quality. --- diff --git a/plugins/sadd/skills/subagent-driven-development/SKILL.md b/plugins/sadd/skills/subagent-driven-development/SKILL.md index 50da0f4..c5693fa 100644 --- a/plugins/sadd/skills/subagent-driven-development/SKILL.md +++ b/plugins/sadd/skills/subagent-driven-development/SKILL.md @@ -1,5 +1,5 @@ --- -name: sadd:subagent-driven-development +name: subagent-driven-development description: Use when executing implementation plans with independent tasks in the current session or facing 3+ independent issues that can be investigated without shared state or dependencies - dispatches fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates --- diff --git a/plugins/sadd/skills/tree-of-thoughts/SKILL.md b/plugins/sadd/skills/tree-of-thoughts/SKILL.md index 0e90d0f..7ef2dbc 100644 --- a/plugins/sadd/skills/tree-of-thoughts/SKILL.md +++ b/plugins/sadd/skills/tree-of-thoughts/SKILL.md @@ -1,5 +1,5 @@ --- -name: sadd:tree-of-thoughts +name: tree-of-thoughts description: Execute tasks through systematic exploration, pruning, and expansion using Tree of Thoughts methodology with meta-judge evaluation specifications and multi-agent evaluation argument-hint: Task description and optional output path/criteria --- diff --git a/plugins/sdd/.claude-plugin/plugin.json b/plugins/sdd/.claude-plugin/plugin.json index fa17f32..4a2cf88 100644 --- a/plugins/sdd/.claude-plugin/plugin.json +++ b/plugins/sdd/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "sdd", - "version": "2.1.1", + "version": "3.0.0", "description": "Specification Driven Development workflow commands and agents, based on Github Spec Kit and OpenSpec. Uses specialized agents for effective context management and quality review.", "author": { "name": "Vlad Goncharov", diff --git a/plugins/sdd/README.md b/plugins/sdd/README.md index a657813..515b582 100644 --- a/plugins/sdd/README.md +++ b/plugins/sdd/README.md @@ -6,13 +6,13 @@ This plugin is designed to consistently and reproducibly produce working code. I ## Key Features -- **Development as compilation** — The plugin functions like a "compilation" or "nightly build" for your development process: `task specs → run /sdd:implement → working code`. After writing your prompt, you can launch the plugin and expect a functional result when you return. The completion time depends on task complexity — simple tasks may finish within 30 minutes, while complex ones can take several days. +- **Development as compilation** — The plugin functions like a "compilation" or "nightly build" for your development process: `task specs → run /implement-task → working code`. After writing your prompt, you can launch the plugin and expect a functional result when you return. The completion time depends on task complexity — simple tasks may finish within 30 minutes, while complex ones can take several days. - **Benchmark-level quality in real life** — Model benchmarks improve with each release, yet real-world results often stagnate. This is because benchmarks reflect the best possible output a model can achieve, whereas in practice LLMs tend to drift toward sub-optimal, non-functional solutions. This plugin uses a variety of patterns to keep the model operating at peak performance. - **Customizable** — Balance result quality and process speed by adjusting command parameters. Learn more in the [Customization](customization.md) section. - **Developer time-efficiency** — The overall process is designed to minimize developer time and reduce the number of interactions, while still producing results superior to what a model can generate from scratch. However, overall quality is proportional to the time invested in iterating on and refining the specification. - **Industry-standard** — The plugin's specification template is based on the arc42 standard, adjusted for LLM capabilities. Arc42 is a widely adopted, high-quality standard for software development documentation used by many organizations. - **Works best in complex or large codebases** — While most other frameworks work best for new projects and greenfield development, this plugin is designed to perform better as your codebase grows and your architecture becomes more structured. Each planning phase includes a **codebase impact analysis** step that evaluates which files may be affected and which patterns to follow to achieve the desired result. -- **Simple** — This plugin avoids unnecessary complexity by primarily using only three commands, offloading process complexity to the model via multi-agent orchestration. `/sdd:implement` is a single command that produces functional code from a task specification. To create that specification, you run `/sdd:add-task` and `/sdd:plan`, which analyze your prompt and iteratively refine the specification until it meets the required quality standards. +- **Simple** — This plugin avoids unnecessary complexity by primarily using only three commands, offloading process complexity to the model via multi-agent orchestration. `/implement-task` is a single command that produces functional code from a task specification. To create that specification, you run `/sdd:add-task` and `/plan-task`, which analyze your prompt and iteratively refine the specification until it meets the required quality standards. ## Quick Start @@ -31,10 +31,10 @@ Then run the following commands: ```bash # Create the .specs/tasks/draft/design-auth-middleware.feature.md file with the initial prompt -/sdd:add-task "Design and implement authentication middleware with JWT support" +/add-task "Design and implement authentication middleware with JWT support" # Write a detailed specification for the task -/sdd:plan +/plan-task # Moves the task to the .specs/tasks/todo/ folder ``` @@ -42,7 +42,7 @@ Run `/clear` (or re-open Claude Code) to clear context and start fresh. Then run ```bash # Implement the task -/sdd:implement @.specs/tasks/todo/design-auth-middleware.feature.md +/implement-task @.specs/tasks/todo/design-auth-middleware.feature.md # Produces a working implementation and moves the task to the .specs/tasks/done/ folder ``` @@ -54,19 +54,19 @@ Run `/clear` (or re-open Claude Code) to clear context and start fresh. Then run End-to-end task implementation process from initial prompt to pull request, including commands from the [git](../git/README.md) plugin: -- `/sdd:add-task` → Creates a `.specs/tasks/draft/..md` file with the initial task description. -- `/sdd:plan` → Generates a `.claude/skills//SKILL.md` file with the skills needed to implement the task (by analyzing the library and framework documentation used in the codebase), then updates the task file with a refined specification and moves it to `.specs/tasks/todo/`. -- `/sdd:implement` → Produces a working implementation, verifies it, then moves the task to `.specs/tasks/done/`. -- `/git:commit` → Commits changes. -- `/git:create-pr` → Creates a pull request. +- `/add-task` → Creates a `.specs/tasks/draft/..md` file with the initial task description. +- `/plan-task` → Generates a `.claude/skills//SKILL.md` file with the skills needed to implement the task (by analyzing the library and framework documentation used in the codebase), then updates the task file with a refined specification and moves it to `.specs/tasks/todo/`. +- `/implement-task` → Produces a working implementation, verifies it, then moves the task to `.specs/tasks/done/`. +- `/commit` → Commits changes. +- `/create-pr` → Creates a pull request. ``` 1. Create 2. Plan 3. Implement 4. Ship +-------------+ +-----------+ +---------------+ +-----------------+ -|/sdd:add-task| | /sdd:plan | |/sdd:implement | | /git:commit | +|/add-task| | /plan-task | |/implement-task| | /commit | +------+------+ +-----+-----+ +------+--------+ | | | | | | | v | - v v v |/git:create-pr | + v v v |/create-pr | +-------+---------+ | Task Lifecycle | @@ -80,14 +80,14 @@ End-to-end task implementation process from initial prompt to pull request, incl Core workflow commands: -- [/sdd:add-task](add-task.md) - Create task template file with initial prompt -- [/sdd:plan](plan.md) - Analyze prompt, generate required skills and refine task specification -- [/sdd:implement](implement.md) - Produce working implementation of the task and verify it +- [/add-task](add-task.md) - Create task template file with initial prompt +- [/plan-task](plan-task.md) - Analyze prompt, generate required skills and refine task specification +- [/implement-task](implement-task.md) - Produce working implementation of the task and verify it Additional commands useful before creating a task: -- [/sdd:create-ideas](create-ideas.md) - Generate diverse ideas on a given topic using creative sampling techniques -- [/sdd:brainstorm](brainstorm.md) - Refine vague ideas into fully-formed designs through collaborative dialogue +- [/create-ideas](create-ideas.md) - Generate diverse ideas on a given topic using creative sampling techniques +- [/brainstorm](brainstorm.md) - Refine vague ideas into fully-formed designs through collaborative dialogue ## Available Agents @@ -95,15 +95,15 @@ The SDD plugin uses specialized agents for different phases of development: | Agent | Description | Used By | |-------|-------------|---------| -| `researcher` | Technology research, dependency analysis, best practices | `/sdd:plan` (Phase 2a) | -| `code-explorer` | Codebase analysis, pattern identification, architecture mapping | `/sdd:plan` (Phase 2b) | -| `business-analyst` | Requirements discovery, stakeholder analysis, specification writing | `/sdd:plan` (Phase 2c) | -| `software-architect` | Architecture design, component design, implementation planning | `/sdd:plan` (Phase 3) | -| `tech-lead` | Task decomposition, dependency mapping, risk analysis | `/sdd:plan` (Phase 4) | -| `team-lead` | Step parallelization, agent assignment, execution planning | `/sdd:plan` (Phase 5) | -| `qa-engineer` | Verification rubrics, quality gates, LLM-as-Judge definitions | `/sdd:plan` (Phase 6) | -| `developer` | Code implementation, TDD execution, quality review, verification | `/sdd:implement` | -| `tech-writer` | Technical documentation, API guides, architecture updates, and lessons learned | `/sdd:implement` | +| `researcher` | Technology research, dependency analysis, best practices | `/plan-task` (Phase 2a) | +| `code-explorer` | Codebase analysis, pattern identification, architecture mapping | `/plan-task` (Phase 2b) | +| `business-analyst` | Requirements discovery, stakeholder analysis, specification writing | `/plan-task` (Phase 2c) | +| `software-architect` | Architecture design, component design, implementation planning | `/plan-task` (Phase 3) | +| `tech-lead` | Task decomposition, dependency mapping, risk analysis | `/plan-task` (Phase 4) | +| `team-lead` | Step parallelization, agent assignment, execution planning | `/plan-task` (Phase 5) | +| `qa-engineer` | Verification rubrics, quality gates, LLM-as-Judge definitions | `/plan-task` (Phase 6) | +| `developer` | Code implementation, TDD execution, quality review, verification | `/implement-task` | +| `tech-writer` | Technical documentation, API guides, architecture updates, and lessons learned | `/implement-task` | ## Patterns @@ -120,7 +120,7 @@ Key patterns implemented in this plugin: This plugin is not a "vibe coding" solution, though it can function like one out of the box. By default, it is designed to work from a single prompt through to task completion, making reasonable assumptions and evidence-based decisions instead of constantly asking for clarification. This is because developer time is more valuable than model time, allowing the developer to decide how much time is worth spending on a task. The plugin will always produce functional results, but quality may be sub-optimal without human feedback. -To improve quality, you can correct the generated specification or leave comments using `//`, then run the `/sdd:plan` command again with the `--refine` flag. You can also verify each planning and implementation phase by adding the `--human-in-the-loop` flag. Majority of researches show that human feedback is the most effective way to improve results. +To improve quality, you can correct the generated specification or leave comments using `//`, then run the `/plan-task` command again with the `--refine` flag. You can also verify each planning and implementation phase by adding the `--human-in-the-loop` flag. Majority of researches show that human feedback is the most effective way to improve results. Our tests showed that even when the initially generated specification was incorrect due to missing information or task complexity, the agent was still able to self-correct until it reached a working solution. However, this process often took longer, as the agent explored incorrect paths and stopped more frequently. To avoid this, we strongly recommend decomposing complex tasks into smaller, separate tasks with dependencies and reviewing the specification for each one. You can add dependencies between tasks as arguments to the `/sdd:add-task` command, and the model will link them by adding a `depends_on` section to the task file's frontmatter. @@ -130,17 +130,17 @@ Learn more about available customization options in [Customization](customizatio ## FAQ -**Do I need to re-run `/plan` or `/implement` after context compaction (`/compact`)?** +**Do I need to re-run `/plan-task` or `/implement-task` after context compaction (`/compact`)?** -After compaction, close the terminal and resume with `/plan --continue` or `/implement --continue`. This produces more predictable results than continuing in a compacted context. Using `/model sonnet[1m]` reduces compaction frequency. +After compaction, close the terminal and resume with `/plan-task --continue` or `/implement-task --continue`. This produces more predictable results than continuing in a compacted context. Using `/model sonnet[1m]` reduces compaction frequency. -**Do I need to prefix every prompt with `/plan` or `/implement`?** +**Do I need to prefix every prompt with `/plan-task` or `/implement-task`?** -No. Run these commands once to start the workflow. The only time to invoke them again is when you change the specification or code and want agents to update misaligned sections — use `/plan --refine` or `/implement --refine`. +No. Run these commands once to start the workflow. The only time to invoke them again is when you change the specification or code and want agents to update misaligned sections — use `/plan-task --refine` or `/implement-task --refine`. -**Should I clear context between `/plan` and `/implement`?** +**Should I clear context between `/plan-task` and `/implement-task`?** -Yes. Run `/clear` (or re-open Claude Code) after `/plan` completes and before running `/implement`. The planning phase fills the context with analysis artifacts; a clean context gives implementation agents better results. +Yes. Run `/clear` (or re-open Claude Code) after `/plan-task` completes and before running `/implement-task`. The planning phase fills the context with analysis artifacts; a clean context gives implementation agents better results. ## Theoretical Foundation diff --git a/plugins/sdd/agents/team-lead.md b/plugins/sdd/agents/team-lead.md index ce97fe2..4bd2f73 100644 --- a/plugins/sdd/agents/team-lead.md +++ b/plugins/sdd/agents/team-lead.md @@ -271,8 +271,8 @@ Use agents that are available in the project. There are examples of agents that | `business-analyst` | Requirements documents, user stories | Code, technical docs | | `researcher` | Skill definitions, technology evaluations | Code, implementation | | `code-explorer` | Codebase analysis reports | Code changes, docs | -| `code-review:code-reviewer` | Code review feedback | Code changes | -| `code-review:bug-hunter` | Bug analysis reports | Bug fixes (code) | +| `review:code-reviewer` | Code review feedback | Code changes | +| `review:bug-hunter` | Bug analysis reports | Bug fixes (code) | ##### Model Selection Guide @@ -308,7 +308,7 @@ Also used as general agents for any task when unsure about specialized agents. │ └─► researcher │ ├─► Code review feedback - │ └─► code-review:code-reviewer + │ └─► review:code-reviewer │ └─► Mixed/Other outputs │ diff --git a/plugins/sdd/skills/add-task/SKILL.md b/plugins/sdd/skills/add-task/SKILL.md index 0c75e37..afe5069 100644 --- a/plugins/sdd/skills/add-task/SKILL.md +++ b/plugins/sdd/skills/add-task/SKILL.md @@ -1,5 +1,5 @@ --- -name: sdd:add-task +name: add-task description: creates draft task file in .specs/tasks/draft/ with original user intent argument-hint: Task title or description (e.g., "Add validation to form inputs") [list of task files that this task depends on] --- diff --git a/plugins/sdd/skills/brainstorm/SKILL.md b/plugins/sdd/skills/brainstorm/SKILL.md index 0cf0c17..1d78163 100644 --- a/plugins/sdd/skills/brainstorm/SKILL.md +++ b/plugins/sdd/skills/brainstorm/SKILL.md @@ -1,5 +1,5 @@ --- -name: sdd:brainstorm +name: brainstorm description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes argument-hint: Optional initial feature concept or topic to brainstorm --- @@ -43,14 +43,14 @@ Start by understanding the current project context, then ask questions one at a **Documentation:** - Write the validated design to `.specs/plans/.design.md` -- Use docs:write-concisely skill if available +- Use write-concisely skill if available - Commit the design document to git **Implementation (if continuing):** - Ask: "Ready to set up for implementation?" -- Use git:create-worktree to create isolated workspace -- Use sdd:add-task to create task file for target approach +- Use `/worktrees create` to create isolated workspace +- Use `/add-task` to create task file for target approach ## Key Principles diff --git a/plugins/sdd/skills/create-ideas/SKILL.md b/plugins/sdd/skills/create-ideas/SKILL.md index e9ab73f..ed0c2e1 100644 --- a/plugins/sdd/skills/create-ideas/SKILL.md +++ b/plugins/sdd/skills/create-ideas/SKILL.md @@ -1,5 +1,5 @@ --- -name: sdd:create-ideas +name: create-ideas description: Generate ideas in one shot using creative sampling argument-hint: Topic or problem to generate ideas for. Optional amount of ideas to generate. --- diff --git a/plugins/sdd/skills/implement/SKILL.md b/plugins/sdd/skills/implement-task/SKILL.md similarity index 99% rename from plugins/sdd/skills/implement/SKILL.md rename to plugins/sdd/skills/implement-task/SKILL.md index 7580a24..73ab00b 100644 --- a/plugins/sdd/skills/implement/SKILL.md +++ b/plugins/sdd/skills/implement-task/SKILL.md @@ -1,5 +1,5 @@ --- -name: sdd:implement +name: implement-task description: Implement a task with automated LLM-as-Judge verification for critical steps argument-hint: Task file [options] (e.g., "add-validation.feature.md --continue --human-in-the-loop") --- diff --git a/plugins/sdd/skills/plan/SKILL.md b/plugins/sdd/skills/plan-task/SKILL.md similarity index 99% rename from plugins/sdd/skills/plan/SKILL.md rename to plugins/sdd/skills/plan-task/SKILL.md index ab0763c..b0cdc57 100644 --- a/plugins/sdd/skills/plan/SKILL.md +++ b/plugins/sdd/skills/plan-task/SKILL.md @@ -1,5 +1,5 @@ --- -name: sdd:plan +name: plan-task description: Refine, parallelize, and verify a draft task specification into a fully planned implementation-ready task argument-hint: Path to draft task file (e.g., ".specs/tasks/draft/add-validation.feature.md") [options] --- @@ -500,7 +500,7 @@ Launch agent: ``` CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT} - Read ${CLAUDE_PLUGIN_ROOT}/skills/plan/analyse-business-requirements.md and execute it exactly as is! + Read ${CLAUDE_PLUGIN_ROOT}/skills/plan-task/analyse-business-requirements.md and execute it exactly as is! Task File: Task Title: @@ -896,7 +896,7 @@ Launch agent: Task File: <TASK_FILE> - Use agents only from this list: {list ALL available agents with plugin prefix if available, e.g. sdd:developer, code-review:bug-hunter. Also include general agents: opus, sonnet, haiku} + Use agents only from this list: {list ALL available agents with plugin prefix if available, e.g. sdd:developer, review:bug-hunter. Also include general agents: opus, sonnet, haiku} CRITICAL: DO NOT OUTPUT YOUR PARALLELIZATION, ONLY CREATE THE SCRATCHPAD AND UPDATE THE TASK FILE. ``` @@ -935,7 +935,7 @@ Launch judge: reorganized for maximum parallel execution with explicit dependencies, agent assignments, and parallelization diagram. - Use agents only from this list: {list ALL available agents with plugin prefix if available, e.g. sdd:developer, code-review:bug-hunter. Also include general agents: opus, sonnet, haiku} + Use agents only from this list: {list ALL available agents with plugin prefix if available, e.g. sdd:developer, review:bug-hunter. Also include general agents: opus, sonnet, haiku} ### Rubric 1. Dependency Accuracy (weight: 0.35) diff --git a/plugins/sdd/skills/plan/analyse-business-requirements.md b/plugins/sdd/skills/plan-task/analyse-business-requirements.md similarity index 100% rename from plugins/sdd/skills/plan/analyse-business-requirements.md rename to plugins/sdd/skills/plan-task/analyse-business-requirements.md diff --git a/plugins/tdd/.claude-plugin/plugin.json b/plugins/tdd/.claude-plugin/plugin.json index 75a2ac3..7eb8945 100644 --- a/plugins/tdd/.claude-plugin/plugin.json +++ b/plugins/tdd/.claude-plugin/plugin.json @@ -1,9 +1,9 @@ { - "name": "tdd", - "version": "1.1.0", - "description": "Introduces commands for test-driven development, common anti-patterns and skills for testing using subagents.", - "author": { - "name": "Vlad Goncharov", - "email": "vlad.goncharov@neolab.finance" - } + "name": "tdd", + "version": "3.0.0", + "description": "Introduces commands for test-driven development, common anti-patterns and skills for testing using subagents.", + "author": { + "name": "Vlad Goncharov", + "email": "vlad.goncharov@neolab.finance" + } } diff --git a/plugins/tdd/README.md b/plugins/tdd/README.md index 6e3e246..f227356 100644 --- a/plugins/tdd/README.md +++ b/plugins/tdd/README.md @@ -33,7 +33,7 @@ The plugin is based on foundational works including Kent Beck's *Test-Driven Dev # Manually make some changes that cause test failures # Fix failing tests -> /tdd:fix-tests +> /fix-tests ``` ### After Implementation @@ -44,7 +44,7 @@ If you implemented a new feature but have not written tests, you can use the `wr > claude "implement email validation for user registration" # Write tests after you made changes -> /tdd:write-tests +> /write-tests ``` [Usage Examples](./usage-examples.md) diff --git a/plugins/tdd/skills/fix-tests/SKILL.md b/plugins/tdd/skills/fix-tests/SKILL.md index e29e2f8..f2dd69f 100644 --- a/plugins/tdd/skills/fix-tests/SKILL.md +++ b/plugins/tdd/skills/fix-tests/SKILL.md @@ -1,5 +1,5 @@ --- -name: tdd:fix-tests +name: fix-tests description: Systematically fix all failing tests after business logic changes or refactoring argument-hint: what tests or modules to focus on --- diff --git a/plugins/tdd/skills/test-driven-development/SKILL.md b/plugins/tdd/skills/test-driven-development/SKILL.md index 3ee0c2c..7a8020f 100644 --- a/plugins/tdd/skills/test-driven-development/SKILL.md +++ b/plugins/tdd/skills/test-driven-development/SKILL.md @@ -1,5 +1,5 @@ --- -name: tdd:test-driven-development +name: test-driven-development description: Use when implementing any feature or bugfix, before writing implementation code - write the test first, watch it fail, write minimal code to pass; ensures tests actually verify behavior by requiring failure first --- diff --git a/plugins/tdd/skills/write-tests/SKILL.md b/plugins/tdd/skills/write-tests/SKILL.md index 4a0695b..833da47 100644 --- a/plugins/tdd/skills/write-tests/SKILL.md +++ b/plugins/tdd/skills/write-tests/SKILL.md @@ -1,5 +1,5 @@ --- -name: tdd:write-tests +name: write-tests description: Systematically add test coverage for all local code changes using specialized review and development agents. Add tests for uncommitted changes (including untracked files), or if everything is commited, then will cover latest commit. argument-hint: what tests or modules to focus on --- @@ -89,7 +89,7 @@ Ensure tests are: If there are multiple changed files, or one file with complex logic, then you need to use specialized agents to cover the changes. Following this guidline: -6. **Launch `code-review:test-coverage-reviewer` agents (parallel)** (Sonnet or Opus models) +6. **Launch `review:test-coverage-reviewer` agents (parallel)** (Sonnet or Opus models) - Launch one coverage-reviewer agent per changed file - Provide each agent with: - **Context**: What changed in this file (git diff) @@ -112,7 +112,7 @@ If there are multiple changed files, or one file with complex logic, then you ne - **Constraint**: Add new tests, don't modify existing logic (unless clearly broken) 8. **Verify coverage (iteration)** (Sonnet or Opus models) - - Launch `code-review:test-coverage-reviewer` agents again per file + - Launch `review:test-coverage-reviewer` agents again per file - Provide: - **Context**: Original changes + new tests added - **Goal**: Verify all critical business logic is covered diff --git a/plugins/tech-stack/.claude-plugin/plugin.json b/plugins/tech-stack/.claude-plugin/plugin.json index 477c55a..fa37d42 100644 --- a/plugins/tech-stack/.claude-plugin/plugin.json +++ b/plugins/tech-stack/.claude-plugin/plugin.json @@ -1,9 +1,9 @@ { - "name": "tech-stack", - "version": "1.0.0", - "description": "Commands for setup or update of CLAUDE.md file with best practices for specific language or framework.", - "author": { - "name": "Vlad Goncharov", - "email": "vlad.goncharov@neolab.finance" - } + "name": "tech-stack", + "version": "3.0.0", + "description": "Commands for setup or update of CLAUDE.md file with best practices for specific language or framework.", + "author": { + "name": "Vlad Goncharov", + "email": "vlad.goncharov@neolab.finance" + } } diff --git a/plugins/tech-stack/README.md b/plugins/tech-stack/README.md index 533acd9..9b0019a 100644 --- a/plugins/tech-stack/README.md +++ b/plugins/tech-stack/README.md @@ -1,17 +1,16 @@ # Tech Stack Plugin -Language and framework-specific best practices plugin that configures your CLAUDE.md with standardized coding standards, ensuring consistent code quality across all AI-assisted development. +Language and framework-specific best practices plugin that provides rules automatically loaded into agent context when working with matching file types, ensuring consistent code quality across all AI-assisted development. Focused on: -- **Standardized Guidelines** - Pre-defined best practices for specific languages and frameworks -- **Initial context building** - Updates of CLAUDE.md, so it will be loaded during every claude code session +- **Automatic Rules** - Best practices loaded into context based on file types being worked on +- **Zero Configuration** - Rules activate automatically when agent reads or writes matching files ## Overview -The Tech Stack plugin provides commands for setting up language and framework-specific best practices in your CLAUDE.md file. Instead of manually defining coding standards, this plugin provides curated, production-tested guidelines that can be applied with a single command. +The Tech Stack plugin provides rules for language and framework-specific best practices. Rules are automatically loaded into the agent's context when working with matching file types (e.g., `**/*.ts` for TypeScript). No manual invocation is needed -- once the plugin is installed, the agent receives relevant coding standards whenever it reads or writes files of that type. -When Claude operates with explicit coding standards in CLAUDE.md, it produces more consistent and higher-quality code. The Tech Stack plugin bridges the gap between starting a new project and having well-defined development standards. ## Quick Start @@ -19,26 +18,25 @@ When Claude operates with explicit coding standards in CLAUDE.md, it produces mo # Install the plugin /plugin install tech-stack@NeoLabHQ/context-engineering-kit -# Add TypeScript best practices to your project -/tech-stack:add-typescript-best-practices +# Rules activate automatically when working on TypeScript files +# No additional setup needed -# Review the updated CLAUDE.md -cat CLAUDE.md +Refactor @src/main.ts to use generics +-> TypeScript Best Practices automatically loaded and applied ``` -[Usage Examples](./usage-examples.md) +## Rules +Rules are context files that are automatically loaded when the agent works on files matching specific glob patterns. Unlike skills (which require manual invocation), rules apply transparently based on the file types being edited. -### Why CLAUDE.md Matters +| Rule | File Pattern | Description | +|------|-------------|-------------| +| [TypeScript Best Practices](typescript-best-practices.md) | `**/*.ts` | Type system guidelines, code style, async patterns, utility types, and code quality standards | -CLAUDE.md is read by Claude at the start of every conversation. By placing coding standards here: - -1. **Persistent Context** - Guidelines are always available to Claude -2. **Project-Specific Rules** - Different projects can have different standards -3. **Team Synchronization** - All team members share the same AI configuration -4. **Version Control** - Guidelines are tracked alongside your code - -## Commands - -- [/tech-stack:add-typescript-best-practices](./add-typescript-best-practices.md) - Sets up TypeScript best practices and code style rules in your CLAUDE.md file, providing Claude with explicit guidelines for generating consistent, type-safe code. +### What TypeScript Best Practices Covers +- **Code Style** - Strict typing, interfaces over types, enum usage, type guards +- **Type System** - Inference, generics, conditional types, mapped types, opaque types +- **Async Patterns** - async/await, Promise-based APIs, concurrent operations +- **Code Quality** - Destructuring, naming conventions, library-first approach +- **Utility Types** - Practical usage of Record, Partial, Omit, Pick, and more diff --git a/plugins/tech-stack/rules/typescript-best-practices.md b/plugins/tech-stack/rules/typescript-best-practices.md new file mode 100644 index 0000000..0ccf08d --- /dev/null +++ b/plugins/tech-stack/rules/typescript-best-practices.md @@ -0,0 +1,796 @@ +--- +title: TypeScript Best Practices +paths: + - "**/*.ts" +--- + +# TypeScript Best Practices + +## Code Style Rules + +### General Principles + +- **TypeScript**: All code must be strictly typed, leverage TypeScript's type safety features + +### Code style rules + +- Interfaces over types - use interfaces for object types +- Use enum for constant values, prefer them over string literals +- Export all types by default +- Use type guards instead of type assertions + +### Best Practices + +#### Library-First Approach + +- Common areas where libraries should be preferred: + - Date/time manipulation → date-fns, dayjs + - Form validation → joi, yup, zod + - HTTP requests → axios, got + - State management → Redux, MobX, Zustand + - Utility functions → lodash, ramda + +#### Code Quality + +- Use destructuring of objects where possible: + - Instead of `const name = user.name` use `const { name } = user` + - Instead of `const result = await getUser(userId)` use `const { data: user } = await getUser(userId)` + - Instead of `const parseData = (data) => data.name` use `const parseData = ({ name }) => name` +- Use `ms` package for time related configuration and environment variables, instead of multiplying numbers by 1000 + + +## Types and Type Safety + +- Avoid explicit type annotations when TypeScript can infer +- Avoid implicitly `any`; explicitly type when necessary +- Use accurate types: prefer `Record<PropertyKey, unknown>` over `object` or `any` +- Prefer `interface` for object shapes (e.g., React props); use `type` for unions/intersections +- Prefer `as const satisfies XyzInterface` over plain `as const` +- Prefer `@ts-expect-error` over `@ts-ignore` over `as any` +- Avoid meaningless null/undefined parameters; design strict function contracts +- Prefer ES module augmentation (`declare module '...'`) over `namespace`; do not introduce `namespace`-based extension patterns +- When a type needs extensibility, expose a small mergeable interface at the source type and let each feature/plugin augment it locally instead of centralizing all extension fields in one registry file +- For package-local extensibility patterns like `PipelineContext.metadata`, define the metadata fields next to the processor/provider/plugin that reads or writes them + +## Async Patterns + +- Prefer `async`/`await` over callbacks or `.then()` chains +- Prefer async APIs over sync ones (avoid `*Sync`) +- Use promise-based variants: `import { readFile } from 'fs/promises'` +- Use `Promise.all`, `Promise.race` for concurrent operations where safe + +## Code Structure + +- Prefer object destructuring +- Use consistent, descriptive naming; avoid obscure abbreviations +- Replace magic numbers/strings with well-named constants +- Defer formatting to tooling + + +## Performance + +- Prefer `for…of` loops over index-based `for` loops +- Reuse existing functions and logic from codebase or installed npm packages + +## Time Consistency + +- Assign `Date.now()` to a constant once and reuse for consistency + +## Logging + +- Never log user private information (API keys, etc.) +- Always log the error in `.catch()` callbacks — silent `.catch(() => fallback)` swallows failures and makes debugging impossible + + +# Quick Examples + +## Eliminating `any` with generics + +**Before** +```ts +function getProperty(obj: any, key: string): any { + return obj[key]; +} +``` + +**After** +```ts +function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] { + return obj[key]; +} +// getProperty({ name: "Alice" }, "name") → inferred as string ✓ +``` + +## Narrowing an unknown API response + +**Before** +```ts +async function fetchUser(): Promise<any> { + const res = await fetch("/api/user"); + return res.json(); +} +``` + +**After** +```ts +interface User { id: number; name: string } + +function isUser(value: unknown): value is User { + return ( + typeof value === "object" && + value !== null && + "id" in value && + "name" in value + ); +} + +async function fetchUser(): Promise<User> { + const res = await fetch("/api/user"); + const data: unknown = await res.json(); + if (!isUser(data)) throw new Error("Invalid user shape"); + return data; +} +``` + + +## The `as const` Assertion + +`as const` is a const assertion that makes an object deeply readonly and infers literal types instead of widened types. + +```typescript +// Without as const - types are widened +const config = { + GROUP: "group", + ANNOUNCEMENT: "announcement", +}; +// Type: { GROUP: string; ANNOUNCEMENT: string } + +// With as const - literal types are preserved +const config = { + GROUP: "group", + ANNOUNCEMENT: "announcement", +} as const; +// Type: { readonly GROUP: "group"; readonly ANNOUNCEMENT: "announcement" } +``` + +## Array Index Access with `[number]` + +Just like you can access object properties with string keys, you can access array elements with numeric indices: + +```typescript +const roles = ["user", "admin", "anonymous"] as const; + +// Access specific index +type FirstRole = typeof roles[0]; // "user" +type SecondRole = typeof roles[1]; // "admin" + +// Access all elements with [number] +type AnyRole = typeof roles[number]; // "user" | "admin" | "anonymous" +``` + +## Conditional Types + +```typescript +type Conditional = SomeType extends OtherType ? TrueType : FalseType; +``` + +The condition checks if `SomeType` is assignable to `OtherType`. + +```typescript +// Check if type is string +type IsString<T> = T extends string ? true : false; + +type Test1 = IsString<string>; // true +type Test2 = IsString<number>; // false +type Test3 = IsString<"hello">; // true (literal extends string) + +// Check type relationships +type Result1 = string extends string ? "yes" : "no"; // "yes" +type Result2 = string extends number ? "yes" : "no"; // "no" +type Result3 = "hello" extends string ? "yes" : "no"; // "yes" +``` + +## Function Overloads + + +Function overloads allow you to define multiple function signatures for a single function implementation. TypeScript selects the appropriate signature based on the arguments provided. + +```typescript +// Overload signatures (what callers see) +function greet(name: string): string; +function greet(firstName: string, lastName: string): string; + +// Implementation signature (must be compatible with all overloads) +function greet(nameOrFirst: string, lastName?: string): string { + if (lastName) { + return `Hello, ${nameOrFirst} ${lastName}!`; + } + return `Hello, ${nameOrFirst}!`; +} + +// Usage - TypeScript picks the right overload +greet("Alice"); // Uses first overload +greet("Alice", "Smith"); // Uses second overload +``` + + +## Generics Fundamentals + +Generics allow you to create reusable components that work with multiple types while maintaining type safety. They're essential for building flexible, type-safe APIs. + +```typescript +// Without generics - loses type information +function identity(value: any): any { + return value; +} + +// With generics - preserves type +function identity<T>(value: T): T { + return value; +} + +const num = identity(42); // Type: number (inferred) +const str = identity("hello"); // Type: string (inferred) +const explicit = identity<boolean>(true); // Type: boolean (explicit) +``` + + +## The `infer` Keyword + +The `infer` keyword allows you to extract and capture type information within conditional types. It's like pattern matching for types - you define a pattern and capture parts of it. + +```typescript +type ExtractType<T> = T extends SomePattern<infer U> ? U : never; +// ^^^^^^^^ +// Captures this part into U +``` + +Extract Array Element Type + +```typescript +type ArrayElement<T> = T extends (infer U)[] ? U : never; + +type Test1 = ArrayElement<string[]>; // string +type Test2 = ArrayElement<number[]>; // number +type Test3 = ArrayElement<(string | number)[]>; // string | number +type Test4 = ArrayElement<string>; // never (not an array) +``` + +## Mapped Types + +Mapped types allow you to create new types by transforming each property of an existing type. They iterate over keys and apply transformations to create new type structures. + +```typescript +type MappedType<T> = { + [K in keyof T]: TransformedType; +}; +``` + +Make All Properties Optional + +```typescript +type MyPartial<T> = { + [K in keyof T]?: T[K]; +}; + +interface User { + id: string; + name: string; + email: string; +} + +type PartialUser = MyPartial<User>; +// { id?: string; name?: string; email?: string } +``` + +## Opaque Types (Brand Types) + +Opaque types (also called brand types or nominal types) create distinct types from primitive types. They prevent mixing up values that have the same underlying type but different semantic meanings. + +TypeScript uses structural typing, so these are interchangeable: + +```typescript +type UserId = string; +type PostId = string; + +function getUser(id: UserId): User { /* ... */ } +function getPost(id: PostId): Post { /* ... */ } + +const userId: UserId = "user-123"; +const postId: PostId = "post-456"; + +// BUG: Wrong ID type, but TypeScript allows it! +getUser(postId); // No error - both are just strings +``` + +Add a phantom property to create nominal distinction: + +```typescript +type Opaque<TValue, TBrand> = TValue & { __brand: TBrand }; + +type UserId = Opaque<string, "UserId">; +type PostId = Opaque<string, "PostId">; +type ValidEmail = Opaque<string, "ValidEmail">; +type ValidAge = Opaque<number, "ValidAge">; +``` + +Now these types are incompatible: + +```typescript +function getUser(id: UserId): User { /* ... */ } +function getPost(id: PostId): Post { /* ... */ } + +const userId = "user-123" as UserId; +const postId = "post-456" as PostId; + +getUser(userId); // OK +getUser(postId); // Error: Type 'PostId' is not assignable to type 'UserId' +``` + +## Template Literal Types + +Template literal types allow you to manipulate string types using the same syntax as JavaScript template literals. Combined with `infer`, they enable powerful string parsing and transformation at the type level. + +```typescript +type Greeting = `Hello, ${string}`; + +const valid: Greeting = "Hello, World"; // OK +const invalid: Greeting = "Hi, World"; // Error: doesn't match pattern +``` + +Template literals distribute over unions: + +```typescript +type Size = "small" | "medium" | "large"; +type Color = "red" | "blue" | "green"; + +type SizedColor = `${Size}-${Color}`; +// "small-red" | "small-blue" | "small-green" | +// "medium-red" | "medium-blue" | "medium-green" | +// "large-red" | "large-blue" | "large-green" +``` + +Extract parts of string types: + +```typescript +// Remove "maps:" prefix +type RemoveMaps<T> = T extends `maps:${infer Rest}` ? Rest : T; + +type Test1 = RemoveMaps<"maps:longitude">; // "longitude" +type Test2 = RemoveMaps<"maps:latitude">; // "latitude" +type Test3 = RemoveMaps<"other">; // "other" +``` + +## Type Narrowing + +Type narrowing is TypeScript's ability to refine types based on control flow analysis. When you check a type condition, TypeScript narrows the type within that code block. + +### `typeof` Guards + +```typescript +function processValue(value: string | number) { + if (typeof value === "string") { + // value is string here + return value.toUpperCase(); + } + // value is number here + return value.toFixed(2); +} +``` + +### `instanceof` Guards + +```typescript +function logError(error: Error | string) { + if (error instanceof Error) { + // error is Error here + console.log(error.stack); + } else { + // error is string here + console.log(error); + } +} +``` + +### Truthiness Narrowing + +```typescript +function printName(name: string | null | undefined) { + if (name) { + // name is string here (truthy) + console.log(name.toUpperCase()); + } +} +``` + +### Equality Narrowing + +```typescript +function example(x: string | number, y: string | boolean) { + if (x === y) { + // Both are string here (only common type) + console.log(x.toUpperCase()); + console.log(y.toUpperCase()); + } +} +``` + +### `in` Operator + +```typescript +interface Fish { + swim: () => void; +} + +interface Bird { + fly: () => void; +} + +function move(animal: Fish | Bird) { + if ("swim" in animal) { + // animal is Fish here + animal.swim(); + } else { + // animal is Bird here + animal.fly(); + } +} +``` + +### Custom Type Guards + +#### Type Predicates + +Functions that return `value is Type`: + +```typescript +interface Fish { + swim: () => void; +} + +interface Bird { + fly: () => void; +} + +function isFish(pet: Fish | Bird): pet is Fish { + return (pet as Fish).swim !== undefined; +} + +function move(pet: Fish | Bird) { + if (isFish(pet)) { + // pet is Fish here + pet.swim(); + } else { + // pet is Bird here + pet.fly(); + } +} +``` + +#### Generic Type Guards + +```typescript +function isNotNull<T>(value: T | null | undefined): value is T { + return value !== null && value !== undefined; +} + +const values = [1, null, 2, undefined, 3]; +const filtered = values.filter(isNotNull); +// filtered is number[] +``` + +#### Object Property Check + +```typescript +function hasProperty<T extends object, K extends string>( + obj: T, + key: K +): obj is T & Record<K, unknown> { + return key in obj; +} + +const data: unknown = { name: "Alice" }; + +if (typeof data === "object" && data !== null && hasProperty(data, "name")) { + // data.name is now accessible + console.log(data.name); +} +``` + +### Assertion Functions + +Functions that throw on invalid input: + +```typescript +function assertIsString(value: unknown): asserts value is string { + if (typeof value !== "string") { + throw new Error(`Expected string, got ${typeof value}`); + } +} + +function processInput(input: unknown) { + assertIsString(input); + // input is string here + console.log(input.toUpperCase()); +} +``` + +# TypeScript Utility Types + + +## Parameters<T> + +Extracts the parameter types of a function type as a tuple: + +```typescript +function fetchUser(id: string, opts?: { timeout?: number }): Promise<User> { + // ... +} + +type FetchUserParams = Parameters<typeof fetchUser>; +// Type: [id: string, opts?: { timeout?: number } | undefined] + +// Use in wrapper functions +const fetchUserWithLogging = async ( + ...args: Parameters<typeof fetchUser> +): Promise<User> => { + console.log("Fetching user:", args[0]); + return fetchUser(...args); +}; +``` + +## ReturnType<T> + +Extracts the return type of a function type: + +```typescript +function createUser(name: string, email: string) { + return { + id: crypto.randomUUID(), + name, + email, + createdAt: new Date(), + }; +} + +type User = ReturnType<typeof createUser>; +// Type: { id: string; name: string; email: string; createdAt: Date } +``` + +## Awaited<T> + +Unwraps the type inside a Promise (including nested Promises): + +```typescript +type PromiseString = Promise<string>; +type NestedPromise = Promise<Promise<number>>; + +type Unwrapped1 = Awaited<PromiseString>; // string +type Unwrapped2 = Awaited<NestedPromise>; // number + +// Combine with ReturnType for async functions +async function fetchUser(id: string): Promise<User> { + // ... +} + +type FetchUserResult = Awaited<ReturnType<typeof fetchUser>>; +// Type: User (not Promise<User>) +``` + +## Pattern: Wrapping External Library Functions + +When extending functions from external libraries that don't export their types: + +```typescript +import { fetchUser } from "external-lib"; + +// Extract and extend the return type +type FetchUserReturn = Awaited<ReturnType<typeof fetchUser>>; + +export const fetchUserWithFullName = async ( + ...args: Parameters<typeof fetchUser> +): Promise<FetchUserReturn & { fullName: string }> => { + const user = await fetchUser(...args); + return { + ...user, + fullName: `${user.firstName} ${user.lastName}`, + }; +}; +``` + +## Record<Keys, Type> + +Creates an object type with specified keys and value type: + +```typescript +type Role = "admin" | "user" | "guest"; +type Permissions = Record<Role, string[]>; + +const rolePermissions: Permissions = { + admin: ["read", "write", "delete"], + user: ["read", "write"], + guest: ["read"], +}; + +// Dynamic keys with constraint +function createLookup<K extends string, V>( + keys: K[], + getValue: (key: K) => V +): Record<K, V> { + const result = {} as Record<K, V>; + for (const key of keys) { + result[key] = getValue(key); + } + return result; +} +``` + +## Partial<T> + +Makes all properties optional: + +```typescript +interface User { + id: string; + name: string; + email: string; +} + +type UpdateUserInput = Partial<User>; +// Type: { id?: string; name?: string; email?: string } + +function updateUser(id: string, updates: Partial<User>): User { + // ... +} + +updateUser("123", { name: "New Name" }); // OK - only updating name +``` + +## Required<T> + +Makes all properties required (opposite of Partial): + +```typescript +interface Config { + host?: string; + port?: number; + debug?: boolean; +} + +type RequiredConfig = Required<Config>; +// Type: { host: string; port: number; debug: boolean } +``` + +## Omit<T, Keys> + +Creates a type by omitting specified properties: + +```typescript +interface User { + id: string; + name: string; + email: string; + password: string; +} + +type PublicUser = Omit<User, "password">; +// Type: { id: string; name: string; email: string } + +type CreateUserInput = Omit<User, "id">; +// Type: { name: string; email: string; password: string } +``` + +## Pick<T, Keys> + +Creates a type by picking specified properties (opposite of Omit): + +```typescript +interface User { + id: string; + name: string; + email: string; + password: string; + createdAt: Date; +} + +type UserCredentials = Pick<User, "email" | "password">; +// Type: { email: string; password: string } +``` + +## Exclude<T, U> and Extract<T, U> + +Work with union types: + +```typescript +type AllColors = "red" | "green" | "blue" | "yellow"; + +type PrimaryColors = Extract<AllColors, "red" | "blue">; +// Type: "red" | "blue" + +type NonPrimaryColors = Exclude<AllColors, "red" | "blue">; +// Type: "green" | "yellow" +``` + +## NonNullable<T> + +Removes null and undefined from a type: + +```typescript +type MaybeString = string | null | undefined; +type DefiniteString = NonNullable<MaybeString>; +// Type: string +``` + +## Creating a Reusable Wrapper Type + +Combine utilities to create reusable type helpers: + +```typescript +// A type that wraps any async function, extending its return type +type WrapFunction< + TFunc extends (...args: any) => any, + TAdditional = {} +> = ( + ...args: Parameters<TFunc> +) => Promise<Awaited<ReturnType<TFunc>> & TAdditional>; + +// Usage +import { fetchUser, fetchPost } from "external-lib"; + +const fetchUserWithMeta: WrapFunction< + typeof fetchUser, + { meta: { fetchedAt: Date } } +> = async (...args) => { + const user = await fetchUser(...args); + return { + ...user, + meta: { fetchedAt: new Date() }, + }; +}; +``` + +## When to Use Each Utility + +| Utility | Use Case | +|---------|----------| +| `Parameters<T>` | Wrapping functions, creating function variants | +| `ReturnType<T>` | Extracting return types when not explicitly exported | +| `Awaited<T>` | Unwrapping Promise types | +| `Record<K, V>` | Creating object types with dynamic keys | +| `Partial<T>` | Update/patch operations | +| `Required<T>` | Ensuring all config options are provided | +| `Omit<T, K>` | Removing sensitive or internal fields | +| `Pick<T, K>` | Creating focused subsets of types | +| `Exclude<T, U>` | Filtering union types | +| `Extract<T, U>` | Selecting from union types | +| `NonNullable<T>` | Removing null/undefined after validation | + +## Common Pitfalls + +### Using ReturnType on Async Functions + +```typescript +async function getData(): Promise<string[]> { + return ["data"]; +} + +// This gives Promise<string[]>, not string[] +type Wrong = ReturnType<typeof getData>; // Promise<string[]> + +// Use Awaited to unwrap +type Right = Awaited<ReturnType<typeof getData>>; // string[] +``` + +### Forgetting typeof for Runtime Functions + +```typescript +function myFunc(x: number): string { + return String(x); +} + +// Wrong - myFunc is a value, not a type +type Params = Parameters<myFunc>; // Error + +// Correct - use typeof +type Params = Parameters<typeof myFunc>; // [x: number] +``` \ No newline at end of file diff --git a/plugins/tech-stack/skills/add-typescript-best-practices/SKILL.md b/plugins/tech-stack/skills/add-typescript-best-practices/SKILL.md deleted file mode 100644 index 8cebb39..0000000 --- a/plugins/tech-stack/skills/add-typescript-best-practices/SKILL.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: tech-stack:add-typescript-best-practices -description: Setup TypeScript best practices and code style rules in CLAUDE.md -argument-hint: Optional argument which practices to add or avoid ---- - -# Setup TypeScript Best Practices - -Create or update CLAUDE.md in with following content, <critical>write it strictly as it is<critical>, do not summaraise or introduce and new additional information: - -```markdown -## Code Style Rules - -### General Principles - -- **TypeScript**: All code must be strictly typed, leverage TypeScript's type safety features - -### Code style rules - -- Interfaces over types - use interfaces for object types -- Use enum for constant values, prefer them over string literals -- Export all types by default -- Use type guards instead of type assertions - -### Best Practices - -#### Library-First Approach - -- Common areas where libraries should be preferred: - - Date/time manipulation → date-fns, dayjs - - Form validation → joi, yup, zod - - HTTP requests → axios, got - - State management → Redux, MobX, Zustand - - Utility functions → lodash, ramda - -#### Code Quality - -- Use destructuring of objects where possible: - - Instead of `const name = user.name` use `const { name } = user` - - Instead of `const result = await getUser(userId)` use `const { data: user } = await getUser(userId)` - - Instead of `const parseData = (data) => data.name` use `const parseData = ({ name }) => name` -- Use `ms` package for time related configuration and environment variables, instead of multiplying numbers by 1000 -```