From d1a6d2a2bc5b8302e61446f7440548e54cdb0b19 Mon Sep 17 00:00:00 2001 From: duthaho Date: Sun, 19 Apr 2026 14:09:14 +0700 Subject: [PATCH] feat: improved the Claude Kit as a plugin --- .claude-plugin/marketplace.json | 15 + .claude-plugin/plugin.json | 20 + .claude/CLAUDE.md | 387 ------------------ .claude/hooks/notify.cjs | 40 -- .claude/mcp/README.md | 309 -------------- .claude/mcp/context7.json | 31 -- .claude/mcp/magic.json | 43 -- .claude/mcp/puppeteer.json | 43 -- .claude/mcp/sequential.json | 31 -- .claude/settings.json | 66 --- .../writing-plans/templates/plan-template.md | 147 ------- .gitignore | 7 + .mcp.json | 24 -- CHANGELOG.md | 50 +++ CLAUDE.md | 31 ++ LICENSE | 21 + README.md | 292 +++++-------- {.claude/agents => agents}/api-designer.md | 0 {.claude/agents => agents}/brainstormer.md | 0 {.claude/agents => agents}/cicd-manager.md | 0 {.claude/agents => agents}/code-reviewer.md | 0 {.claude/agents => agents}/copywriter.md | 0 {.claude/agents => agents}/database-admin.md | 0 {.claude/agents => agents}/debugger.md | 0 {.claude/agents => agents}/docs-manager.md | 0 {.claude/agents => agents}/git-manager.md | 0 {.claude/agents => agents}/journal-writer.md | 0 .../agents => agents}/pipeline-architect.md | 0 {.claude/agents => agents}/planner.md | 0 {.claude/agents => agents}/project-manager.md | 0 {.claude/agents => agents}/researcher.md | 0 {.claude/agents => agents}/scout-external.md | 0 {.claude/agents => agents}/scout.md | 0 .../agents => agents}/security-auditor.md | 0 {.claude/agents => agents}/tester.md | 0 {.claude/agents => agents}/ui-ux-designer.md | 0 .../vulnerability-scanner.md | 0 {.claude/hooks => scripts}/auto-format.cjs | 15 +- .../block-dangerous-commands.cjs | 0 scripts/notify.cjs | 52 +++ .../skills => skills}/api-client/SKILL.md | 0 .../references/http-client-patterns.md | 0 .../api-client/references/patterns.md | 0 .../skills => skills}/authentication/SKILL.md | 0 .../authentication/references/auth-flows.md | 0 .../authentication/references/patterns.md | 0 .../backend-frameworks/SKILL.md | 0 .../backend-frameworks/references/django.md | 0 .../backend-frameworks/references/express.md | 0 .../backend-frameworks/references/fastapi.md | 0 .../backend-frameworks/references/nestjs.md | 0 .../background-jobs/SKILL.md | 0 .../skills => skills}/brainstorming/SKILL.md | 0 .../references/question-patterns.md | 0 {.claude/skills => skills}/caching/SKILL.md | 0 .../references/caching-decision-tree.md | 0 .../caching/references/patterns.md | 0 .../condition-based-waiting/SKILL.md | 0 {.claude/skills => skills}/databases/SKILL.md | 0 .../databases/references/migrations.md | 0 .../databases/references/mongodb.md | 0 .../databases/references/postgresql.md | 0 .../databases/references/redis.md | 0 .../defense-in-depth/SKILL.md | 0 .../references/validation-layers.md | 0 {.claude/skills => skills}/devops/SKILL.md | 0 .../devops/references/cloudflare-workers.md | 0 .../devops/references/docker.md | 0 .../devops/references/github-actions.md | 0 .../dispatching-parallel-agents/SKILL.md | 0 .../references/parallelization-patterns.md | 0 .../skills => skills}/documentation/SKILL.md | 0 .../documentation/references/api-docs.md | 0 .../documentation/references/code-docs.md | 0 .../documentation/references/project-docs.md | 0 .../skills => skills}/error-handling/SKILL.md | 0 .../references/error-taxonomy.md | 0 .../references/python-patterns.md | 0 .../references/typescript-patterns.md | 0 .../executing-plans/SKILL.md | 0 .../references/execution-checklist.md | 0 .../feature-workflow/SKILL.md | 0 .../finishing-a-development-branch/SKILL.md | 0 .../references/branch-completion-checklist.md | 0 .../frontend-styling/SKILL.md | 0 .../references/accessibility.md | 0 .../frontend-styling/references/tailwind.md | 0 {.claude/skills => skills}/frontend/SKILL.md | 0 .../frontend/references/nextjs.md | 0 .../frontend/references/react.md | 0 .../frontend/references/shadcn-ui.md | 0 .../skills => skills}/git-workflows/SKILL.md | 0 .../git-workflows/references/changelogs.md | 0 .../git-workflows/references/committing.md | 0 .../git-workflows/references/pull-requests.md | 0 .../git-workflows/references/shipping.md | 0 skills/init/SKILL.md | 161 ++++++++ skills/init/templates/hooks.json | 20 + skills/init/templates/mcp-servers.json | 52 +++ .../init/templates}/modes/brainstorm.md | 0 .../init/templates}/modes/deep-research.md | 0 .../init/templates}/modes/default.md | 0 .../init/templates}/modes/implementation.md | 6 - .../init/templates}/modes/orchestration.md | 44 +- .../init/templates}/modes/review.md | 64 +-- .../init/templates}/modes/token-efficient.md | 0 .../init/templates}/rules/api.md | 0 .../init/templates}/rules/frontend.md | 0 .../init/templates}/rules/migrations.md | 0 .../init/templates}/rules/security.md | 0 .../init/templates}/rules/testing.md | 0 {.claude/skills => skills}/languages/SKILL.md | 0 .../languages/references/javascript.md | 0 .../languages/references/python.md | 0 .../languages/references/typescript.md | 0 {.claude/skills => skills}/logging/SKILL.md | 0 .../logging/references/log-levels.md | 0 .../logging/references/python-patterns.md | 0 .../logging/references/typescript-patterns.md | 0 .../skills => skills}/mode-switching/SKILL.md | 0 {.claude/skills => skills}/openapi/SKILL.md | 0 .../openapi/references/api-governance.md | 0 .../openapi/references/http-status-codes.md | 0 .../openapi/references/production-patterns.md | 0 .../openapi/references/rest-naming.md | 0 .../templates/openapi-3.1-starter.yaml | 0 {.claude/skills => skills}/owasp/SKILL.md | 0 .../references/owasp-top10-cheatsheet.md | 0 .../owasp/references/patterns.md | 0 .../owasp/references/security-headers.md | 0 .../owasp/scripts/security-audit.py | 0 .../owasp/templates/security-checklist.md | 0 .../performance-optimization/SKILL.md | 0 .../references/anti-patterns.md | 0 .../references/profiling.md | 0 .../skills => skills}/playwright/SKILL.md | 0 .../playwright/references/e2e-patterns.md | 0 .../playwright/templates/playwright.config.ts | 0 .../receiving-code-review/SKILL.md | 0 .../references/feedback-categories.md | 0 .../skills => skills}/refactoring/SKILL.md | 0 .../refactoring/references/code-smells.md | 0 .../refactoring/references/patterns.md | 0 .../requesting-code-review/SKILL.md | 0 .../templates/review-request-template.md | 0 .../root-cause-tracing/SKILL.md | 0 .../references/tracing-techniques.md | 0 .../sequential-thinking/SKILL.md | 0 .../session-management/SKILL.md | 0 .../references/checkpoints.md | 0 .../session-management/references/indexing.md | 0 .../session-management/references/loading.md | 0 .../session-management/references/status.md | 0 .../state-management/SKILL.md | 0 .../state-management/references/patterns.md | 0 .../references/state-decision-tree.md | 0 .../subagent-driven-development/SKILL.md | 0 .../systematic-debugging/SKILL.md | 0 .../references/debugging-checklist.md | 0 .../test-driven-development/SKILL.md | 0 .../references/tdd-decision-tree.md | 0 .../testing-anti-patterns/SKILL.md | 0 .../references/anti-pattern-catalog.md | 0 {.claude/skills => skills}/testing/SKILL.md | 0 .../testing/references/jest.md | 0 .../testing/references/pytest.md | 0 .../testing/references/vitest.md | 0 .../using-git-worktrees/SKILL.md | 0 .../verification-before-completion/SKILL.md | 0 .../templates/verification-checklist.md | 0 .../writing-concisely/SKILL.md | 0 .../skills => skills}/writing-plans/SKILL.md | 0 .../skills => skills}/writing-skills/SKILL.md | 0 .../creating-agents-and-modes.md | 14 +- .../docs/customization/creating-skills.md | 6 +- .../docs/getting-started/configuration.md | 219 ++++------ .../docs/getting-started/installation.md | 156 ++++--- .../docs/getting-started/introduction.md | 15 +- website/src/content/docs/index.mdx | 23 +- website/src/content/docs/reference/agents.md | 2 +- .../src/content/docs/reference/mcp-servers.md | 36 +- website/src/content/docs/reference/modes.md | 4 +- website/src/content/docs/reference/skills.md | 10 +- .../docs/workflows/planning-and-building.md | 2 +- .../docs/workflows/reviewing-and-shipping.md | 2 +- .../docs/workflows/testing-and-debugging.md | 2 +- 186 files changed, 771 insertions(+), 1691 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json delete mode 100644 .claude/CLAUDE.md delete mode 100644 .claude/hooks/notify.cjs delete mode 100644 .claude/mcp/README.md delete mode 100644 .claude/mcp/context7.json delete mode 100644 .claude/mcp/magic.json delete mode 100644 .claude/mcp/puppeteer.json delete mode 100644 .claude/mcp/sequential.json delete mode 100644 .claude/settings.json delete mode 100644 .claude/skills/writing-plans/templates/plan-template.md create mode 100644 .gitignore delete mode 100644 .mcp.json create mode 100644 CHANGELOG.md create mode 100644 CLAUDE.md create mode 100644 LICENSE rename {.claude/agents => agents}/api-designer.md (100%) rename {.claude/agents => agents}/brainstormer.md (100%) rename {.claude/agents => agents}/cicd-manager.md (100%) rename {.claude/agents => agents}/code-reviewer.md (100%) rename {.claude/agents => agents}/copywriter.md (100%) rename {.claude/agents => agents}/database-admin.md (100%) rename {.claude/agents => agents}/debugger.md (100%) rename {.claude/agents => agents}/docs-manager.md (100%) rename {.claude/agents => agents}/git-manager.md (100%) rename {.claude/agents => agents}/journal-writer.md (100%) rename {.claude/agents => agents}/pipeline-architect.md (100%) rename {.claude/agents => agents}/planner.md (100%) rename {.claude/agents => agents}/project-manager.md (100%) rename {.claude/agents => agents}/researcher.md (100%) rename {.claude/agents => agents}/scout-external.md (100%) rename {.claude/agents => agents}/scout.md (100%) rename {.claude/agents => agents}/security-auditor.md (100%) rename {.claude/agents => agents}/tester.md (100%) rename {.claude/agents => agents}/ui-ux-designer.md (100%) rename {.claude/agents => agents}/vulnerability-scanner.md (100%) rename {.claude/hooks => scripts}/auto-format.cjs (63%) rename {.claude/hooks => scripts}/block-dangerous-commands.cjs (100%) create mode 100644 scripts/notify.cjs rename {.claude/skills => skills}/api-client/SKILL.md (100%) rename {.claude/skills => skills}/api-client/references/http-client-patterns.md (100%) rename {.claude/skills => skills}/api-client/references/patterns.md (100%) rename {.claude/skills => skills}/authentication/SKILL.md (100%) rename {.claude/skills => skills}/authentication/references/auth-flows.md (100%) rename {.claude/skills => skills}/authentication/references/patterns.md (100%) rename {.claude/skills => skills}/backend-frameworks/SKILL.md (100%) rename {.claude/skills => skills}/backend-frameworks/references/django.md (100%) rename {.claude/skills => skills}/backend-frameworks/references/express.md (100%) rename {.claude/skills => skills}/backend-frameworks/references/fastapi.md (100%) rename {.claude/skills => skills}/backend-frameworks/references/nestjs.md (100%) rename {.claude/skills => skills}/background-jobs/SKILL.md (100%) rename {.claude/skills => skills}/brainstorming/SKILL.md (100%) rename {.claude/skills => skills}/brainstorming/references/question-patterns.md (100%) rename {.claude/skills => skills}/caching/SKILL.md (100%) rename {.claude/skills => skills}/caching/references/caching-decision-tree.md (100%) rename {.claude/skills => skills}/caching/references/patterns.md (100%) rename {.claude/skills => skills}/condition-based-waiting/SKILL.md (100%) rename {.claude/skills => skills}/databases/SKILL.md (100%) rename {.claude/skills => skills}/databases/references/migrations.md (100%) rename {.claude/skills => skills}/databases/references/mongodb.md (100%) rename {.claude/skills => skills}/databases/references/postgresql.md (100%) rename {.claude/skills => skills}/databases/references/redis.md (100%) rename {.claude/skills => skills}/defense-in-depth/SKILL.md (100%) rename {.claude/skills => skills}/defense-in-depth/references/validation-layers.md (100%) rename {.claude/skills => skills}/devops/SKILL.md (100%) rename {.claude/skills => skills}/devops/references/cloudflare-workers.md (100%) rename {.claude/skills => skills}/devops/references/docker.md (100%) rename {.claude/skills => skills}/devops/references/github-actions.md (100%) rename {.claude/skills => skills}/dispatching-parallel-agents/SKILL.md (100%) rename {.claude/skills => skills}/dispatching-parallel-agents/references/parallelization-patterns.md (100%) rename {.claude/skills => skills}/documentation/SKILL.md (100%) rename {.claude/skills => skills}/documentation/references/api-docs.md (100%) rename {.claude/skills => skills}/documentation/references/code-docs.md (100%) rename {.claude/skills => skills}/documentation/references/project-docs.md (100%) rename {.claude/skills => skills}/error-handling/SKILL.md (100%) rename {.claude/skills => skills}/error-handling/references/error-taxonomy.md (100%) rename {.claude/skills => skills}/error-handling/references/python-patterns.md (100%) rename {.claude/skills => skills}/error-handling/references/typescript-patterns.md (100%) rename {.claude/skills => skills}/executing-plans/SKILL.md (100%) rename {.claude/skills => skills}/executing-plans/references/execution-checklist.md (100%) rename {.claude/skills => skills}/feature-workflow/SKILL.md (100%) rename {.claude/skills => skills}/finishing-a-development-branch/SKILL.md (100%) rename {.claude/skills => skills}/finishing-a-development-branch/references/branch-completion-checklist.md (100%) rename {.claude/skills => skills}/frontend-styling/SKILL.md (100%) rename {.claude/skills => skills}/frontend-styling/references/accessibility.md (100%) rename {.claude/skills => skills}/frontend-styling/references/tailwind.md (100%) rename {.claude/skills => skills}/frontend/SKILL.md (100%) rename {.claude/skills => skills}/frontend/references/nextjs.md (100%) rename {.claude/skills => skills}/frontend/references/react.md (100%) rename {.claude/skills => skills}/frontend/references/shadcn-ui.md (100%) rename {.claude/skills => skills}/git-workflows/SKILL.md (100%) rename {.claude/skills => skills}/git-workflows/references/changelogs.md (100%) rename {.claude/skills => skills}/git-workflows/references/committing.md (100%) rename {.claude/skills => skills}/git-workflows/references/pull-requests.md (100%) rename {.claude/skills => skills}/git-workflows/references/shipping.md (100%) create mode 100644 skills/init/SKILL.md create mode 100644 skills/init/templates/hooks.json create mode 100644 skills/init/templates/mcp-servers.json rename {.claude => skills/init/templates}/modes/brainstorm.md (100%) rename {.claude => skills/init/templates}/modes/deep-research.md (100%) rename {.claude => skills/init/templates}/modes/default.md (100%) rename {.claude => skills/init/templates}/modes/implementation.md (95%) rename {.claude => skills/init/templates}/modes/orchestration.md (76%) rename {.claude => skills/init/templates}/modes/review.md (64%) rename {.claude => skills/init/templates}/modes/token-efficient.md (100%) rename {.claude => skills/init/templates}/rules/api.md (100%) rename {.claude => skills/init/templates}/rules/frontend.md (100%) rename {.claude => skills/init/templates}/rules/migrations.md (100%) rename {.claude => skills/init/templates}/rules/security.md (100%) rename {.claude => skills/init/templates}/rules/testing.md (100%) rename {.claude/skills => skills}/languages/SKILL.md (100%) rename {.claude/skills => skills}/languages/references/javascript.md (100%) rename {.claude/skills => skills}/languages/references/python.md (100%) rename {.claude/skills => skills}/languages/references/typescript.md (100%) rename {.claude/skills => skills}/logging/SKILL.md (100%) rename {.claude/skills => skills}/logging/references/log-levels.md (100%) rename {.claude/skills => skills}/logging/references/python-patterns.md (100%) rename {.claude/skills => skills}/logging/references/typescript-patterns.md (100%) rename {.claude/skills => skills}/mode-switching/SKILL.md (100%) rename {.claude/skills => skills}/openapi/SKILL.md (100%) rename {.claude/skills => skills}/openapi/references/api-governance.md (100%) rename {.claude/skills => skills}/openapi/references/http-status-codes.md (100%) rename {.claude/skills => skills}/openapi/references/production-patterns.md (100%) rename {.claude/skills => skills}/openapi/references/rest-naming.md (100%) rename {.claude/skills => skills}/openapi/templates/openapi-3.1-starter.yaml (100%) rename {.claude/skills => skills}/owasp/SKILL.md (100%) rename {.claude/skills => skills}/owasp/references/owasp-top10-cheatsheet.md (100%) rename {.claude/skills => skills}/owasp/references/patterns.md (100%) rename {.claude/skills => skills}/owasp/references/security-headers.md (100%) rename {.claude/skills => skills}/owasp/scripts/security-audit.py (100%) rename {.claude/skills => skills}/owasp/templates/security-checklist.md (100%) rename {.claude/skills => skills}/performance-optimization/SKILL.md (100%) rename {.claude/skills => skills}/performance-optimization/references/anti-patterns.md (100%) rename {.claude/skills => skills}/performance-optimization/references/profiling.md (100%) rename {.claude/skills => skills}/playwright/SKILL.md (100%) rename {.claude/skills => skills}/playwright/references/e2e-patterns.md (100%) rename {.claude/skills => skills}/playwright/templates/playwright.config.ts (100%) rename {.claude/skills => skills}/receiving-code-review/SKILL.md (100%) rename {.claude/skills => skills}/receiving-code-review/references/feedback-categories.md (100%) rename {.claude/skills => skills}/refactoring/SKILL.md (100%) rename {.claude/skills => skills}/refactoring/references/code-smells.md (100%) rename {.claude/skills => skills}/refactoring/references/patterns.md (100%) rename {.claude/skills => skills}/requesting-code-review/SKILL.md (100%) rename {.claude/skills => skills}/requesting-code-review/templates/review-request-template.md (100%) rename {.claude/skills => skills}/root-cause-tracing/SKILL.md (100%) rename {.claude/skills => skills}/root-cause-tracing/references/tracing-techniques.md (100%) rename {.claude/skills => skills}/sequential-thinking/SKILL.md (100%) rename {.claude/skills => skills}/session-management/SKILL.md (100%) rename {.claude/skills => skills}/session-management/references/checkpoints.md (100%) rename {.claude/skills => skills}/session-management/references/indexing.md (100%) rename {.claude/skills => skills}/session-management/references/loading.md (100%) rename {.claude/skills => skills}/session-management/references/status.md (100%) rename {.claude/skills => skills}/state-management/SKILL.md (100%) rename {.claude/skills => skills}/state-management/references/patterns.md (100%) rename {.claude/skills => skills}/state-management/references/state-decision-tree.md (100%) rename {.claude/skills => skills}/subagent-driven-development/SKILL.md (100%) rename {.claude/skills => skills}/systematic-debugging/SKILL.md (100%) rename {.claude/skills => skills}/systematic-debugging/references/debugging-checklist.md (100%) rename {.claude/skills => skills}/test-driven-development/SKILL.md (100%) rename {.claude/skills => skills}/test-driven-development/references/tdd-decision-tree.md (100%) rename {.claude/skills => skills}/testing-anti-patterns/SKILL.md (100%) rename {.claude/skills => skills}/testing-anti-patterns/references/anti-pattern-catalog.md (100%) rename {.claude/skills => skills}/testing/SKILL.md (100%) rename {.claude/skills => skills}/testing/references/jest.md (100%) rename {.claude/skills => skills}/testing/references/pytest.md (100%) rename {.claude/skills => skills}/testing/references/vitest.md (100%) rename {.claude/skills => skills}/using-git-worktrees/SKILL.md (100%) rename {.claude/skills => skills}/verification-before-completion/SKILL.md (100%) rename {.claude/skills => skills}/verification-before-completion/templates/verification-checklist.md (100%) rename {.claude/skills => skills}/writing-concisely/SKILL.md (100%) rename {.claude/skills => skills}/writing-plans/SKILL.md (100%) rename {.claude/skills => skills}/writing-skills/SKILL.md (100%) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..72706e6 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,15 @@ +{ + "name": "claudekit-dev", + "owner": { + "name": "duthaho", + "url": "https://github.com/duthaho" + }, + "plugins": [ + { + "name": "claudekit", + "description": "Comprehensive toolkit — 44 skills, 20 agents, interactive setup wizard for rules, modes, hooks, and MCP servers.", + "version": "3.0.0", + "source": "./" + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..1599113 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "claudekit", + "version": "3.0.0", + "description": "Comprehensive toolkit for Claude Code — 44 skills, 20 agents, and an interactive setup wizard for rules, modes, hooks, and MCP servers.", + "author": { + "name": "duthaho", + "url": "https://github.com/duthaho" + }, + "repository": "https://github.com/duthaho/claudekit", + "license": "MIT", + "keywords": [ + "claudekit", + "skills", + "agents", + "workflow", + "tdd", + "debugging", + "planning" + ] +} diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md deleted file mode 100644 index 5b0d99a..0000000 --- a/.claude/CLAUDE.md +++ /dev/null @@ -1,387 +0,0 @@ -# Claude Kit - Project Context Template - -## Overview - -This is a comprehensive Claude Kit for Claude Code, designed to accelerate development workflows for small teams (1-3 developers) working with Python and JavaScript/TypeScript multi-stack projects. - -## Quick Reference - -### Key Skills (auto-triggered) - -| Skill | Triggers on | -|-------|------------| -| `feature-workflow` | "feature", "implement", "build", "add functionality" | -| `systematic-debugging` | "bug", "error", "failing", "broken", stack traces | -| `git-workflows` | "commit", "PR", "ship", "changelog" | -| `writing-plans` | "plan", "break down", "implementation steps" | -| `brainstorming` | "brainstorm", "design", "explore", "trade-offs" | -| `documentation` | "document", "docstring", "README", "API docs" | -| `refactoring` | "refactor", "clean up", "extract", "simplify" | -| `performance-optimization` | "slow", "performance", "profiling", "N+1" | -| `mode-switching` | "mode", "switch mode", "token-efficient" | -| `session-management` | "checkpoint", "index", "load context", "status" | - -## Tech Stack - - -- **Languages**: Python, TypeScript, JavaScript -- **Backend Frameworks**: FastAPI, Django, NestJS, Express -- **Frontend Frameworks**: Next.js, React -- **Databases**: PostgreSQL, MongoDB -- **Testing**: pytest, vitest, Jest, Playwright -- **DevOps**: Docker, GitHub Actions, Cloudflare - -## Architecture - - -``` -src/ -├── api/ # API endpoints -├── services/ # Business logic -├── models/ # Data models -├── utils/ # Utilities -└── tests/ # Test files -``` - -## Code Conventions - -### Naming Conventions - -| Type | Python | TypeScript/JavaScript | -|------|--------|----------------------| -| Files | `snake_case.py` | `kebab-case.ts` | -| Functions | `snake_case` | `camelCase` | -| Classes | `PascalCase` | `PascalCase` | -| Constants | `UPPER_SNAKE` | `UPPER_SNAKE` | -| Components | N/A | `PascalCase.tsx` | - -### Code Style - -- **Python**: Follow PEP 8, use type hints, docstrings for public APIs -- **TypeScript**: Strict mode enabled, no `any` types, use interfaces -- **JavaScript**: ESLint + Prettier, prefer `const` over `let` - -### File Organization - -- One component/class per file -- Group related files in feature directories -- Keep test files adjacent to source files or in `tests/` directory - -## Testing Standards - -### Coverage Requirements -- Minimum coverage: 80% -- Critical paths: 95% - -### Test Naming -- **Python**: `test_[function]_[scenario]_[expected]` -- **TypeScript**: `describe('[Component]', () => { it('should [behavior]') })` - -### Test Types -1. **Unit tests**: All business logic functions -2. **Integration tests**: API endpoints, database operations -3. **E2E tests**: Critical user flows - -## Security Standards - -### Forbidden Patterns -- No hardcoded secrets or API keys -- No `eval()` or dynamic code execution -- No SQL string concatenation (use parameterized queries) -- No `any` types in TypeScript -- No disabled security headers - -### Required Practices -- Input validation on all user inputs -- Output encoding for all rendered content -- Authentication on all protected endpoints -- Rate limiting on public APIs -- Secrets via environment variables only - -## Git Conventions - -### Branch Naming -- `feature/[ticket]-[description]` -- `fix/[ticket]-[description]` -- `hotfix/[description]` -- `chore/[description]` - -### Commit Messages -``` -type(scope): subject - -body (optional) - -footer (optional) -``` - -Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` - -### PR Requirements -- Descriptive title and description -- Linked to issue/ticket -- All tests passing -- Code review approved -- No merge conflicts - -## Agent Behavior Overrides - - - -### Planner Agent -- Break tasks into chunks of 15-60 minutes -- Always identify testing requirements -- Flag external dependencies - -### Code-Reviewer Agent -- Enforce strict typing -- Security-first reviews -- Check for test coverage - -### Tester Agent -- Prefer pytest for Python, vitest for TypeScript -- Generate edge case tests -- Include error scenario tests - -### Debugger Agent -- Check logs first -- Reproduce before fixing -- Add regression tests - -## Behavioral Modes - - - -Modes adjust communication style, output format, and problem-solving approach. - -| Mode | Description | Best For | -|------|-------------|----------| -| `default` | Balanced standard behavior | General tasks | -| `brainstorm` | Creative exploration, questions | Design, ideation | -| `writing-concisely` | Compressed, concise output | High-volume, cost savings | -| `deep-research` | Thorough analysis, citations | Investigation, audits | -| `implementation` | Code-focused, minimal prose | Executing plans | -| `review` | Critical analysis, finding issues | Code review, QA | -| `orchestration` | Multi-task coordination | Complex parallel work | - -### Mode Activation - -Ask Claude to switch modes naturally: -- "switch to brainstorm mode" → creative exploration -- "use implementation mode" → code-focused, minimal prose -- "switch to token-efficient mode" → compressed output (30-70% savings) - -Mode files: `.claude/modes/` - -## Token Optimization - - - -Control output verbosity for cost optimization. - -| Level | Activation | Savings | Description | -|-------|-----------|---------|-------------| -| Standard | (default) | 0% | Full explanations | -| Concise | "be concise" | 30-40% | Reduced explanations | -| Ultra | "code only" | 60-70% | Code-only responses | -| Session | "switch to token-efficient mode" | 30-70% | Compressed for session | - -Reference: `.claude/skills/writing-concisely/SKILL.md` - -## Context Management - -These features are provided by the `session-management` skill: - -- **Project Indexing** — "generate a project index" → scans and creates PROJECT_INDEX.md -- **Context Loading** — "load the API context" → reads relevant files into context -- **Checkpoints** — "save checkpoint feature-x" → git stash + metadata for session recovery -- **Status** — "what's the project status?" → git state, tasks, recent commits - -## MCP Integrations - - - -Optional MCP servers for extended capabilities. - -| Server | Purpose | Status | -|--------|---------|--------| -| Context7 | Library documentation lookup | Optional | -| Sequential | Multi-step reasoning tools | Optional | -| Playwright | Browser automation (Microsoft) | Optional | -| Memory | Persistent knowledge graph | Optional | -| Filesystem | Secure file operations | Optional | - -Setup: See `.claude/mcp/README.md` - -## Methodology Settings - - - -Settings to control the integrated superpowers development methodology. - -### Planning Granularity - -| Mode | Task Size | Use Case | -|------|-----------|----------| -| `standard` | 15-60 min | Quick planning, experienced team | -| `detailed` | 2-5 min | Thorough plans with exact code | - -To use detailed mode: "plan this in detail" or "break this into 2-5 min tasks" - -### Brainstorming Style - -| Style | Description | -|-------|-------------| -| `standard` | All questions at once | -| `interactive` | One question per message with validation | - -To use interactive mode: "let's brainstorm [topic]" - -### Execution Mode - -| Mode | Description | -|------|-------------| -| `manual` | Developer executes tasks from plan | -| `subagent` | Automated execution with code review gates | - -To use subagent mode: "execute the plan" or "run the plan with subagents" - -### TDD Strictness - -For strict TDD enforcement (no production code without failing test): -- Auto-triggers on implementation tasks -- Reference: `.claude/skills/test-driven-development/SKILL.md` - -### Verification Requirements - -Enable mandatory verification before completion claims: -- Reference: `.claude/skills/verification-before-completion/SKILL.md` - -### Available Skills - -| Category | Skills | -|----------|--------| -| **Languages** | languages (Python, TypeScript, JavaScript) | -| **Backend** | backend-frameworks (FastAPI, Django, NestJS, Express) | -| **Frontend** | frontend (React, Next.js, shadcn/ui), frontend-styling (Tailwind, accessibility) | -| **Databases** | databases (PostgreSQL, MongoDB, Redis, migrations) | -| **DevOps** | devops (Docker, GitHub Actions, Cloudflare Workers) | -| **Security** | owasp | -| **API** | openapi | -| **Testing** | testing (pytest, vitest, Jest), playwright | -| **Optimization** | writing-concisely, performance-optimization | -| **Developer Patterns** | error-handling, state-management, logging, caching, api-client, authentication, background-jobs | -| **Workflows** | feature-workflow, git-workflows, documentation, refactoring | -| **Session** | mode-switching, session-management | -| **Methodology - Planning** | brainstorming, writing-plans, executing-plans, writing-skills | -| **Methodology - Testing** | test-driven-development, verification-before-completion, testing-anti-patterns | -| **Methodology - Debugging** | systematic-debugging, root-cause-tracing, defense-in-depth | -| **Methodology - Collaboration** | dispatching-parallel-agents, requesting-code-review, receiving-code-review, finishing-a-development-branch | -| **Methodology - Execution** | subagent-driven-development, using-git-worktrees, condition-based-waiting | -| **Methodology - Reasoning** | sequential-thinking | - -Skills location: `.claude/skills/` - -Each skill includes: -- YAML frontmatter with trigger description -- "When to Use" / "When NOT to Use" sections -- Core patterns with code examples -- Best practices and common pitfalls -- Bundled reference docs, templates, and scripts - -### Sequential Thinking - -For complex problems requiring step-by-step analysis: -- Reference: `.claude/skills/sequential-thinking/SKILL.md` -- Activation: auto-triggers on complex reasoning tasks, or use deep-research mode - -## Environment Configuration - - - -### Development -```bash -# Python -python -m venv venv -source venv/bin/activate # or venv\Scripts\activate on Windows -pip install -r requirements.txt - -# Node.js -pnpm install -pnpm dev -``` - -### Testing -```bash -# Python -pytest -v --cov=src - -# Node.js -pnpm test -pnpm test:coverage -``` - -### Deployment -```bash -# Build -pnpm build - -# Deploy -pnpm deploy:staging -pnpm deploy:production -``` - -## External Integrations - - - -### APIs -- GitHub API for issue tracking -- Slack for notifications (optional) - -### Services -- Database: PostgreSQL / MongoDB -- Cache: Redis (optional) -- Storage: S3 / Cloudflare R2 - -## Documentation Standards - -### Code Documentation -- Public functions: Docstrings required -- Complex logic: Inline comments -- APIs: OpenAPI/Swagger specs - -### Project Documentation -- README.md: Quick start guide -- CONTRIBUTING.md: Contribution guidelines -- CHANGELOG.md: Version history - -## Troubleshooting - -### Common Issues - -**Python import errors** -```bash -export PYTHONPATH="${PYTHONPATH}:${PWD}" -``` - -**Node modules issues** -```bash -rm -rf node_modules pnpm-lock.yaml -pnpm install -``` - -**Database connection** -- Check `.env` file for correct credentials -- Ensure database service is running - ---- - -## Kit Version - -- **Claude Kit Version**: 3.0.0 -- **Last Updated**: 2026-04-18 -- **Compatible with**: Claude Code 1.0+ -- **Total Skills**: 43 (with YAML frontmatter, bundled resources) -- **Total Agents**: 20 -- **Behavioral Modes**: 7 diff --git a/.claude/hooks/notify.cjs b/.claude/hooks/notify.cjs deleted file mode 100644 index 5ab44f8..0000000 --- a/.claude/hooks/notify.cjs +++ /dev/null @@ -1,40 +0,0 @@ -#!/usr/bin/env node -/** - * Notification hook: cross-platform desktop notification. - * Supports macOS (osascript), Linux (notify-send), and Windows (PowerShell). - * Fails open — notification errors are silently ignored. - */ -"use strict"; - -const { execSync } = require("child_process"); -const os = require("os"); - -function notify(title, message) { - const platform = os.platform(); - - const commands = { - darwin: `osascript -e 'display notification "${message}" with title "${title}"'`, - linux: `notify-send "${title}" "${message}"`, - win32: `powershell.exe -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('${message}', '${title}', 'OK', 'Information')"`, - }; - - const cmd = commands[platform]; - if (cmd) { - execSync(cmd, { stdio: "ignore", timeout: 5000 }); - } -} - -async function main() { - try { - let data = ""; - for await (const chunk of process.stdin) data += chunk; - const input = JSON.parse(data); - - const message = input?.message ?? "Needs your attention"; - notify("Claude Code", message); - } catch { - // Fail open — notification errors should never block work - } -} - -main(); diff --git a/.claude/mcp/README.md b/.claude/mcp/README.md deleted file mode 100644 index 8211643..0000000 --- a/.claude/mcp/README.md +++ /dev/null @@ -1,309 +0,0 @@ -# MCP Server Integrations - -Model Context Protocol (MCP) servers extend Claude Code capabilities with specialized tools and integrations. - -## Available MCP Servers - -| Server | Purpose | Status | -|--------|---------|--------| -| Context7 | Up-to-date library documentation | Optional | -| Sequential | Multi-step reasoning tools | Optional | -| Playwright | Browser automation (Microsoft) | Optional | -| Memory | Persistent knowledge graph | Optional | -| Filesystem | Secure file operations | Optional | - -## Installation - -### Prerequisites -- Node.js 18+ -- npx available in PATH - -### Global Configuration - -MCP servers are configured in your Claude Code settings: - -**Location**: `~/.claude/settings.json` (user) or `.mcp.json` (project) - -### Quick Setup - -1. Copy the configuration for your platform (see below) -2. Add to your `.mcp.json` or `settings.json` under `mcpServers` -3. Restart Claude Code - -## Platform-Specific Configuration - -MCP server configuration differs between platforms: - -### Linux / macOS - -```json -{ - "mcpServers": { - "context7": { - "command": "npx", - "args": ["-y", "@upstash/context7-mcp"] - } - } -} -``` - -### Windows - -Windows requires the `cmd /c` wrapper to execute npx: - -```json -{ - "mcpServers": { - "context7": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@upstash/context7-mcp"] - } - } -} -``` - -> **Note**: The `.mcp.json` included in this repository uses Windows syntax. Linux/macOS users should use the configurations in this README. - -## Server Configurations - -### Context7 (Documentation Lookup) - -Provides up-to-date documentation for libraries and frameworks. - -```json -{ - "mcpServers": { - "context7": { - "command": "npx", - "args": ["-y", "@upstash/context7-mcp"] - } - } -} -``` - -**Usage**: Ask about any library and get current documentation. - -**Tools**: -- `resolve-library-id` - Find library IDs for documentation lookup -- `get-library-docs` - Fetch documentation for a specific library - -### Sequential Thinking - -Provides structured reasoning tools for complex problem-solving. - -```json -{ - "mcpServers": { - "sequential": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] - } - } -} -``` - -**Usage**: Complex analysis with step-by-step reasoning. - -**Tools**: -- `sequentialthinking` - Dynamic problem-solving through thought sequences - -### Playwright (Browser Automation) - -Microsoft's browser automation using accessibility tree for fast, LLM-friendly interaction. - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": ["-y", "@playwright/mcp"] - } - } -} -``` - -**Usage**: Web testing, screenshots, form automation. - -**Key Features**: -- Fast and lightweight - uses accessibility tree, not pixels -- LLM-friendly - no vision models needed -- Supports Chrome, Firefox, WebKit, Edge -- Device emulation and profile management - -**Command-Line Options**: -- `--browser ` - Browser to use (chrome, firefox, webkit, msedge) -- `--headless` - Run browser in headless mode -- `--viewport-size ` - Viewport size (e.g., "1280x720") -- `--device ` - Device to emulate (e.g., "iPhone 15") - -### Memory (Persistent Knowledge Graph) - -Maintains persistent memory across sessions using a local knowledge graph. - -```json -{ - "mcpServers": { - "memory": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-memory"] - } - } -} -``` - -**Usage**: Remember information across conversations and sessions. - -**Tools**: -- `create_entities` - Create new entities in the knowledge graph -- `create_relations` - Create relationships between entities -- `add_observations` - Add observations to entities -- `delete_entities` - Remove entities from the graph -- `delete_observations` - Remove observations -- `delete_relations` - Remove relationships -- `read_graph` - Read the entire knowledge graph -- `search_nodes` - Search for entities -- `open_nodes` - Open specific entities by name - -### Filesystem (Secure File Operations) - -Enables secure file operations with configurable access controls. - -```json -{ - "mcpServers": { - "filesystem": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] - } - } -} -``` - -**Usage**: Read, write, and manage files with access controls. - -**Tools**: -- `read_file` - Read file contents -- `read_multiple_files` - Read multiple files at once -- `write_file` - Write content to a file -- `edit_file` - Make edits to a file -- `create_directory` - Create a new directory -- `list_directory` - List directory contents -- `directory_tree` - Get directory tree structure -- `move_file` - Move or rename files -- `search_files` - Search for files by pattern -- `get_file_info` - Get file metadata - -**Note**: The last argument specifies the allowed directory (`.` for current directory). - -## Full Configuration Example - -### Linux / macOS - -```json -{ - "mcpServers": { - "context7": { - "command": "npx", - "args": ["-y", "@upstash/context7-mcp"] - }, - "sequential": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] - }, - "playwright": { - "command": "npx", - "args": ["-y", "@playwright/mcp"] - }, - "memory": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-memory"] - }, - "filesystem": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] - } - } -} -``` - -### Windows - -```json -{ - "mcpServers": { - "context7": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@upstash/context7-mcp"] - }, - "sequential": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"] - }, - "playwright": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@playwright/mcp"] - }, - "memory": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"] - }, - "filesystem": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "."] - } - } -} -``` - -## Optional Additional Servers - -These servers can be added for extended functionality: - -| Server | Package | Purpose | -|--------|---------|---------| -| Fetch | `mcp-server-fetch` (uvx) | Web content fetching | -| Brave Search | `@modelcontextprotocol/server-brave-search` | Web search (requires API key) | -| PostgreSQL | `@modelcontextprotocol/server-postgres` | Database access | -| Sentry | `@sentry/mcp-server` | Error tracking | -| GitHub | `@github/mcp-server` | GitHub API operations | - -## Verification - -After configuration, verify servers are loaded: - -1. Start a new Claude Code session -2. Check for MCP tools in available capabilities -3. Test with a simple request - -## Troubleshooting - -### Server Not Loading -- Check Node.js version (18+ required) -- Verify npx is in PATH -- Check for typos in configuration -- Review Claude Code logs - -### Permission Errors -- Ensure network access for package installation -- Check firewall settings -- Verify npm registry access - -### Slow Startup -- First run downloads packages (one-time) -- Subsequent starts should be faster -- Consider pre-installing packages globally - -## Security Notes - -- MCP servers run with your user permissions -- Review server source before installing -- Playwright has browser access - use carefully -- Context7 makes network requests to documentation sources -- Filesystem server restricts access to specified directories - -## Resources - -- [MCP Protocol Documentation](https://modelcontextprotocol.io/) -- [Available MCP Servers](https://github.com/modelcontextprotocol/servers) -- [Microsoft Playwright MCP](https://github.com/microsoft/playwright-mcp) -- [Claude Code MCP Guide](https://docs.anthropic.com/claude-code/mcp) diff --git a/.claude/mcp/context7.json b/.claude/mcp/context7.json deleted file mode 100644 index fd9ed40..0000000 --- a/.claude/mcp/context7.json +++ /dev/null @@ -1,31 +0,0 @@ -{ - "name": "context7", - "description": "Up-to-date library documentation lookup via Context7", - "config": { - "mcpServers": { - "context7": { - "command": "npx", - "args": ["-y", "@context7/mcp-server"] - } - } - }, - "capabilities": [ - "Library documentation lookup", - "API reference retrieval", - "Framework documentation", - "Package documentation" - ], - "usage": { - "example_prompts": [ - "What's the latest API for React useEffect?", - "Show me FastAPI dependency injection docs", - "How do I use Prisma transactions?", - "What are the Next.js 14 app router conventions?" - ] - }, - "requirements": { - "node": ">=18.0.0", - "network": true - }, - "notes": "Provides real-time documentation lookup. Useful for getting current API information that may be newer than training data." -} diff --git a/.claude/mcp/magic.json b/.claude/mcp/magic.json deleted file mode 100644 index 66897b2..0000000 --- a/.claude/mcp/magic.json +++ /dev/null @@ -1,43 +0,0 @@ -{ - "name": "magic", - "description": "AI-powered UI component generation from descriptions", - "config": { - "mcpServers": { - "magic": { - "command": "npx", - "args": ["-y", "@anthropic/magic-mcp-server"] - } - } - }, - "capabilities": [ - "UI component generation", - "React component creation", - "Tailwind CSS styling", - "Responsive design", - "Component variations" - ], - "usage": { - "example_prompts": [ - "Generate a pricing card component", - "Create a navigation header with dropdown menus", - "Build a user profile card with avatar and stats", - "Design a dashboard layout with sidebar", - "Make a responsive hero section" - ] - }, - "requirements": { - "node": ">=18.0.0", - "network": true - }, - "output": { - "formats": ["React", "Vue", "HTML"], - "styling": ["Tailwind CSS", "CSS Modules", "Styled Components"], - "features": [ - "Responsive by default", - "Accessible markup", - "Dark mode support", - "Component composition" - ] - }, - "notes": "Generates production-ready UI components. Best used with Tailwind CSS projects. Review generated code before using in production." -} diff --git a/.claude/mcp/puppeteer.json b/.claude/mcp/puppeteer.json deleted file mode 100644 index 43666fb..0000000 --- a/.claude/mcp/puppeteer.json +++ /dev/null @@ -1,43 +0,0 @@ -{ - "name": "puppeteer", - "description": "Browser automation for testing and web interaction", - "config": { - "mcpServers": { - "puppeteer": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-puppeteer"] - } - } - }, - "capabilities": [ - "Browser automation", - "Screenshot capture", - "Form interaction", - "Page navigation", - "DOM manipulation", - "Network interception" - ], - "usage": { - "example_prompts": [ - "Take a screenshot of the login page", - "Fill out the registration form and submit", - "Navigate through the checkout flow", - "Extract data from this web page", - "Test the responsive design at different viewports" - ] - }, - "requirements": { - "node": ">=18.0.0", - "chromium": "Auto-downloaded by Puppeteer" - }, - "security": { - "warning": "Puppeteer has full browser access. Use with caution.", - "recommendations": [ - "Only use on trusted sites", - "Avoid entering real credentials", - "Review actions before execution", - "Use in sandboxed environments when possible" - ] - }, - "notes": "Powerful for E2E testing and web automation. Use responsibly and verify actions before execution." -} diff --git a/.claude/mcp/sequential.json b/.claude/mcp/sequential.json deleted file mode 100644 index 491a6dd..0000000 --- a/.claude/mcp/sequential.json +++ /dev/null @@ -1,31 +0,0 @@ -{ - "name": "sequential-thinking", - "description": "Structured multi-step reasoning tools for complex analysis", - "config": { - "mcpServers": { - "sequential": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] - } - } - }, - "capabilities": [ - "Step-by-step reasoning", - "Hypothesis tracking", - "Evidence collection", - "Confidence scoring", - "Decision documentation" - ], - "usage": { - "example_prompts": [ - "Analyze this bug systematically", - "Walk through this architecture decision step by step", - "Investigate the root cause with sequential thinking", - "Document the reasoning for this design choice" - ] - }, - "requirements": { - "node": ">=18.0.0" - }, - "notes": "Enhances complex problem-solving with structured reasoning. Pairs well with the sequential-thinking skill and deep-research mode." -} diff --git a/.claude/settings.json b/.claude/settings.json deleted file mode 100644 index 2878a3a..0000000 --- a/.claude/settings.json +++ /dev/null @@ -1,66 +0,0 @@ -{ - "$schema": "https://json.schemastore.org/claude-code-settings.json", - "permissions": { - "allow": [ - "Bash(git:*)", - "Bash(npm:*)", - "Bash(npx:*)", - "Bash(pnpm:*)", - "Bash(yarn:*)", - "Bash(pip:*)", - "Bash(poetry:*)", - "Bash(python:*)", - "Bash(node:*)", - "Bash(pytest:*)", - "Bash(ruff:*)", - "Bash(eslint:*)", - "Bash(prettier:*)", - "Bash(tsc:*)", - "Bash(docker:*)", - "Bash(gh:*)" - ], - "deny": [ - "Read(.env*)", - "Write(.env*)", - "Edit(.env*)", - "Read(**/secrets/**)", - "Write(**/secrets/**)", - "Edit(**/secrets/**)" - ] - }, - "hooks": { - "PreToolUse": [ - { - "matcher": "Bash", - "hooks": [ - { - "type": "command", - "command": "node .claude/hooks/block-dangerous-commands.cjs" - } - ] - } - ], - "PostToolUse": [ - { - "matcher": "Write|Edit", - "hooks": [ - { - "type": "command", - "command": "node .claude/hooks/auto-format.cjs" - } - ] - } - ], - "Notification": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "node .claude/hooks/notify.cjs" - } - ] - } - ] - } -} diff --git a/.claude/skills/writing-plans/templates/plan-template.md b/.claude/skills/writing-plans/templates/plan-template.md deleted file mode 100644 index f823701..0000000 --- a/.claude/skills/writing-plans/templates/plan-template.md +++ /dev/null @@ -1,147 +0,0 @@ -# [Feature Name] Implementation Plan - -> **Author:** [name] -> **Date:** [date] -> **Status:** Draft | In Review | Approved | In Progress | Complete -> **Estimated Total:** [X hours/days] - ---- - -## Context - -### Problem Statement -[One paragraph describing what problem this solves and why it matters now.] - -### Background -[Any relevant context: prior decisions, related features, technical debt involved.] - -### Goals -- [Primary goal] -- [Secondary goal] - -### Non-Goals -- [What this plan explicitly does NOT address] - ---- - -## Tasks - -### Task 1: [Name] (estimated: Xmin) - -**Description:** [What this task accomplishes and why it's needed.] - -**Files to modify:** -- `path/to/file.ts` — [what changes] -- `path/to/other.py` — [what changes] - -**New files:** -- `path/to/new-file.ts` — [purpose] - -**Changes:** -1. [Specific change with enough detail to implement without ambiguity] -2. [Next change] - -**Tests:** -- [ ] [Test description — what behavior is verified] -- [ ] [Edge case test] - -**Verification:** -- [ ] [How to verify this task is complete — command to run, behavior to observe] - ---- - -### Task 2: [Name] (estimated: Xmin) - -**Description:** [What this task accomplishes.] - -**Dependencies:** Task 1 (requires [specific output]) - -**Files to modify:** -- `path/to/file.ts` — [what changes] - -**Changes:** -1. [Specific change] -2. [Next change] - -**Tests:** -- [ ] [Test description] - -**Verification:** -- [ ] [Verification step] - ---- - -### Task 3: [Name] (estimated: Xmin) - -[Repeat the same structure. Add as many tasks as needed.] - ---- - -## Dependencies - -### Internal Dependencies -| Task | Depends On | Reason | -|------|-----------|--------| -| Task 2 | Task 1 | [Why] | - -### External Dependencies -- [ ] [External service, API key, environment setup, etc.] -- [ ] [Approval or decision needed from someone] - -### Parallel Work -[Which tasks can be done simultaneously? Group them.] - -- **Group A (independent):** Task 1, Task 3 -- **Group B (requires Group A):** Task 2, Task 4 - ---- - -## Risks - -| Risk | Likelihood | Impact | Mitigation | -|------|-----------|--------|------------| -| [What could go wrong] | Low/Med/High | Low/Med/High | [How to prevent or handle it] | - ---- - -## Verification Plan - -### Automated Checks -```bash -# Run full test suite -[test command] - -# Run type checks -[type check command] - -# Run linter -[lint command] -``` - -### Manual Checks -- [ ] [Specific scenario to test manually] -- [ ] [Edge case to verify by hand] - -### Acceptance Criteria -- [ ] [Criterion 1 — ties back to Goals section] -- [ ] [Criterion 2] - ---- - -## Notes - -[Any additional context, open questions, or decisions to revisit.] - ---- - -## Usage Instructions - -**To use this template:** - -1. Copy this file and rename it: `plan-[feature-name].md` -2. Fill in all sections. If a section doesn't apply, write "N/A" rather than deleting it -3. For **standard plans**: tasks should be 15-60 minutes each -4. For **detailed plans** (`--detailed`): tasks should be 2-5 minutes with exact code snippets -5. Every task must have at least one verification step -6. Every task must list the specific files it touches -7. Remove these usage instructions from your copy diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7857ef2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +node_modules/ +.env +.env.* +.DS_Store +Thumbs.db +PLAN-*.md +*.log diff --git a/.mcp.json b/.mcp.json deleted file mode 100644 index a3b624a..0000000 --- a/.mcp.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "mcpServers": { - "context7": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@upstash/context7-mcp"] - }, - "sequential": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"] - }, - "playwright": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@playwright/mcp"] - }, - "memory": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"] - }, - "filesystem": { - "command": "cmd", - "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "."] - } - } -} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d4ebaea --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,50 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [3.0.0] - 2026-04-19 + +### Changed +- Migrated from clone-and-copy `.claude/` directory to Claude Code plugin format +- Skills moved from `.claude/skills/` to `skills/` at repo root (namespaced as `/claudekit:`) +- Agents moved from `.claude/agents/` to `agents/` at repo root (namespaced as `claudekit:`) +- Hook scripts moved from `.claude/hooks/` to `scripts/` (opt-in via init wizard) +- Rules and modes converted to templates scaffolded by `/claudekit:init` +- MCP server configs now opt-in via `/claudekit:init` with platform auto-detection +- Fixed command injection vulnerabilities in auto-format and notify hook scripts + +### Added +- `/claudekit:init` setup wizard — interactive scaffolding for rules, modes, hooks, and MCP servers +- `--all` flag for `/claudekit:init` to skip prompts and install everything +- `.claude-plugin/plugin.json` manifest for plugin distribution +- `.claude-plugin/marketplace.json` for local development testing +- Platform-aware MCP configs (win32 and posix variants) +- `MARKETPLACE.md` with instructions for creating the distribution marketplace +- `CHANGELOG.md`, `LICENSE`, `CLAUDE.md` + +### Removed +- `.claude/CLAUDE.md` (project-specific, not distributed with plugin) +- `.claude/settings.json` (too project-specific for plugin distribution) +- Root `.mcp.json` (replaced by opt-in setup via init wizard) + +## [2.0.0] - 2026-04-18 + +### Changed +- Migrated 27 slash commands to skills with YAML frontmatter +- Restructured all skills to flat directory layout with router pattern + +### Added +- YAML frontmatter parameters on all 43 skills +- Bundled resources (references/, templates/, scripts/) per skill +- 7 behavioral modes +- 5 rules with path-based activation + +## [1.0.0] - 2026-04-17 + +### Added +- Initial release with 20 agents, 43 skills +- MCP server integrations (Context7, Sequential, Playwright, Memory, Filesystem) +- 3 hooks (auto-format, block-dangerous-commands, notify) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7e1accc --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,31 @@ +# Claudekit Plugin + +This is the claudekit plugin — a comprehensive toolkit for Claude Code with 44 skills, 20 agents, and an interactive setup wizard. + +## Plugin Structure + +- `skills/` — 44 auto-triggered skills (invoked as `/claudekit:`) +- `agents/` — 20 specialized agents (invoked as `claudekit:`) +- `scripts/` — Hook scripts installed via `/claudekit:init` +- `skills/init/templates/` — Templates for rules, modes, hooks, and MCP configs + +## Setup + +After installing the plugin, run `/claudekit:init` to scaffold project-level configuration (rules, modes, hooks, MCP servers) into your project's `.claude/` directory. + +## Skills + +Skills auto-trigger based on context. Key categories: + +- **Tech Stack**: languages, backend-frameworks, frontend, frontend-styling, databases, devops, testing +- **Domain**: openapi, owasp, playwright, error-handling, state-management, logging, caching, api-client +- **Patterns**: authentication, background-jobs, writing-concisely +- **Workflows**: feature-workflow, git-workflows, documentation, refactoring, performance-optimization, mode-switching, session-management +- **Methodology**: brainstorming, writing-plans, executing-plans, test-driven-development, systematic-debugging, verification-before-completion, and more + +## Conventions + +- Skills use YAML frontmatter with `name`, `description`, and optional `user-invocable`, `argument-hint`, `disable-model-invocation` +- Agents use markdown frontmatter with `name`, `description`, `model`, `tools`, `disallowedTools` +- Hook scripts follow "fail open" pattern — errors never block work +- Templates in `skills/init/templates/` are copied to the user's project, not loaded as plugin context diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..5d5ba14 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 duthaho + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index e3af527..f9753b6 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,74 @@ # Claude Kit -A comprehensive toolkit for Claude Code to accelerate development workflows for teams working with Python and JavaScript/TypeScript. +A comprehensive Claude Code plugin to accelerate development workflows for teams working with Python and JavaScript/TypeScript. ## Features +- **44 Skills** - Auto-triggered by context: framework, language, methodology, patterns, workflows, optimization (all with YAML frontmatter and bundled resources) - **20 Specialized Agents** - From planning to deployment -- **43 Skills** - Auto-triggered by context: framework, language, methodology, patterns, workflows, optimization (all with YAML frontmatter and bundled resources) -- **7 Behavioral Modes** - Task-specific response optimization +- **Interactive Setup Wizard** - `/claudekit:init` scaffolds rules, modes, hooks, and MCP configs into your project +- **7 Behavioral Modes** - Task-specific response optimization (installed via init) - **Token Optimization** - 30-70% cost savings with compressed output modes -- **MCP Integrations** - Context7, Sequential Thinking, Playwright, Memory, Filesystem -- **Context Management** - Project indexing, checkpoints, parallel tasks +- **MCP Integrations** - Context7, Sequential Thinking, Playwright, Memory, Filesystem (configured via init) ## Quick Start -1. Copy the `.claude` folder to your project root -2. Customize `.claude/CLAUDE.md` for your project -3. Start working — skills auto-trigger based on what you ask ("implement X", "fix Y", "review Z") +### Install via Marketplace -## Directory Structure +1. Add the claudekit marketplace: + ``` + /plugin marketplace add duthaho/claudekit-marketplace + ``` + +2. Install the plugin: + ``` + /plugin install claudekit + ``` + +3. Run the setup wizard to configure your project: + ``` + /claudekit:init + ``` + + Or install everything at once: + ``` + /claudekit:init --all + ``` + +### Local Development + +Test the plugin locally without installing: +``` +claude --plugin-dir ./path/to/claudekit +``` + +## What `/claudekit:init` Configures + +The setup wizard interactively scaffolds project-level configuration: + +| Category | What | Location | +|----------|------|----------| +| **Rules** | API, frontend, migrations, security, testing | `.claude/rules/` | +| **Modes** | brainstorm, deep-research, default, implementation, orchestration, review, token-efficient | `.claude/modes/` | +| **Hooks** | auto-format, block-dangerous-commands, notifications | `.claude/hooks/` + `settings.local.json` | +| **MCP Servers** | Context7, Sequential, Playwright, Memory, Filesystem | `.mcp.json` | + +## Plugin Structure ``` -.claude/ -├── CLAUDE.md # Project context (customize this!) -├── settings.json # Hooks, permissions, and MCP config -├── agents/ # 20 specialized agents -├── modes/ # 7 behavioral mode definitions -├── mcp/ # MCP server configurations -└── skills/ # 43 flat skills (router pattern) - ├── / # Each skill is a top-level directory - │ ├── SKILL.md # Trigger description + core patterns - │ └── references/ # Deep content loaded on demand - └── ... +claudekit/ +├── .claude-plugin/ +│ └── plugin.json # Plugin manifest +├── skills/ # 44 skills (auto-triggered) +│ ├── init/ # Setup wizard (/claudekit:init) +│ │ ├── SKILL.md +│ │ └── templates/ # Rules, modes, hooks, MCP templates +│ ├── brainstorming/ +│ ├── systematic-debugging/ +│ └── ... +├── agents/ # 20 specialized agents +├── scripts/ # Hook scripts (installed via init) +└── website/ # Documentation site ``` ## Agents @@ -38,51 +76,43 @@ A comprehensive toolkit for Claude Code to accelerate development workflows for ### Core Development | Agent | Description | |-------|-------------| -| `planner` | Task decomposition and planning | -| `researcher` | Technology research | -| `debugger` | Error analysis and fixing | -| `tester` | Test generation | -| `code-reviewer` | Code review with security focus | -| `scout` | Codebase exploration | +| `claudekit:planner` | Task decomposition and planning | +| `claudekit:debugger` | Error analysis and fixing | +| `claudekit:tester` | Test generation | +| `claudekit:code-reviewer` | Code review with security focus | +| `claudekit:scout` | Codebase exploration | ### Operations | Agent | Description | |-------|-------------| -| `git-manager` | Git operations and PRs | -| `docs-manager` | Documentation generation | -| `project-manager` | Progress tracking | -| `database-admin` | Schema and migrations | -| `ui-ux-designer` | UI component creation | +| `claudekit:git-manager` | Git operations and PRs | +| `claudekit:docs-manager` | Documentation generation | +| `claudekit:project-manager` | Progress tracking | +| `claudekit:database-admin` | Schema and migrations | +| `claudekit:ui-ux-designer` | UI component creation | + +### Content & Research +| Agent | Description | +|-------|-------------| +| `claudekit:researcher` | Technology research | +| `claudekit:scout-external` | External resource exploration | +| `claudekit:copywriter` | Marketing copy and release notes | +| `claudekit:journal-writer` | Development journals and decision logs | ### Extended | Agent | Description | |-------|-------------| -| `cicd-manager` | CI/CD pipeline management | -| `security-auditor` | Security reviews | -| `api-designer` | API design and OpenAPI | -| `vulnerability-scanner` | Security scanning | -| `pipeline-architect` | Pipeline optimization | +| `claudekit:cicd-manager` | CI/CD pipeline management | +| `claudekit:security-auditor` | Security reviews | +| `claudekit:api-designer` | API design and OpenAPI | +| `claudekit:vulnerability-scanner` | Security scanning | +| `claudekit:pipeline-architect` | Pipeline optimization | -## Skills as Commands +## Skills (44 Total) -All former slash commands have been migrated to skills that auto-trigger based on context: +Skills auto-trigger based on context. After plugin install, invoke manually with `/claudekit:`. -```bash -# Skills auto-trigger — just describe what you want: -"implement user authentication" # → feature-workflow + authentication -"this endpoint is slow" # → performance-optimization -"commit these changes" # → git-workflows -"refactor this function" # → refactoring -"add docs to this module" # → documentation -"scan for security issues" # → owasp -"switch to brainstorm mode" # → mode-switching -``` - -## Skills (43 Total) - -Every skill follows a flat directory structure with a router pattern: short `SKILL.md` for triggering + `references/` for deep content loaded on demand. Skills auto-trigger based on context — no slash commands needed. - -### Tech Stack Skills (7 merged routers) +### Tech Stack Skills (7) | Skill | Covers | Key Topics | |-------|--------|------------| @@ -115,11 +145,11 @@ Every skill follows a flat directory structure with a router pattern: short `SKI | **background-jobs** | Celery, BullMQ, task queues, scheduled tasks, async workers | | **writing-concisely** | Compressed output modes (30-70% token savings) | -### Workflow Skills (7 — migrated from commands) +### Workflow Skills (7) | Skill | Description | |-------|-------------| -| **feature-workflow** | End-to-end feature development: requirements → planning → implementation → testing → review | +| **feature-workflow** | End-to-end feature development: requirements -> planning -> implementation -> testing -> review | | **git-workflows** | Conventional commits, shipping, PRs, changelogs | | **documentation** | Docstrings, JSDoc, API docs, README generation | | **refactoring** | Code smell detection, extract/rename/simplify patterns, safe refactoring workflow | @@ -138,12 +168,11 @@ Every skill follows a flat directory structure with a router pattern: short `SKI | **Execution** | subagent-driven-development, using-git-worktrees, condition-based-waiting | | **Reasoning** | sequential-thinking | -Key methodology principles: -- **TDD Strict**: No production code without failing test first -- **Verification**: Evidence-based completion claims -- **Quality Gates**: Code review between every task -- **Bite-sized Tasks**: 2-5 minute increments with exact code -- **Sequential Thinking**: Step-by-step reasoning with confidence scores +### Setup Skill (1) + +| Skill | Description | +|-------|-------------| +| **init** | Interactive setup wizard — scaffolds rules, modes, hooks, MCP configs | ### Bundled Resources @@ -157,7 +186,7 @@ Skills include progressive-disclosure resources loaded on demand: ## Behavioral Modes -Switch modes to optimize responses for different task types: +Installed via `/claudekit:init`. Switch modes to optimize responses: | Mode | Description | Best For | |------|-------------|----------| @@ -170,24 +199,13 @@ Switch modes to optimize responses for different task types: | `orchestration` | Multi-task coordination | Parallel work | ``` -"switch to brainstorm mode" # → mode-switching skill activates -"let's focus on implementation" # → implementation mode +"switch to brainstorm mode" # -> mode-switching skill activates +"let's focus on implementation" # -> implementation mode ``` -## Token Optimization - -Reduce costs by 30-70% with compressed output modes: - -| Level | Activation | Savings | -|-------|------------|---------| -| Standard | (default) | 0% | -| Concise | Ask for concise output | 30-40% | -| Ultra | Ask for code-only responses | 60-70% | -| Session | "switch to token-efficient mode" | 30-70% | - ## MCP Integrations -MCP servers extend Claude Kit with powerful capabilities. They are **automatically used** when configured. +Configured via `/claudekit:init`. MCP servers extend Claude Kit with powerful capabilities. | Server | Package | Purpose | |--------|---------|---------| @@ -197,137 +215,29 @@ MCP servers extend Claude Kit with powerful capabilities. They are **automatical | Memory | `@modelcontextprotocol/server-memory` | Persistent knowledge graph | | Filesystem | `@modelcontextprotocol/server-filesystem` | Secure file operations | -### How MCP Servers Enhance Skills - -| Skill | MCP Servers Used | Enhancement | -|-------|------------------|-------------| -| feature-workflow | Context7, Sequential, Filesystem | Accurate docs, structured planning, safe file ops | -| systematic-debugging | Sequential, Memory, Playwright | Step-by-step debugging, context recall, browser testing | -| testing, playwright | Playwright, Filesystem | E2E browser tests, test file management | -| writing-plans | Sequential, Memory | Structured breakdown, remembers decisions | -| brainstorming | Sequential, Memory, Context7 | Creative exploration, persistent ideas | -| session-management | Filesystem, Memory | Project scanning, context persistence | - -### Example: Full Feature Development - -``` -"Add user profile with avatar upload" -``` - -1. **feature-workflow** skill activates → orchestrates the workflow -2. **Context7** → Fetches latest React/Next.js file upload docs -3. **Sequential** → Plans component structure step-by-step -4. **Memory** → Recalls your UI patterns from previous sessions -5. **Playwright** → Tests the upload flow in browser - -Setup: See `.claude/mcp/README.md` - -## Customization - -### CLAUDE.md - -The `.claude/CLAUDE.md` file is your project context. Customize it with: - -```markdown -# Project: Your Project Name - -## Tech Stack -- **Backend**: FastAPI -- **Frontend**: Next.js -- **Database**: PostgreSQL - -## Conventions -- Use type hints -- 80% test coverage -- Conventional commits - -## Agent Overrides -### Tester -- Framework: pytest -- Coverage: 90% -``` - -### Adding Custom Skills - -Create a new skill in `.claude/skills//SKILL.md`: - -```yaml ---- -name: my-skill -description: > - What this skill does and when to trigger it. Be specific — list - contexts, keywords, and scenarios. 2-4 pushy sentences. ---- -``` - -```markdown -# My Skill - -Brief overview. - -## When to Use -- Scenario 1 -- Scenario 2 - -## When NOT to Use -- Anti-trigger scenario - ---- - -## Core Patterns -### Pattern Name -Code examples with good/bad comparisons. - -## Best Practices -## Common Pitfalls -## Related Skills -``` - -Optionally add bundled resources: -``` -my-skill/ -├── SKILL.md -├── references/ # Loaded into context on demand -├── scripts/ # Executed without loading into context -└── templates/ # Scaffolded into user's project -``` - ## Workflow Chains -Skills chain automatically based on context. Here are common flows: +Skills chain automatically based on context: ### Feature Development ``` -brainstorming → writing-plans → feature-workflow → requesting-code-review → git-workflows +brainstorming -> writing-plans -> feature-workflow -> requesting-code-review -> git-workflows ``` ### Bug Fix ``` -systematic-debugging → root-cause-tracing → test-driven-development → verification-before-completion +systematic-debugging -> root-cause-tracing -> test-driven-development -> verification-before-completion ``` ### Ship Code ``` -verification-before-completion → requesting-code-review → git-workflows → finishing-a-development-branch +verification-before-completion -> requesting-code-review -> git-workflows -> finishing-a-development-branch ``` -### Superpowers Workflow (Detailed) -``` -brainstorming → writing-plans → executing-plans → git-workflows -``` -Uses one-question-at-a-time design, 2-5 min tasks with exact code, subagent execution with code review gates. - ### Parallel Work ``` -dispatching-parallel-agents → subagent-driven-development → verification-before-completion +dispatching-parallel-agents -> subagent-driven-development -> verification-before-completion ``` -Launch multiple agents for independent tasks, then verify results. - -### Cost-Optimized Session -``` -"switch to token-efficient mode" → [work on tasks] → "switch to default mode" -``` -Enable compressed outputs for high-volume sessions. ## Requirements @@ -341,4 +251,4 @@ MIT --- -Built with duthaho +Built by duthaho diff --git a/.claude/agents/api-designer.md b/agents/api-designer.md similarity index 100% rename from .claude/agents/api-designer.md rename to agents/api-designer.md diff --git a/.claude/agents/brainstormer.md b/agents/brainstormer.md similarity index 100% rename from .claude/agents/brainstormer.md rename to agents/brainstormer.md diff --git a/.claude/agents/cicd-manager.md b/agents/cicd-manager.md similarity index 100% rename from .claude/agents/cicd-manager.md rename to agents/cicd-manager.md diff --git a/.claude/agents/code-reviewer.md b/agents/code-reviewer.md similarity index 100% rename from .claude/agents/code-reviewer.md rename to agents/code-reviewer.md diff --git a/.claude/agents/copywriter.md b/agents/copywriter.md similarity index 100% rename from .claude/agents/copywriter.md rename to agents/copywriter.md diff --git a/.claude/agents/database-admin.md b/agents/database-admin.md similarity index 100% rename from .claude/agents/database-admin.md rename to agents/database-admin.md diff --git a/.claude/agents/debugger.md b/agents/debugger.md similarity index 100% rename from .claude/agents/debugger.md rename to agents/debugger.md diff --git a/.claude/agents/docs-manager.md b/agents/docs-manager.md similarity index 100% rename from .claude/agents/docs-manager.md rename to agents/docs-manager.md diff --git a/.claude/agents/git-manager.md b/agents/git-manager.md similarity index 100% rename from .claude/agents/git-manager.md rename to agents/git-manager.md diff --git a/.claude/agents/journal-writer.md b/agents/journal-writer.md similarity index 100% rename from .claude/agents/journal-writer.md rename to agents/journal-writer.md diff --git a/.claude/agents/pipeline-architect.md b/agents/pipeline-architect.md similarity index 100% rename from .claude/agents/pipeline-architect.md rename to agents/pipeline-architect.md diff --git a/.claude/agents/planner.md b/agents/planner.md similarity index 100% rename from .claude/agents/planner.md rename to agents/planner.md diff --git a/.claude/agents/project-manager.md b/agents/project-manager.md similarity index 100% rename from .claude/agents/project-manager.md rename to agents/project-manager.md diff --git a/.claude/agents/researcher.md b/agents/researcher.md similarity index 100% rename from .claude/agents/researcher.md rename to agents/researcher.md diff --git a/.claude/agents/scout-external.md b/agents/scout-external.md similarity index 100% rename from .claude/agents/scout-external.md rename to agents/scout-external.md diff --git a/.claude/agents/scout.md b/agents/scout.md similarity index 100% rename from .claude/agents/scout.md rename to agents/scout.md diff --git a/.claude/agents/security-auditor.md b/agents/security-auditor.md similarity index 100% rename from .claude/agents/security-auditor.md rename to agents/security-auditor.md diff --git a/.claude/agents/tester.md b/agents/tester.md similarity index 100% rename from .claude/agents/tester.md rename to agents/tester.md diff --git a/.claude/agents/ui-ux-designer.md b/agents/ui-ux-designer.md similarity index 100% rename from .claude/agents/ui-ux-designer.md rename to agents/ui-ux-designer.md diff --git a/.claude/agents/vulnerability-scanner.md b/agents/vulnerability-scanner.md similarity index 100% rename from .claude/agents/vulnerability-scanner.md rename to agents/vulnerability-scanner.md diff --git a/.claude/hooks/auto-format.cjs b/scripts/auto-format.cjs similarity index 63% rename from .claude/hooks/auto-format.cjs rename to scripts/auto-format.cjs index d564881..768abaf 100644 --- a/.claude/hooks/auto-format.cjs +++ b/scripts/auto-format.cjs @@ -6,15 +6,15 @@ */ "use strict"; -const { execSync } = require("child_process"); +const { execFileSync } = require("child_process"); const path = require("path"); const FORMATTERS = { - ".py": (f) => `ruff check --fix "${f}"`, - ".ts": (f) => `npx eslint --fix "${f}"`, - ".tsx": (f) => `npx eslint --fix "${f}"`, - ".js": (f) => `npx eslint --fix "${f}"`, - ".jsx": (f) => `npx eslint --fix "${f}"`, + ".py": (f) => ({ cmd: "ruff", args: ["check", "--fix", f] }), + ".ts": (f) => ({ cmd: "npx", args: ["eslint", "--fix", f] }), + ".tsx": (f) => ({ cmd: "npx", args: ["eslint", "--fix", f] }), + ".js": (f) => ({ cmd: "npx", args: ["eslint", "--fix", f] }), + ".jsx": (f) => ({ cmd: "npx", args: ["eslint", "--fix", f] }), }; async function main() { @@ -30,7 +30,8 @@ async function main() { const formatter = FORMATTERS[ext]; if (!formatter) return; - execSync(formatter(filePath), { + const { cmd, args } = formatter(filePath); + execFileSync(cmd, args, { stdio: "ignore", timeout: 10000, }); diff --git a/.claude/hooks/block-dangerous-commands.cjs b/scripts/block-dangerous-commands.cjs similarity index 100% rename from .claude/hooks/block-dangerous-commands.cjs rename to scripts/block-dangerous-commands.cjs diff --git a/scripts/notify.cjs b/scripts/notify.cjs new file mode 100644 index 0000000..c4f1940 --- /dev/null +++ b/scripts/notify.cjs @@ -0,0 +1,52 @@ +#!/usr/bin/env node +/** + * Notification hook: cross-platform desktop notification. + * Supports macOS (osascript), Linux (notify-send), and Windows (PowerShell). + * Fails open — notification errors are silently ignored. + */ +"use strict"; + +const { execFileSync } = require("child_process"); +const os = require("os"); + +function sanitize(str) { + return str.replace(/[^\w\s.,!?:;\-()]/g, ""); +} + +function notify(title, message) { + const platform = os.platform(); + const safeTitle = sanitize(title); + const safeMessage = sanitize(message); + + if (platform === "darwin") { + execFileSync("osascript", [ + "-e", + `display notification "${safeMessage}" with title "${safeTitle}"`, + ], { stdio: "ignore", timeout: 5000 }); + } else if (platform === "linux") { + execFileSync("notify-send", [safeTitle, safeMessage], { + stdio: "ignore", + timeout: 5000, + }); + } else if (platform === "win32") { + execFileSync("powershell.exe", [ + "-Command", + `Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('${safeMessage}', '${safeTitle}', 'OK', 'Information')`, + ], { stdio: "ignore", timeout: 5000 }); + } +} + +async function main() { + try { + let data = ""; + for await (const chunk of process.stdin) data += chunk; + const input = JSON.parse(data); + + const message = input?.message ?? "Needs your attention"; + notify("Claude Code", message); + } catch { + // Fail open — notification errors should never block work + } +} + +main(); diff --git a/.claude/skills/api-client/SKILL.md b/skills/api-client/SKILL.md similarity index 100% rename from .claude/skills/api-client/SKILL.md rename to skills/api-client/SKILL.md diff --git a/.claude/skills/api-client/references/http-client-patterns.md b/skills/api-client/references/http-client-patterns.md similarity index 100% rename from .claude/skills/api-client/references/http-client-patterns.md rename to skills/api-client/references/http-client-patterns.md diff --git a/.claude/skills/api-client/references/patterns.md b/skills/api-client/references/patterns.md similarity index 100% rename from .claude/skills/api-client/references/patterns.md rename to skills/api-client/references/patterns.md diff --git a/.claude/skills/authentication/SKILL.md b/skills/authentication/SKILL.md similarity index 100% rename from .claude/skills/authentication/SKILL.md rename to skills/authentication/SKILL.md diff --git a/.claude/skills/authentication/references/auth-flows.md b/skills/authentication/references/auth-flows.md similarity index 100% rename from .claude/skills/authentication/references/auth-flows.md rename to skills/authentication/references/auth-flows.md diff --git a/.claude/skills/authentication/references/patterns.md b/skills/authentication/references/patterns.md similarity index 100% rename from .claude/skills/authentication/references/patterns.md rename to skills/authentication/references/patterns.md diff --git a/.claude/skills/backend-frameworks/SKILL.md b/skills/backend-frameworks/SKILL.md similarity index 100% rename from .claude/skills/backend-frameworks/SKILL.md rename to skills/backend-frameworks/SKILL.md diff --git a/.claude/skills/backend-frameworks/references/django.md b/skills/backend-frameworks/references/django.md similarity index 100% rename from .claude/skills/backend-frameworks/references/django.md rename to skills/backend-frameworks/references/django.md diff --git a/.claude/skills/backend-frameworks/references/express.md b/skills/backend-frameworks/references/express.md similarity index 100% rename from .claude/skills/backend-frameworks/references/express.md rename to skills/backend-frameworks/references/express.md diff --git a/.claude/skills/backend-frameworks/references/fastapi.md b/skills/backend-frameworks/references/fastapi.md similarity index 100% rename from .claude/skills/backend-frameworks/references/fastapi.md rename to skills/backend-frameworks/references/fastapi.md diff --git a/.claude/skills/backend-frameworks/references/nestjs.md b/skills/backend-frameworks/references/nestjs.md similarity index 100% rename from .claude/skills/backend-frameworks/references/nestjs.md rename to skills/backend-frameworks/references/nestjs.md diff --git a/.claude/skills/background-jobs/SKILL.md b/skills/background-jobs/SKILL.md similarity index 100% rename from .claude/skills/background-jobs/SKILL.md rename to skills/background-jobs/SKILL.md diff --git a/.claude/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md similarity index 100% rename from .claude/skills/brainstorming/SKILL.md rename to skills/brainstorming/SKILL.md diff --git a/.claude/skills/brainstorming/references/question-patterns.md b/skills/brainstorming/references/question-patterns.md similarity index 100% rename from .claude/skills/brainstorming/references/question-patterns.md rename to skills/brainstorming/references/question-patterns.md diff --git a/.claude/skills/caching/SKILL.md b/skills/caching/SKILL.md similarity index 100% rename from .claude/skills/caching/SKILL.md rename to skills/caching/SKILL.md diff --git a/.claude/skills/caching/references/caching-decision-tree.md b/skills/caching/references/caching-decision-tree.md similarity index 100% rename from .claude/skills/caching/references/caching-decision-tree.md rename to skills/caching/references/caching-decision-tree.md diff --git a/.claude/skills/caching/references/patterns.md b/skills/caching/references/patterns.md similarity index 100% rename from .claude/skills/caching/references/patterns.md rename to skills/caching/references/patterns.md diff --git a/.claude/skills/condition-based-waiting/SKILL.md b/skills/condition-based-waiting/SKILL.md similarity index 100% rename from .claude/skills/condition-based-waiting/SKILL.md rename to skills/condition-based-waiting/SKILL.md diff --git a/.claude/skills/databases/SKILL.md b/skills/databases/SKILL.md similarity index 100% rename from .claude/skills/databases/SKILL.md rename to skills/databases/SKILL.md diff --git a/.claude/skills/databases/references/migrations.md b/skills/databases/references/migrations.md similarity index 100% rename from .claude/skills/databases/references/migrations.md rename to skills/databases/references/migrations.md diff --git a/.claude/skills/databases/references/mongodb.md b/skills/databases/references/mongodb.md similarity index 100% rename from .claude/skills/databases/references/mongodb.md rename to skills/databases/references/mongodb.md diff --git a/.claude/skills/databases/references/postgresql.md b/skills/databases/references/postgresql.md similarity index 100% rename from .claude/skills/databases/references/postgresql.md rename to skills/databases/references/postgresql.md diff --git a/.claude/skills/databases/references/redis.md b/skills/databases/references/redis.md similarity index 100% rename from .claude/skills/databases/references/redis.md rename to skills/databases/references/redis.md diff --git a/.claude/skills/defense-in-depth/SKILL.md b/skills/defense-in-depth/SKILL.md similarity index 100% rename from .claude/skills/defense-in-depth/SKILL.md rename to skills/defense-in-depth/SKILL.md diff --git a/.claude/skills/defense-in-depth/references/validation-layers.md b/skills/defense-in-depth/references/validation-layers.md similarity index 100% rename from .claude/skills/defense-in-depth/references/validation-layers.md rename to skills/defense-in-depth/references/validation-layers.md diff --git a/.claude/skills/devops/SKILL.md b/skills/devops/SKILL.md similarity index 100% rename from .claude/skills/devops/SKILL.md rename to skills/devops/SKILL.md diff --git a/.claude/skills/devops/references/cloudflare-workers.md b/skills/devops/references/cloudflare-workers.md similarity index 100% rename from .claude/skills/devops/references/cloudflare-workers.md rename to skills/devops/references/cloudflare-workers.md diff --git a/.claude/skills/devops/references/docker.md b/skills/devops/references/docker.md similarity index 100% rename from .claude/skills/devops/references/docker.md rename to skills/devops/references/docker.md diff --git a/.claude/skills/devops/references/github-actions.md b/skills/devops/references/github-actions.md similarity index 100% rename from .claude/skills/devops/references/github-actions.md rename to skills/devops/references/github-actions.md diff --git a/.claude/skills/dispatching-parallel-agents/SKILL.md b/skills/dispatching-parallel-agents/SKILL.md similarity index 100% rename from .claude/skills/dispatching-parallel-agents/SKILL.md rename to skills/dispatching-parallel-agents/SKILL.md diff --git a/.claude/skills/dispatching-parallel-agents/references/parallelization-patterns.md b/skills/dispatching-parallel-agents/references/parallelization-patterns.md similarity index 100% rename from .claude/skills/dispatching-parallel-agents/references/parallelization-patterns.md rename to skills/dispatching-parallel-agents/references/parallelization-patterns.md diff --git a/.claude/skills/documentation/SKILL.md b/skills/documentation/SKILL.md similarity index 100% rename from .claude/skills/documentation/SKILL.md rename to skills/documentation/SKILL.md diff --git a/.claude/skills/documentation/references/api-docs.md b/skills/documentation/references/api-docs.md similarity index 100% rename from .claude/skills/documentation/references/api-docs.md rename to skills/documentation/references/api-docs.md diff --git a/.claude/skills/documentation/references/code-docs.md b/skills/documentation/references/code-docs.md similarity index 100% rename from .claude/skills/documentation/references/code-docs.md rename to skills/documentation/references/code-docs.md diff --git a/.claude/skills/documentation/references/project-docs.md b/skills/documentation/references/project-docs.md similarity index 100% rename from .claude/skills/documentation/references/project-docs.md rename to skills/documentation/references/project-docs.md diff --git a/.claude/skills/error-handling/SKILL.md b/skills/error-handling/SKILL.md similarity index 100% rename from .claude/skills/error-handling/SKILL.md rename to skills/error-handling/SKILL.md diff --git a/.claude/skills/error-handling/references/error-taxonomy.md b/skills/error-handling/references/error-taxonomy.md similarity index 100% rename from .claude/skills/error-handling/references/error-taxonomy.md rename to skills/error-handling/references/error-taxonomy.md diff --git a/.claude/skills/error-handling/references/python-patterns.md b/skills/error-handling/references/python-patterns.md similarity index 100% rename from .claude/skills/error-handling/references/python-patterns.md rename to skills/error-handling/references/python-patterns.md diff --git a/.claude/skills/error-handling/references/typescript-patterns.md b/skills/error-handling/references/typescript-patterns.md similarity index 100% rename from .claude/skills/error-handling/references/typescript-patterns.md rename to skills/error-handling/references/typescript-patterns.md diff --git a/.claude/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md similarity index 100% rename from .claude/skills/executing-plans/SKILL.md rename to skills/executing-plans/SKILL.md diff --git a/.claude/skills/executing-plans/references/execution-checklist.md b/skills/executing-plans/references/execution-checklist.md similarity index 100% rename from .claude/skills/executing-plans/references/execution-checklist.md rename to skills/executing-plans/references/execution-checklist.md diff --git a/.claude/skills/feature-workflow/SKILL.md b/skills/feature-workflow/SKILL.md similarity index 100% rename from .claude/skills/feature-workflow/SKILL.md rename to skills/feature-workflow/SKILL.md diff --git a/.claude/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.md similarity index 100% rename from .claude/skills/finishing-a-development-branch/SKILL.md rename to skills/finishing-a-development-branch/SKILL.md diff --git a/.claude/skills/finishing-a-development-branch/references/branch-completion-checklist.md b/skills/finishing-a-development-branch/references/branch-completion-checklist.md similarity index 100% rename from .claude/skills/finishing-a-development-branch/references/branch-completion-checklist.md rename to skills/finishing-a-development-branch/references/branch-completion-checklist.md diff --git a/.claude/skills/frontend-styling/SKILL.md b/skills/frontend-styling/SKILL.md similarity index 100% rename from .claude/skills/frontend-styling/SKILL.md rename to skills/frontend-styling/SKILL.md diff --git a/.claude/skills/frontend-styling/references/accessibility.md b/skills/frontend-styling/references/accessibility.md similarity index 100% rename from .claude/skills/frontend-styling/references/accessibility.md rename to skills/frontend-styling/references/accessibility.md diff --git a/.claude/skills/frontend-styling/references/tailwind.md b/skills/frontend-styling/references/tailwind.md similarity index 100% rename from .claude/skills/frontend-styling/references/tailwind.md rename to skills/frontend-styling/references/tailwind.md diff --git a/.claude/skills/frontend/SKILL.md b/skills/frontend/SKILL.md similarity index 100% rename from .claude/skills/frontend/SKILL.md rename to skills/frontend/SKILL.md diff --git a/.claude/skills/frontend/references/nextjs.md b/skills/frontend/references/nextjs.md similarity index 100% rename from .claude/skills/frontend/references/nextjs.md rename to skills/frontend/references/nextjs.md diff --git a/.claude/skills/frontend/references/react.md b/skills/frontend/references/react.md similarity index 100% rename from .claude/skills/frontend/references/react.md rename to skills/frontend/references/react.md diff --git a/.claude/skills/frontend/references/shadcn-ui.md b/skills/frontend/references/shadcn-ui.md similarity index 100% rename from .claude/skills/frontend/references/shadcn-ui.md rename to skills/frontend/references/shadcn-ui.md diff --git a/.claude/skills/git-workflows/SKILL.md b/skills/git-workflows/SKILL.md similarity index 100% rename from .claude/skills/git-workflows/SKILL.md rename to skills/git-workflows/SKILL.md diff --git a/.claude/skills/git-workflows/references/changelogs.md b/skills/git-workflows/references/changelogs.md similarity index 100% rename from .claude/skills/git-workflows/references/changelogs.md rename to skills/git-workflows/references/changelogs.md diff --git a/.claude/skills/git-workflows/references/committing.md b/skills/git-workflows/references/committing.md similarity index 100% rename from .claude/skills/git-workflows/references/committing.md rename to skills/git-workflows/references/committing.md diff --git a/.claude/skills/git-workflows/references/pull-requests.md b/skills/git-workflows/references/pull-requests.md similarity index 100% rename from .claude/skills/git-workflows/references/pull-requests.md rename to skills/git-workflows/references/pull-requests.md diff --git a/.claude/skills/git-workflows/references/shipping.md b/skills/git-workflows/references/shipping.md similarity index 100% rename from .claude/skills/git-workflows/references/shipping.md rename to skills/git-workflows/references/shipping.md diff --git a/skills/init/SKILL.md b/skills/init/SKILL.md new file mode 100644 index 0000000..79877a0 --- /dev/null +++ b/skills/init/SKILL.md @@ -0,0 +1,161 @@ +--- +name: init +description: > + Interactive setup wizard for claudekit. Scaffolds rules, modes, hooks, and MCP + server configs into the user's project. Run /claudekit:init to configure. + Use when setting up a new project with claudekit or reconfiguring an existing one. +user-invocable: true +argument-hint: "[--all] to skip prompts and install everything" +--- + +# Claudekit Init + +Interactive setup wizard that scaffolds project-level configuration files into the user's `.claude/` directory. + +## What It Generates + +| Category | Files | Location | +|----------|-------|----------| +| Rules | api.md, frontend.md, migrations.md, security.md, testing.md | `.claude/rules/` | +| Modes | brainstorm.md, deep-research.md, default.md, implementation.md, orchestration.md, review.md, token-efficient.md | `.claude/modes/` | +| Hooks | auto-format, block-dangerous-commands, notify | `.claude/hooks/` + `settings.local.json` | +| MCP Servers | context7, sequential, playwright, memory, filesystem | `.mcp.json` | + +--- + +## Wizard Flow + +When invoked, ask the user **ONE question at a time**: + +### Step 1: Rules + +"Which rules do you want to install?" +- a) All rules (api, frontend, migrations, security, testing) +- b) Let me pick individually +- c) Skip rules + +If (b), list each rule with a one-line description and let user select: +- **api.md** — REST API design conventions (naming, versioning, error responses) +- **frontend.md** — React/Next.js component patterns and file organization +- **migrations.md** — Database migration safety rules (backward compatibility, rollback) +- **security.md** — OWASP-aligned security rules (no hardcoded secrets, parameterized queries) +- **testing.md** — Test naming, coverage thresholds, mocking conventions + +For each selected rule, read the template from `${CLAUDE_PLUGIN_ROOT}/skills/init/templates/rules/.md` and write it to `.claude/rules/.md`. + +### Step 2: Modes + +"Which behavioral modes do you want to install?" +- a) All modes (brainstorm, deep-research, default, implementation, orchestration, review, token-efficient) +- b) Let me pick individually +- c) Skip modes + +If (b), list each mode with a one-line description: +- **brainstorm.md** — Creative exploration, divergent thinking, pro/con comparisons +- **deep-research.md** — Thorough analysis with citations and evidence +- **default.md** — Balanced standard behavior +- **implementation.md** — Code-focused, minimal prose, maximum productivity +- **orchestration.md** — Multi-task coordination and parallel work +- **review.md** — Critical analysis, finding issues, security focus +- **token-efficient.md** — Compressed output for cost savings (30-70%) + +For each selected mode, read the template from `${CLAUDE_PLUGIN_ROOT}/skills/init/templates/modes/.md` and write it to `.claude/modes/.md`. + +### Step 3: Hooks + +"Which hooks do you want to install?" +- a) Auto-format (runs linter after Write/Edit) +- b) Block dangerous commands (prevents rm -rf /, force push main, etc.) +- c) Notifications (desktop notifications on completion) +- d) All of the above +- e) Skip hooks + +For each selected hook: + +1. Read the hook metadata from `${CLAUDE_PLUGIN_ROOT}/skills/init/templates/hooks.json` +2. Copy the hook script from `${CLAUDE_PLUGIN_ROOT}/scripts/