pew-pew-plaza-packs

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #go #golang #machine-learning #linux #docker #windows #cli #vue #awesome-list #mcp #ios

pew-pew-plaza-packs

(★ 85)

AI-powered project management framework based on an opinionated view on effective prompts and a highly modular approach to building effective agents, workflows, templates, prompts and context documents.

File Explorer

Download Latest Version (.zip)

- hero.png
- - bug-fix-planner-agent.md
  - bug-reporter-agent.md
  - bug-triage-agent.md
  - bug-verifier-agent.md
  - bug-workflow-orchestrator.md
  - claude-code-command-agent.md
  - claude-code-hook-architect.md
  - claude-code-mcp-specialist.md
  - code-reviewer.md
  - content-drafter.md
  - discovery-agent.md
  - feature-workflow-orchestrator.md
  - flutter-developer.md
  - flutter-template-refiner.md
  - git-expert.md
  - implementation-agent.md
  - lead-developer.md
  - maestro-test-expert.md
  - makefile-expert.md
  - meta-context-expert.md
  - meta-feature-agent.md
  - meta-instructions-expert.md
  - meta-issue-agent.md
  - meta-prompt-engineer.md
  - meta-sub-agent-architect.md
  - meta-template-expert.md
  - meta-workflow-specialist.md
  - refinement-agent.md
  - requirements-agent.md
  - roadmap-agent.md
  - story-agent.md
  - ultra-meta-agent.md
  - unit-test-engineer.md
- - advise.md
  - clarify.md
  - commit.md
  - contextualize.md
  - create.md
  - delete.md
  - expand.md
  - help.md
  - improve.md
  - make.md
  - pew.md
  - push.md
  - read.md
  - reduce.md
  - refine.md
  - shard.md
  - simplify.md
  - update.md
- - claude-code-sub-agents-reference.md
  - folder-structure-reference.md
  - maestro-commands-reference.md
- install.sh
- Makefile
- plx.yaml
- - .repo_ignore
  - README.md
- - brainstorm-agent.md
  - idea-agent.md
  - prompt-engineer-agent.md
  - proposal-agent.md
  - research-agent.md
- - brainstorm-template.md
  - idea-template.md
  - proposal-template.md
  - research-template.md
- discovery-agent.md
- - bad-examples-agent.md
  - best-practices-agent.md
  - collection-agent.md
  - good-examples-agent.md
  - personal-preferences-agent.md
  - prompt-engineer-agent.md
  - proposal-agent.md
  - suggested-approach-agent.md
- - plx-create-flutter-code-context-docs.md
- - bad-examples-template.md
  - best-practices-template.md
  - collection-template.md
  - good-examples-template.md
  - personal-preferences-template.md
  - proposal-template.md
  - suggested-approach-template.md
- context-agent.md
- - activities-agent.md
  - actors-components-agent.md
  - behaviours-agent.md
  - prompt-engineer-agent.md
  - properties-agent.md
  - proposal-agent.md
  - scenarios-agent.md
- - proposal-template.md
  - requirements-template.md
- requirements-agent.md
- - architecture-agent.md
  - prd-agent.md
  - prompt-engineer-agent.md
  - proposal-agent.md
  - ui-ux-design-agent.md
- - architecture-template.md
  - prd-template.md
  - proposal-template.md
- refinement-agent.md
- - dev-plan-agent.md
  - epic-agent.md
  - prompt-engineer-agent.md
  - proposal-agent.md
  - roadmap-agent.md
  - story-agent.md
  - task-agent.md
- - dev-plan-template.md
  - epic-template.md
  - proposal-template.md
  - roadmap-template.md
  - story-template.md
  - task-template.md
- plan-agent.md
- - acceptance-test-agent.md
  - lead-developer-agent.md
  - prompt-engineer-agent.md
  - proposal-agent.md
  - result-report-agent.md
  - ui-ux-implementation-agent.md
  - unit-test-agent.md
- - proposal-template.md
  - work-log-template.md
- act-agent.md
- - acceptance-criteria-agent.md
  - code-review-agent.md
  - feedback-agent.md
  - prompt-engineer-agent.md
  - proposal-agent.md
  - quality-standards-agent.md
  - restrictions-agent.md
  - rules-agent.md
  - ui-ux-review-agent.md
- - acceptance-criteria-template.md
  - feedback-template.md
  - proposal-template.md
  - quality-standards-template.md
  - restrictions-template.md
  - rules-template.md
- review-agent.md
- 01-all-discovery-team.md
- 02-all-context-team.md
- 03-all-requirements-team.md
- 04-all-refinement-team.md
- 05-all-plan-team.md
- 06-all-act-team.md
- 07-all-review-team.md
- 100-all-teams.md
- - claude-code-command-agent.md
  - claude-code-hook-architect.md
  - claude-code-mcp-specialist.md
- - flutter-developer.md
  - flutter-template-refiner.md
  - git-expert.md
  - lead-developer.md
- - makefile-expert.md
  - meta-context-expert.md
  - meta-feature-agent.md
  - meta-instructions-expert.md
  - meta-issue-agent.md
  - meta-prompt-engineer.md
  - meta-sub-agent-architect.md
  - meta-template-expert.md
  - meta-workflow-specialist.md
  - ultra-meta-agent.md
