Pew Pew Plx

Pew Pew Plx aligns humans and AI coding assistants with spec-driven development. Agree on what to build before any code is written. No API keys required.

Fork of OpenSpec with extended task management, review workflows, and automatic migration from OpenSpec projects.

Installation

npm install -g @appboypov/pew-pew-plx
plx --version

Prerequisites: Node.js >= 20.19.0

Quick Start

cd my-project
plx init

This creates the workspace/ directory structure and configures slash commands for your AI tools.

How It Works

1. Draft    → Create a change proposal capturing spec updates
2. Review   → Iterate with your AI until everyone agrees
3. Implement → AI works through tasks referencing agreed specs
4. Archive  → Merge approved updates into source-of-truth specs

Commands

Navigation & Listing

| Command | Description | |---------|-------------| | plx get changes | List active changes | | plx get specs | List specifications | | plx get reviews | List active reviews | | plx view | Interactive dashboard |

Note: plx list is deprecated. Use plx get changes, plx get specs, or plx get reviews instead.

Task Management

| Command | Description | |---------|-------------| | plx get task | Get next prioritized task | | plx get task --id <id> | Get specific task | | plx get task --did-complete-previous | Complete current, get next | | plx get task --constraints | Show only Constraints | | plx get task --acceptance-criteria | Show only Acceptance Criteria | | plx get tasks | List all open tasks | | plx complete task --id <id> | Mark task done | | plx complete change --id <id> | Complete all tasks in change | | plx undo task --id <id> | Revert task to to-do | | plx undo change --id <id> | Revert all tasks in change |

Item Retrieval

| Command | Description | |---------|-------------| | plx get change --id <id> | Get change by ID | | plx get spec --id <id> | Get spec by ID | | plx get review --id <id> | Get review by ID |

Note: plx show is deprecated. Use plx get change --id <id> or plx get spec --id <id> instead.

Review System

| Command | Description | |---------|-------------| | plx review change --id <id> | Review a change | | plx review spec --id <id> | Review a spec | | plx review task --id <id> | Review a task | | plx parse feedback <name> --parent-id <id> --parent-type change|spec|task | Parse feedback markers |

Draft Management

| Command | Description | |---------|-------------| | plx paste request | Paste clipboard content as draft request |

Validation & Archival

| Command | Description | |---------|-------------| | plx validate change --id <id> | Validate specific change | | plx validate changes | Validate all changes | | plx validate spec --id <id> | Validate specific spec | | plx validate specs | Validate all specs | | plx validate all | Validate everything | | plx archive change --id <id> | Archive completed change | | plx archive review --id <id> | Archive completed review |

Configuration

| Command | Description | |---------|-------------| | plx config path | Show config file location | | plx config list | Show all settings | | plx update | Refresh instruction files | | plx upgrade | Upgrade CLI to latest version | | plx upgrade --check | Check for updates without installing |

Subdirectory Support

All PLX commands work from any subdirectory within a project. The CLI automatically finds the project root by scanning upward for workspace/AGENTS.md.

Multi-Workspace (Monorepo)

| Command | Description | |---------|-------------| | plx get changes --workspace <name> | Filter to specific workspace | | plx get task --workspace <name> | Get task from specific workspace | | plx validate all --workspace <name> | Validate specific workspace |

In monorepos, items display with project prefixes (e.g., project-a/add-feature). Use --workspace to filter operations.

Transfer (Cross-Workspace)

| Command | Description | |---------|-------------| | plx transfer change --id <id> --target <path> | Move change and linked tasks | | plx transfer spec --id <id> --target <path> | Move spec and related changes | | plx transfer task --id <id> --target <path> | Move single task | | plx transfer review --id <id> --target <path> | Move review and linked tasks | | plx transfer request --id <id> --target <path> | Move request to target change |

Transfer options: --source <path>, --target-name <name>, --dry-run, --yes, --json.

Task Structure

Tasks are stored centrally in workspace/tasks/ as numbered files:

workspace/tasks/
├── 001-add-feature-implement.md          # Parented task (linked to change)
├── 002-add-feature-review.md             # Parented task (linked to change)
├── 003-standalone-task.md                # Standalone task
└── archive/                              # Archived tasks
    └── 001-completed-task.md

Task Filename Patterns:

• Parented tasks: NNN-<parent-id>-<kebab-case-name>.md (e.g., 001-add-feature-implement.md)
• Standalone tasks: NNN-<kebab-case-name>.md (e.g., 003-standalone-task.md)

