codingbuddy-rules 4.5.0 → 5.1.0

package/.ai-rules/skills/onboard/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: onboard
+description: "Guided onboarding for new projects - scans tech stack, generates codingbuddy.config.json, sets up adapters, and installs .ai-rules with interactive Q&A."
+---
+
+# Onboard: New Project Setup
+
+## Overview
+
+Guide users through setting up codingbuddy in a new project via interactive, step-by-step onboarding. Detect the tech stack automatically, generate configuration, and create adapter files for their AI tools.
+
+## Step 1: Project Scanning
+
+Scan the project root to detect:
+
+**Package managers & languages:**
+- `package.json` → Node.js/TypeScript (check for `typescript` dep)
+- `requirements.txt` / `pyproject.toml` / `setup.py` → Python
+- `go.mod` → Go
+- `Cargo.toml` → Rust
+- `pom.xml` / `build.gradle` → Java/Kotlin
+- `Gemfile` → Ruby
+- `composer.json` → PHP
+
+**Frameworks** (from dependency files):
+- React, Next.js, Vue, Angular, Svelte, Express, NestJS, Django, Flask, FastAPI, Spring Boot, Rails, Laravel, Gin, Echo, etc.
+
+**Test setup:**
+- Jest, Vitest, Mocha, Pytest, Go test, JUnit, RSpec, PHPUnit, etc.
+
+**Monorepo indicators:**
+- `workspaces` in package.json, `lerna.json`, `pnpm-workspace.yaml`, `nx.json`, `turbo.json`
+
+**AI tools already present:**
+- `.cursor/` → Cursor
+- `.claude/` → Claude Code
+- `.antigravity/` → Antigravity (Gemini)
+- `.codex/` → Codex
+- `.q/` → Amazon Q
+- `.kiro/` → Kiro
+- `.github/copilot/` → GitHub Copilot
+
+After scanning, present findings to the user:
+
+```
+Detected:
+- Language: TypeScript
+- Framework: Next.js 14, React 18
+- Test: Vitest
+- Monorepo: Yarn workspaces
+- AI tools: .claude/ (existing)
+```
+
+Ask: "Does this look correct? Anything to add or change?" (use AskUserQuestion)
+
+## Step 2: Generate codingbuddy.config.json
+
+Based on detected info, generate a draft config:
+
+```json
+{
+  "language": "en",
+  "techStack": {
+    "languages": ["typescript"],
+    "frameworks": ["nextjs", "react"],
+    "testing": ["vitest"],
+    "packageManager": "yarn"
+  },
+  "architecture": {
+    "pattern": "layered",
+    "monorepo": true
+  },
+  "agents": {
+    "primary": "software-engineer",
+    "specialists": ["frontend-developer", "test-engineer"]
+  }
+}
+```
+
+Ask the user to confirm or adjust:
+- Communication language (en, ko, ja, zh, es, etc.)
+- Primary agent selection (show top 3 recommendations based on tech stack)
+- Architecture pattern (layered, clean, hexagonal, or custom)
+
+Write `codingbuddy.config.json` to project root after confirmation.
+
+## Step 3: Adapter Setup
+
+Based on detected AI tools (or ask which tools the user wants to set up):
+
+| Tool | Config Path | What to Create |
+|------|------------|----------------|
+| Cursor | `.cursor/rules/codingbuddy.mdc` | Rules include pointing to .ai-rules |
+| Claude Code | `.claude/settings.json` + `CLAUDE.md` | MCP server config + instructions |
+| Antigravity | `.antigravity/rules/codingbuddy.md` | Gemini rules file |
+| Codex | `.codex/AGENTS.md` | Codex agent instructions |
+| Amazon Q | `.q/rules/codingbuddy.md` | Q rules file |
+| Kiro | `.kiro/rules/codingbuddy.md` | Kiro rules file |
+
+For each selected tool:
+1. Create the config directory if it does not exist
+2. Generate a starter config file referencing the shared `.ai-rules/` rules
+3. Show the user what was created
+
+Ask: "Which AI tools do you want to configure?" (use AskUserQuestion with multiSelect)
+
+## Step 4: Optional .ai-rules Setup
+
+Present two options:
+
+**Option A: Copy rules locally** (recommended for customization)
+- Copy `packages/rules/.ai-rules/` into the project as `.ai-rules/`
+- User can customize rules for their project
+
+**Option B: Install via npm package**
+- `npm install codingbuddy-rules` / `yarn add codingbuddy-rules`
+- Reference rules from `node_modules/codingbuddy-rules/.ai-rules/`
+- Stays in sync with upstream updates
+
+Ask: "How would you like to set up the AI rules?" (use AskUserQuestion)
+
+If Option A: copy the rules directory and confirm.
+If Option B: run the install command and update adapter configs to point to node_modules path.
+
+## Step 5: Summary
+
+Present a summary of everything that was created:
+
+```
+Onboarding complete!
+
+Created files:
+  - codingbuddy.config.json (project configuration)
+  - .claude/settings.json (Claude Code MCP config)
+  - .ai-rules/ (shared AI coding rules)
+
+Next steps:
+  1. Review codingbuddy.config.json and adjust settings
+  2. Start with: PLAN <your first task>
+  3. Use AUTO mode for autonomous development cycles
+  4. Run /help to see available commands
+```
+
+## Key Principles
+
+- **Interactive** — Ask one question at a time using AskUserQuestion, never assume
+- **Non-destructive** — Never overwrite existing config files; ask before modifying
+- **Detect first** — Auto-detect as much as possible, then confirm with user
+- **Minimal setup** — Only create what the user needs; skip unnecessary adapters
+- **Clear output** — Show exactly what files were created and what to do next