- - discovery-agent.md
  - feature-workflow-orchestrator.md
  - implementation-agent.md
  - refinement-agent.md
  - requirements-agent.md
  - roadmap-agent.md
  - story-agent.md
- - bug-fix-planner-agent.md
  - bug-reporter-agent.md
  - bug-triage-agent.md
  - bug-verifier-agent.md
  - bug-workflow-orchestrator.md
  - code-reviewer.md
  - content-drafter.md
  - maestro-test-expert.md
  - unit-test-engineer.md
- abilities-block.md
- acceptance-criteria-block.md
- access-config-block.md
- activities-block.md
- activity-flows-block.md
- actors-components-block.md
- agent-command-block.md
- ai-agent-context-block.md
- analytics-block.md
- anti-patterns-block.md
- api-block.md
- architecture-diagram-block.md
- background-block.md
- bad-examples-block.md
- behaviours-block.md
- best-practices-block.md
- block-command-block.md
- business-value-block.md
- capabilities-block.md
- component-analysis-block.md
- component-breakdown-block.md
- component-diagram-block.md
- constraints-block.md
- data-flow-block.md
- data-models-block.md
- deliverables-block.md
- dependencies-block.md
- detailed-action-plan-block.md
- devils-advocate-block.md
- domain-block.md
- effort-breakdown-block.md
- end-goal-block.md
- event-flow-block.md
- experience-block.md
- expertise-block.md
- final-remarks-block.md
- firebase-security-rules-block.md
- frustrations-block.md
- function-block.md
- goals-block.md
- good-examples-block.md
- high-level-crud-block.md
- high-level-requirements-block.md
- impact-communication-block.md
- initial-request-block.md
- initial-requirement-block.md
- inputs-block.md
- instruction-command-block.md
- interests-block.md
- isolation-block.md
- knowledge-block.md
- main-goal-block.md
- milestone-block.md
- milestone-timeline-block.md
- mockless-tests-block.md
- mode-command-block.md
- non-functional-requirements-block.md
- open-questions-block.md
- orchestrator-block.md
- output-format-command-block.md
- outputs-block.md
- persona-command-block.md
- persona-responsibilities-block.md
- persona-role-block.md
- persona-skills-block.md
- personal-preferences-block.md
- preferences-block.md
- prerequisites-block.md
- project-conventions-block.md
- prompt-command-block.md
- properties-block.md
- proposed-solution-block.md
- purpose-block.md
- quality-standards-block.md
- reasoning-block.md
- refinement-block.md
- relevant-context-block.md
- request-block.md
- responsibilities-block.md
- roles-todos-block.md
- rules-block.md
- scenario-block.md
- scenarios-block.md
- scope-block.md
- scope-check-block.md
- stakeholders-block.md
- steps-block.md
- story-timeline-block.md
- suggested-approach-block.md
- supabase-rls-block.md
- target-audience-block.md
- tech-usage-block.md
- template-command-block.md
- test-focus.md
- title-block.md
- ui-ux-behaviour-block.md
- understanding-block.md
- user-story-block.md
- workflow-acceptance-criteria-block.md
- workflow-command-block.md
- workflow-deliverables-block.md
- all-instruction-types.md
- all-pew-pew-workspace-conventions.md
- a-good-prompt.md
- context-rot-awareness.md
- feedback-strategies.md
- meta-concepts.md
- mvp-mindset.md
- pew-pew-philosphy.md
- prompt-modularity.md
- scope-integrity.md
- target-audience.md
- feedback-prompts-pew-20250117.md
- meta-entity-overhaul-prompt.md
- - agent-best-practices.md
  - maestro-flutter-best-practices.md
  - maestro-mcp-tools-best-practices.md
  - maestro-selectors-best-practices.md
  - make-file-best-practices.md
  - prompt-best-practices.md
- - agent-conventions.md
  - git-conventions.md
  - mvpm-issue-conventions.md
  - prompt-conventions.md
- - agent-rules.md
  - maestro-testing-rules.md
  - prompt-rules.md
  - template-rules.md
  - wikilink-rules.md