Each task uses YAML frontmatter for status, skill-level, and parent linking:

---
status: to-do  # or: in-progress, done
skill-level: medior  # or: junior, senior (optional, guides AI model selection)
parent-type: change  # or: review, spec (optional, for parented tasks)
parent-id: add-feature  # optional, for parented tasks
---

Prioritization: Changes with highest completion percentage are prioritized first. Within a change, the first to-do or in-progress task is selected.

Auto-completion: When all Implementation Checklist items are checked, the task is automatically marked done and the next task begins.

Review Workflow

Add inline feedback markers during code review:

// #FEEDBACK #TODO | Validate input before processing

# #FEEDBACK #TODO | Add error handling here

<!-- #FEEDBACK #TODO | Missing accessibility attributes -->

For parent-linked feedback, include parent type and ID in the marker:

// #FEEDBACK #TODO | change:add-feature | Validate input before processing
// #FEEDBACK #TODO | spec:user-auth | Update validation logic

Parse markers with: plx parse feedback review-name --parent-id <id> --parent-type change|spec|task

Slash Commands

When you run plx init, these commands are installed for supported AI tools:

• /plx/plan-request - Clarify intent via iterative yes/no questions
• /plx/plan-proposal - Scaffold change proposal (auto-consumes request.md)
• /plx/plan-implementation - Generate PROGRESS.md for multi-agent task handoff
• /plx/get-task - Get next prioritized task
• /plx/copy-next-task - Copy next task or feedback block to clipboard
• /plx/copy-review-request - Copy review request with REVIEW.md guidelines to clipboard
• /plx/copy-test-request - Copy test request with TESTING.md configuration to clipboard
• /plx/complete-task - Mark task as done
• /plx/undo-task - Revert task to to-do
• /plx/implement - Implement current task with guided workflow
• /plx/orchestrate - Coordinate sub-agents for multi-task work
• /plx/refine-architecture - Create or update ARCHITECTURE.md with spec-ready component inventories
• /plx/refine-review - Create or update REVIEW.md template
• /plx/refine-release - Create or update RELEASE.md template
• /plx/refine-testing - Create or update TESTING.md template
• /plx/test - Run tests based on scope (change, task, or spec)
• /plx/review - Review implementations
• /plx/parse-feedback - Parse feedback markers
• /plx/prepare-release - Guided release preparation workflow
• /plx/prepare-compact - Preserve session progress in PROGRESS.md
• /plx/sync-workspace - Sync workspace state across changes

Supported AI Tools

| Tool | Command Format | |------|----------------| | Amazon Q Developer | @plx-plan-proposal, @plx-implement, @plx-archive | | Antigravity | /plx-plan-proposal, /plx-implement, /plx-archive | | Auggie (Augment CLI) | /plx-plan-proposal, /plx-implement, /plx-archive | | Claude Code | /plx:plan-proposal, /plx:implement, /plx:archive | | Cline | Workflows in .clinerules/workflows/ | | CodeBuddy Code | /plx:plan-proposal, /plx:implement, /plx:archive | | Codex | /plx-plan-proposal, /plx-implement, /plx-archive | | CoStrict | /plx-plan-proposal, /plx-implement, /plx-archive | | Crush | /plx-plan-proposal, /plx-implement, /plx-archive | | Cursor | /plx-plan-proposal, /plx-implement, /plx-archive | | Factory Droid | /plx-plan-proposal, /plx-implement, /plx-archive | | Gemini CLI | /plx:plan-proposal, /plx:implement, /plx:archive | | GitHub Copilot | /plx-plan-proposal, /plx-implement, /plx-archive | | iFlow | /plx-plan-proposal, /plx-implement, /plx-archive | | Kilo Code | /plx-plan-proposal.md, /plx-implement.md, /plx-archive.md | | OpenCode | /plx-plan-proposal, /plx-implement, /plx-archive | | Qoder | /plx:plan-proposal, /plx:implement, /plx:archive | | Qwen Code | /plx-plan-proposal, /plx-implement, /plx-archive | | RooCode | /plx-plan-proposal, /plx-implement, /plx-archive | | Windsurf | /plx-plan-proposal, /plx-implement, /plx-archive |

Tools that read workflow instructions from workspace/AGENTS.md:

Amp, Jules, and others following the AGENTS.md convention.

Contributing

pnpm install
pnpm run build
pnpm test

License

MIT