package/.ai-rules/skills/performance-optimization/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: performance-optimization
 description: Use when optimizing code performance, addressing slowness complaints, or measuring application speed improvements
+context: fork
+agent: general-purpose
+allowed-tools: Read, Grep, Glob, Bash
 ---
 
 # Performance Optimization

package/.ai-rules/skills/plan-and-review/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: plan-and-review
+description: Use when creating implementation plans that need quality review before execution — 4-phase workflow combining plan creation with automated plan-reviewer validation
+---
+
+# Plan and Review
+
+## Overview
+
+Create implementation plans and validate them through automated review before execution. This skill combines the writing-plans methodology with plan-reviewer agent dispatch to catch quality issues (missing file paths, vague acceptance criteria, scope gaps, TDD omissions) before any code is written.
+
+**Announce at start:** "I'm using the plan-and-review skill to create and validate the implementation plan."
+
+**Core principle:** No plan reaches execution without passing review. Critical/High findings must be resolved first.
+
+## The 4 Phases
+
+```
+Phase 1: Create Plan → Phase 2: Review → Phase 3: Revise (if needed) → Phase 4: Approved
+```
+
+### Phase 1: Create Plan
+
+Use the writing-plans methodology to create the implementation plan.
+
+1. **Invoke the writing-plans skill** (superpowers:writing-plans or equivalent)
+2. Follow all writing-plans requirements:
+   - Bite-sized tasks (2-5 minutes each)
+   - Exact file paths for all changes
+   - TDD structure (Red-Green-Refactor) for core logic
+   - Complete code in plan (no placeholders)
+   - Alternatives exploration for non-trivial decisions
+3. Save plan to `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+### Phase 2: Dispatch Plan Reviewer
+
+Dispatch the plan-reviewer agent as a subAgent to review the plan.
+
+1. **Dispatch plan-reviewer** using the Agent tool:
+   ```
+   subagent_type: "general-purpose"
+   prompt: |
+     You are the Plan Reviewer agent. Review the implementation plan at
+     docs/plans/<plan-file>.md against the original spec/issue.
+
+     Review checklist:
+     - File paths: All paths valid (Modify files exist, Create paths have valid parents)
+     - Acceptance criteria: Specific, measurable, verifiable (no vague terms)
+     - Scope alignment: Plan matches spec — no scope creep, no missing items
+     - TDD compliance: Red-Green-Refactor for core logic tasks
+     - Backward compatibility: Breaking changes documented with migration steps
+
+     Output a severity-rated findings table:
+     | Finding | Location | Severity | Recommendation |
+
+     End with Review Summary showing counts per severity and verdict:
+     APPROVED (Critical=0 AND High=0) or REVISE REQUIRED.
+   ```
+2. Collect the review results
+
+### Phase 3: Revise Plan (if Critical/High findings)
+
+If the review verdict is **REVISE REQUIRED**:
+
+1. Read each Critical and High finding
+2. Revise the plan to address each finding:
+   - Fix invalid file paths
+   - Make acceptance criteria specific and testable
+   - Add missing spec requirements as tasks
+   - Add TDD structure where missing
+   - Document breaking changes with migration steps
+3. Save the revised plan (overwrite the same file)
+4. **Re-dispatch plan-reviewer** (return to Phase 2)
+5. Repeat until verdict is **APPROVED**
+
+**Maximum iterations:** 3 revision cycles. If still not approved after 3 cycles, present remaining findings to user for manual resolution.
+
+### Phase 4: Plan Approved
+
+When the review verdict is **APPROVED**:
+
+1. Announce: "Plan approved by plan-reviewer — ready for execution."
+2. Present remaining Medium/Low findings as optional improvements
+3. Offer execution choice:
+   - **Subagent-Driven (this session):** Use superpowers:subagent-driven-development
+   - **Parallel Session (separate):** Use superpowers:executing-plans
+
+## When to Use This Skill
+
+- Creating implementation plans for non-trivial features
+- Plans that will be executed by other agents or in separate sessions
+- When plan quality is critical (e.g., parallel execution with multiple workers)
+- When the spec is complex and scope alignment matters
+
+## When NOT to Use This Skill
+
+- Single-file changes or trivial fixes
+- Plans you will execute yourself immediately in the same session
+- Exploratory prototyping where the plan will evolve rapidly
+
+## Integration with Parallel Orchestrator
+
+When used within parallel execution workflows:
+
+- The conductor generates worker directives that include plan creation
+- Each worker can use this skill to self-validate their plan before ACT mode
+- The plan-reviewer findings feed into the conductor's quality gates
+
+## Key Principles
+
+- **No plan without review** — every plan gets at least one review pass
+- **Severity drives action** — Critical/High must be fixed, Medium/Low are optional
+- **Evidence-based findings** — every finding references a specific plan section
+- **Bounded iteration** — maximum 3 revision cycles to prevent infinite loops
+- **Clear verdict** — APPROVED or REVISE REQUIRED, no ambiguity

package/.ai-rules/skills/plan-to-issues/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: plan-to-issues
+description: Decompose specs or implementation plans into independent GitHub issues with dependency graphs, wave grouping, and file overlap analysis for safe parallel execution.
+---
+
+# Plan to Issues
+
+## Overview
+
+Turn specs and implementation plans into a set of independent, well-structured GitHub issues ready for parallel execution. Each issue gets acceptance criteria, file dependency mapping, wave assignment, and priority labels.
+
+**Core principle:** Issues that touch the same files MUST NOT be in the same wave. File overlap = sequential execution.
+
+**Announce at start:** "I'm using the plan-to-issues skill to decompose this plan into GitHub issues."
+
+**Iron Law:**
+
+```
+ISSUES MODIFYING THE SAME FILE MUST NEVER RUN IN THE SAME WAVE
+```
+
+## When to Use
+
+- Implementation plan is ready and needs to be broken into trackable units of work
+- Spec document needs decomposition into parallel-safe issues
+- Planning a multi-issue feature that will use `/taskmaestro` for parallel execution
+- Roadmap or design doc needs to become actionable GitHub issues
+
+**Use this ESPECIALLY when:**
+- The plan has 3+ independent deliverables
+- Multiple developers or agents will work in parallel
+- You need wave grouping for `/taskmaestro` execution
+
+**Don't use when:**
+- Single-file change or trivial fix (just create the issue directly)
+- Requirements are still unclear (use brainstorming skill first)
+- Plan hasn't been written yet (use writing-plans skill first)
+
+## Input
+
+The skill accepts one of:
+- **Spec document path**: `docs/plans/YYYY-MM-DD-<feature>.md`
+- **Plan document path**: Any markdown file with implementation steps
+- **Inline description**: Direct feature description in the prompt
+
+## The Five Phases
+
+### Phase 1: Analyze — Identify Independent Deliverables
+
+**Read the plan and extract discrete units of work:**
+
+1. **Parse the plan document**
+   - Read the spec/plan file
+   - Identify each distinct feature, component, or change
+   - Note dependencies between items
+
+2. **Define each deliverable**
+   - Summary: What does this issue deliver?
+   - Scope: Which files will be created or modified?
+   - Dependencies: What must be done before this?
+   - Acceptance criteria: How do we know it's done?
+
+3. **Estimate file touchpoints**
+   - List every file each deliverable will create or modify
+   - Be specific — `src/utils/parse.ts` not `src/utils/`
+   - Include test files: `src/utils/parse.test.ts`
+
+**Completion criteria:**
+- [ ] All deliverables identified with clear scope
+- [ ] File touchpoints listed for each deliverable
+- [ ] Dependencies between deliverables noted
+
+### Phase 2: Overlap Detection — Map File Conflicts
+
+**Use `validate_parallel_issues` to verify safety:**
+
+1. **Build the file overlap matrix**
+   - Compare file lists between all deliverables
+   - Identify any shared files
+
+2. **Validate with MCP tool**
+
+   ```
+   Call: codingbuddy validate_parallel_issues
+     issues: [issue_numbers]
+     issueContents: { "1": "body1", "2": "body2", ... }
+   ```
+
+3. **Apply the Iron Rule**
+   - Same file in two deliverables = different waves
+   - No exceptions — even "small" changes to shared files cause merge conflicts
+
+**Decision matrix:**
+
+| Overlap | Action |
+|---------|--------|
+| No shared files | Same wave OK |
+| Shared test helpers only | Same wave OK (read-only imports) |
+| Shared source files | Different waves MANDATORY |
+| Shared config files | Different waves MANDATORY |
+
+**Completion criteria:**
+- [ ] File overlap matrix built
+- [ ] `validate_parallel_issues` called (if issues already exist)
+- [ ] Conflicts resolved via wave separation
+
+### Phase 3: Prioritize — Assign Priority and Wave Groups
+
+**Priority levels:**
+
+| Priority | Meaning | Criteria |
+|----------|---------|----------|
+| `P0` | Critical | Blocks other issues; foundational setup |
+| `P1` | High | Core feature; needed for MVP |
+| `P2` | Medium | Enhancement; improves quality |
+| `P3` | Low | Nice-to-have; polish |
+
+**Wave assignment rules:**
+
+1. **Wave 1**: All P0 issues + any P1 issues with zero file overlaps with P0
+2. **Wave 2**: Issues that depend on Wave 1 completion + P1/P2 with no overlap with each other
+3. **Wave N**: Remaining issues grouped by zero-overlap constraint
+
+```
+Wave 1: [#1, #2, #3]  ← No file overlaps between these
+Wave 2: [#4, #5]       ← Depend on Wave 1; no overlaps between these
+Wave 3: [#6]           ← Depends on Wave 2
+```
+
+**Completion criteria:**
+- [ ] All deliverables have priority labels
+- [ ] Wave groups assigned with zero intra-wave file overlap
+- [ ] Dependency chain is clear
+
+### Phase 4: Create — Generate GitHub Issues
+
+**Create each issue with structured body:**
+
+```bash
+gh issue create \
+  --title "<type>(<scope>): <description>" \
+  --label "<priority>,<wave>,<feature-area>" \
+  --body "$(cat <<'EOF'
+## Summary
+
+<1-2 sentence description of what this issue delivers>
+
+## Details
+
+<Implementation details, approach, key decisions>
+
+## Files to Create/Modify
+
+- [ ] `path/to/file.ts` — <what changes>
+- [ ] `path/to/file.test.ts` — <what tests>
+
+## Acceptance Criteria
+
+- [ ] <Criterion 1>
+- [ ] <Criterion 2>
+- [ ] <Criterion 3>
+
+## Dependencies
+
+- Depends on: #<number> (if any)
+- Blocks: #<number> (if any)
+
+## Wave Assignment
+
+**Wave <N>** — <reason for this wave>
+Can run in parallel with: #<numbers>
+Must wait for: #<numbers> (if any)
+EOF
+)"
+```
+
+**Label conventions:**
+
+| Label | Format | Example |
+|-------|--------|---------|
+| Priority | `P0` through `P3` | `P1` |
+| Wave | `wave-<N>` | `wave-1` |
+| Feature area | Project-specific | `auth`, `api`, `ui` |
+| Type | Conventional commits | `feat`, `fix`, `refactor` |
+
+**Auto-create missing labels:**
+
+```bash
+gh label create "wave-1" --color "4ECDC4" --description "Wave 1: parallel group" 2>/dev/null || true
+gh label create "wave-2" --color "45B7D1" --description "Wave 2: parallel group" 2>/dev/null || true
+gh label create "P0" --color "FF0000" --description "Critical priority" 2>/dev/null || true
+gh label create "P1" --color "FF6B6B" --description "High priority" 2>/dev/null || true
+gh label create "P2" --color "FFD93D" --description "Medium priority" 2>/dev/null || true
+gh label create "P3" --color "95E1D3" --description "Low priority" 2>/dev/null || true
+```
+
+**Completion criteria:**
+- [ ] All issues created with structured body
+- [ ] Labels applied (created if missing)
+- [ ] Dependencies linked between issues
+
+### Phase 5: Summarize — Output Dependency Graph and Execution Plan
+
+**Present the final decomposition:**
+
+```markdown
+## Decomposition Summary
+
+### Dependency Graph
+
+#1 ─┬─► #3
+    └─► #4 ──► #6
+#2 ────► #5
+
+### Wave Execution Plan
+
+| Wave | Issues | Parallel Safe | Depends On |
+|------|--------|---------------|------------|
+| 1 | #1, #2 | Yes (0 file overlaps) | — |
+| 2 | #3, #4, #5 | Yes (0 file overlaps) | Wave 1 |
+| 3 | #6 | N/A (single) | Wave 2 |
+
+### File Overlap Matrix
+
+| | #1 | #2 | #3 | #4 | #5 | #6 |
+|---|---|---|---|---|---|---|
+| #1 | — | 0 | 1 | 0 | 0 | 0 |
+| #2 | 0 | — | 0 | 0 | 1 | 0 |
+...
+
+Total issues: 6
+Waves: 3
+Estimated parallel speedup: ~3x
+```
+
+**Completion criteria:**
+- [ ] Dependency graph visualized
+- [ ] Wave execution plan table complete
+- [ ] File overlap matrix shown
+- [ ] Summary shared with user
+
+## Integration with taskmaestro
+
+The wave grouping output is designed for direct use with `/taskmaestro`:
+
+```
+/taskmaestro --issues "#1,#2,#3" --wave 1
+/taskmaestro --issues "#4,#5" --wave 2
+```
+
+Each wave runs in parallel tmux panes with git worktree isolation.
+
+## Quick Reference
+
+| Phase | Action | Tool |
+|-------|--------|------|
+| **1. Analyze** | Extract deliverables from plan | Read tool |
+| **2. Overlap** | Detect file conflicts | `validate_parallel_issues` |
+| **3. Prioritize** | Assign P0-P3 and waves | Manual analysis |
+| **4. Create** | Generate GitHub issues | `gh issue create` |
+| **5. Summarize** | Dependency graph + execution plan | Output |
+
+## Safety Checklist
+
+Before creating issues:
+
+- [ ] Plan document read completely
+- [ ] Every deliverable has specific file touchpoints (not directories)
+- [ ] File overlap matrix checked — no intra-wave conflicts
+- [ ] Priority levels assigned based on dependency chain
+- [ ] Issue bodies include acceptance criteria
+- [ ] Wave assignments respect the Iron Rule
+- [ ] Labels exist or will be auto-created
+- [ ] `validate_parallel_issues` called for final verification
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "These issues probably don't overlap" | CHECK. Run overlap detection. Assumptions cause merge conflicts. |
+| "I'll put them all in Wave 1 for speed" | STOP. Overlapping files in one wave = guaranteed conflicts. |
+| "File overlap is minor, just a config file" | STOP. Config conflicts are the hardest to resolve. Different waves. |
+| "I don't need acceptance criteria" | You do. Issues without AC get implemented wrong. |
+| "I'll figure out waves later" | Waves are determined by file overlap. Do it now. |
+| "This deliverable is too small for its own issue" | Small, focused issues are easier to parallelize and review. |
+| "I'll skip validate_parallel_issues" | The MCP tool catches overlaps you missed. Always validate. |
+
+## Examples
+
+### Spec to Issues
+
+```
+Input:  docs/plans/2025-03-15-auth-redesign.md
+Output: 5 GitHub issues across 2 waves
+
+Wave 1 (parallel):
+  #101 feat(auth): add JWT token service        [P0, wave-1]
+  #102 feat(auth): add password hashing utils    [P0, wave-1]
+  #103 feat(db): add users migration             [P0, wave-1]
+
+Wave 2 (parallel, after Wave 1):
+  #104 feat(auth): add login/register endpoints  [P1, wave-2]
+  #105 feat(auth): add auth middleware            [P1, wave-2]
+```
+
+### Plan with Overlaps
+
+```
+Input:  docs/plans/2025-04-01-api-v2.md
+
+Overlap detected:
+  Issue A: modifies src/routes/index.ts
+  Issue B: modifies src/routes/index.ts
+  → A and B MUST be in different waves
+
+Wave 1: [A, C, D]  ← A here
+Wave 2: [B, E]     ← B here (after A merges)
+```

package/.ai-rules/skills/pr-all-in-one/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: pr-all-in-one
 description: Unified commit and PR workflow. Auto-commits changes, creates/updates PRs with smart issue linking and multi-language support.
+disable-model-invocation: true
+argument-hint: [target-branch] [issue-id]
 ---
 
 # PR All-in-One
@@ -92,7 +94,7 @@ Step 7: Update existing PR (if exists)
 │   └── "bilingual" → Bilingual Template
 ├── Generate title:
 │   ├── "en"/"bilingual" → English title
-│   └── "ko" → 한국어 title
+│   └── "ko" → Korean title
 ├── Generate body with selected template
 ├── Merge with .github/pull_request_template.md (if exists)
 ├── NO AI signature
@@ -107,7 +109,7 @@ Step 8: Create new PR (if not exists)
 │   └── "bilingual" → Bilingual Template
 ├── Generate title:
 │   ├── "en"/"bilingual" → English (e.g., "feat: add auth")
-│   └── "ko" → 한국어 (e.g., "feat: 인증 추가")
+│   └── "ko" → Korean (e.g., "feat: add authentication")
 ├── Generate body with selected template + commit analysis
 ├── Merge with project template if exists
 ├── NO AI signature
@@ -246,22 +248,22 @@ N/A (no UI changes)
 
 #### When `prLanguage: "ko"`
 
-**Title**: `feat: 사용자 인증 추가`
+**Title**: `feat: add user authentication`
 
 **Body**:
 ```markdown
-## 컨텍스트
+## Context
 
-**관련 링크:**
-- 이슈: [AUTH-123](https://jira.example.com/browse/AUTH-123)
+**Related Links:**
+- Issue: [AUTH-123](https://jira.example.com/browse/AUTH-123)
 
-**상세 설명:**
+**Description Details:**
 
-JWT 기반 인증과 리프레시 토큰 지원을 추가했습니다.
+Added JWT-based authentication with refresh token support.
 
-## 스크린샷 또는 비디오
+## Screenshots or Videos
 
-N/A (UI 변경 없음)
+N/A (no UI changes)
 ```
 
 #### When `prLanguage: "bilingual"`
@@ -281,13 +283,13 @@ Added JWT-based authentication with refresh token support.
 
 ---
 
-**상세 설명:**
+**Description Details (Korean):**
 
-JWT 기반 인증과 리프레시 토큰 지원을 추가했습니다.
+Added JWT-based authentication with refresh token support. (Korean translation here)
 
 ## Screenshots or Videos
 
-N/A (no UI changes / UI 변경 없음)
+N/A (no UI changes)
 ```
 
 ### Template Definitions