🔫 Pew Pew 💨 Plx 🙏

Advanced AI project management framework for Claude Code that systematically transforms requirements into production-ready artifacts through intelligent decomposition and component reuse.

🚀 Quick Start

# Install globally via npm
npm install -g pew-pew-plx

# Initialize in your project
plx init

# Sync with Claude Code
plx sync claude

That's it! You now have access to the complete artifact creation philosophy, specialized agents, smart templates, and intelligent workflows in Claude Code.

📝 A Good Prompt

The foundation of this framework is understanding what makes an effective prompt. Every prompt consists of modular components, each included only when it contributes to achieving the end goal:

graph TD
    EG[🎯 End Goal<br/>Measurable Objective]
    
    P[👤 Persona<br/>Optional Expertise]
    R[📋 Request<br/>Verb-First Activity]
    W[🔄 Workflow<br/>Optional Steps]
    I[📏 Instructions<br/>Optional Rules]
    O[📊 Output Format<br/>Optional Structure]
    
    EG --> P
    EG --> R
    EG --> W
    EG --> I
    EG --> O
    
    P -.->|Contributes to| EG
    R -.->|Required for| EG
    W -.->|Enhances| EG
    I -.->|Guides toward| EG
    O -.->|Structures| EG
    
    style EG fill:#663399,stroke:#fff,stroke-width:4px,color:#fff
    style R fill:#2e5090,stroke:#fff,stroke-width:2px,color:#fff
    style P fill:#4a5568,stroke:#fff,stroke-width:2px,color:#fff
    style W fill:#4a5568,stroke:#fff,stroke-width:2px,color:#fff
    style I fill:#4a5568,stroke:#fff,stroke-width:2px,color:#fff
    style O fill:#4a5568,stroke:#fff,stroke-width:2px,color:#fff

Core Components

🎯 End Goal

The measurable objective that determines whether any following section provides value. This is your north star - every component should improve your chances of achieving this goal exactly as intended.

👤 Persona (Optional)

Specialized expertise attributes included when they enhance outcomes:

Role, Expertise, Domain, Knowledge
Experience, Skills, Abilities, Responsibilities
Interests, Background, Preferences, Perspective
Communication Style

📋 Request

Verb-first activity specification with optional deliverables and acceptance criteria. Always starts with an action: Create, Update, Analyze, Transform, etc.

🔄 Workflow (Optional)

Atomic steps with specific deliverables and acceptance criteria for each phase. Used when multi-step processes are required.

📏 Instructions (Optional)

Event-driven guidance following the pattern: "When {scenario} occurs, then {apply these instructions}". Includes best practices, conventions, constraints, and rules.

📊 Output Format (Optional)

Specifications for how deliverables should be structured - templates, format types (JSON, YAML, Markdown), or specific structural requirements.

The Modular Approach

Each component can and should be extracted and referenced via wikilinks when it can be reused:

graph LR
    subgraph "1. Inline Phase"
        I1[persona: Expert issue creator...]
        I2[workflow: Step-by-step process...]
        I3[instructions: When creating...]
    end
    
    subgraph "2. Extraction Phase"
        E1["persona: [[issue-expert-persona]]"]
        E2["workflow: [[issue-creation-workflow]]"]
        E3["instructions: [[issue-conventions]]"]
    end
    
    subgraph "3. Embedding Phase"
        EM1["![[issue-expert-persona]]"]
        EM2["![[issue-creation-workflow]]"]
        EM3["![[issue-conventions]]"]
    end
    
    I1 -->|Extract| E1
    I2 -->|Extract| E2
    I3 -->|Extract| E3
    
    E1 -->|Embed| EM1
    E2 -->|Embed| EM2
    E3 -->|Embed| EM3
    
    style I1 fill:#8b4513,stroke:#fff,color:#fff
    style I2 fill:#8b4513,stroke:#fff,color:#fff
    style I3 fill:#8b4513,stroke:#fff,color:#fff
    style E1 fill:#2e7d32,stroke:#fff,color:#fff
    style E2 fill:#2e7d32,stroke:#fff,color:#fff
    style E3 fill:#2e7d32,stroke:#fff,color:#fff
    style EM1 fill:#1565c0,stroke:#fff,color:#fff
    style EM2 fill:#1565c0,stroke:#fff,color:#fff
    style EM3 fill:#1565c0,stroke:#fff,color:#fff

During sync, the framework:

Converts [[references]] to @path/to/file.md for dynamic loading
Replaces ![[embeds]] with actual file content
Enables component reuse across all artifacts

🤖 From Prompts to Agents

When certain prompt components naturally align around a common purpose, they can be composed into agents:

graph TD
    subgraph "Prompt Components"
        P1[👤 Persona]
        W1[🔄 Workflow]
        I1[📏 Instructions]
        O1[📊 Output Format]
    end
    
    subgraph "Agent Composition"
        A[🤖 Agent<br/>flutter-developer.md]
    end
    
    subgraph "Reusable Everywhere"
        PR1[📝 Prompt 1]
        PR2[📝 Prompt 2]
        PR3[📝 Prompt 3]
    end
    
    P1 --> A
    W1 --> A
    I1 --> A
    O1 --> A
    
    A -->|"Embed: ![[flutter-developer]]"| PR1
    A -->|"Embed: ![[flutter-developer]]"| PR2
    A -->|"Embed: ![[flutter-developer]]"| PR3
    
    style A fill:#663399,stroke:#fff,stroke-width:3px,color:#fff
    style P1 fill:#4a5568,stroke:#fff,color:#fff
    style W1 fill:#4a5568,stroke:#fff,color:#fff
    style I1 fill:#4a5568,stroke:#fff,color:#fff
    style O1 fill:#4a5568,stroke:#fff,color:#fff
    style PR1 fill:#2e7d32,stroke:#fff,color:#fff
    style PR2 fill:#2e7d32,stroke:#fff,color:#fff
    style PR3 fill:#2e7d32,stroke:#fff,color:#fff

Agent Composition

An agent combines:

Persona - The expertise and characteristics
Workflow - The systematic process
Instructions - The rules and conventions
Output Format - The delivery structure

📋 Templates and Blocks

Templates provide structured formats, while blocks offer reusable content sections:

Templates

Complete document structures in templates/outputs/:

Issue templates, story templates, epic templates
Bug reports, pull requests, documentation
Implementation plans, requirements, roadmaps

Blocks

Reusable content sections in templates/blocks/:

Context blocks (capabilities, purpose, functions)
Instruction blocks (best practices, rules, standards)
Workflow blocks (steps, inputs, outputs)
40+ specialized blocks for comprehensive documentation

🎨 Core Philosophy: From Monolithic to Modular

The framework's philosophy is based on natural evolution - we don't start by building components. We start by solving problems completely, then extract patterns:

1️⃣ Start with Complete Solutions

First, create a fully functional prompt with everything inline:

Write the complete prompt with all components defined directly
Focus on solving the immediate problem completely
Don't worry about reusability initially
Get it working first, optimize later

2️⃣ Identify Reusable Patterns

After creating several prompts, patterns emerge:

Notice repeated personas across prompts
Identify common workflows being duplicated
Spot recurring instructions and conventions
Recognize standard output formats

3️⃣ Extract and Modularize

Only after patterns prove their value:

Extract repeated components to separate files
Replace inline content with wikilink references
Create agents when persona + workflow + instructions naturally align
Build a library of reusable components from proven patterns

4️⃣ Systematic Refinement

Apply structured validation through targeted questioning:

🔄 Simplify - Can we reduce complexity?
❓ Clarify - Are requirements unambiguous?
🔧 Improve - What enhancements add value?
➕ Expand - What edge cases are missing?
➖ Reduce - What can be deferred to MVP?

🎮 Universal Creation Commands

The framework provides comprehensive artifact management through systematic commands:

🎨 `/plx:create/anything`

Intelligently generates the appropriate artifact type based on requirements:

Example: "Identify all actors in the project"
→ Generates: identify-actors.md prompt containing:
  - Actor identification workflow
  - Actor template output format
  - Systematic discovery methodology

🔄 `/plx:update/anything`

Enhances existing artifacts to meet current standards:

Analyzes current implementation against best practices
Identifies improvement opportunities
Applies modular enhancements
Extracts reusable components

🔮 `/plx:make/anything`

Transforms content between different formats:

Raw text → Structured documentation
Conceptual ideas → Actionable components
Requirements → Implementation plans
Conversations → Formal specifications

🧩 `/plx:shard/anything`

Decomposes monolithic artifacts into modular components:

Identifies reusable patterns
Creates standalone component files
Implements wikilink references
Enables cross-artifact sharing

🔗 WikiLink Architecture: Component Reusability

The framework leverages a sophisticated component referencing system:

graph LR
    subgraph "Development Time"
        D1["Write: [[component]]"]
        D2["Write: ![[component-example-wiki-link]]"]
    end
    
    subgraph "Sync Process"
        S1[plx sync claude]
        S2[WikiLink Resolution]
        S3[Content Embedding]
    end
    
    subgraph "Runtime"
        R1[@path/to/component.md<br/>Dynamic Loading]
        R2[Actual Content<br/>Embedded Inline]
    end
    
    D1 --> S1
    D2 --> S1
    S1 --> S2
    S1 --> S3
    S2 --> R1
    S3 --> R2
    
    style D1 fill:#4a5568,stroke:#fff,color:#fff
    style D2 fill:#4a5568,stroke:#fff,color:#fff
    style S1 fill:#b8860b,stroke:#fff,stroke-width:2px,color:#fff
    style S2 fill:#8b4513,stroke:#fff,color:#fff
    style S3 fill:#8b4513,stroke:#fff,color:#fff
    style R1 fill:#2e7d32,stroke:#fff,color:#fff
    style R2 fill:#1565c0,stroke:#fff,color:#fff

Standard WikiLinks: Dynamic Loading

# In your artifact:
Follow [[project-conventions]] and use [[story-template]]

# After sync transformation:
Follow @instructions/project-conventions.md and use @templates/story-template.md

# Result: Claude automatically loads referenced files at runtime

Embedded WikiLinks: Content Insertion

# Reference mode (loads on activation):
Use the workflow in [[issue-workflow-example-wiki-link]]

# Embedding mode (content inserted during sync):
![[issue-workflow-example-wiki-link]]

# Note: Embedded wikilinks must occupy their own line

Component Evolution Lifecycle

1. Inline definition → Components defined within the artifact
2. File extraction → [[component-name-example-wiki-link]] references to external files
3. Agent composition → Combining persona, workflow, and instructions
4. Agent embedding → ![[agent-name-example-wiki-link]] inclusion in prompts

📋 Issue Management Philosophy

Parallel AI Working Paths

Enable maximum productivity through strategic organization:

Team Structure

Tech - Development and architecture
Marketing - Content and engagement
Sales - Customer relations and revenue

Subject-Based Parallel Work

Within each team, subjects advance independently:

Each subject improves one at a time
MVP must-have mindset for granular releases
Global scale productivity across levels
Non-interrupting workflows

Question Mode Integration

Systematic refinement through YES/NO questions:

Simplify - Reduce complexity suggestions
Clarify - Validate understanding
Improve - Enhancement opportunities
Expand - Missing requirements
Reduce - MVP analysis

🎮 Commands

Core Framework Commands

plx init              # Initialize framework
plx sync claude       # Sync to Claude Code
plx sync claude clean # Clean sync
plx watch claude      # Auto-sync during development
plx pull main         # Update framework

Claude Code Commands (After Sync)

Creation Suite

/plx:create/anything - Transform desires into artifacts
/plx:create/issue - Systematic issue documentation
/plx:create/story - User stories with criteria
/plx:create/agent - New AI agents
/plx:create/workflow - Multi-step processes

Transformation Suite

/plx:update/anything - Enhance existing artifacts
/plx:make/anything - Transform content types
/plx:shard/anything - Extract components
/plx:update/issue - Refine existing issues
/plx:make/issue - Convert content to issues

Agent Commands

/act:flutter/developer - Flutter expertise
/act:story/agent - Story creation
/act:code/reviewer - Code analysis

Workflow Commands

/start:feature-workflow - 6-phase feature development
/start:refinement-workflow - 5-layer decomposition
/start:bug-workflow - 4-phase bug resolution

🏗️ Architecture

Directory Structure

pew-pew-plx/
├── agents/          # Specialized AI agents organized by category
│   ├── claude/      # Claude Code specialists
│   ├── dev/         # Development experts
│   ├── discovery/   # Research specialists
│   ├── meta/        # Meta-framework agents
│   ├── plan/        # Planning and orchestration
│   └── review/      # Quality assurance agents
├── prompts/         # Quick-action commands
│   ├── create.md
│   ├── update.md
│   ├── make-anything.md
│   ├── shard-anything.md
│   └── 90+ specialized prompts
├── templates/       # Document templates
│   ├── outputs/     # Complete templates (30+ files)
│   └── blocks/      # Reusable sections (80+ blocks)
├── workflows/       # Multi-step processes
│   ├── bug-workflow.md
│   ├── feature-workflow.md
│   ├── refinement-workflow.md
│   └── feedback-triage-workflow.md
├── instructions/    # Conventions and rules
│   ├── best-practices/
│   ├── conventions/
│   └── rules/
├── modes/           # Behavioral modifications
│   └── question-mode.md
├── context/         # Project knowledge (not synced)
│   ├── collections/ # Reference collections
│   ├── docs/        # Documentation
│   ├── platforms/   # Platform contexts
│   ├── roles/       # Role definitions
│   └── teams/       # Team structures
├── issues/          # Issue management (not synced)
│   ├── configuration/
│   ├── tech/
│   └── workflows/
├── output-formats/  # Response format specifications
├── drafts/          # Work in progress (not synced)
├── feedback/        # Framework feedback (not synced)
└── scripts/         # Sync and utility scripts
    └── claude-code/ # Claude Code sync scripts

