npm package: @fermindi/pwn-cli
Description: Professional AI Workspace - Inject structured memory and automation into any project for AI-powered development
Author: Diego Fernandes
Latest version: 0.9.13

# 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

```bash
# 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:

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

```bash
# 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 run            # Run autonomous batch loop
pwn batch run --dry-run  # Preview next story
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
│   │   └── prd.json         # Stories (structured JSON)
│   ├── 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:

```markdown
## 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 stories autonomously via `batch_runner.sh`:

```bash
./.ai/batch/batch_runner.sh              # Run batch loop
./.ai/batch/batch_runner.sh --dry-run    # Preview next story
pwn batch run --phase 3                  # Via CLI
```

Features:
- Reads stories from `.ai/tasks/prd.json`
- Quality gates (lint, test, typecheck) per task
- Retry with error context (up to 2x)
- Circuit breaker (3 consecutive failures)
- Rate limit detection + auto-wait
- Per-task logs in `logs/`

### Codespaces Integration

Work from anywhere (including mobile):

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

```bash
# 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`:

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

### Quality Gates

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

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

## Development

```bash
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](docs/getting-started.md) - Installation, setup, and first steps
- [Commands Reference](docs/commands.md) - Complete CLI command reference
- [Migration Guide](docs/migration.md) - Migrate from CLAUDE.md, memory-bank, Cursor, etc.

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT - see [LICENSE](LICENSE)

---

**Version:** 0.1.0 | **Status:** Production Ready