- confirmation-mode.md
- question-mode.md
- refinement-mode.md
- git-output-format.md
- add-mcp.md
- advise.md
- ask-help.md
- ask-more-questions.md
- ask-question.md
- brainstorm-requirements.md
- checkout-branch.md
- clarify.md
- commit.md
- contextualize.md
- convert-feature.md
- create-activity.md
- create-actor.md
- create-agent-plan.md
- create-agent.md
- create-branch.md
- create-bug-report.md
- create-cmu-prompts.md
- create-discovery.md
- create-feature.md
- create-finance-issue.md
- create-github-release.md
- create-implementation-plan.md
- create-issue.md
- create-maestro-test.md
- create-marketing-issue.md
- create-milestone.md
- create-operations-issue.md
- create-people-issue.md
- create-pr.md
- create-project-developer.md
- create-project-instructions.md
- create-prompt.md
- create-promptorial.md
- create-questions-document.md
- create-refinement.md
- create-report.md
- create-requirements.md
- create-roadmap.md
- create-sales-issue.md
- create-story.md
- create-template.md
- create-test.md
- create-tutorial.md
- create-workflow-step.md
- create-workflow.md
- create.md
- delete-claude-code-history.md
- delete.md
- expand.md
- fix-bug-tdd.md
- give-feedback.md
- help.md
- improve.md
- maestro-flutter-test-expert-complete.md
- maestro-flutter-test-expert.md
- make-agent.md
- make-finance-issue.md
- make-issue.md
- make-marketing-issue.md
- make-mvp-focused.md
- make-operations-issue.md
- make-people-issue.md
- make-prompt.md
- make-sales-issue.md
- make-sure.md
- make.md
- open-in-android-studio.md
- open-in-browser.md
- open-in-cursor.md
- open-in-finder.md
- open-in-fork.md
- open-in-github.md
- open-in-intellij.md
- open-in-terminal.md
- open-in-vs-code.md
- open-in-warp.md
- open-in-xcode.md
- pew.md
- plan-bug-fix.md
- plx-pull-sync-claude-clean.md
- process-answers.md
- process-feedback.md
- pull-sync-claude.md
- push.md
- read.md
- reduce.md
- refine-feature.md
- refine.md
- research-project.md
- review-code.md
- run-in-parallel.md
- run-test.md
- shard-task-complex.md
- shard-task-simple.md
- shard.md
- simplify.md
- suggest-content.md
- sync-claude.md
- sync-to-ppw.md
- triage-bug-report.md
- update-agent.md
- update-bug-report.md
- update-discovery.md
- update-everywhere.md
- update-feature.md
- update-finance-issue.md
- update-implementation-plan.md
- update-issue.md
- update-maestro-docs.md
- update-maestro-test.md
- update-makefile.md
- update-marketing-issue.md
- update-milestone.md
- update-operations-issue.md
- update-people-issue.md
- update-plx-clean.md
- update-plx.md
- update-pr.md
- update-prompt.md
- update-readme.md
- update-refinement.md
- update-requirements.md
- update-roadmap.md
- update-sales-issue.md
- update-story.md
- update-template.md
- update-workflow.md
- update.md
- verify-bug-fix.md
- claude-code-sub-agents-reference.md
- folder-structure-reference.md
- gpt-5-prompting-guide-reference.md
- maestro-commands-reference.md
- - agent-persona-template.md
  - agent-template.md
- - finance-issue-template.md
  - marketing-issue-template.md
  - operations-issue-template.md
  - people-issue-template.md
  - sales-issue-template.md
- - ghost-author-template.md
  - ghost-post-template.md
  - ghost-tag-template.md
  - ghost-tutorial-template.md
- - activity-template.md
  - actor-template.md
  - block-template.md
  - channel-template.md
  - collection-template.md
  - communication.md
  - component-template.md
  - concept-template.md
  - content-format-template.md
  - content-strategy-template.md
  - decision-template.md
  - entity-template.md
  - feature-template.md
  - meeting-template.md
  - persona-template.md
  - platform-template.md
  - project-template.md
  - prompt-template.md
  - role-template.md
  - target-audience-template.md
  - team-template.md
  - workflow-template.md
- - agent-plan-template.md
  - bug-report-template.md
  - discovery-template.md
  - epic-milestone-template.md
  - implementation-plan-template.md
  - issue-template.md
  - proposal-template.md
  - refinement-template.md
  - requirements-template.md
  - roadmap-template.md
  - story-template.md
  - task-template.md
- - feedback-report-template.md
  - feedback-template.md
  - github-issues-analysis-template.md
  - pull-request-template.md
  - research-report-template.md
  - work-log-template.md
- agent-workflow.md
- bug-workflow.md
- feature-workflow.md
- feedback-triage-workflow.md
- github-issues-analysis-workflow.md
- issue-workflow.md
- milestone-planning-workflow.md
- prompt-workflow.md
- refinement-workflow.md
.gitignore
.plxignore
CHANGELOG.md
CLAUDE.md
CONTRIBUTING.md
lead-orchestrator-agent.md
LICENSE
README.md
RELEASE-v0.5.0.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ⚡ Pew Pew Workspace 🏗️

