awesome-slash 2.4.3 → 2.5.0

package/README.md

@@ -6,127 +6,127 @@ A cross-platform plugin providing powerful, zero-configuration slash commands fo
 
 [![npm](https://img.shields.io/npm/v/awesome-slash?color=red)](https://www.npmjs.com/package/awesome-slash)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-2.4.3-blue)](https://github.com/avifenesh/awesome-slash/releases)
-[![GitHub stars](https://img.shields.io/github/stars/awesome-slash?style=flat&color=yellow)](https://github.com/avifenesh/awesome-slash/stargazers)
+[![Version](https://img.shields.io/badge/version-2.5.0-blue)](https://github.com/avifenesh/awesome-slash/releases)
+[![GitHub stars](https://img.shields.io/github/stars/avifenesh/awesome-slash?style=flat&color=yellow)](https://github.com/avifenesh/awesome-slash/stargazers)
 [![Claude Code](https://img.shields.io/badge/Claude-Code%20Plugin-blue)](https://docs.anthropic.com/en/docs/claude-code)
 [![Codex CLI](https://img.shields.io/badge/Codex-CLI%20Compatible-green)](https://developers.openai.com/codex/cli)
 [![OpenCode](https://img.shields.io/badge/OpenCode-Compatible-orange)](https://opencode.ai)
 
-## What's New in v2.4.3
+> **📋 Disclaimer**: This project originated from personal workflow needs and was made public due to its effective delivery. Usage is entirely at your own responsibility. The maintainers make no guarantees about fitness for any particular purpose. Context/token efficiency has not been formally benchmarked.
 
-- **Documentation Sync** - Fixed outdated phase counts, agent lists, and install commands
-- **CLAUDE.md Guidelines** - Added project guidelines with release process and PR auto-review workflow
-- **npm Installation** - Added npm as primary installation option across all docs
+> **💡 Model Recommendation**: Using **Opus** as the main agent model produces significantly better results and follows workflow phases more tightly. While Sonnet works for simpler tasks, Opus is recommended for complex multi-step workflows.
 
----
-
-## Installation
-
-### npm (Recommended)
-
-```bash
-npm install awesome-slash
-```
+## What's New in v2.5.0
 
-### Claude Code
+- **Multi-Source Task Discovery** - Support for GitHub, GitLab, local files, custom CLI tools, and ad-hoc sources
+- **Source Preference Caching** - Your last-used source appears first on subsequent runs
+- **Security Hardening** - Fixed command injection and path traversal vulnerabilities
+- **Large Backlog Handling** - Intelligent pagination and priority filtering for repos with many issues
+- **Streamlined Policy Selection** - Direct questions from orchestrator, removed separate agent
 
-```bash
-# Option 1: npm (recommended)
-claude plugin add npm:awesome-slash
+## What's New in v2.4.7
 
-# Option 2: GitHub
-claude plugin add github:avifenesh/awesome-slash
+- **Simplified State Management** - Rewrote workflow-state.js, removed 9,000+ lines of overengineered code
+- **Removed Config System** - Deleted unused schemas and config system
+- **Tasks Lifecycle Wiring** - tasks.json now auto-registers/clears with workflow lifecycle
+- **Project Philosophy** - Added development guidelines to CLAUDE.md
+- **Agent Model Updates** - task-discoverer and code-explorer upgraded to opus
 
-# Option 3: Local clone
-git clone https://github.com/avifenesh/awesome-slash.git
-./scripts/install/claude.sh
-```
+---
 
-### OpenCode
+## Quick Install
 
 ```bash
+# npm (recommended)
 npm install awesome-slash
-# or
-git clone https://github.com/avifenesh/awesome-slash.git
-cd awesome-slash
-./scripts/install/opencode.sh
-```
 
-### Codex CLI
+# Claude Code
+claude plugin add npm:awesome-slash
 
-```bash
-npm install awesome-slash
-# or
+# OpenCode / Codex CLI
 git clone https://github.com/avifenesh/awesome-slash.git
-cd awesome-slash
-./scripts/install/codex.sh
+./scripts/install/opencode.sh  # or codex.sh
 ```
 
+**See [docs/INSTALLATION.md](./docs/INSTALLATION.md) for all options, prerequisites, and troubleshooting.**
+
 ---
 
 ## Available Commands
 
-### 📋 `/next-task:next-task` - Master Workflow Orchestrator
+### `/next-task` - Master Workflow Orchestrator
 
 Complete task-to-production automation with state management and resume capability.
 
 ```bash
-/next-task:next-task                   # Start new workflow with policy selection
-/next-task:next-task --status          # Check current workflow state
-/next-task:next-task --resume          # Resume from last checkpoint
-/next-task:next-task --abort           # Cancel workflow and cleanup
-/next-task:next-task bug               # Filter by task type
+/next-task                        # Start new workflow with policy selection
+/next-task --status               # Check current workflow state
+/next-task --resume               # Resume from last checkpoint
+/next-task --abort                # Cancel workflow and cleanup
+/next-task bug                    # Filter by task type
 ```
 
-**13-Phase Autonomous Workflow:**
-1. Policy Selection → Ask user preferences via checkboxes
-2. Task Discovery → Find and prioritize tasks from GitHub/Linear/PLAN.md
-3. Worktree Setup → Create isolated development environment [sonnet]
-4. Exploration → Deep codebase analysis [opus]
-5. Planning → Design implementation plan [opus]
-6. **User Approval → Get plan approval (LAST human interaction)**
-7. Implementation → Execute the plan [opus]
-8. **Pre-Review Gates → deslop-work + test-coverage-checker [sonnet]**
-9. Review Loop → Multi-agent review until approved [opus]
-10. **Delivery Validation → Autonomous task completion check [sonnet]**
-11. **Docs Update → Auto-update related documentation [sonnet]**
-12. Ship → PR creation, CI monitoring, merge
-13. Cleanup → Remove worktree, update state
-
-**Features:**
-- **Fully autonomous** after plan approval - no human in the loop
-- Resume capability with `.claude/.workflow-state.json`
-- 18 specialist agents with model optimization (opus/sonnet)
-- Quality gates: deslop-work, test-coverage-checker, delivery-validator, docs-updater
-- SubagentStop hooks for automatic workflow transitions
+**Workflow phases (tracked in `.claude/flow.json`):**
+- policy-selection
+- task-discovery
+- worktree-setup
+- exploration
+- planning
+- user-approval
+- implementation
+- review-loop
+- delivery-approval
+- ship-prep
+- create-pr
+- ci-wait
+- comment-fix
+- merge
+- production-ci
+- deploy
+- production-release
+- complete
+
+**Quality gates:**
+- deslop-work
+- test-coverage-checker
+- review-orchestrator
+- delivery-validator
+- docs-updater
+
+**Task Sources:**
+- **GitHub Issues** - Uses `gh` CLI (handles large backlogs with priority filtering)
+- **GitLab Issues** - Uses `glab` CLI
+- **Local files** - Reads from PLAN.md, tasks.md, or TODO.md
+- **Custom CLI** - Any CLI tool (tea, jira-cli, etc.) with auto-discovery
+- **Other** - Describe your source and the agent figures it out
+
+Your source preference is cached in `.claude/sources/preference.json` for fast subsequent runs.
+
+**Notes:**
+- Fully autonomous after plan approval
+- Resume capability with `.claude/flow.json`
 - Policy-based stopping points (pr-created, merged, deployed, production)
+- /ship handles PR creation, CI monitoring, merge, and cleanup
 
 ---
 
-### 🚀 `/ship:ship` - Complete PR Workflow
+### `/ship` - Complete PR Workflow
 
 Ship your code from commit to production with full validation and state integration.
 
 ```bash
-/ship:ship                        # Default workflow
-/ship:ship --strategy rebase      # Rebase before merge
-/ship:ship --dry-run              # Show plan without executing
-/ship:ship --state-file PATH      # Integrate with next-task workflow
+/ship                             # Default workflow
+/ship --strategy rebase           # Rebase before merge
+/ship --dry-run                   # Show plan without executing
+/ship --state-file PATH           # Integrate with next-task workflow
 ```
 
-**12-Phase Workflow:**
-1. Pre-flight checks and platform detection
-2. Commit with AI-generated message
-3. Create PR with context
-4. Wait for CI
-5. Multi-agent review (code quality, silent failures, test coverage)
-6. Merge PR
-7. Deploy to development (if multi-branch)
-8. Validate development
-9. Deploy to production
-10. Validate production
-11. Cleanup
-12. Completion report
+**Stages:**
+- Pre-flight checks and platform detection
+- Commit and PR creation
+- CI wait and review loop
+- Merge and (optional) deploy validation
+- Cleanup and completion report
 
 **Platform Support:**
 - **CI:** GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis CI
@@ -134,14 +134,14 @@ Ship your code from commit to production with full validation and state integrat
 
 ---
 
-### 🧹 `/deslop-around:deslop-around` - AI Slop Cleanup
+### `/deslop-around` - AI Slop Cleanup
 
 Remove debugging code, old TODOs, and AI slop from your codebase.
 
 ```bash
-/deslop-around:deslop-around               # Report mode - analyze only
-/deslop-around:deslop-around apply         # Apply fixes with verification
-/deslop-around:deslop-around apply src/ 10 # Fix up to 10 issues in src/
+/deslop-around                    # Report mode - analyze only
+/deslop-around apply              # Apply fixes with verification
+/deslop-around apply src/ 10      # Fix up to 10 issues in src/
 ```
 
 **Detects:**
@@ -152,29 +152,29 @@ Remove debugging code, old TODOs, and AI slop from your codebase.
 
 ---
 
-### 🔍 `/project-review:project-review` - Multi-Agent Code Review
+### `/project-review` - Multi-Agent Code Review
 
 Comprehensive code review with specialized agents that iterate until zero issues.
 
 ```bash
-/project-review:project-review              # Full codebase review
-/project-review:project-review --recent     # Only recent changes
-/project-review:project-review --domain security
+/project-review                   # Full codebase review
+/project-review --recent          # Only recent changes
+/project-review --domain security # Domain-focused review
 ```
 
-**8 Specialized Agents:**
-Security · Performance · Architecture · Testing · Error Handling · Code Quality · Type Safety · Documentation
+**Review domains:**
+Security, Performance, Architecture, Testing, Error Handling, Code Quality, Type Safety, Documentation
 
 ---
 
-### 📝 `/next-task:update-docs-around` - Documentation Sync
+### `/update-docs-around` - Documentation Sync
 
-Sync documentation with actual code state across the entire repository.
+Sync documentation with actual code state across the repository.
 
 ```bash
-/next-task:update-docs-around               # Report mode - analyze only
-/next-task:update-docs-around --apply       # Apply safe fixes
-/next-task:update-docs-around docs/ --apply # Sync specific directory
+/update-docs-around               # Report mode - analyze only
+/update-docs-around --apply       # Apply safe fixes
+/update-docs-around docs/ --apply # Sync specific directory
 ```
 
 **Checks:**
@@ -186,26 +186,26 @@ Sync documentation with actual code state across the entire repository.
 
 ---
 
-### ✅ `/next-task:delivery-approval` - Delivery Validation
+### `/delivery-approval` - Delivery Validation
 
 Validate task completion and approve for shipping (standalone or part of workflow).
 
 ```bash
-/next-task:delivery-approval                # Validate current work
-/next-task:delivery-approval --task-id 142  # Validate specific task
-/next-task:delivery-approval --verbose      # Show detailed check output
+/delivery-approval                # Validate current work
+/delivery-approval --task-id 142  # Validate specific task
+/delivery-approval --verbose      # Show detailed check output
 ```
 
-**Validation Checks:**
-- Tests pass (npm test)
-- Build passes (npm run build)
+**Validation checks:**
+- Tests pass
+- Build passes
 - Lint passes
 - Type check passes
 - Task requirements met
 
 ---
 
-### 🎯 `/reality-check:scan` - Plan Drift Detection
+### `/reality-check:scan` - Plan Drift Detection
 
 Deep repository analysis to identify where documented plans diverge from actual code reality.
 
@@ -214,30 +214,11 @@ Deep repository analysis to identify where documented plans diverge from actual
 /reality-check:set            # Configure scan settings
 ```
 
-**Multi-Agent Parallel Scan:**
-1. **Issue Scanner** - Analyzes GitHub issues, PRs, milestones
-2. **Doc Analyzer** - Examines README, PLAN.md, CLAUDE.md, docs/
-3. **Code Explorer** - Deep codebase structure and feature analysis
-4. **Plan Synthesizer** - Combines findings and creates prioritized plan
-
-**Detects:**
-- Plan stagnation (low completion rates)
-- Priority neglect (stale high-priority issues)
-- Documentation lag (features not documented)
-- Scope overcommit (documented but not implemented)
-- Missing tests, outdated docs, overdue milestones
-
-**Output:**
-- Drift analysis with severity ratings
-- Gap identification (missing tests, docs, CI)
-- Cross-reference: documented vs implemented features
-- Prioritized reconstruction plan (immediate, short-term, medium-term)
-
-**First-Run Setup:**
-Interactive checkboxes configure:
-- Data sources (GitHub, Linear, docs, code)
-- Scan depth (quick, medium, thorough)
-- Output format (file, display, both)
+**Multi-agent parallel scan:**
+1. Issue scanner - analyzes GitHub issues, PRs, milestones
+2. Doc analyzer - examines README, PLAN.md, CLAUDE.md, docs/
+3. Code explorer - deep codebase structure and feature analysis
+4. Plan synthesizer - combines findings into prioritized plan
 
 ---
 
@@ -252,7 +233,7 @@ All platforms share the same workflow tools via MCP (Model Context Protocol):
 | `workflow_resume` | Resume from checkpoint |
 | `workflow_abort` | Cancel and cleanup |
 | `task_discover` | Find and prioritize tasks |
-| `review_code` | Run multi-agent review |
+| `review_code` | Run pattern-based code review | 
 
 See [docs/CROSS_PLATFORM.md](./docs/CROSS_PLATFORM.md) for details.
 
@@ -262,19 +243,44 @@ See [docs/CROSS_PLATFORM.md](./docs/CROSS_PLATFORM.md) for details.
 
 ### State Management
 
-Workflows persist state in `.claude/.workflow-state.json`:
+Simple state tracking with three locations:
 
+**Main project: `.claude/tasks.json`** - Tracks active worktree/task:
 ```json
 {
-  "workflow": { "id": "...", "status": "in_progress" },
-  "policy": { "taskSource": "gh-issues", "stoppingPoint": "merged" },
-  "task": { "id": "142", "title": "Fix auth timeout" },
-  "phases": { "current": "implementation", "history": [...] },
-  "checkpoints": { "canResume": true, "resumeFrom": "implementation" }
+  "active": {
+    "worktree": "../project-task-123",
+    "branch": "feature/123-fix-auth",
+    "taskId": "123",
+    "taskTitle": "Fix auth timeout"
+  }
 }
 ```
 
-### Specialist Agents (18 Total)
+**Worktree: `.claude/flow.json`** - Tracks workflow progress:
+```json
+{
+  "task": { "id": "123", "title": "Fix auth timeout" },
+  "policy": { "stoppingPoint": "merged" },
+  "phase": "implementation",
+  "status": "in_progress",
+  "exploration": { "keyFiles": [...] },
+  "plan": { "steps": [...] },
+  "pr": { "number": 456, "url": "..." }
+}
+```
+
+**Source Preferences: `.claude/sources/preference.json`** - Caches task source selection:
+```json
+{
+  "source": "custom",
+  "type": "cli",
+  "tool": "tea",
+  "savedAt": "2025-01-19T08:00:00.000Z"
+}
+```
+
+### Specialist Agents (17 Total)
 
 **Core Workflow (Opus - Complex Tasks):**
 | Agent | Purpose |
@@ -289,16 +295,17 @@ Workflows persist state in `.claude/.workflow-state.json`:
 |-------|---------|
 | deslop-work | Clean AI slop from new work (committed but unpushed) |
 | test-coverage-checker | Validate new work has test coverage |
-| delivery-validator | Autonomous delivery validation (NOT manual) |
+| delivery-validator | Autonomous delivery validation (not manual) |
 | docs-updater | Update docs related to changes |
 
 **Operational (Sonnet - Infrastructure):**
 | Agent | Purpose |
 |-------|---------|
-| policy-selector | Configure workflow policy |
-| task-discoverer | Find and prioritize tasks |
+| task-discoverer | Find and prioritize tasks (multi-source) |
 | worktree-manager | Create isolated worktrees |
 | ci-monitor | Monitor CI/PR status with sleep loops |
+| ci-fixer | Fix CI failures and review comments |
+| simple-fixer | Execute predefined code fixes |
 
 **Reality Check (Sonnet + Opus - Plan Drift Detection):**
 | Agent | Purpose |
@@ -314,24 +321,27 @@ Workflows persist state in `.claude/.workflow-state.json`:
 
 ```
 awesome-slash/
-├── .claude-plugin/
-│   └── marketplace.json      # Claude Code marketplace manifest
-├── plugins/
-│   ├── next-task/           # Master workflow orchestrator
-│   │   ├── commands/        # next-task, update-docs-around, delivery-approval
-│   │   ├── agents/          # 18 specialist agents
-│   │   └── hooks/           # SubagentStop hooks for workflow automation
-│   ├── ship/                # PR workflow
-│   ├── deslop-around/       # AI slop cleanup
-│   ├── project-review/      # Multi-agent review
-│   └── reality-check/       # Plan drift detection
-├── lib/
-│   ├── state/               # Workflow state management
-│   ├── platform/            # Auto-detection
-│   └── patterns/            # Code analysis patterns
-├── mcp-server/              # Cross-platform MCP server
-├── scripts/install/         # Platform installers
-└── docs/
+|-- .claude-plugin/
+|   |-- marketplace.json      # Claude Code marketplace manifest
+|-- plugins/
+|   |-- next-task/             # Master workflow orchestrator
+|   |   |-- commands/          # next-task, update-docs-around, delivery-approval
+|   |   |-- agents/            # Specialist agents
+|   |   |-- hooks/             # SubagentStop hooks for workflow automation
+|   |-- ship/                  # PR workflow
+|   |-- deslop-around/         # AI slop cleanup
+|   |-- project-review/        # Multi-agent review
+|   |-- reality-check/         # Plan drift detection
+|-- lib/
+|   |-- config/                # Configuration management
+|   |-- state/                 # Workflow state management
+|   |-- sources/               # Multi-source task discovery
+|   |-- platform/              # Auto-detection
+|   |-- patterns/              # Code analysis patterns
+|   |-- utils/                 # Shell escaping and context optimization
+|-- mcp-server/                # Cross-platform MCP server
+|-- scripts/install/           # Platform installers
+|-- docs/
 ```
 
 ---
@@ -341,6 +351,8 @@ awesome-slash/
 **Required:**
 - Git
 - Node.js 18+
+
+**Required for GitHub-backed workflows:**
 - GitHub CLI (`gh`) with authentication
 
 **For Claude Code:**
@@ -356,11 +368,11 @@ awesome-slash/
 
 ## Contributing
 
-Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md).
+Contributions welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License
 
-MIT © [Avi Fenesh](https://github.com/avifenesh)
+MIT - [Avi Fenesh](https://github.com/avifenesh)
 
 ## Support
 
@@ -369,4 +381,4 @@ MIT © [Avi Fenesh](https://github.com/avifenesh)
 
 ---
 
-Made with ❤️ for the AI coding community
+Made with care for the AI coding community

package/SECURITY.md

@@ -1,101 +1,45 @@
 # Security Policy
 
-## Supported Versions
-
-We release patches for security vulnerabilities. Currently supported versions:
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 1.x.x   | :white_check_mark: |
-| < 1.0   | :x:                |
+> **Disclaimer:** This plugin is provided as-is. Usage is entirely at your own responsibility. The maintainers make no guarantees about security or fitness for any particular purpose.
 
 ## Reporting a Vulnerability
 
-We take security seriously. If you discover a security vulnerability, please follow these steps:
-
-### 1. Do Not Publicly Disclose
-
-Please **do not** open a public issue. Security vulnerabilities should be reported privately.
-
-### 2. Report Via GitHub Security Advisories
-
-Use GitHub's Security Advisory feature:
-1. Go to the [Security tab](https://github.com/avifenesh/awesome-slash/security/advisories)
-2. Click "Report a vulnerability"
-3. Provide detailed information about the vulnerability
-
-### 3. Or Email Directly
-
-If you prefer, you can email security reports to:
-- **Email:** Create a private security advisory on GitHub instead (preferred method)
-
-### 4. Include in Your Report
+If you discover a security vulnerability:
 
-Please include:
-- Description of the vulnerability
-- Steps to reproduce
-- Potential impact
-- Suggested fix (if you have one)
-- Your contact information
+1. **Do not** open a public issue
+2. Use [GitHub Security Advisories](https://github.com/avifenesh/awesome-slash/security/advisories) to report privately
+3. Include steps to reproduce and potential impact
 
-## What to Expect
+## User Responsibility
 
-- **Acknowledgment:** Within 48 hours
-- **Initial Assessment:** Within 1 week
-- **Status Updates:** We'll keep you informed of our progress
-- **Disclosure:** We'll coordinate disclosure timing with you
+**You are responsible for:**
+- Reviewing all code changes made by agents before committing
+- Never committing secrets, API keys, or credentials
+- Validating deployments before shipping to production
+- Understanding what commands do before running them
 
-## Security Best Practices for Users
-
-### When Using Commands
-
-1. **Review Generated Code:** Always review code changes made by agents before committing
-2. **Check Credentials:** Never commit secrets, API keys, or credentials
-3. **Deployment Caution:** Validate deployments before shipping to production
-4. **PR Reviews:** Use `/project-review` quality gates to catch security issues
-
-### Platform Detection Scripts
-
-The platform detection scripts in `lib/` execute shell commands. They:
-- Do not execute arbitrary user input
-- Only read configuration files
-- Do not modify system files
-- Run in the project directory only
-
-### Command Safety
-
-Commands that modify your repository:
-- `/ship` - Commits, pushes code, creates and merges PRs
+**Commands that modify your repository:**
+- `/ship` - Commits, pushes, creates and merges PRs
 - `/next-task` - Full workflow automation including code changes
 - `/deslop-around --apply` - Modifies source files
 
 Always review changes with `git status` and `git diff` before running commands that commit or push.
 
-## Scope
-
-This security policy covers:
-- Awesome Slash Commands plugin code
-- Platform detection scripts
-- Command implementations
-- Dependencies
+## Security Measures (v2.5.0+)
 
-Does not cover:
-- Vulnerabilities in Claude Code itself (report to Anthropic)
-- Vulnerabilities in external tools (gh, git, npm, etc.)
-- Issues with deployment platforms (Railway, Vercel, etc.)
+The plugin includes basic protections:
 
-## Dependencies
+- **Command Injection Prevention:** Uses `execFileSync` with input validation
+- **Path Traversal Prevention:** Tool names validated with allowlist patterns
+- **Input Validation:** User-provided values sanitized before use
 
-We regularly update dependencies to patch security vulnerabilities. If you find a vulnerability in one of our dependencies:
-1. Check if we're using the latest version
-2. If not, please report it
-3. If we are, please report to the dependency maintainer
+These measures reduce risk but do not guarantee security.
 
-## Recognition
+## Scope
 
-We appreciate security researchers who responsibly disclose vulnerabilities. With your permission, we'll acknowledge your contribution in:
-- Our CHANGELOG.md
-- The security advisory
-- This SECURITY.md file
+This policy covers the awesome-slash plugin code only.
 
-Thank you for helping keep Awesome Slash Commands secure!
+**Not covered:**
+- Claude Code itself (report to Anthropic)
+- External tools (gh, git, npm, etc.)
+- Deployment platforms (Railway, Vercel, etc.)