claude-code-context-workspace

Name: claude-code-context-workspace
Availability: InStock
Author: Brian, with AI

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.

GitHub Website Docs

GitHub Stars

User Rating

Not Rated

Favorites

Views

Forks

Issues

README

⚡ Pew Pew Workspace 🏗️

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.

🚀 Quick Start

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

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

This wi
ll:

Download all framework components into .pew/ subdirectories
Preserve your existing project files
Add the .claude/ directory with all synced artifacts
Enable all /plx: commands in your project

After Installation: Sync Anytime

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

make -f .pew/Makefile sync claude

Or directly:

./.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.

graph TD
    EG[🎯 End Goal<br/>Achievement 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 (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:

Read existing docs to avoid duplication
Determine the type (convention | best‑practice | rule | tool‑instructions)
Rename file to match suffix exactly
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.

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

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<br/>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

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

🔗 WikiLink Architecture: Component Reusability

The framework leverages a sophisticated component referencing system:

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<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-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

# 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

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

# 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

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<br/>WikiLink Resolution<br/>Content Distribution<br/>YAML-Configured Paths]
    end
    
    subgraph ".claude/ Destination"
        A2[.claude/agents/<br/>+<br/>.claude/commands/act/]
        P2[.claude/commands/ (single-verb)<br/>+<br/>.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:

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

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

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

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/<br/>team-backend]
    L --> K
    K --> M[Create MVS files]
    M --> N[ESS-001-flutter-setup-story.md<br/>ESS-002-configure-db-plan.md<br/>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

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 file for details.

Author Information

Brian, with AI

Anything Is Promptable 💬 Freelance App Developer 📲 Entrepenerd

De App SpecialistThe Netherlands

GitHub

Followers

Repositories

Gists

Total Contributions