[![Version](https://img.shields.io/badge/Version-v0.8.0-green)](https://github.com/pew-pew-prompts/pew-pew-workspace/releases/tag/v0.8.0)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Brought to you by pewpewprompts.com](https://img.shields.io/badge/Brought%20to%20you%20by-pewpewprompts.com-blue)](https://pewpewprompts.com)

> AI-powered project management framework based on an opinionated view on effective prompts and a highly modular approach to building effective agents, workflows, templates, prompts and context documents.

![Pew Pew Plx Hero](https://raw.githubusercontent.com/appboypov/pew-pew-plaza-packs/main/.assets/hero.png)

## 🚀 Quick Start

Add the latest files of the Pew Pew framework to any existing project with a single command:

```bash
curl -fsSL https://raw.githubusercontent.com/pew-pew-prompts/pew-pew-workspace/main/.pew/install.sh | bash
```

This wi
ll:
1. Download all framework components into `.pew/` subdirectories
2. Preserve your existing project files
3. Add the `.claude/` directory with all synced artifacts
4. Enable all `/plx:` commands in your project

### After Installation: Sync Anytime

Once installed, sync all docs from your project root with:

```bash
make -f .pew/Makefile sync claude
```

Or directly:
```bash
./.pew/scripts/claude-code/sync-claude-code.sh
```

### Configuration (.pew/plx.yaml)

The sync process uses `.pew/plx.yaml` as the main configuration:
- **`.pew/plx.yaml`**: Main configuration file (committed, uses `.pew/` subdirectories)
- **`.pew/plx.local.yaml`**: Optional local override (never committed, for personal customizations)

Customize sync behavior in `.pew/plx.yaml`:
- **sync_sources**: Which directories to sync from
- **sync_targets**: Where to sync files to
- **delete_before_sync_targets**: Directories to clean before syncing
- **delete_after_sync_targets**: Directories to clean after syncing

**Local Override:** Create `.pew/plx.local.yaml` to override settings without modifying the main config. This file is gitignored and perfect for personal customizations.

## ✨ What's New in v0.8.0

### 🚀 Raycast Power Prompter Framework
- **Comprehensive Freelancer Toolkit**: New `00-freelancers/raycast-power-prompter/` directory with:
  - 20+ reusable blocks for requirements, analytics, components, user stories
  - Extensive Flutter development instructions (concepts, patterns, best practices)
  - Universal refinement prompts with strategic questioning methodology
  - Export/import system for Raycast snippet management
  - Templates for events, meetings, milestones, and development plans

### 🛠️ Enhanced Template System
- **Integrated Agent Instructions**: Plan templates now include comprehensive agent instructions
- **Universal Refinement Mode**: Systematically refine ANY template through strategic questioning
- **File Reference Conventions**: Proper `@[relative/path]` format for file references

### ✨ New Features & Improvements
- **Pew Prompt**: Ultimate starting point for any task in any project
- **GitHub Release Workflow**: Comprehensive documentation validation and release creation
- **Activity System**: Reusable actions organized by concept categories
- **Scope Integrity**: Prevents AI over-engineering by ensuring exact requirement delivery

### 🔧 Architecture Enhancements
- **Collections System**: Curated lists for Flutter concepts and instructions
- **Single-Verb Prompt Routing**: YAML configuration for separate routing patterns
- **Dynamic Project Key Detection**: Automatic detection from commit history

## 📝 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.

```mermaid
graph TD
 EG[🎯 End Goal Achievement Objective]
 
 P[👤 Persona Optional Expertise]
 R[📋 Request Verb-First Activity]
 W[🔄 Workflow Optional Steps]
 I[📏 Instructions Optional Rules]
 O[📊 Output Format 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** (Prompts) / **Main Goal** (Agents & Workflows)
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.

- **Prompts** define **End Goal**: Achievement-focused objective
- **Agents** define **Main Goal**: Behavioral-focused objective  
- **Workflows** define **Main Goal**: Process-focused objective

**Required subsections:**
- **Deliverables**: What must be produced or accomplished
- **Acceptance Criteria**: How to verify the goal has been achieved

Every section and component must align with and contribute to these goals to ensure clear, measurable success.

#### 👤 **Persona** (Optional)
Specialized expertise attributes included when they enhance outcomes:
- Role, Expertise, Domain, Knowledge
- Experience, Skills, Abilities, Responsibilities
- Interests, Background, Preferences, Perspective
- Communication Style

**Claude Command:** `/act:<persona-name>` - Activate this persona directly
**In Files:** `[[persona-name-wl-example]]` to reference, `![[persona-name-wl-example]]` to embed content

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

#### 🔄 **Workflow** (Optional)
Multi-phase processes with clear deliverables and acceptance criteria. Each workflow must define its main goal, and every phase must specify what it delivers and how to verify success.

**Key Elements:**
- Main Goal with success criteria
- Phases with deliverables and acceptance criteria
- Steps with purpose and instructions
- Quality gates and decision points

**Claude Command:** `/start:<workflow-name>` - Launch this workflow
**In Files:** `[[workflow-name-wl-example]]` to reference, `![[workflow-name-wl-example]]` to embed content

#### 📏 **Instructions** (Optional)
Event‑driven guidance following the pattern: "When {scenario} occurs, then {apply these instructions}".

Instruction categories and naming rules:
- Type → suffix → folder
 - Conventions → `-conventions.md` → `instructions/conventions/`
 - Best practices → `-best-practices.md` → `instructions/best-practices/`
 - Rules (always/never) → `-rules.md` → `instructions/rules/`
 - Tool-specific instructions (e.g., Maestro) → `-instructions.md` → `instructions/<tool>/` (e.g., `instructions/maestro/`)

4‑step rule for any new instruction:
1) Read existing docs to avoid duplication
2) Determine the type (convention | best‑practice | rule | tool‑instructions)
3) Rename file to match suffix exactly
4) Place in the correct folder under `instructions/`

**Claude Command:** `/apply:<instruction-name>` - Apply these instructions
**In Files:** `[[instruction-name-wl-example]]` to reference, `![[instruction-name-wl-example]]` to embed content

#### 📊 **Output Format** (Optional)
Specifications for how deliverables should be structured - templates, format types (JSON, YAML, Markdown), or specific structural requirements.

**Claude Command:** `/output:<format-name>` - Apply this output format
**In Files:** `[[format-name-wl-example]]` to reference, `![[format-name-wl-example]]` to embed content

### The Modular Approach

Each component can and should be extracted and referenced via wikilinks when it can be reused. During sync:
- `[[wikilinks-wl-example]]` are transformed to `@path/to/file.md` for dynamic loading by Claude
- `![[embedded-wikilinks-wl-example]]` are replaced with the actual file content inline

⚠️ **Important:** The `@path/to/file.md` references inside command files auto-load when you use slash commands (e.g., `/use:template-file` will automatically read all `@` references inside that template). However, if you just type `@template-file` directly in chat, Claude only sees the path - no automatic reading occurs.

```mermaid
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-wl-example]]"]
        E2["workflow: [[issue-creation-workflow-wl-example]]"]
        E3["instructions: [[issue-conventions-wl-example]]"]
    end
    
    subgraph "3. Embedding Phase"
        EM1["![[issue-expert-persona-wl-example]]"]
        EM2["![[issue-creation-workflow-wl-example]]"]
        EM3["![[issue-conventions-wl-example]]"]
    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
```

### 🎩 A Good Agent

When certain prompt components naturally align around a common purpose and main goal, they can be composed into agents. Benefits:
- Use as **sub-agents** for specific tasks within larger workflows
- Activate directly via **`/act:<agent-name>`** commands
- **Reusable expertise** across all your prompts and projects

```mermaid
graph TD
 subgraph "Agent Core"
 MG[🎯 Main Goal]
 PR[🎯 Purpose & Role]
 end
 
 subgraph "Prompt Components"
 P1[👤 Persona]
 W1[🔄 Workflow]
 I1[📏 Instructions]
 O1[📊 Output Format]
 end
 
 subgraph "Agent Composition"
 A[🤖 Agent flutter-developer.md]
 end
 
 subgraph "Reusable Everywhere"
 PR1[📝 Prompt 1]
 PR2[📝 Prompt 2]
 PR3[📝 Prompt 3]
 end
 
 MG --> A
 PR --> A
 P1 --> A
 W1 --> A
 I1 --> A
 O1 --> A
 
 A -->|"Embed: ![[flutter-developer-wl-example]]"| PR1
 A -->|"Embed: ![[flutter-developer-wl-example]]"| PR2
 A -->|"Embed: ![[flutter-developer-wl-example]]"| PR3
 
 style MG fill:#663399,stroke:#fff,stroke-width:3px,color:#fff
 style PR fill:#663399,stroke:#fff,stroke-width:3px,color:#fff
 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
Agents reuse the same modular components as prompts, but with behavioral focus:
- **Main Goal** - The behavioral objective with deliverables and acceptance criteria (replaces End Goal)
- **Persona** - Specialized expertise attributes (optional, only if enhances goal)
- **Request** - What the agent does, verb-first specification
- **Workflow** - Multi-step process (optional, only if needed)
- **Instructions** - All guidance including best practices, rules, conventions, references (optional subsections, only what contributes to goal)
- **Output Format** - How the agent delivers results (optional, only if specific format needed)

## 📋 Templates and Blocks

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

### Templates
Complete document structures in `templates/`:
- Issue templates, story templates, epic templates
- Bug reports, pull requests, documentation
- Implementation plans, requirements, roadmaps

**Claude Command:** `/use:<template-name>` - Use this template
**In Files:** `[[template-name-wl-example]]` to reference, `![[template-name-wl-example]]` to embed content

### Blocks
Reusable content sections in `blocks/`:
- **Goal blocks** (main-goal-block with deliverables and acceptance criteria)
- **Workflow blocks** (deliverables, acceptance criteria, steps)
- **Context blocks** (capabilities, purpose, functions)
- **Instruction blocks** (best practices, rules, standards)
- 40+ specialized blocks for comprehensive documentation

**Claude Command:** `/add:<block-name>` - Insert this block
**In Files:** `[[block-name-wl-example]]` to reference, `![[block-name-wl-example]]` to embed content

### Modes
Operational contexts in `modes/`:
- Different working modes for various scenarios
- Context-specific behaviors and rules
- Switchable operational states

**Claude Command:** `/activate:<mode-name>` - Switch to this mode

## 🎨 Core Philosophy: From Monolithic to Modular

**Evolution Path:** Inline → Extract → Modularize → Reuse

1. **Start Complete** - Solve the problem with everything inline first
2. **Identify Patterns** - Notice what gets repeated across solutions  
3. **Extract Components** - Move patterns to reusable files with wikilinks
4. **Systematic Refinement** - Simplify, Clarify, Improve, Expand, Reduce

## 🔗 WikiLink Architecture: Component Reusability

The framework leverages a sophisticated component referencing system:

```mermaid
graph LR
 subgraph "Development Time"
 D1["Write: [[component-wl-example]]"]
 D2["Write: ![[component-wl-example]]"]
 end
 
 subgraph "Sync Process"
 S1[plx sync]
 S2[WikiLink Resolution]
 S3[Content Embedding]
 end
 
 subgraph "Runtime"
 R1["@path/to/component.md Dynamic Loading"]
 R2["Actual Content 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
```markdown
# In your artifact:
Follow [[project-conventions-wl-example]] and use [[story-template-wl-example]]

# 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
```markdown
# Reference mode (loads on activation):
Use the workflow in [[issue-workflow-wl-example]]

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

# Note: Embedded wikilinks must occupy their own line
```

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

## 🎮 Commands & Usage

### Core Setup & Sync
```bash
# The sync process uses plx.yaml configuration for all paths
./.pew/scripts/claude-code/sync-claude-code.sh       # Sync to Claude Code
./.pew/scripts/claude-code/test-sync.sh              # Test sync in isolated environment
./.pew/scripts/claude-code/watch-claude-code.sh      # Auto-sync during development
# OR using make from root:
make -f .pew/Makefile sync claude                    # Sync to Claude Code
make -f .pew/Makefile watch claude                   # Auto-sync during development

# Pull latest framework updates and sync:
make -f .pew/Makefile pull main                      # Pull latest framework updates
make -f .pew/Makefile sync claude                    # Then sync with Claude

# YAML configuration controls:
# - Source directories (sync_sources)
# - Target directories (sync_targets)
# - Pre-sync cleanup (delete_before_sync_targets)
# - Post-sync cleanup (delete_after_sync_targets)
```

### Claude Code Commands (After Sync)

| Command Type | Examples | Purpose |
|:------------|:---------|:--------|
| **Single Verb Commands** | `/create`, `/update`, `/commit` | Single-verb prompts for common actions |
| **Creation** | `/plx:create-issue`, `/plx:create-agent` | Generate new artifacts from requirements |
| **Transformation** | `/plx:update-agent`, `/plx:make-issue`, `/plx:shard-task-complex` | Modify and convert existing content |
| **Git & Release** | `/commit`, `/plx:create-github-release` | Handle commits with documentation checks and create releases |
| **Sync & Framework** | `/plx:sync-claude`, `/plx:pull-sync-claude` | Sync with Claude Code, update framework, and clean sync with backup |
| **Agents** | `/act:flutter:developer`, `/act:story:agent` | Activate specialized AI personas |
| **Workflows** | `/start:feature-workflow`, `/start:bug-workflow` | Launch multi-phase processes |
| **Components** | `/add:`, `/output:`, `/apply:`, `/use:` | Insert blocks, formats, instructions, templates |
| **Collections** | `/collect:<collection-name>` | Access curated lists and compilations |
| **Concepts** | `/understand:<concept-name>` | Access core principles and ideas |
| **References** | `/refer:<reference-name>` | Access reference documentation |
| **Modes** | `/activate:<mode-name>` | Switch operational contexts |

### Sync Transformation

```mermaid
graph TD
 subgraph "Root Source"
 A1[agents/]
 P1[prompts/]
 T1[templates/]
 I1[instructions/]
 W1[workflows/]
 M1[modes/]
 B1[blocks/]
 O1[output-formats/]
 PE1[personas/]
 CO1[collections/]
 CN1[concepts/]
 R1[references/]
 end
 
 subgraph "plx.yaml sync"
 SYNC[Sync Process WikiLink Resolution Content Distribution YAML-Configured Paths]
 end
 
 subgraph ".claude/ Destination"
 A2[.claude/agents/ + .claude/commands/act/]
 P2[.claude/commands/ (single-verb) + .claude/commands/plx/ (verb-subject)]
 T2[.claude/commands/use/]
 I2[.claude/commands/apply/]
 W2[.claude/commands/start/]
 M2[.claude/commands/activate/]
 B2[.claude/commands/add/]
 O2[.claude/commands/output/]
 PE2[.claude/commands/act/]
 CO2[.claude/commands/collect/]
 CN2[.claude/commands/understand/]
 R2[.claude/commands/refer/]
 end
 
 A1 --> SYNC
 P1 --> SYNC
 T1 --> SYNC
 I1 --> SYNC
 W1 --> SYNC
 M1 --> SYNC
 B1 --> SYNC
 O1 --> SYNC
 PE1 --> SYNC
 CO1 --> SYNC
 CN1 --> SYNC
 R1 --> SYNC
 
 SYNC --> A2
 SYNC --> P2
 SYNC --> T2
 SYNC --> I2
 SYNC --> W2
 SYNC --> M2
 SYNC --> B2
 SYNC --> O2
 SYNC --> PE2
 SYNC --> CO2
 SYNC --> CN2
 SYNC --> R2
 
 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 B1 fill:#4a5568,stroke:#fff,color:#fff
 style O1 fill:#4a5568,stroke:#fff,color:#fff
 style PE1 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
 style B2 fill:#2e7d32,stroke:#fff,color:#fff
 style O2 fill:#2e7d32,stroke:#fff,color:#fff
 style PE2 fill:#2e7d32,stroke:#fff,color:#fff
```

## 💡 Key Principles

### 1. Goal as North Star
Artifacts define clear, measurable goals:
- **End Goal** (Prompts): Achievement-focused objective
- **Main Goal** (Agents/Workflows): Behavioral/process-focused objective

Each goal requires:
- **Deliverables**: Specific outputs to be produced
- **Acceptance Criteria**: Checkable conditions for success

All sections and components must align with and contribute to achieving these goals. Without clear deliverables and acceptance criteria, success cannot be measured.

### 2. Requirement-Driven Development
Begin with functional requirements rather than artifact types - understand the objective before selecting the implementation.

### 3. Component Modularity
Define components once and reference them throughout the system via wikilinks for consistency and maintainability.

### 4. Progressive Enhancement
Evolution path: inline implementation → extracted components → composed agents → universal reusability.

### 5. Systematic Validation
Apply structured questioning methodology to validate and refine each component and decision.

### 6. Natural Agent Emergence
When persona, workflow, and instructions align organically around a common purpose and main goal (behavioral focus), they naturally form a reusable agent.

## 🔧 Configuration: plx.yaml

The entire sync process is controlled by the `plx.yaml` configuration file:

```yaml
sync_sources:
  agents:
    - agents
  instructions:
    - instructions
  output-formats:
    - output-formats
  personas:
    - personas
  prompts:
    - prompts
  templates:
    - templates
  workflows:
    - workflows
  modes:
    - modes
  blocks:
    - blocks

delete_before_sync_targets:
  - .claude/agents
  - .claude/commands

delete_after_sync_targets: []

sync_targets:
  agents:
    - .claude/agents/
    - .claude/commands/act/
  personas:
    - .claude/commands/act/
  prompts:
    single_verb: .claude/commands/
    verb_subject: .claude/commands/plx/
  templates:
    - .claude/commands/use/
  blocks:
    - .claude/commands/add/
  output-formats:
    - .claude/commands/output/
  instructions:
    - .claude/commands/apply/
  workflows:
    - .claude/commands/start/
  modes:
    - .claude/commands/activate/
```

### Sync Features

- **Automatic Cleanup**: Removes old `.claude/` directories before sync
- **WikiLink Resolution**: Converts `[[references-wl-example]]` to `@path/to/file.md`
- **Content Embedding**: Replaces `![[embeds-wl-example]]` with actual file content
- **Error Handling**: Comprehensive error handling with automatic cleanup
- **Temporary Directory Management**: Auto-removes empty tmp directories after sync

## 🎯 Most Valuable Project Management (MVPM)

**Most Valuable Project Management (MVPM)** is a flexible organizational system that:
- **Prioritizes work** by what delivers the most value first (MVM → MVS)
- **Enables parallel execution** through company concepts that can be worked on simultaneously
- **Scales naturally** from solo developers to enterprise teams
- **Integrates seamlessly** with existing tools (GitHub, Jira, Linear)
- **Provides context** for both humans and AI during development

The core principle: **Start with what's most valuable, structure only what enables parallel work.**

### Core Organization Structure

Flexible structure based on parallel work:
```
{company-concept}/{most-valuable-milestone}/{most-valuable-step}.md
```
Company concepts can be inserted anywhere to enable parallel work.

**Key Principle:** The same issue can have multiple document types with the SAME number:
```
AUTH-042-oauth-integration-story.md    # User story
AUTH-042-oauth-integration-plan.md     # Technical plan  
AUTH-042-oauth-integration-bug.md      # Bug report
AUTH-042-oauth-integration-pr.md       # Pull request
```
This maintains traceability - all work for issue #042 stays connected!

### Structure Flow Diagram

```mermaid
graph TD
    A[company-concept/] --> B[000-backlog/]
    A --> C[001-most-valuable-milestone/]
    C --> D[000-backlog/]
    C --> E[001-most-valuable-step/]
    E --> F[000-backlog/]
    E --> G[CONC-001-description-type.md]
    E --> H[CONC-002-description-type.md]
    E --> I[CONC-003-description-type.md]
    
    style A fill:#37474f,color:#fff
    style B fill:#b71c1c,color:#fff
    style D fill:#b71c1c,color:#fff
    style F fill:#b71c1c,color:#fff
    style G fill:#1565c0,color:#fff
    style H fill:#1565c0,color:#fff
    style I fill:#1565c0,color:#fff
```

### Parallel Work Visualization

```mermaid
graph LR
    A[Company] --> B[Engineering Dept]
    A --> C[Marketing Dept]
    A --> D[Sales Dept]
    
    B --> B1[Infrastructure Concept]
    B --> B2[Authentication Concept]
    C --> C1[Campaigns Concept]
    D --> D1[Leads Concept]
    D --> D2[Infrastructure Concept]
    
    B1 --> B3[001-cloud-migration MVM]
    B2 --> B4[001-user-auth MVM]
    C1 --> C2[001-summer-launch MVM]
    D1 --> D3[001-q4-targets MVM]
    D2 --> D4[001-cloud-migration MVM]
    
    style B fill:#1e3a5f,color:#fff
    style C fill:#4a148c,color:#fff
    style D fill:#1b5e20,color:#fff
    
    style B3 fill:#0d47a1,color:#fff
    style B4 fill:#0d47a1,color:#fff
    style C2 fill:#6a1b9a,color:#fff
    style D3 fill:#2e7d32,color:#fff
    style D4 fill:#2e7d32,color:#fff
```

Note: Departments can work on the same milestone (e.g., Engineering and Sales both working on cloud-migration) or completely different milestones based on their priorities.

### When Overwhelmed: Start with MVS

If it feels overwhelming to define the whole structure, start with the next MVS (Most Valuable Step) to reduce cognitive overload.

### Workflow Decision Tree

```mermaid
flowchart TD
 A[What needs to be done?] --> B[Define MVS: set-up-flutter-app]
 B --> C{What concept?}
 C --> D[essentials]
 D --> E{Which department?}
 E --> F[tech department]
 F --> G{Build hierarchy}
 G --> H[tech/essentials/001-initial-setup/001-set-up-flutter-app]
 H --> I{Teams needed?}
 I -->|Yes| J[Create team folders]
 I -->|No| K[Create MVS files directly]
 J --> L[team-app/ team-backend]
 L --> K
 K --> M[Create MVS files]
 M --> N[ESS-001-flutter-setup-story.md ESS-002-configure-db-plan.md ESS-003-deploy-pipeline-issue.md]
 
 style A fill:#263238,color:#fff
 style B fill:#2e7d32,color:#fff
 style N fill:#1565c0,color:#fff
```

### MVS Evolution Timeline

```mermaid
timeline
    title MVS Evolution Over Time
    
    Day 1 : AUTH-001-create-jwt-story.md
          : Initial story created
    
    Day 3 : AUTH-002-token-validation-issue.md
          : Validation issue identified
    
    Day 5 : AUTH-003-refresh-logic-plan.md
          : Refresh mechanism planned
```

## 📂 File Structure Overview

The repository follows a clear modular structure:

```
pew-pew-workspace/
├── issues/ # MVPM-structured project issues
│ └── {company-concept}/
│ ├── 000-backlog/
│ └── {001-most-valuable-milestone}/
│ ├── 000-backlog/
│ └── {001-most-valuable-step}/
│ ├── 000-backlog/
│ ├── CONC-001-feature-story.md # Same issue #001
│ ├── CONC-001-feature-plan.md # Same issue #001
│ ├── CONC-001-feature-pr.md # Same issue #001
│ └── CONC-002-bugfix-issue.md # Different issue #002
├── agents/ # AI agent definitions
├── prompts/ # Reusable prompts
├── templates/ # Document templates
├── workflows/ # Multi-step processes
├── instructions/ # Rules and conventions
│ ├── conventions/
│ ├── best-practices/
│ ├── rules/
│ └── <tool-specific>/
├── modes/ # Operational modes
├── blocks/ # Reusable content blocks
├── output-formats/ # Output format specifications
├── personas/ # Role definitions
├── collections/ # Curated lists and compilations
├── concepts/ # Core ideas and principles
├── references/ # Reference documentation
├── .pew/ # All framework files and configuration
│ ├── plx.yaml # Sync configuration
│ ├── plx.local.yaml # Optional local override (gitignored)
│ ├── Makefile # Make commands for sync operations
│ ├── install.sh # Installation script
│ ├── scripts/ # Sync and utility scripts
│ │ └── claude-code/
│ │ ├── plx-yaml-parser.sh # YAML configuration parser
│ │ ├── sync-claude-code.sh # Main sync script
│ │ ├── test-sync.sh # Test runner
│ │ └── sync-claude-code-*.sh # Component sync scripts
│ └── [component dirs] # Copies of framework components
├── .claude/ # Synced Claude Code artifacts (auto-generated)
│ ├── agents/
│ └── commands/
│ ├── act/ # Agent & persona commands
│ ├── plx/ # Prompt commands
│ ├── use/ # Template commands
│ ├── add/ # Block commands
│ ├── output/ # Output format commands
│ ├── apply/ # Instruction commands
│ ├── start/ # Workflow commands
│ ├── activate/ # Mode commands
│ ├── collect/ # Collection commands
│ ├── understand/ # Concept commands
│ └── refer/ # Reference commands
├── README.md # This file
│
├── 00-freelancers/ # [Legacy] Individual specialist agents
├── 01-discovery-team/ # [Legacy] Research & ideation team
├── 02-context-team/ # [Legacy] Context gathering team
├── 03-requirements-team/ # [Legacy] Requirements specification team
├── 04-refinement-team/ # [Legacy] PRD & architecture team
├── 05-plan-team/ # [Legacy] Planning & roadmap team
├── 06-act-team/ # [Legacy] Development execution team
├── 07-review-team/ # [Legacy] Quality review team
└── 100-all-teams/ # [Legacy] Single-file team compilations
```

## 🏛️ Legacy Teams Structure

The `00-freelancers/` through `07-review-team/` directories contain the previous 7-phase team model:
- **Discovery → Context → Requirements → Refinement → Plan → Act → Review**
- Being extracted into modular components in the current framework
- Provides proven patterns for comprehensive project lifecycle management

### 00-freelancers/raycast-power-prompter
The freelancers directory now includes the **Raycast Power Prompter** - a comprehensive prompt engineering toolkit:
- **Modular Blocks**: 20+ reusable components for building complex documents
- **Flutter Conventions**: Detailed guides for Flutter development patterns and best practices
- **Workflow Prompts**: Ready-to-use prompts for common development tasks
- **Raycast Integration**: Scriptable system for exporting snippets to Raycast format
- See `00-freelancers/raycast-power-prompter/README.md` for detailed setup instructions

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pew-pew-plaza-packs

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

pew-pew-plaza-packs

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README