{"id":47582628,"url":"https://github.com/serpro69/claude-toolbox","last_synced_at":"2026-04-26T19:01:24.863Z","repository":{"id":321960959,"uuid":"1078182326","full_name":"serpro69/claude-toolbox","owner":"serpro69","description":"Minimal by design, explicitly multi-lang, production-ready and battle-tested collection of configs and plugins for your Claude Code agentic development workflows: mcp, configs, skills, agents and more.","archived":false,"fork":false,"pushed_at":"2026-04-23T21:14:58.000Z","size":10374,"stargazers_count":133,"open_issues_count":18,"forks_count":31,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-04-23T21:32:27.106Z","etag":null,"topics":["agent-skills","agents","claude","claude-code","claude-code-plugin","claude-config","claude-plugin","claude-skills","claude-starter","go","java","js","kotlin","python","skill","skills","starter-project","starter-template","typescript","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serpro69.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-17T10:31:30.000Z","updated_at":"2026-04-23T19:29:23.000Z","dependencies_parsed_at":"2026-04-02T03:06:44.169Z","dependency_job_id":"24de10f2-5ca1-4645-b394-14f71b4fa724","html_url":"https://github.com/serpro69/claude-toolbox","commit_stats":null,"previous_names":["serpro69/claude-starter-kit","serpro69/claude-sak"],"tags_count":32,"template":true,"template_full_name":null,"purl":"pkg:github/serpro69/claude-toolbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpro69%2Fclaude-toolbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpro69%2Fclaude-toolbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpro69%2Fclaude-toolbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpro69%2Fclaude-toolbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serpro69","download_url":"https://codeload.github.com/serpro69/claude-toolbox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpro69%2Fclaude-toolbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32308878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T17:23:19.671Z","status":"ssl_error","status_checked_at":"2026-04-26T17:23:19.195Z","response_time":129,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","agents","claude","claude-code","claude-code-plugin","claude-config","claude-plugin","claude-skills","claude-starter","go","java","js","kotlin","python","skill","skills","starter-project","starter-template","typescript","vibe-coding"],"created_at":"2026-04-01T00:00:30.579Z","updated_at":"2026-04-26T19:01:19.817Z","avatar_url":"https://github.com/serpro69.png","language":"Shell","funding_links":[],"categories":["Tooling 🧰","MCP Servers \u0026 Protocol"],"sub_categories":["General"],"readme":"# claude-toolbox\n\n[![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/hesreallyhim/awesome-claude-code)\n\nclaude-toolbox is a collection of \"tools\" for all your Claude Code workflows — pre-configured MCP servers, skills, sub-agents, commands, hooks, statuslines with themes, and more - everything you need for AI-powered development workflows, used and battle-tested daily on many of my own projects.\n\n\u003e [!IMPORTANT]\n\u003e This project was created with the help of Claude-Code. Is it, however, reviewed, tested, and reworked with a human-in-the-loop.\n\u003e\n\u003e No AI slop here. Purely AI-made skills are hot garbage, and that's putting it mildly.\n\u003e\n\u003e That said, if you have any problems with code that is written by AI - you've been warned. But, then again, why would you be interested in AI-related configs and skills in the first place... `¯\\_(ツ)_/¯`\n\n\u003cimg width=\"3440\" height=\"521\" alt=\"image\" src=\"https://github.com/user-attachments/assets/27ef7269-0153-47c0-b07d-ed6a9504a176\" /\u003e\n\n## Why claude-toolbox?\n\nClaude Code is powerful on its own, but it doesn't know your development workflow. This project started as a way for me to streamline claude configurations across all my projects without needing to copy-paste things. With time, patterns and re-curring prompts evolved into skills and agents. Currently, claude-toolbox gives you two things:\n\n**A minimal, opinionated Claude Code configuration** — sensible permission baselines, a rich statusline, Serena LSP integration, MCP server wiring, and sync infrastructure to keep it all up to date across your projects. Think of it as a dotfiles repo for Claude Code.\n\n**A structured development pipeline** — 10 workflow skills that take you from idea through design, implementation, code review, testing, to documentation, with persistent knowledge that carries across sessions.\n\n```\n/design → /review-design → /implement → /review-code → /test → /document\n```\n\nOut of the box you get:\n\n- **10 workflow skills** — a complete development pipeline invoked as `/skill-name`\n- **Multi-language support** — precise and distinct instructions from implementation to testing to review for: go, java, js/ts, kotlin, python\n- **Multi-model code review** — independent reviewers using sub-agents and external models (Gemini, etc.)\n- **Semantic code analysis** — LSP-powered symbol navigation and reference tracking via Serena\n- **Persistent knowledge base** — findings, decisions, and conventions that survive across sessions via Capy\n- **Up-to-date library docs** — always-current documentation lookup via Context7\n- **Battle-tested configuration** — permissions, statusline themes, hooks, sensible defaults\n\n## Choose Your Path\n\n**Starting a new project?** Use the template — you get the full configuration and plugin pre-wired, plus sync infrastructure to pull future updates.\n→ [Template Setup](#template-setup)\n\n**Existing project, want the full setup?** Adopt the configuration, plugin, and sync infrastructure without creating from the template.\n→ [Adopting into Existing Repositories](#adopting-into-existing-repositories)\n\n**Just want the skills?** Install the kk plugin — all 10 skills, commands, and hooks in one command. No template needed.\n→ [Plugin-Only Setup](#plugin-only-setup)\n\n## Requirements\n\n- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — the AI coding assistant this toolbox extends\n- **[npm](https://www.npmjs.com/package/npm)** — used by some MCP server installations\n- **[uv](https://docs.astral.sh/uv/)** — Python package runner for Serena and Pal MCP servers\n- **[jq](https://jqlang.github.io/jq/)** — JSON processor, required for template-cleanup\n\n### API Keys\n\n- [Context7](https://context7.com/) API key — for library documentation lookups\n- Gemini API key for [Pal](https://github.com/BeehiveInnovations/pal-mcp-server) (or [any other provider](https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/getting-started.md)) — for multi-model code review\n\n### MCP Server Configuration\n\n\u003e [!NOTE]\n\u003e MCP servers must be configured in `~/.claude.json` (not in the repo) to keep API keys safe.\n\u003e These configs are generic enough to reuse across all your projects.\n\nYou don't need all servers to get started. Add them incrementally:\n\n1. **Serena** (no API key needed) — semantic code analysis via LSP. Works immediately after setup.\n2. **Context7** (needs API key) — up-to-date library documentation and code examples.\n3. **Pal** (needs API key) — multi-model AI integration for code review, debugging, planning, and security audit.\n4. [**Capy**](https://github.com/serpro69/capy) (optional, auto-configured by bootstrap) — persistent knowledge base across sessions. Install with `brew install serpro69/tap/capy`.\n\n\u003cdetails\u003e\n\u003csummary\u003eExample \u003ccode\u003emcpServers\u003c/code\u003e configuration\u003c/summary\u003e\n\n```json\n{\n  \"context7\": {\n    \"type\": \"http\",\n    \"url\": \"https://mcp.context7.com/mcp\",\n    \"headers\": {\n      \"CONTEXT7_API_KEY\": \"YOUR_CONTEXT7_API_KEY\"\n    }\n  },\n  \"serena\": {\n    \"type\": \"stdio\",\n    \"command\": \"uvx\",\n    \"args\": [\n      \"--from\",\n      \"git+https://github.com/oraios/serena\",\n      \"serena\",\n      \"start-mcp-server\",\n      \"--context\",\n      \"ide-assistant\",\n      \"--project\",\n      \".\"\n    ],\n    \"env\": {}\n  },\n  \"pal\": {\n    \"command\": \"sh\",\n    \"args\": [\n      \"-c\",\n      \"$HOME/.local/bin/uvx --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server\"\n    ],\n    \"env\": {\n      \"PATH\": \"/usr/local/bin:/usr/bin:/bin:$HOME/.local/bin\",\n      # see https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/configuration.md#model-configuration\n      \"DEFAULT_MODEL\": \"auto\",\n      # see https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/advanced-usage.md#thinking-modes\n      \"DEFAULT_THINKING_MODE_THINKDEEP\": \"high\",\n      \"GEMINI_API_KEY\": \"YOUR_GEMINI_API_KEY\",\n      # see https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/configuration.md#model-usage-restrictions\n      \"GOOGLE_ALLOWED_MODELS\": \"gemini-3.1-pro-preview,gemini-3-flash-preview\"\n    }\n  }\n}\n```\n\nSee [Pal configuration docs](https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/configuration.md) for model and thinking mode options.\n\n\u003c/details\u003e\n\n\u003e [!TIP]\n\u003e If you're using my [claude-in-docker](https://github.com/serpro69/claude-in-docker) images, consider replacing `npx` and `uvx` calls with direct tool invocations. The images come shipped with all of the above MCP tools pre-installed, and you will avoid downloading dependencies every time you launch claude cli.\n\u003e\n\u003e ```json\n\u003e   \"serena\": {\n\u003e     \"type\": \"stdio\",\n\u003e     \"command\": \"serena\",\n\u003e     \"args\": [\n\u003e       \"start-mcp-server\",\n\u003e       \"--context\",\n\u003e       \"ide-assistant\",\n\u003e       \"--project\",\n\u003e       \".\"\n\u003e     ],\n\u003e     \"env\": {}\n\u003e   },\n\u003e   \"pal\": {\n\u003e     \"command\": \"pal-mcp-server\",\n\u003e     \"args\": [],\n\u003e     \"env\": { ... }\n\u003e   }\n\u003e ```\n\u003e\n\u003e You also may want to look into your `env` settings for the given mcp server, especially the `PATH` variable, and make sure you're not adding anything custom that may not be avaiable in the image.\n\u003e This may cause the mcp server to fail to connect.\n\n## Template Setup\n\n1. [Create a new project from this template](https://github.com/new?template_name=claude-toolbox\u0026template_owner=serpro69) using the **Use this template** button.\n\n2. Initialize the template — choose one method:\n\n   **Option A: GitHub Actions** (recommended)\n\n   Go to your new repo's **Actions** tab → **Template Cleanup** → **Run workflow**. Provide:\n   - `LANGUAGES` (required) — programming languages, comma-separated (e.g., `python`, `python,typescript`).\n     See [supported languages](https://github.com/oraios/serena?tab=readme-ov-file#programming-language-support--semantic-analysis-capabilities).\n   - `SERENA_INITIAL_PROMPT` — initial prompt given to the LLM on project activation\n   - Other inputs are optional with sensible defaults.\n\n\u003e [!TIP]\n\u003e Take a look at serena [project.yaml](./.serena/project.yml) configuration file for more details.\n\n**Option B: Run locally**\n\n```bash\n./.github/scripts/template-cleanup.sh\n```\n\nInteractive mode walks you through each option. Run with `--help` for all flags, or pass them directly:\n\n```bash\n./.github/scripts/template-cleanup.sh --languages python,typescript -y\n```\n\n3. Clone your repo (if using Option A) and verify MCP servers:\n\n   ```\n   \u003e /mcp\n   ╭────────────────────────────────────────────────────────────────────╮\n   │ Manage MCP servers                                                 │\n   │                                                                    │\n   │ ❯ 1. context7                  ✔ connected · Enter to view details │\n   │   2. serena                    ✔ connected · Enter to view details │\n   │   3. pal                       ✔ connected · Enter to view details │\n   ╰────────────────────────────────────────────────────────────────────╯\n   ```\n\n   The kk plugin (skills, commands, hooks) is available via the claude-toolbox marketplace configured in `.claude/settings.json`.\n\n4. Finalize initialization:\n\n   ```bash\n   chmod +x .github/scripts/bootstrap.sh \u0026\u0026 ./.github/scripts/bootstrap.sh\n   ```\n\n   This installs the kk plugin, wires up the Capy knowledge base (if installed), and commits the configuration.\n\n5. **Recommended:** Run `/config` in Claude Code and disable **Auto-compact**. This prevents Claude from compacting context mid-task, which degrades quality significantly. See [Recommended Settings](#recommended-settings) for the full config.\n\n6. [Try it out!](#try-it)\n\n## Plugin-Only Setup\n\nAlready have a project? Install just the kk plugin to get all skills, commands, and hooks:\n\n```\n/plugin install kk@claude-toolbox\n```\n\nThat's it. All 10 skills are now available as `/skill-name` (annotated with `(kk)` in the slash command menu). See the [kk plugin documentation](./klaude-plugin/README.md) for details.\n\n\u003e [!TIP]\n\u003e Want the full configuration too (settings, statusline, Serena, sync infrastructure)? See [Adopting into Existing Repositories](#adopting-into-existing-repositories).\n\u003e For MCP servers, see [MCP Server Configuration](#mcp-server-configuration) and add the configs you want to `~/.claude.json`.\n\n## Try It\n\nAfter setup, try the core workflow:\n\n1. **Start with an idea.** Type `/design` and describe a feature you want to build. Claude will ask you refinement questions one at a time, then produce design docs and a task list in `docs/wip/`.\n\n2. **Review the design.** Run `/review-design your-feature` to catch gaps before writing code.\n\n3. **Build it.** Type `/implement` — Claude executes the task list with code review checkpoints between batches.\n\n4. **Review the code.** `/review-code` checks for SOLID violations, security risks, and quality issues. Use `/review-code:isolated` for independent sub-agent reviewers with zero authorship bias.\n\nThis is the core loop. See the [kk plugin README](./klaude-plugin/README.md) for all available skills and the full workflow pipeline.\n\n## What's Included\n\n### MCP Servers\n\nFour servers provide complementary capabilities:\n\n| Server                                                          | Purpose                                                                                |\n| --------------------------------------------------------------- | -------------------------------------------------------------------------------------- |\n| **[Context7](https://context7.com/)**                           | Up-to-date library documentation and code examples                                     |\n| **[Serena](https://github.com/oraios/serena)**                  | Semantic code analysis via LSP — symbol navigation, reference tracking, targeted reads |\n| **[Pal](https://github.com/BeehiveInnovations/pal-mcp-server)** | Multi-model AI integration — chat, debugging, code review, planning, security audit    |\n| **[Capy](https://github.com/serpro69/capy)**                    | Persistent knowledge base — cross-session project memory with FTS5 search              |\n\n### Knowledge Base (Capy)\n\nSkills are **knowledge-aware** via [Capy](https://github.com/serpro69/capy). They search for relevant context before executing (architecture decisions, review findings, language idioms) and index valuable learnings after producing output. Knowledge persists across sessions per-project using an FTS5 full-text search index.\n\nWithout Capy, each session starts fresh — all skills still work, they just don't carry learnings forward. Install when you want cross-session memory.\n\n**Installation:** `brew install serpro69/tap/capy` then run `capy setup` in your project directory. The bootstrap script sets up Capy automatically if the binary is on PATH.\n\n### kk Plugin ([`klaude-plugin/`](./klaude-plugin/README.md))\n\nThe **kk** plugin contains all development workflow functionality — 10 skills, 4 commands, and hooks — distributed via the Claude Code plugin system. Skills are invoked as `/skill-name`, commands as `/kk:dir:command`.\n\nIncludes: **design**, **implement**, **test**, **document**, **development-guidelines**, **review-code**, **review-spec**, **review-design**, **merge-docs**, **chain-of-verification**. Plus commands for CoVe, implementation review, design review, Task Master migration, and sync workflow updates. See the [plugin README](./klaude-plugin/README.md) for full details.\n\n### Configuration\n\n- **Permission allowlist/denylist** (`.claude/settings.json`) — baseline permissions: auto-approves safe bash commands and WebSearch while blocking dangerous patterns. Per-repo MCP tool permissions go in `settings.local.json`.\n- **Status line** (`.claude/scripts/statusline_enhanced.sh`) — rich statusline with model, context %, git branch, session duration, thinking mode, and rate limits. Themes: set `CLAUDE_STATUSLINE_THEME` to `darcula`, `nord`, or `catppuccin`, and `CLAUDE_STATUSLINE_MODE` to `dark` (default) or `light` to match your terminal background\n- **Serena config** (`.serena/project.yml`) — language detection, gitignore integration, encoding settings\n\n### Template Infrastructure\n\n- **template-cleanup** — GitHub Action or local CLI script to initialize a new repo from this template\n- **template-sync** workflow — pull upstream configuration updates into your project via PR\n- **Sync exclusions** — prevent specific files from being re-added during sync\n- **Test suite** — 157 tests across 5 suites covering the plugin structure, sync/cleanup infrastructure\n\n## Recommended Settings\n\n\u003e [!TIP]\n\u003e Configure via `claude /config`. The config file is usually at `~/.claude.json`.\n\nThis is my current config, tweaked for best results. **I can't recommend enough disabling auto-compact** — I've seen many a time claude starting to compact conversations in the middle of a task, which produces very poor results for the remaining work it does after compacting.\n\n\u003cdetails\u003e\n\u003csummary\u003eFull \u003ccode\u003e/config\u003c/code\u003e settings\u003c/summary\u003e\n\n```\n\n\u003e /config\n────────────────────────────────────────────────────────────\n Configure Claude Code preferences\n\n    Auto-compact                              false\n    Show tips                                 true\n    Reduce motion                             false\n    Thinking mode                             true\n    Prompt suggestions                        true\n    Rewind code (checkpoints)                 true\n    Verbose output                            false\n    Terminal progress bar                     true\n    Default permission mode                   Default\n    Respect .gitignore in file picker         true\n    Auto-update channel                       latest\n    Theme                                     Dark mode\n    Notifications                             Auto\n    Output style                              default\n    Language                                  Default (English)\n    Editor mode                               vim\n    Show code diff footer                     true\n    Show PR status footer                     true\n    Model                                     opus\n    Auto-connect to IDE (external terminal)   false\n    Claude in Chrome enabled by default       false\n```\n\n\u003c/details\u003e\n\n## Receiving Template Updates\n\nRepos created from this template can pull configuration updates via the **Template Sync** workflow.\n\n### How Configuration Works\n\n\u003e [!NOTE]\n\u003e Claude Code settings are split between two project-scoped files:\n\u003e\n\u003e - **`.claude/settings.json`** — upstream-managed defaults, synced from this template (permissions baseline, env vars, model, plugins, statusline)\n\u003e - **`.claude/settings.local.json`** — your per-repo overrides, never synced (hooks, MCP server enables, additional permissions, personal preferences)\n\u003e\n\u003e You can edit `settings.json` directly if you like, they will be intelligently merged with this repo's settings, but the general advice is to place your customizations in `settings.local.json`. As an added bonus, \"Don't ask again\" grant prompts in claude-code sessions land in local settings automatically (as of v2.1.92).\n\n### Prerequisites\n\n- `.github/template-state.json` must exist (created automatically for new repos, or [manually for older ones](#migration-for-existing-repositories))\n- Allow actions to create pull-requests: repo **Settings** → **Actions**\n  \u003cimg width=\"792\" height=\"376\" alt=\"image\" src=\"https://github.com/user-attachments/assets/81343169-fa87-4631-ad5d-60fde7685538\" /\u003e\n\n### Using Template Sync\n\n1. Go to **Actions** → **Template Sync** → **Run workflow**\n2. Choose a version: `latest` (default), `master`, or a specific tag (e.g., `v1.2.3`)\n3. Optionally enable **dry_run** to preview changes without creating a PR\n4. Review and merge the created PR\n5. Merge to apply updates\n\n### What Gets Synced\n\n**Updated:** `.claude/` (settings, CLAUDE.extra.md, statusline scripts), `.serena/`, and the sync infrastructure itself. Skills, commands, and hooks are managed by the plugin system — not template sync.\n\n**Preserved:** Project-specific values (name, language, prompts), `settings.local.json`, gitignored files\n\n**settings.json merge behavior:** The sync uses smart-merge semantics — your downstream `settings.json` is \"master\" and upstream fills gaps:\n\n- **New keys** from upstream are added (e.g., new deny patterns, new env vars)\n- **Existing values** are never overwritten (your customizations are preserved)\n- **Arrays** are concatenated with deduplication (e.g., new upstream deny rules are appended)\n- **Manifest variables** (`CC_MODEL`, `CC_EFFORT_LEVEL`, etc.) still override after the merge — these are your explicit choices\n\n### Sync Exclusions\n\nIf you've removed template files you don't need, prevent sync from re-adding them:\n\nEdit `.github/template-state.json` and add a `sync_exclusions` array:\n\n```diff\n{\n  \"schema_version\": \"1\",\n  \"upstream_repo\": \"serpro69/claude-toolbox\",\n  \"template_version\": \"v0.2.0\",\n  \"synced_at\": \"2025-01-27T10:00:00Z\",\n+ \"sync_exclusions\": [\n+   \".claude/CLAUDE.extra.md\",\n+   \".claude/settings.json\"\n+ ],\n  \"variables\": { \"...\" : \"...\" }\n}\n```\n\n**Pattern syntax:**\n\n- Patterns use glob syntax where `*` matches any characters including directory separators\n- Patterns are matched against project-relative paths (e.g., `.claude/settings.json`)\n- Common patterns: `.claude/CLAUDE.extra.md` (single file), `.serena/*` (entire directory)\n\n**Behavior:**\n\n- Excluded files are NOT added if they exist upstream but not locally\n- Excluded files are NOT updated if they exist in both places\n- Excluded files are NOT flagged as deleted if they exist locally but not upstream\n- Excluded files appear as \"Excluded\" in the sync report for transparency\n\n### Migrating from Task Master\n\nTask Master MCP was removed in favor of native markdown-based task tracking integrated into the `design` and `implement` skills.\n\nThe easiest way to migrate is to run the migration command in Claude Code:\n\n```\n/kk:migrate-from-taskmaster:migrate\n```\n\nIt will port pending tasks, clean up TM files, update configs, and walk you through each step with confirmation prompts.\n\n\u003cdetails\u003e\n\u003csummary\u003eManual migration steps\u003c/summary\u003e\n\nIf you prefer to migrate manually, follow these steps after syncing:\n\n1. **Port any pending tasks** to the new format: create `/docs/wip/[feature]/tasks.md` files following the [example task file](./klaude-plugin/skills/design/example-tasks.md). Completed tasks don't need porting.\n\n1. **Remove Task Master files and config:**\n\n   ```bash\n   rm -rf .taskmaster\n   rm -rf .claude/commands/tm\n   rm -f .claude/TM_COMMANDS_GUIDE.md\n   rm -f .claude/agents/task-orchestrator.md\n   rm -f .claude/agents/task-executor.md\n   rm -f .claude/agents/task-checker.md\n   ```\n\n1. **Remove Task Master from `~/.claude.json`:** delete the `task-master-ai` entry from your `mcpServers` config.\n\n1. **Remove TM variables from `.github/template-state.json`:** delete `TM_CUSTOM_SYSTEM_PROMPT`, `TM_APPEND_SYSTEM_PROMPT`, and `TM_PERMISSION_MODE` from the `variables` object.\n\n1. **Remove TM references from `CLAUDE.md`:** delete the \"Task Master Integration\" and \"Task Master AI Instructions\" sections (including the `@./.taskmaster/CLAUDE.md` import).\n\n1. **Update the template-sync workflow** ([why?](https://github.com/serpro69/claude-toolbox/issues/17)): the old workflow contains taskmaster-specific sync logic that will break future syncs. Run `/kk:sync-workflow:sync-workflow latest` or manually replace both files:\n\n   ```bash\n   VERSION=\"v0.3.0\"  # or use latest tag\n   curl -fsSL \"https://raw.githubusercontent.com/serpro69/claude-toolbox/${VERSION}/.github/workflows/template-sync.yml\" \\\n     -o .github/workflows/template-sync.yml\n   curl -fsSL \"https://raw.githubusercontent.com/serpro69/claude-toolbox/${VERSION}/.github/scripts/template-sync.sh\" \\\n     -o .github/scripts/template-sync.sh\n   chmod +x .github/scripts/template-sync.sh\n   ```\n\nTask tracking now lives in simple markdown files (`/docs/wip/[feature]/tasks.md`) created by the `design` skill and consumed by `implement`. No external MCP server required.\n\n\u003c/details\u003e\n\n### Upgrading to the Plugin System (v0.5.0+)\n\nSkills and commands have moved from the template to the **kk** plugin:\n\n- Skills remain unprefixed: `/design` (annotated with `(kk)` in the menu)\n- Commands are now namespaced: `/project:chain-of-verification` → `/kk:chain-of-verification:default`\n- The template-sync workflow handles migration automatically on next sync\n- After merging the sync PR, run `/plugin install kk@claude-toolbox`\n\n### Adopting into Existing Repositories\n\nYou don't need to create a repo from this template to use the full configuration and sync infrastructure. Any existing repo can adopt it:\n\n1. **Install the kk plugin** to get all skills, commands, and hooks:\n\n   ```\n   /plugin install kk@claude-toolbox\n   ```\n\n2. **Set up sync infrastructure.** Create `.github/template-state.json`:\n\n   ```json\n   {\n     \"schema_version\": \"1\",\n     \"upstream_repo\": \"serpro69/claude-toolbox\",\n     \"template_version\": \"v1.0.0\",\n     \"synced_at\": \"1970-01-01T00:00:00Z\",\n     \"variables\": {\n       \"PROJECT_NAME\": \"my-cool-project\",\n       \"LANGUAGES\": \"go\",\n       \"CC_MODEL\": \"default\",\n       \"SERENA_INITIAL_PROMPT\": \"\"\n     }\n   }\n   ```\n\n   Copy `.github/workflows/template-sync.yml` and `.github/scripts/template-sync.sh` from the [template repository](https://github.com/serpro69/claude-toolbox).\n\n3. **Run Template Sync** from your repo's Actions tab to pull in the configuration (settings, Serena config, statusline, permissions). Review and merge the PR.\n\n\u003e [!TIP]\n\u003e Step 1 works standalone if you only want the skills. Steps 2-3 add the opinionated configuration and keep it in sync with upstream improvements.\n\n## Development\n\n### Running Tests\n\nTests across 5 suites cover the plugin structure, template sync/cleanup infrastructure:\n\n```bash\n# Run all test suites\nfor test in test/test-*.sh; do $test; done\n\n# Run individual suites\n./test/test-plugin-structure.sh  # Plugin manifest, skills, commands, hooks validation\n./test/test-template-sync.sh     # template-sync.sh function tests + plugin migration\n./test/test-template-cleanup.sh  # generate_manifest() tests\n./test/test-claude-extra.sh      # CLAUDE.extra.md detection and auto-import\n./test/test-manifest-jq.sh       # jq JSON pattern tests\n```\n\n| Test Suite               | Coverage                                                           |\n| ------------------------ | ------------------------------------------------------------------ |\n| test-plugin-structure.sh | Plugin/marketplace manifests, skills, commands, hooks, cross-refs  |\n| test-template-sync.sh    | CLI parsing, manifest validation, substitutions, plugin migration  |\n| test-template-cleanup.sh | Manifest generation, variable capture, git tag/SHA detection       |\n| test-claude-extra.sh     | CLAUDE.extra.md existence, compare_files detection, auto-import    |\n| test-manifest-jq.sh      | JSON generation, special character handling, round-trip validation |\n\n## Repository Structure\n\n```\nklaude-plugin/                   # kk plugin (distributed via plugin system)\n├── .claude-plugin/plugin.json   # Plugin manifest\n├── skills/                      # 10 development workflow skills\n├── commands/                    # 4 slash commands\n├── hooks/hooks.json             # Bash validation hook config\n└── scripts/validate-bash.sh     # Hook script\n\n.claude-plugin/marketplace.json  # Marketplace catalog\n\n.claude/\n├── CLAUDE.extra.md              # Always-loaded instructions\n├── settings.json                # Upstream-managed: permissions baseline, env, model, plugins\n├── settings.local.json          # Per-repo: hooks, MCP enables, additional permissions\n└── scripts/                     # statusline.sh, statusline_enhanced.sh, sync-workflow.sh\n\n.serena/\n└── project.yml                  # Serena LSP configuration\n\n.github/\n├── scripts/                     # template-cleanup.sh, template-sync.sh, bootstrap.sh\n├── workflows/                   # template-cleanup, template-sync\n└── template-state.json          # Sync manifest and variables\n\ntest/\n├── helpers.sh                   # Shared test utilities and assertions\n├── test-*.sh                    # 5 test suites\n└── fixtures/                    # Test manifests and templates\n```\n\n## Examples\n\nExamples of actual Claude Code workflows executed using this template's configs, skills, and tools: [examples/](./examples)\n\n## Contributing\n\nFeel free to open new PRs/issues. Any contributions you make are greatly appreciated.\n\n## License\n\nCopyright \u0026copy; 2025 - present, [serpro69](https://github.com/serpro69)\n\nDistributed under the ELv2 License.\n\nSee [`LICENSE.md`](https://github.com/serpro69/claude-toolbox/blob/master/LICENSE.md) file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserpro69%2Fclaude-toolbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserpro69%2Fclaude-toolbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserpro69%2Fclaude-toolbox/lists"}