nitm-ai-dev-toolkit 3.0.15

package/src/repo/.agents/skills/bkt-cli/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: bkt-cli
+description: Manage Bitbucket pull requests, issues, and repositories from the command line using the bkt CLI. Use when the user asks about Bitbucket PRs, issues, repos, pipelines, or needs to manage project work items via the command line.
+---
+
+# Bitbucket CLI (bkt)
+
+Interact with Bitbucket Cloud & Data Center from the command line using [bkt](https://github.com/avivsinai/bitbucket-cli).
+
+## When to Use
+
+- User asks to create, view, edit, or search Bitbucket pull requests
+- User needs to manage Bitbucket issues (Cloud only)
+- User wants to manage repositories, branches, or permissions
+- User needs to trigger or view pipelines
+- User needs to manage webhooks or extensions
+- MCP tools (`mcp_bitbucket_*`) are unavailable or failing
+- User needs scripted/batch PR or issue operations
+
+## Prerequisites
+
+1. Install bkt: `brew install avivsinai/tap/bitbucket-cli` (macOS) or see [install instructions](https://github.com/avivsinai/bitbucket-cli#installation)
+2. Authenticate: `bkt auth login`
+3. Create and activate a context: `bkt context create`
+
+## Authentication
+
+### Bitbucket Data Center
+
+```bash
+# Interactive flow: opens browser to create a Personal Access Token
+bkt auth login https://bitbucket.mycorp.example --web-token
+
+# Or provide credentials directly
+bkt auth login https://bitbucket.mycorp.example --username alice --token <PAT>
+```
+
+### Bitbucket Cloud
+
+```bash
+# Browser OAuth flow
+bkt auth login https://bitbucket.org --kind cloud --web
+
+# Or provide credentials directly
+bkt auth login https://bitbucket.org --kind cloud --username <email> --token <api-token>
+```
+
+### Context Management
+
+```bash
+# Create context for Data Center
+bkt context create dc-prod --host bitbucket.mycorp.example --project ABC --set-active
+
+# Create context for Cloud
+bkt context create cloud-prod --host api.bitbucket.org --workspace myteam --set-active
+
+# List contexts
+bkt context list
+
+# Check auth status
+bkt auth status
+```
+
+## Pull Request Commands
+
+### List PRs
+
+```bash
+# List open PRs
+bkt pr list --state OPEN
+
+# List PRs with limit
+bkt pr list --state OPEN --limit 10
+
+# List merged PRs
+bkt pr list --state MERGED
+
+# List declined PRs
+bkt pr list --state DECLINED
+
+# JSON output for scripting
+bkt pr list --json id,title,state --limit 20
+```
+
+### Create PRs
+
+```bash
+# Create PR
+bkt pr create --title "feat: cache" --source feature/cache --target main
+
+# Create with reviewer
+bkt pr create --title "Fix auth" --source fix/auth --target main --reviewer alice
+
+# Create with description
+bkt pr create \
+  --title "feat: add caching" \
+  --source feature/cache \
+  --target main \
+  --description "Implements Redis caching for API responses"
+
+# Create for specific project/repo
+bkt pr create --project DATA --repo platform-api \
+  --title "Fix bug" --source fix/bug --target main
+```
+
+### View PRs
+
+```bash
+# View PR details
+bkt pr view 42
+
+# View with comments
+bkt pr comments 42 --details
+
+# JSON output
+bkt pr view 42 --json id,title,state,author
+```
+
+### Merge & Decline PRs
+
+```bash
+# Merge PR
+bkt pr merge 42 --message "merge: feature/cache"
+
+# Decline PR
+bkt pr decline 42 --reason "Superseded by PR 99"
+```
+
+### PR Checks & CI Status
+
+```bash
+# Show build/CI status
+bkt pr checks 42
+
+# Wait for builds to complete
+bkt pr checks 42 --wait
+
+# Wait with timeout
+bkt pr checks 42 --wait --timeout 5m
+```
+
+### PR Comments & Review Threads
+
+```bash
+# List PR comments
+bkt pr comments 42 --details
+
+# Resolve a comment thread
+bkt pr comments resolve 42 <thread-id>
+
+# Reopen a resolved thread
+bkt pr comments reopen 42 <thread-id>
+
+# Delete a comment
+bkt pr comments delete 42 <thread-id>
+```
+
+## Issue Commands (Bitbucket Cloud Only)
+
+### List Issues
+
+```bash
+# List open issues
+bkt issue list --state open
+
+# List by kind
+bkt issue list --state open --kind bug
+
+# List by priority
+bkt issue list --state open --priority major
+```
+
+### Create Issues
+
+```bash
+# Create issue
+bkt issue create -t "Login broken" -k bug -p major
+
+# Create with description
+bkt issue create \
+  --title "API timeout" \
+  --kind bug \
+  --priority critical \
+  --description "Endpoints timeout after 30s"
+```
+
+### View Issues
+
+```bash
+# View issue
+bkt issue view 42
+
+# View with comments
+bkt issue view 42 --comments
+```
+
+### Edit Issues
+
+```bash
+# Edit assignee and priority
+bkt issue edit 42 --assignee "{abc-123}" --priority critical
+
+# Change kind
+bkt issue edit 42 --kind improvement
+```
+
+### Close & Reopen Issues
+
+```bash
+# Close issue
+bkt issue close 42
+
+# Reopen issue
+bkt issue reopen 42
+```
+
+### Issue Comments
+
+```bash
+# Add comment
+bkt issue comment 42 -b "Fixed in v1.2.0"
+```
+
+### Issue Status
+
+```bash
+# Show your assigned/created issues
+bkt issue status
+```
+
+### Attachments
+
+```bash
+# List attachments
+bkt issue attachment list 42
+
+# Upload file
+bkt issue attachment upload 42 screenshot.png
+
+# Download all attachments
+bkt issue attachment download 42 --all
+
+# Delete attachment
+bkt issue attachment delete 42 old-file.txt
+```
+
+## Repository Commands
+
+```bash
+# List repos
+bkt repo list --limit 20
+
+# List repos in a workspace (Cloud)
+bkt repo list --workspace myteam --limit 10
+
+# View repo details
+bkt repo view platform-api
+
+# Create repo (Data Center)
+bkt repo create data-pipeline --description "Data ingestion" --project DATA
+
+# Create repo (Cloud)
+bkt repo create frontend-app --workspace myteam --cloud-project WEB
+
+# Clone repo
+bkt repo clone platform-api --project DATA --ssh
+
+# Browse repo in browser
+bkt repo browse --project DATA --repo platform-api
+```
+
+## Branch Commands
+
+```bash
+# List branches (Cloud)
+bkt branch list --workspace myteam
+
+# Create branch
+bkt branch create release/1.9 --from main
+```
+
+## Permission Commands
+
+```bash
+# List permissions
+bkt perms repo list --project DATA --repo platform-api
+```
+
+## Webhook Commands
+
+```bash
+# Create webhook
+bkt webhook create \
+  --name "CI" \
+  --url https://ci.example.com/hook \
+  --event repo:refs_changed
+```
+
+## Pipeline Commands
+
+```bash
+# Trigger pipeline
+bkt pipeline run --workspace myteam --repo api --ref main --var ENV=staging
+
+# View pipeline status
+bkt status pipeline {pipeline-uuid}
+
+# Check rate limit
+bkt status rate-limit
+```
+
+## Extension Commands
+
+```bash
+# Install extension
+bkt extension install https://github.com/example/bkt-hello.git
+
+# Run extension
+bkt extension exec hello -- --flag=1
+```
+
+## Raw API Access
+
+```bash
+# Access any API endpoint directly
+bkt api /rest/api/1.0/projects --param limit=100 --json
+bkt api /repositories --param workspace=myteam --field pagelen=50
+```
+
+## Environment Variables
+
+| Variable              | Description                                      |
+| --------------------- | ------------------------------------------------ |
+| `BKT_TOKEN`           | Authentication token (bypasses keyring)          |
+| `BKT_HOST`            | Bitbucket server base URL                        |
+| `BKT_USERNAME`        | Username for basic auth in headless mode         |
+| `BKT_PROJECT`         | Default Data Center project key                  |
+| `BKT_WORKSPACE`       | Default Bitbucket Cloud workspace                |
+| `BKT_REPO`            | Default repository slug                          |
+| `BKT_CONFIG_DIR`      | Override config file directory                   |
+| `BKT_HTTP_DEBUG`      | Set to `1` to log HTTP request URLs and status   |
+
+## Common Workflows
+
+### PR Review Workflow
+
+```bash
+# List open PRs
+bkt pr list --state OPEN --limit 10
+
+# Check CI status
+bkt pr checks 42
+
+# View PR comments
+bkt pr comments 42 --details
+```
+
+### Batch Operations
+
+```bash
+# Close multiple issues
+for id in 10 11 12; do bkt issue close "$id"; done
+
+# Check status of multiple PRs
+for pr in 40 41 42; do bkt pr checks "$pr"; done
+```
+
+## Limitations
+
+- Issue tracking is only available for Bitbucket Cloud (Data Center uses Jira)
+- Requires `bkt auth login` and context creation before first use
+- Rate limits apply based on Bitbucket instance configuration
+- Some commands may differ between Cloud and Data Center
+- PR comment thread operations use top-level comment IDs

package/src/repo/.agents/skills/brainstorming/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: brainstorming
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+
+## The Process
+
+**Understanding the idea:**
+- Check out the current project state first (files, docs, recent commits)
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+- Once you believe you understand what you're building, present the design
+- Break it into sections of 200-300 words
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+## After the Design
+
+**Documentation:**
+- Write the validated design to `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/design.md`
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Implementation (if continuing):**
+- Ask: "Ready to set up for implementation?"
+- Use superpowers:using-git-worktrees to create isolated workspace
+- Use superpowers:writing-plans to create detailed implementation plan
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design in sections, validate each
+- **Be flexible** - Go back and clarify when something doesn't make sense

package/src/repo/.agents/skills/code-simplifier/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: code-simplifier
+description: Use after coding sessions or before commits to analyze recently modified code for simplification opportunities. Two-phase process: generate suggestions, then spawn a Staff Engineer reviewer to validate before presenting recommendations. Do not make code changes — analyze and report only.
+---
+
+# Code Simplifier
+
+Analyzes recently modified code for simplification opportunities with mandatory peer review of suggestions.
+
+**Purpose:** Reduce unnecessary complexity without changing behavior.
+
+**When to use:**
+- At the end of coding sessions
+- Before creating commits
+- Before code review
+- When code has become overly complex
+
+**DO NOT make any code changes.** Only analyze and report.
+
+## Process
+
+### Phase 1: Generate Suggestions
+
+1. **Identify recently modified files:**
+   ```bash
+   git status --short
+   git diff --name-only HEAD~3
+   ```
+
+2. **Analyze each file** for:
+   - Unnecessary complexity and nesting
+   - Redundant code
+   - Poor variable/function names
+   - Dead code
+   - Language-specific anti-patterns
+
+3. **Document suggestions:**
+   ```markdown
+   ### [filename]
+
+   **Issues found:** [count]
+
+   1. [Line X]: [Description of issue]
+      - Current: `[code snippet]`
+      - Suggested: `[improved code]`
+   ```
+
+### Phase 2: Peer Review (MANDATORY)
+
+After generating suggestions, spawn a reviewer subagent to validate each one. Not all "simplifications" are improvements.
+
+**Reviewer instructions:**
+
+For EACH suggestion:
+1. **Verify the claim** — Read the actual code. Is the issue real?
+2. **Evaluate the fix** — Does it introduce new problems?
+3. **Assign a verdict** — APPROVE, REJECT, or MODIFY
+
+**Rejection heuristics:**
+
+REJECT if:
+- Only 2 occurrences of "duplication" (rule of three — wait for 3+)
+- Abstraction would require complex parameters
+- Context is intentionally different across "duplicates"
+- The "fix" trades one complexity for another
+- Current code is idiomatic for the framework
+- Nested ternary is actually readable in context
+
+APPROVE if:
+- Confirmed dead code (unreachable branches)
+- Genuine unused functions/variables
+- 3+ identical patterns that could share a helper
+- Clear bug or logic error
+
+MODIFY if:
+- Valid issue but wrong solution proposed
+
+### Phase 3: Present Final Report
+
+```markdown
+## Code Simplification Report
+
+### Suggestions
+
+[Phase 1 analysis]
+
+### Review Verdicts
+
+| # | Suggestion | Verdict | Action |
+|---|------------|---------|--------|
+| 1 | ... | APPROVE | ... |
+| 2 | ... | REJECT | Keep as-is |
+
+### Final Recommendations
+
+Only APPROVED and MODIFIED items are actionable.
+```
+
+## Integration with Pre-Commit Workflow
+
+```
+1. RUN TESTS
+2. RUN TYPECHECK
+3. CODE SIMPLIFIER     ← This skill (analyze + review)
+4. IMPLEMENT approved changes only
+5. CODE REVIEW
+6. RE-RUN TESTS
+7. COMMIT
+```

package/src/repo/.agents/skills/debugger/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: debugger
+description: Use when dispatched to debug an issue — enforces systematic root cause investigation before any fix attempts. Complements the systematic-debugging skill with a structured dispatch template and reporting format.
+---
+
+# Debugger
+
+Structured debugging dispatch template with mandatory root cause investigation.
+
+**Core principle:** NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
+
+**When to use:**
+- Dispatched by a coordinator to investigate a specific bug
+- Test failures, production bugs, unexpected behavior
+- Performance problems, build failures, integration issues
+
+**Related skill:** `systematic-debugging` — contains the full methodology. This skill provides the dispatch template and report format.
+
+## Dispatch Template
+
+When dispatching a debugger subagent, use this prompt structure:
+
+```
+You are debugging an issue. Follow the systematic-debugging skill process.
+
+## The Issue
+
+[Describe the problem — error messages, unexpected behavior, symptoms]
+
+## Reproduction Steps
+
+[How to trigger the issue — commands, URLs, user actions]
+
+## Environment
+
+Project: [Project name and stack]
+
+## MANDATORY: Use Systematic Debugging
+
+You MUST follow the systematic-debugging skill process. This is non-negotiable.
+
+**The Iron Law:** NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+## Phases
+
+### Phase 1: Root Cause Investigation (REQUIRED BEFORE ANY FIX)
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+
+4. **Gather Evidence**
+   - Add diagnostic logging at component boundaries
+   - Log what data enters/exits each layer
+   - Run once to gather evidence showing WHERE it breaks
+
+5. **Trace Data Flow**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+
+### Phase 2: Pattern Analysis
+
+1. Find working examples in the codebase
+2. Compare against references
+3. Identify differences between working and broken
+4. Understand dependencies
+
+### Phase 3: Hypothesis and Testing
+
+1. Form single hypothesis: "I think X is the root cause because Y"
+2. Test minimally — SMALLEST possible change
+3. Verify before continuing
+4. If didn't work, form NEW hypothesis (don't stack fixes)
+
+### Phase 4: Implementation
+
+1. Create failing test case FIRST
+2. Implement single fix addressing root cause
+3. Verify fix — test passes, no regressions
+4. If 3+ fixes failed: STOP and question the architecture
+
+## Red Flags — STOP If You Think
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "I don't fully understand but this might work"
+- "Let me add multiple changes and run tests"
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+## Report Format
+
+When done, report:
+
+1. **Root Cause:** What was actually causing the issue
+2. **Evidence:** How you confirmed this was the root cause
+3. **Fix Applied:** The specific change made
+4. **Verification:** How you confirmed it's fixed
+5. **Regression Test:** Test added to prevent recurrence
+6. **Files Changed:** List of modified files
+
+## When Stuck
+
+If the debugger reports:
+
+- "I've tried 3+ fixes without success"
+- "Each fix reveals new problems"
+- "This requires architectural changes"
+
+**STOP** — This indicates an architectural problem, not a bug. Escalate before continuing.