@cloudstreamsoftware/claude-tools 1.2.2 → 1.2.4

package/commands/orchestrate.md

@@ -0,0 +1,177 @@
+---
+name: orchestrate
+description: Sequential agent workflow for complex multi-step tasks. Chains agents (planner → architect → tdd-guide → code-reviewer) in optimal order.
+---
+
+# Orchestrate Command
+
+Sequential agent workflow for complex tasks.
+
+## Usage
+
+`/orchestrate [workflow-type] [task-description]`
+
+## Workflow Types
+
+### feature
+Full feature implementation workflow:
+```
+planner -> tdd-guide -> code-reviewer -> security-reviewer
+```
+
+### bugfix
+Bug investigation and fix workflow:
+```
+architect -> tdd-guide -> code-reviewer
+```
+
+### refactor
+Safe refactoring workflow:
+```
+architect -> code-reviewer -> tdd-guide
+```
+
+### security
+Security-focused review:
+```
+security-reviewer -> code-reviewer -> architect
+```
+
+## Execution Pattern
+
+For each agent in the workflow:
+
+1. **Invoke agent** with context from previous agent
+2. **Collect output** as structured handoff document
+3. **Pass to next agent** in chain
+4. **Aggregate results** into final report
+
+## Handoff Document Format
+
+Between agents, create handoff document:
+
+```markdown
+## HANDOFF: [previous-agent] -> [next-agent]
+
+### Context
+[Summary of what was done]
+
+### Findings
+[Key discoveries or decisions]
+
+### Files Modified
+[List of files touched]
+
+### Open Questions
+[Unresolved items for next agent]
+
+### Recommendations
+[Suggested next steps]
+```
+
+## Example: Feature Workflow
+
+```
+/orchestrate feature "Add user authentication"
+```
+
+Executes:
+
+1. **Planner Agent**
+   - Analyzes requirements
+   - Creates implementation plan
+   - Identifies dependencies
+   - Output: `HANDOFF: planner -> tdd-guide`
+
+2. **TDD Guide Agent**
+   - Reads planner handoff
+   - Writes tests first
+   - Implements to pass tests
+   - Output: `HANDOFF: tdd-guide -> code-reviewer`
+
+3. **Code Reviewer Agent**
+   - Reviews implementation
+   - Checks for issues
+   - Suggests improvements
+   - Output: `HANDOFF: code-reviewer -> security-reviewer`
+
+4. **Security Reviewer Agent**
+   - Security audit
+   - Vulnerability check
+   - Final approval
+   - Output: Final Report
+
+## Final Report Format
+
+```
+ORCHESTRATION REPORT
+====================
+Workflow: feature
+Task: Add user authentication
+Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer
+
+SUMMARY
+-------
+[One paragraph summary]
+
+AGENT OUTPUTS
+-------------
+Planner: [summary]
+TDD Guide: [summary]
+Code Reviewer: [summary]
+Security Reviewer: [summary]
+
+FILES CHANGED
+-------------
+[List all files modified]
+
+TEST RESULTS
+------------
+[Test pass/fail summary]
+
+SECURITY STATUS
+---------------
+[Security findings]
+
+RECOMMENDATION
+--------------
+[SHIP / NEEDS WORK / BLOCKED]
+```
+
+## Parallel Execution
+
+For independent checks, run agents in parallel:
+
+```markdown
+### Parallel Phase
+Run simultaneously:
+- code-reviewer (quality)
+- security-reviewer (security)
+- architect (design)
+
+### Merge Results
+Combine outputs into single report
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `feature <description>` - Full feature workflow
+- `bugfix <description>` - Bug fix workflow
+- `refactor <description>` - Refactoring workflow
+- `security <description>` - Security review workflow
+- `custom <agents> <description>` - Custom agent sequence
+
+## Custom Workflow Example
+
+```
+/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"
+```
+
+## Tips
+
+1. **Start with planner** for complex features
+2. **Always include code-reviewer** before merge
+3. **Use security-reviewer** for auth/payment/PII
+4. **Keep handoffs concise** - focus on what next agent needs
+5. **Run verification** between agents if needed

package/commands/plan.md

@@ -0,0 +1,34 @@
+---
+name: plan
+description: Restate requirements, assess risks, and create step-by-step implementation plan. WAIT for user CONFIRM before touching any code.
+---
+
+# /plan [feature-description]
+
+Invoke the **planner** agent to create a comprehensive implementation plan before writing any code.
+
+## Parameters
+- `feature-description` — What needs to be built or changed
+
+## Workflow
+1. Agent restates requirements in clear terms
+2. Breaks down into phased steps with dependencies
+3. Identifies risks and blockers
+4. Assesses complexity (High/Medium/Low)
+5. **WAITS for explicit user confirmation** before proceeding
+
+## When to Use
+- Starting a new feature
+- Significant architectural changes
+- Complex refactoring (multiple files/components)
+- Unclear or ambiguous requirements
+
+## User Responses After Plan
+- `"yes"` / `"proceed"` — Execute the plan
+- `"modify: [changes]"` — Adjust approach
+- `"skip phase X"` — Reorder execution
+
+## Integration
+- After plan approval: `/tdd` to implement
+- After implementation: `/code-review` to validate
+- Final check: `/verify` to confirm everything passes

package/commands/pr-ready.md

@@ -0,0 +1,130 @@
+---
+name: pr-ready
+description: Run pre-PR checklist to verify readiness. Validates branch name, runs tests, checks for secrets, and verifies code quality.
+---
+
+# /pr-ready
+
+Run comprehensive pre-PR validation to ensure readiness for code review.
+
+## Checks Performed
+
+1. **Branch Validation**
+   - Validates branch name follows conventions
+   - Uses `scripts/branch-name-validator.js`
+
+2. **Verification Suite**
+   - Runs `/verify` (lint, test, validate)
+   - Checks for build errors
+   - Verifies test coverage
+
+3. **Code Review**
+   - Runs `/code-review` on changed files
+   - Flags CRITICAL and HIGH issues
+   - Reports MEDIUM issues
+
+4. **Git Status**
+   - Verifies branch is up-to-date with main
+   - Checks for uncommitted changes
+   - Validates commit message format
+
+5. **Security Scan**
+   - Checks for console.log statements
+   - Scans for hardcoded credentials
+   - Detects secrets in code
+
+## Output Format
+
+```
+PR READINESS: [READY/NOT READY]
+
+Branch:      [VALID/INVALID] branch-name
+Verify:      [PASS/FAIL]
+Code Review: [PASS/X issues]
+Up-to-date:  [YES/NO]
+Commits:     [X valid]
+Secrets:     [OK/X found]
+Logs:        [OK/X console.logs]
+
+Blockers: (if any)
+- [list of issues to fix]
+
+Ready for PR: [YES/NO]
+```
+
+## Example Usage
+
+```bash
+# Run full PR readiness check
+/pr-ready
+
+# After fixing issues, run again
+/pr-ready
+```
+
+## Blocker Resolution
+
+### Branch Name Invalid
+```bash
+# Rename branch to follow conventions
+git branch -m feature/CSS/correct-name
+```
+
+### Tests Failing
+```bash
+# Run tests and fix failures
+npm test
+```
+
+### Code Review Issues
+```bash
+# Address CRITICAL and HIGH issues
+# MEDIUM issues are optional but recommended
+```
+
+### Not Up-to-date
+```bash
+# Sync with main
+git fetch origin main
+git rebase origin/main
+```
+
+### Secrets Found
+```bash
+# Remove secrets from code
+# Use environment variables instead
+```
+
+### Console.logs Found
+```bash
+# Remove debugging statements
+# Use proper logging if needed
+```
+
+## Integration
+
+- Use after `/verify` passes locally
+- Run before `gh pr create`
+- Pairs with `.github/workflows/pr-quality-gate.yml`
+
+## When to Use
+
+- Before creating any Pull Request
+- After making significant changes to a PR
+- When CI fails and you need to debug locally
+- Before requesting code review
+
+## Workflow
+
+1. Complete feature development
+2. Run `/verify` to validate locally
+3. Run `/pr-ready` for comprehensive check
+4. Fix any blockers
+5. Create PR with `gh pr create`
+
+## Related Commands
+
+- `/verify` - Quick validation (build, lint, test)
+- `/code-review` - Deep code review
+- `/create-branch` - Create properly-named branch
+- `/health-check` - System health verification

package/commands/quarterly-review.md

@@ -0,0 +1,154 @@
+---
+name: quarterly-review
+description: Conduct quarterly skill and agent review process
+---
+
+# Quarterly Review Command
+
+Guided quarterly review process for evaluating skill effectiveness, identifying deprecation candidates, and managing skill lifecycle.
+
+## Trigger
+
+Use this command when:
+- Starting a quarterly review cycle (every 12 weeks)
+- Evaluating skill/agent effectiveness
+- Identifying skills to deprecate or promote
+- Generating quarterly reports
+
+## Subcommands
+
+### `/quarterly-review` or `/quarterly-review generate`
+Generate the quarterly report with full analysis.
+
+### `/quarterly-review status`
+Show current quarter status summary only.
+
+### `/quarterly-review deprecate <skill-name>`
+Deprecate a specific skill with guided workflow.
+
+## Instructions
+
+### Generate Quarterly Report
+
+1. Run the quarterly report generator:
+   ```bash
+   npm run quarterly:report
+   ```
+
+2. Review the generated report at `~/.claude/knowledge/reports/quarterly-Q[X]-[YEAR].md`
+
+3. Present key findings to user:
+   - Executive summary with metrics
+   - Deprecation candidates with justification
+   - Promotion candidates with impact
+
+4. Ask user which recommendations to act upon
+
+### Deprecation Workflow
+
+When user approves a deprecation:
+
+1. Run deprecation script:
+   ```bash
+   npm run skill:deprecate <skill-name> --superseded-by <replacement> --removal-target 2.0.0
+   ```
+
+2. Review generated migration guide at `skills/<skill-name>/MIGRATION.md`
+
+3. Verify CHANGELOG.md was updated
+
+4. Show deprecation checklist to user
+
+### Status Check
+
+1. Run status command:
+   ```bash
+   npm run quarterly:report --status
+   ```
+
+2. Present summary:
+   - Skills analyzed
+   - Average effectiveness
+   - Action items needed
+
+## Output Format
+
+```
+╔════════════════════════════════════════════════════════════╗
+║          QUARTERLY REVIEW: Q[X] [YEAR]                     ║
+╚════════════════════════════════════════════════════════════╝
+
+EXECUTIVE SUMMARY
+────────────────────────────────────────
+  Total Skills/Agents:     XX
+  Average Effectiveness:   XX%
+  Improving:               X
+  Declining:               X
+  Stable:                  X
+
+DEPRECATION CANDIDATES
+────────────────────────────────────────
+  [!] skill-name
+      Effectiveness 35% after 15 uses
+      Suggested action: Deprecate, supersede with new-skill
+
+  [*] another-skill
+      Not used in 120 days
+      Suggested action: Review usage, consider deprecation
+
+PROMOTION CANDIDATES
+────────────────────────────────────────
+  [+] learned-pattern
+      95% effectiveness, 25 uses
+      Suggested action: Promote to bundled skill
+
+ACTIONS
+────────────────────────────────────────
+Which recommendations would you like to act upon?
+1. Deprecate skill-name
+2. Deprecate another-skill
+3. Promote learned-pattern
+4. Skip all / Review later
+```
+
+## Critical Issues
+
+### Deprecation Rules
+- Always provide replacement skill when possible
+- Set removal target at least one major version ahead
+- Generate migration guide before deprecating
+- Update CHANGELOG.md with deprecation entry
+- Notify team of upcoming deprecations
+
+### Quality Gates
+Before completing quarterly review:
+- [ ] All deprecation candidates reviewed
+- [ ] Migration guides created and reviewed
+- [ ] CHANGELOG updated
+- [ ] Team notified
+- [ ] Version numbers incremented correctly
+
+## Related Commands
+
+- `/health-check` - System health verification
+- `/instinct-status` - View learned instincts with confidence
+- `/learn` - Capture new patterns
+
+## Related Scripts
+
+```bash
+npm run quarterly:report              # Generate full report
+npm run quarterly:report --status     # Quick status
+npm run quarterly:report --json       # JSON output
+npm run quarterly:report --verbose    # Detailed analysis
+npm run skill:deprecate <skill>       # Deprecate a skill
+```
+
+## Documentation
+
+See `docs/quarterly-review-process.md` for complete process documentation including:
+- 4-week review cycle details
+- Deprecation criteria matrix
+- Promotion criteria
+- Stakeholder responsibilities
+- Quality gates checklist

package/commands/refactor-clean.md

@@ -0,0 +1,54 @@
+---
+name: refactor-clean
+description: Safely identify and remove dead code with test verification. Runs analysis tools (knip, depcheck, ts-prune) and removes unused code.
+---
+
+# Refactor Clean
+
+Safely identify and remove dead code with test verification:
+
+1. Run dead code analysis tools:
+   - knip: Find unused exports and files
+   - depcheck: Find unused dependencies
+   - ts-prune: Find unused TypeScript exports
+
+2. Generate comprehensive report in .reports/dead-code-analysis.md
+
+3. Categorize findings by severity:
+   - SAFE: Test files, unused utilities
+   - CAUTION: API routes, components
+   - DANGER: Config files, main entry points
+
+4. Propose safe deletions only
+
+5. Before each deletion:
+   - Run full test suite
+   - Verify tests pass
+   - Apply change
+   - Re-run tests
+   - Rollback if tests fail
+
+6. Show summary of cleaned items
+
+Never delete code without running tests first!
+
+---
+
+## Tools Used
+
+| Tool | Purpose |
+|------|---------|
+| [knip](https://github.com/webpro/knip) | Find unused exports, files, dependencies |
+| [depcheck](https://github.com/depcheck/depcheck) | Find unused npm dependencies |
+| [ts-prune](https://github.com/nadeesha/ts-prune) | Find unused TypeScript exports |
+
+---
+
+## Related
+
+- **Agent:** [refactor-cleaner](../agents/refactor-cleaner.md) - The specialized agent that executes this command
+- **Commands:**
+  - [/verify](./verify.md) - Validate codebase after cleanup
+  - [/code-review](./code-review.md) - Review changes before committing
+  - [/test-coverage](./test-coverage.md) - Ensure tests cover remaining code
+- **Skills:** [coding-standards](../skills/coding-standards/SKILL.md) - Best practices for maintainable code

package/commands/setup-pm.md

@@ -0,0 +1,81 @@
+---
+name: setup-pm
+description: Configure your preferred package manager (npm/pnpm/yarn/bun)
+disable-model-invocation: true
+---
+
+# Package Manager Setup
+
+Configure your preferred package manager for this project or globally.
+
+## Usage
+
+```bash
+# Detect current package manager
+node scripts/setup-package-manager.js --detect
+
+# Set global preference
+node scripts/setup-package-manager.js --global pnpm
+
+# Set project preference
+node scripts/setup-package-manager.js --project bun
+
+# List available package managers
+node scripts/setup-package-manager.js --list
+```
+
+## Detection Priority
+
+When determining which package manager to use, the following order is checked:
+
+1. **Environment variable**: `CLAUDE_PACKAGE_MANAGER`
+2. **Project config**: `.claude/package-manager.json`
+3. **package.json**: `packageManager` field
+4. **Lock file**: Presence of package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb
+5. **Global config**: `~/.claude/package-manager.json`
+6. **Fallback**: First available package manager (pnpm > bun > yarn > npm)
+
+## Configuration Files
+
+### Global Configuration
+```json
+// ~/.claude/package-manager.json
+{
+  "packageManager": "pnpm"
+}
+```
+
+### Project Configuration
+```json
+// .claude/package-manager.json
+{
+  "packageManager": "bun"
+}
+```
+
+### package.json
+```json
+{
+  "packageManager": "pnpm@8.6.0"
+}
+```
+
+## Environment Variable
+
+Set `CLAUDE_PACKAGE_MANAGER` to override all other detection methods:
+
+```bash
+# Windows (PowerShell)
+$env:CLAUDE_PACKAGE_MANAGER = "pnpm"
+
+# macOS/Linux
+export CLAUDE_PACKAGE_MANAGER=pnpm
+```
+
+## Run the Detection
+
+To see current package manager detection results, run:
+
+```bash
+node scripts/setup-package-manager.js --detect
+```