Plan. Work. Review. Learn. — A disciplined skill-based development framework.
Stop vibing, start shipping. PWRL turns chaotic AI-assisted coding into predictable, high-quality software delivery using composable, reusable skills.
# Install
npm install -g @wicttor/pwrl
# Initialize in your project
pwrl init
# Skills are installed globally at ~/.agents/skills/
# Project config written to .pwrlrc.json
# Use in your AI assistant
/pwrl-plan
/pwrl-work
/pwrl-review
/pwrl-learnings
/pwrl-update-learnings
/pwrl-end-sessionResult: Complete, tested, documented feature with clean commit.
| Vibe Coding 😵💫 | PWRL ✅ |
|---|---|
| Incomplete implementations | Complete features with tests |
| Hidden technical debt | Systematic execution |
| Lost context | Persistent knowledge capture |
| Scope creep | Clear boundaries & plans |
| Skill | Purpose | When to Use |
|---|---|---|
/pwrl-plan |
Create implementation plans | Before non-trivial work |
/pwrl-tasks |
Slice plans into executable tasks | After planning, optional |
/pwrl-work |
Execute with orchestrated phases | Implement features/fixes |
/pwrl-review |
Code quality checks | After work, before merge |
/pwrl-learnings |
Document solutions | After solving problems |
/pwrl-refresh-learnings |
Maintain knowledge | After refactors, quarterly |
/pwrl-update-learnings |
Sync learnings index | After session commit |
/pwrl-end-session |
Clean commits | End of every session |
PWRL orchestrates work through composable skills that run in sequence:
Planning Workflow:
/pwrl-plan orchestrates four micro-skills in sequence:
| Phase | Skill | Purpose |
|---|---|---|
| 1 | pwrl-plan-scope |
Gather context, validate domain |
| 2 | pwrl-plan-research |
Discover patterns, detect high-risk areas |
| 3 | pwrl-plan-design |
Decompose into implementation units |
| 4 | pwrl-plan-generate |
Select tier, render plan, save to docs |
Execution Workflow:
/pwrl-work orchestrates four micro-skills in sequence:
| Phase | Skill | Purpose |
|---|---|---|
| 0 | pwrl-work-triage |
Classify input and extract context |
| 1 | pwrl-work-prepare |
Set up environment, move task to progress |
| 2 | pwrl-work-execute |
Implement with test-first discipline |
| 3 | pwrl-work-review |
Code review, quality gates, move to done |
Review Workflow:
/pwrl-review orchestrates four micro-skills in sequence:
| Phase | Skill | Purpose |
|---|---|---|
| 1 | pwrl-review-scope |
Classify input and scope review |
| 2 | pwrl-review-prepare |
Set up review environment |
| 3 | pwrl-review-analyze |
Execute code review, find issues |
| 4 | pwrl-review-report |
Report verdict (APPROVED/CHANGES/REJECT) |
Learning Capture Workflow:
/pwrl-learnings orchestrates five micro-skills in sequence:
| Phase | Skill | Purpose |
|---|---|---|
| 1 | pwrl-learnings-extract |
Extract patterns from work |
| 2 | pwrl-learnings-classify |
Categorize learning type |
| 3 | pwrl-learnings-dedup |
Check for duplicates |
| 4 | pwrl-learnings-save |
Save to persistent storage |
| 5 | pwrl-learnings-structure |
Update learnings INDEX |
Session Finalization Workflow:
/pwrl-end-session orchestrates two micro-skills in sequence:
| Phase | Skill | Purpose |
|---|---|---|
| 1 | pwrl-end-session-checkpoint |
Save checkpoint state |
| 2 | pwrl-end-session-commit |
Create clean commit with learnings |
How it works:
- Direct invocation:
/pwrl-plan [task]→ Runs all four phases in sequence - Or call skills individually:
/pwrl-plan-scope,/pwrl-plan-research, etc. (for fine-grained control) - Same with
/pwrl-work— runs all four phases or call individual micro-skills
All workflows run inline — No external orchestrators needed.
Skill Execution Flow:
/pwrl-plan
└─ Orchestrates: scope → research → design → generate
Output: docs/plans/YYYY-MM-DD-NNN-<name>.md
/pwrl-work
└─ Orchestrates: triage → prepare → execute → review
Output: Feature branch ready for manual PR creation
/pwrl-review (for explicit review before PR)
└─ Orchestrates: scope → prepare → analyze → report
Output: Verdict (APPROVED/REQUEST CHANGES/REJECTED)
/pwrl-learnings
└─ Orchestrates: extract → classify → dedup → save → structure
Output: docs/learnings/YYYY-MM-DD-<category>-<title>.md
/pwrl-end-session
└─ Orchestrates: checkpoint → commit
Output: Clean commit with learnings captured
Each orchestrator runs a deterministic sequence of micro-skills, with phase-based interactions and status tracking.
Task Status Flow: to-do → in-progress → for-review (awaits PR merge)
Optional: Use /pwrl-tasks to break plans into granular task files with GitHub Issues integration.
After running pwrl init, your project settings are stored in .pwrlrc.json:
- Skills location: PWRL skills are always installed globally at
~/.agents/skills/. Runpwrl initin any project to ensure the latest skills are available. - GitHub Issues integration: Enable automatic task tracking with GitHub Issues
You can re-run pwrl init to refresh skills or reconfigure.
- INSTALLATION.md — Setup for GitHub Copilot, Claude, Cursor, Gemini, Pi Agent
- QUICKSTART.md — Example workflows and common tasks
- GUIDE.md — Best practices, anti-patterns, philosophy
- CONTRIBUTING.md — How to contribute new skills
- pwrl-standards/SCHEMA.md — Canonical standardized format for pwrl-* skills
- pwrl-standards/TEMPLATE.md — Unified skill template with examples
- pwrl-standards/AUDIT.md — Standardization audit and migration analysis
# 1. Plan
/pwrl-plan Add JWT authentication with refresh tokens
# 2. Work - Execute with orchestrated phases
/pwrl-work
# Automatically runs: triage → prepare → execute → review
# 3. Document and commit
/pwrl-learnings
/pwrl-end-session# 1. Plan
/pwrl-plan Add JWT authentication with refresh tokens
# Creates docs/plans/2026-05-04-jwt-auth.md with:
# - Technical decisions (JWT vs sessions, with rationale)
# - Implementation units (U1: models, U2: middleware, U3: endpoints)
# - Test scenarios (happy path + edge cases)
# - Risk analysis
# 2. Create Tasks (Optional)
/pwrl-tasks docs/plans/2026-05-04-jwt-auth.md
# Creates granular task files in docs/tasks/to-do/:
# - 2026-05-04-u1-add-user-model.md
# - 2026-05-04-u2-auth-middleware.md
# - 2026-05-04-u3-auth-endpoints.md
# If GitHub integration enabled: creates issues for each task
# 3. Work on First Task
/pwrl-work docs/tasks/to-do/2026-05-04-u1-add-user-model.md
# Executes orchestrated workflow (choose interaction mode: Detailed or Yolo):
# - Triage: Classify task context, select interaction mode
# - Prepare: Set up environment, move task to in-progress/
# - Execute: Implement with tests, move task to for-review/
# - Review: Simplify and consolidate changes
# Task now in for-review/ awaiting explicit /pwrl-review verdict
# 4. Review and Approve Tasks
/pwrl-review
# Reviews code quality, finds issues, returns verdict:
# - APPROVED: Task approved, ready for PR
# - REQUEST CHANGES: Task needs revision, moved back to in-progress/
# - REJECTED: Task rejected, kept in for-review/
# 5. Continue with Remaining Tasks
/pwrl-work docs/tasks/to-do/2026-05-04-u2-auth-middleware.md
/pwrl-work docs/tasks/to-do/2026-05-04-u3-auth-endpoints.md
# Repeat workflow for each unit
# 6. Create Pull Request
# When all tasks are approved:
git push origin feature-branch
# Open PR via GitHub or `gh pr create`
# 7. Learn & Commit
/pwrl-learnings
# Documents in docs/learnings/:
# - JWT token refresh pattern learned
# - Auth middleware gotcha avoided
# - Test strategy for async auth flows
/pwrl-end-session
# Creates clean commit with learnings capturedTime saved vs vibe coding: ~50% Quality improvement: Measurable
# Global (recommended)
npm install -g @wicttor/pwrl
pwrl initSee INSTALLATION.md for platform-specific setup.
pwrl init # Initialize PWRL in project
pwrl info # Show skill locations
pwrl docs # Show documentation paths
pwrl help # Show CLI help
pwrl version # Show versionNote: Skills are invoked through your AI assistant (/pwrl-plan, etc.), not via CLI.
Works with any AI assistant that supports custom instructions or skills:
- ✅ GitHub Copilot (VS Code)
- ✅ Claude (Desktop/Web/Projects)
- ✅ Cursor
- ✅ Gemini (Google AI Studio)
- ✅ Pi Agent
- ✅ Custom setups
After initialization:
Note: PWRL skills are installed globally at
~/.agents/skills/, not in your project directory.
your-project/
docs/
plans/ # Implementation plans
2026-05-04-auth.md
tasks/ # Task files (if using task-based workflow)
INDEX.md # Task overview and dependencies
to-do/ # Ready to implement
in-progress/ # Currently being worked
for-review/ # Awaiting code review
done/ # Approved by /pwrl-review, ready for PR
learnings/ # Knowledge base
technical-fix/
pattern/
workflow/
gotcha/
concept/
decision/
.pwrlrc.json # PWRL configuration
- Plan First — Explore approaches before coding
- Document Fresh — Capture solutions while context is hot
- Ship Complete — Tests, edge cases, quality gates
- Agent-Agnostic — Skills work across any AI framework (LangChain, AutoGen, etc.)
Read GUIDE.md for the full philosophy and best practices.
PWRL skills follow a standardized format:
- Concise main files (100-150 lines) for scannability
- Support files in
references/,assets/,examples/for detailed content - Agent-agnostic language for cross-framework compatibility
- Consistent tone (imperative mood, active voice) for clear execution
See pwrl-standards/SCHEMA.md for the complete specification.
We welcome contributions! See CONTRIBUTING.md for:
- Creating new skills
- Improving workflows
- Documentation
- Examples
MIT
PWRL — Because shipping quality code with AI should be systematic, not chaotic.