PWN - Professional AI Workspace

Inject structured memory and automation into any project for AI-powered development.

PWN gives AI agents like Claude Code persistent memory, auto-applied patterns, and batch execution capabilities.

Quick Start

# Install globally
npm install -g @fermindi/pwn-cli

# Inject into your project
cd your-project
pwn inject

# Check status
pwn status

# Add Codespaces support (optional)
pwn codespaces init

Or use directly with npx:

cd your-project
npx @fermindi/pwn-cli inject

What PWN Does

| Without PWN | With PWN | |-------------|----------| | AI forgets decisions between sessions | Decisions persist in .ai/memory/ | | Repeats failed approaches | Dead-ends documented and avoided | | No project-specific patterns | Auto-applies patterns by context | | Manual task tracking | Structured task management | | No learning consolidation | Knowledge promotes to patterns |

Commands

# Core
pwn inject              # Inject .ai/ workspace
pwn migrate             # Migrate existing AI files (CLAUDE.md, memory-bank/, etc.)
pwn status              # Show workspace status
pwn validate            # Validate structure

# Notifications
pwn notify test         # Test notification channels
pwn notify send "msg"   # Send notification

# Batch Execution
pwn batch               # Execute next task
pwn batch --count 5     # Execute 5 tasks
pwn batch status        # Show progress

# Patterns
pwn patterns list       # List all patterns
pwn patterns eval file  # Check triggers for file
pwn patterns search q   # Search patterns

# Knowledge Lifecycle
pwn knowledge status    # Show knowledge stats
pwn knowledge sync      # Sync with markdown
pwn knowledge gc        # Garbage collection
pwn knowledge promote   # Promote to pattern

# Codespaces
pwn codespaces init     # Add devcontainer
pwn codespaces status   # Check config
pwn codespaces open     # Open in Codespace

Project Structure After Injection

your-project/
├── .ai/
│   ├── state.json           # Session state (git-ignored)
│   ├── memory/
│   │   ├── decisions.md     # Architectural decisions (DEC-XXX)
│   │   ├── patterns.md      # Learned patterns
│   │   └── deadends.md      # Failed approaches (DE-XXX)
│   ├── tasks/
│   │   ├── active.md        # Current work
│   │   └── backlog.md       # Future work
│   ├── patterns/
│   │   ├── index.md         # Trigger mappings
│   │   ├── frontend/        # React, Vue, etc.
│   │   ├── backend/         # Express, FastAPI, etc.
│   │   └── universal/       # Testing, TypeScript, etc.
│   ├── workflows/
│   │   └── batch-task.md    # Batch execution guide
│   ├── agents/
│   │   └── claude.md        # Claude Code bootstrap (600+ lines)
│   └── config/              # Local config (git-ignored)
└── ... your project files

Features

Memory System

Document decisions that AI agents will remember:

## DEC-001: Use TypeScript Strict Mode
**Date:** 2026-01-22
**Status:** Active
**Context:** Need better type safety
**Decision:** Enable strict mode in tsconfig
**Rationale:** Catches bugs at compile time

Pattern Auto-Apply

Triggers automatically load relevant patterns:

*.tsx           → frontend/react/
*.test.ts       → universal/testing/
routes/*.ts     → backend/express/
prisma/schema   → backend/prisma/

Knowledge Lifecycle

Knowledge evolves based on usage:

CREATE → REFERENCE → EVOLVE → PROMOTE/GC
   │         │          │         │
   ▼         ▼          ▼         ▼
decisions  tracking   patterns  cleanup

• Promote: Applied 3+ times in 2+ contexts → becomes pattern
• Archive: No references for 30+ days
• GC: Orphaned with no related code

Batch Execution

Execute tasks autonomously:

pwn batch --count 5 --priority high

Features:

• Quality gates (lint, test, typecheck)
• Checkpoint-based pause/resume
• Auto-commit after each task
• Notifications on completion

Codespaces Integration

Work from anywhere (including mobile):

pwn codespaces init
git push
# Open in GitHub Codespaces

Pre-configured with:

• Node.js 22
• VSCode extensions (ESLint, Prettier, GitLens, Copilot, Claude)
• Bash aliases (p, ps, pb, pk)
• Auto PWN setup

Usage with Claude Code

After pwn inject, Claude Code will:

1. Read .ai/agents/claude.md for bootstrap protocol
2. Load memory (decisions, patterns, dead-ends)
3. Check active tasks
4. Auto-apply patterns based on context
5. Reference decisions in responses

Installation

# npm (global)
npm install -g @fermindi/pwn-cli

# Or run directly with npx
npx @fermindi/pwn-cli inject

Requirements:

• Node.js 18+
• Git (for username detection)

Configuration

Notifications

Edit .ai/config/notifications.json:

{
  "channels": {
    "ntfy": {
      "enabled": true,
      "topic": "pwn-abc123"
    }
  }
}

Quality Gates

Configure in .ai/workflows/batch-task.md:

gates:
  typecheck: true
  lint: true
  test: true
  build: false

Development

git clone https://github.com/diegofornalha/pwn.git
cd pwn
pnpm install
pnpm test
npm link  # For local testing

Roadmap

• [x] Phase 0: Core workspace injection
• [x] Phase 1: Multi-channel notifications
• [x] Phase 2: GitHub Codespaces integration
• [x] Phase 3: Autonomous batch execution
• [x] Phase 4: Advanced pattern system
• [x] Phase 5: Knowledge lifecycle
• [x] Phase 6: npm publish
• [ ] pwn create - Scaffold new projects
• [ ] pwn upgrade - Update existing workspaces
• [ ] Docker support

Documentation

• Getting Started - Installation, setup, and first steps
• Commands Reference - Complete CLI command reference
• Migration Guide - Migrate from CLAUDE.md, memory-bank, Cursor, etc.

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

MIT - see LICENSE

Version: 0.1.0 | Status: Production Ready