Sync Transformation

graph TD
    subgraph "Root Source"
        A1[agents/]
        P1[prompts/]
        T1[templates/]
        I1[instructions/]
        W1[workflows/]
        M1[modes/]
    end
    
    subgraph "plx sync claude"
        SYNC[Sync Process<br/>WikiLink Resolution<br/>Content Distribution]
    end
    
    subgraph ".claude/ Destination"
        A2[.claude/agents/<br/>+<br/>.claude/commands/act/]
        P2[.claude/commands/plx/]
        T2[.claude/commands/use/]
        I2[.claude/commands/apply/]
        W2[.claude/commands/start/]
        M2[.claude/commands/activate/]
    end
    
    A1 --> SYNC
    P1 --> SYNC
    T1 --> SYNC
    I1 --> SYNC
    W1 --> SYNC
    M1 --> SYNC
    
    SYNC --> A2
    SYNC --> P2
    SYNC --> T2
    SYNC --> I2
    SYNC --> W2
    SYNC --> M2
    
    style SYNC fill:#b8860b,stroke:#fff,stroke-width:3px,color:#fff
    style A1 fill:#4a5568,stroke:#fff,color:#fff
    style P1 fill:#4a5568,stroke:#fff,color:#fff
    style T1 fill:#4a5568,stroke:#fff,color:#fff
    style I1 fill:#4a5568,stroke:#fff,color:#fff
    style W1 fill:#4a5568,stroke:#fff,color:#fff
    style M1 fill:#4a5568,stroke:#fff,color:#fff
    style A2 fill:#2e7d32,stroke:#fff,color:#fff
    style P2 fill:#2e7d32,stroke:#fff,color:#fff
    style T2 fill:#2e7d32,stroke:#fff,color:#fff
    style I2 fill:#2e7d32,stroke:#fff,color:#fff
    style W2 fill:#2e7d32,stroke:#fff,color:#fff
    style M2 fill:#2e7d32,stroke:#fff,color:#fff

💡 Key Principles

1. Requirement-Driven Development

Begin with functional requirements rather than artifact types - understand the objective before selecting the implementation.

2. Component Modularity

Define components once and reference them throughout the system via wikilinks for consistency and maintainability.

3. Progressive Enhancement

Evolution path: inline implementation → extracted components → composed agents → universal reusability.

4. Systematic Validation

Apply structured questioning methodology to validate and refine each component and decision.

5. Natural Agent Emergence

When persona, workflow, and instructions align organically around a common purpose, they naturally form a reusable agent.

🚦 Example: Creating an Issue

# Method 1: Direct creation
/plx:create/issue

# Method 2: Transform from notes
/plx:make/issue "Turn my meeting notes into an issue"

# Method 3: Update existing
/plx:update/issue "Enhance my draft issue"

# Method 4: From desire
/plx:create/anything "I want to track a new feature"

Each method leverages the same modular components, demonstrating the framework's flexibility.

📚 Documentation

Prompts: See prompts/ for all creation commands (94 files)
Agents: See agents/ for specialized expertise (38 agents across 6 categories)
Templates: See templates/ for structured formats (30 outputs + 80+ blocks)
Workflows: See workflows/ for orchestrated processes (5 workflows)
Instructions: See instructions/ for conventions and rules
Output Formats: See output-formats/ for response specifications
Modes: See modes/ for behavioral modifications
Context: See context/ for project knowledge and references

🤝 Contributing

We welcome contributions! The framework itself follows its own philosophy:

Start with a desire (what do you want to DO?)
Create components following templates
Extract shareable pieces
Test with question-mode refinement
Submit PR with clear documentation

📄 License

MIT License - see LICENSE for details

🔗 Links

Website: pewpewprompts.com
Repository: GitHub
npm Package: pew-pew-plx
Issues: GitHub Issues

Made with ❤️ by the Pew Pew team

⭐ Star us on GitHub if this helps your workflow!

Name		Name	Last commit message	Last commit date
Latest commit History 111 Commits
.github/workflows		.github/workflows
agents		agents
assets		assets
bin		bin
context		context
drafts		drafts
feedback		feedback
instructions		instructions
issues/tech/framework		issues/tech/framework
lib		lib
modes		modes
output-formats		output-formats
prompts		prompts
scripts/claude-code		scripts/claude-code
templates		templates
workflows		workflows
.gitignore		.gitignore
.plxignore		.plxignore
CLAUDE.md		CLAUDE.md
Makefile		Makefile
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

appboypov/pew-pew-plx-old

Folders and files

Latest commit

History

Repository files navigation