@fermindi/pwn-cli 0.5.0 → 0.6.0

package/templates/workspace/.ai/agents/claude.md

@@ -38,9 +38,9 @@ Read these files in order:
    - Ask user before deviating from active decisions
 
 2. **`/.ai/memory/patterns.md`**
-   - Index of patterns documented in `.ai/patterns/`
-   - Check which patterns exist for this project
-   - Add index entry when creating new pattern files
+   - Codebase patterns learned by team
+   - Apply these patterns to new work
+   - Add new patterns when discovered
 
 3. **`/.ai/memory/deadends.md`**
    - Failed approaches documented (DE-XXX)
@@ -71,10 +71,10 @@ If this is your first session:
    - Blocked items and blockers
    - Priority ordering
 
-2. **`/.ai/tasks/backlog.md`** (if needed)
-   - Future work not yet started
+2. **`/.ai/tasks/prd.json`** (if needed)
+   - Future work as structured JSON stories
    - Use when no active work assigned
-   - Pick highest priority unblocked item
+   - Pick next story with dependencies satisfied
 
 3. **Project-specific notes** (if applicable)
    - Check `/CLAUDE.md` in project root
@@ -208,42 +208,6 @@ If any gate fails:
 - Ask user if unsure how to proceed
 - Don't commit until gates pass
 
-### Pattern Checkpoint (Mandatory Before Commit)
-
-Before every commit, review the work done and check if any pattern should be documented.
-
-**Document a pattern when ANY of these criteria are met:**
-
-1. **User corrected your approach** - The user told you to do something differently. Document the correct approach so future sessions don't repeat the mistake.
-2. **You chose between alternatives** - You evaluated 2+ options and picked one. Document what was chosen and why.
-3. **Workaround for limitation** - A library, framework, or tool has a non-obvious limitation. Document the workaround.
-4. **Convention established** - First time implementing a certain type of thing in this codebase (first API route, first test, first component). Document the convention for consistency.
-5. **Repeated approach** - You used the same approach 2+ times in this session. Document it to avoid re-deriving it.
-6. **Non-trivial solution** - The solution wasn't obvious or took investigation to find. Document it so it's immediately available next time.
-
-**If a criterion is met:**
-
-1. Create pattern file: `.ai/patterns/{category}/{pattern-name}.md`
-   ```markdown
-   # Pattern Name
-
-   ## Context
-   When to apply this pattern.
-
-   ## Pattern
-   Description or code example.
-
-   ## Rationale
-   Why this approach works better.
-
-   ## Examples
-   - `src/path/file.ts:42`
-   ```
-2. Add index entry to `.ai/memory/patterns.md`
-3. Commit pattern files together with the code change
-
-**If no criteria are met:** proceed to commit normally. Don't force patterns that aren't there.
-
 ### Commit Message Format
 
 Use conventional commits:
@@ -281,9 +245,15 @@ When completing work:
    - [x] US-042: My completed task (YYYY-MM-DD)
    ```
 
-2. Document patterns following the **Pattern Checkpoint** criteria above
-   - Create file in `.ai/patterns/{category}/{name}.md`
-   - Add index entry in `.ai/memory/patterns.md`
+2. Update `/.ai/memory/patterns.md` if new pattern discovered
+   ```
+   ## New Pattern Category
+
+   ### Pattern Name
+   **Context:** When to use
+   **Pattern:** Description
+   **Rationale:** Why it's better
+   ```
 
 3. Add to `/.ai/memory/deadends.md` if approach failed
    ```
@@ -298,110 +268,41 @@ When completing work:
 
 ## Batch Mode
 
-When `session_mode` is "batch" (autonomous task execution):
+Autonomous task execution via `.ai/batch/batch_runner.sh`.
 
-### Your Role
-- Execute tasks from backlog autonomously
-- Follow quality gates strictly
-- Make conservative decisions (ask user when uncertain)
-- Commit and push changes automatically
-- Continue until backlog depleted or limits reached
+The runner reads stories from `.ai/tasks/prd.json`, spawns fresh Claude sessions
+per task, runs quality gates, and tracks progress.
 
-### Batch Workflow
-
-```
-1. Read tasks/active.md
-   ├─ If incomplete tasks: resume work
-   └─ If no active tasks: read backlog.md
-
-2. Select highest-priority unblocked task
-   ├─ Check dependencies
-   ├─ Verify not blocked
-   └─ Move to tasks/active.md
-
-3. Create feature branch
-   └─ Name: feature/{task-id}-{slug}
-
-4. Execute work following patterns
-   ├─ Auto-apply triggers from patterns/index.md
-   ├─ Keep commits atomic and descriptive
-   └─ Test incrementally
-
-5. Quality gates must pass
-   ├─ If gate fails:
-   │  ├─ Attempt auto-fix if pattern known
-   │  ├─ Pause batch if can't fix
-   │  └─ Notify user
-   └─ If all pass: proceed to commit
-
-6. Commit and push
-   ├─ Stage all changes
-   ├─ Commit with conventional format
-   ├─ Push to origin
-   └─ Create PR if configured
-
-7. Clean up and continue
-   ├─ Delete local feature branch
-   ├─ Update tasks/active.md
-   ├─ Check if more tasks to execute
-   └─ Continue or stop
-
-8. Completion report
-   └─ Show summary: tasks done, time spent, any issues
+### Usage
+```bash
+./.ai/batch/batch_runner.sh --dry-run    # Preview next task
+./.ai/batch/batch_runner.sh              # Run (default 20 iterations)
+./.ai/batch/batch_runner.sh 50           # Custom iteration limit
+./.ai/batch/batch_runner.sh --phase 3    # Specific phase only
 ```
 
-### Batch Configuration
-
-Read from `/.ai/state.json`:
+### State Files
+| File | Purpose |
+|------|---------|
+| .ai/tasks/prd.json | Single source of truth for task status |
+| .ai/batch/progress.txt | Append-only operational learnings |
+| .ai/batch/prompt.md | Prompt template for Claude sessions |
+| logs/ | Per-task Claude output logs |
 
-```json
-{
-  "batch_config": {
-    "max_tasks": 5,
-    "max_duration_hours": 4,
-    "quality_gates": ["typecheck", "lint", "test"],
-    "skip_gates": [],
-    "auto_commit": true,
-    "auto_push": false,
-    "create_pr": false,
-    "branch_format": "feature/{id}-{slug}",
-    "commit_format": "conventional"
-  }
-}
-```
-
-**Important:** Batch mode is conservative:
-- Don't skip quality gates without explicit config
-- Ask user if uncertain about task interpretation
-- Stop on first blocker and notify user
-- Don't force push or destructive operations
-- Log all decisions and timing
-
-### Batch Error Handling
-
-**Build/Test Fails:**
-- Show error with full context
-- If pattern known: auto-fix
-- If unsure: pause and notify user
-- Don't proceed without resolution
-
-**Git Conflicts:**
-- Stop immediately
-- Notify user of conflict
-- Require manual resolution
-- Resume after conflict resolved
-
-**Missing Dependencies:**
-- Check if dependency task exists
-- Add to batch queue if available
-- Execute dependency first
-- Resume original task
-
-**Resource Limits Reached:**
-- Stop execution gracefully
-- Report progress
-- Create clean state for next batch
-- Notify user of completion status
+### How It Works
+1. Read prd.json → find next incomplete story (deps satisfied)
+2. Spawn: `claude --print --dangerously-skip-permissions -p "implement story X"`
+3. Run quality gates (configurable per project)
+4. If pass → mark story done in prd.json, commit
+5. If fail → retry up to 2x with error context
+6. Append learnings to progress.txt
+7. Repeat until done or max iterations
+
+### Safety
+- Circuit breaker: 3 consecutive failures → stop
+- Rate limit detection + auto-wait
+- Graceful Ctrl+C shutdown
+- Per-task logs for debugging
 
 ---
 
@@ -430,7 +331,7 @@ Reference these files in this priority order:
    - Project changelog or git history
 
 5. **Fifth Priority: Planning**
-   - `/.ai/tasks/backlog.md` - Future work
+   - `/.ai/tasks/prd.json` - Future work (structured)
    - Roadmap or project documentation
    - Upstream issues or features
 
@@ -620,7 +521,7 @@ When finishing a session:
    - Add completion date if done
 
 3. **Document learnings**
-   - Document patterns in `.ai/patterns/` and index in `memory/patterns.md`
+   - Update `/.ai/memory/patterns.md` if discovered pattern
    - Update `/.ai/memory/deadends.md` if failed approach
    - Reference in commit messages
 

package/templates/workspace/.ai/memory/patterns.md

@@ -1,19 +1,65 @@
-# Codebase Patterns Index
+# Codebase Patterns
 
-This file is an index of patterns documented in `.ai/patterns/`.
-Each entry links to the full pattern file.
+This file documents recurring patterns discovered during development.
 
-## Registered Patterns
+## Format
 
-<!-- AI: Add entries here as you create pattern files -->
-<!-- Format: - [{category}/{name}](.ai/patterns/{category}/{name}.md) - Brief description -->
+Each pattern follows this structure:
 
-_No patterns registered yet._
+```markdown
+## Pattern Category
+
+### Pattern Name
+**Context:** When this pattern applies
+**Pattern:** Code example or description
+**Rationale:** Why this is the better approach
+**Example Location:** Where to find real examples
+```
+
+---
+
+## Add New Patterns
+
+When you discover a useful pattern:
+
+1. Identify the category (Frontend, Backend, Testing, etc.)
+2. Fill in all sections
+3. Add code example if possible
+4. Commit with message: `docs: add pattern - [name]`
+5. Update `patterns/index.md` if this should be auto-applied
+
+---
+
+## Pattern Categories
+
+- **Frontend:** React, TypeScript, styling, component patterns
+- **Backend:** API design, database queries, middleware
+- **Testing:** Unit tests, integration tests, fixtures
+- **Performance:** Caching, memoization, optimization
+- **Security:** Input validation, authentication, authorization
+- **Error Handling:** Exception patterns, recovery strategies
+- **Data Structures:** Modeling domain objects effectively
+
+---
+
+## Template for New Pattern
+
+```markdown
+## [Category]
+
+### [Pattern Name]
+**Context:** (When to use this pattern)
+**Pattern:** (Description or code example)
+**Rationale:** (Why this is better)
+**Example Location:** (Where in codebase)
+```
 
 ---
 
-## How to Add
+## Notes
 
-1. Create pattern file: `.ai/patterns/{category}/{pattern-name}.md`
-2. Add index entry here with link and brief description
-3. Commit both files together
+- Patterns should be language-agnostic when possible
+- Prioritize patterns that prevent common bugs
+- Link related patterns together
+- Update this file as team learns new approaches
+- Archive rarely-used patterns after 3 months of no references

package/templates/workspace/.ai/tasks/active.md

@@ -70,7 +70,7 @@ Highlight 1-3 most important tasks for today.
 
 ## Notes
 
-- Check backlog.md for upcoming work
+- Check prd.json for upcoming stories
 - Move completed tasks to archive or backlog with completion date
 - When stuck, create SPIKE task to investigate
 - Reference decisions from `memory/decisions.md`

package/templates/workspace/.ai/workflows/batch-task.md

@@ -4,103 +4,79 @@ This file defines the template for autonomous batch task execution via the `pwn
 
 ## Overview
 
-Batch task execution allows AI agents to autonomously:
-- Select tasks from backlog
-- Execute work in sequence
+Batch task execution uses `.ai/batch/batch_runner.sh` to autonomously:
+- Read stories from `.ai/tasks/prd.json`
+- Spawn fresh Claude sessions per task
 - Run quality gates (tests, linting, type checking)
-- Commit changes following conventions
-- Continue until backlog depleted or threshold reached
+- Track progress and learnings between iterations
+- Handle retries, rate limits, and circuit breaking
 
 ## Usage
 
 ```bash
-# Execute next available task
-pwn batch
+# Preview next task
+./.ai/batch/batch_runner.sh --dry-run
 
-# Execute specific number of tasks
-pwn batch --count 5
+# Run batch (default 20 iterations)
+./.ai/batch/batch_runner.sh
 
-# Dry-run: show what would execute
-pwn batch --dry-run
+# Custom iteration limit
+./.ai/batch/batch_runner.sh 50
 
-# Execute with specific priority
-pwn batch --priority high
+# Specific phase only
+./.ai/batch/batch_runner.sh --phase 3
 
-# Resume interrupted batch
-pwn batch --resume
+# Via pwn CLI
+pwn batch run
+pwn batch run --dry-run
+pwn batch status
 ```
 
 ## Batch Execution Protocol
 
 ### Phase 1: Task Selection
 
-1. Read `tasks/active.md` for incomplete tasks
-2. If active tasks exist and not blocked, resume
-3. Otherwise, read `tasks/backlog.md`
-4. Select highest priority unblocked task
-5. Verify dependencies are met
-6. Move to `active.md`
+1. Read `tasks/prd.json` for stories
+2. Find next story where `passes == false`
+3. Verify all dependencies have `passes == true`
+4. Apply phase filter if specified
 
 ### Phase 2: Execution
 
-1. Analyze task requirements
-2. Create feature branch: `feature/[task-id]-[slug]`
-3. Execute work following patterns in `patterns/index.md`
-4. Test incrementally during development
-5. Keep commits atomic and descriptive
+1. Build prompt from `.ai/batch/prompt.md` template
+2. Substitute story placeholders ({STORY_ID}, {STORY_TITLE}, etc.)
+3. Spawn: `claude --print --dangerously-skip-permissions -p "<prompt>"`
+4. Capture output to `logs/` for debugging
 
 ### Phase 3: Quality Gates
 
-Before commit, verify:
+Customize `run_quality_gates()` in `batch_runner.sh` for your stack:
 
+**Node.js:**
 ```bash
-# Type checking
-[ ] npm run typecheck || tsc --noEmit
-
-# Linting
-[ ] npm run lint || eslint .
-
-# Unit tests
-[ ] npm run test || jest
-
-# Integration tests (if applicable)
-[ ] npm run test:integration
-
-# Build verification
-[ ] npm run build
+npm test
+npm run lint
+npm run typecheck
+```
 
-# Security scan (if configured)
-[ ] npm run security
+**Python:**
+```bash
+pytest --tb=short
+ruff check src/
+mypy src/ --ignore-missing-imports
 ```
 
 **Gate Strategy:**
 - Fail fast on first error
-- Output clear error message
-- Suggest fix if known
-- Option to skip non-critical gates with `--force`
-
-### Phase 4: Commit & Cleanup
-
-1. Stage all changes: `git add .`
-2. Commit with message format:
-   ```
-   feat: [task-id] - [description]
-
-   - Specific change 1
-   - Specific change 2
-
-   Fixes: [task-id]
-   ```
-3. Push to remote: `git push -u origin feature/[task-id]-[slug]`
-4. Create PR if configured
-5. Update `active.md`: mark complete with date
+- Retry up to 2x with error context fed back to Claude
+- Circuit breaker after 3 consecutive failures
 
-### Phase 5: Completion
+### Phase 4: Completion
 
-1. Verify commit is on remote
-2. Delete local feature branch
-3. Report completion to user
-4. Continue to next task or stop
+1. Mark story as `passes: true` in prd.json
+2. Append learnings to `progress.txt`
+3. Commit prd.json + progress.txt update
+4. Continue to next story
 
 ## Batch Configuration
 

package/templates/workspace/.claude/commands/mode.md

@@ -77,10 +77,10 @@ pwn mode interactive
 
 ### Batch Mode
 
-- Claude executes tasks autonomously from backlog
-- Creates feature branches per task
+- Claude executes stories autonomously from prd.json
+- Spawns fresh sessions per task via batch_runner.sh
 - Runs quality gates before committing
-- Continues until backlog empty or limits reached
+- Retries with error context, circuit breaker on failures
 - Good for repetitive tasks and overnight execution
 
 ---
@@ -94,9 +94,10 @@ After executing the command, explain to the user:
 3. **Next steps** - What they can do next
 
 For batch mode, remind them:
-- Add tasks to `.ai/tasks/backlog.md`
-- Run `pwn batch` to start executing tasks
+- Add stories to `.ai/tasks/prd.json`
+- Run `pwn batch run` to start the batch runner
 - Use `pwn batch status` to check progress
+- Use `.ai/batch/prd_status.sh` for detailed PRD view
 
 For interactive mode, remind them:
 - Work proceeds conversationally

package/templates/workspace/.claude/commands/save.md

@@ -103,50 +103,10 @@ Create a session summary:
 ## Dead Ends
 - DE-XXX: description (if any)
 
-## Patterns Documented
-- [{category}/{name}] - description (if any)
-
 ---
 *Saved: {ISO timestamp}*
 ```
 
-### 6. Pattern Extraction (.ai/patterns/)
-
-Review the entire session and extract patterns. Check each criterion:
-
-1. **User corrected your approach** → Document the correct approach
-2. **You chose between alternatives** → Document what was chosen and why
-3. **Workaround for limitation** → Document the workaround
-4. **Convention established** → Document for consistency
-5. **Repeated approach** → Document to avoid re-deriving
-6. **Non-trivial solution** → Document for future sessions
-
-**For each pattern found:**
-
-1. Create file: `.ai/patterns/{category}/{pattern-name}.md`
-   ```markdown
-   # Pattern Name
-
-   ## Context
-   When to apply this pattern.
-
-   ## Pattern
-   Description or code example.
-
-   ## Rationale
-   Why this approach works better.
-
-   ## Examples
-   - `src/path/file.ts:42`
-   ```
-
-2. Add index entry to `.ai/memory/patterns.md`:
-   ```markdown
-   - [{category}/{name}](.ai/patterns/{category}/{name}.md) - Brief description
-   ```
-
-**If no patterns found:** Confirm "Patterns: no new patterns this session"
-
 ---
 
 ## Output Format
@@ -159,7 +119,6 @@ PWN Save Complete:
 - Tasks: {X} active, {Y} completed
 - Dead Ends: {new count or "no new"}
 - Decisions: {new count or "no new"}
-- Patterns: {new count or "no new"}
 - Archive: .ai/memory/archive/{filename}
 - Last updated: {timestamp}
 ```
@@ -173,7 +132,6 @@ PWN Save Complete:
 3. **decisions.md**: Organized entries with proper DEC-XXX IDs
 4. **active.md**: Only current sprint tasks
 5. **archive/**: One file per session with summary
-6. **patterns/**: One file per pattern, indexed in memory/patterns.md
 
 ---
 

package/templates/workspace/.claude/settings.json

@@ -2,11 +2,20 @@
   "hooks": {
     "Notification": [
       {
-        "matcher": "",
+        "matcher": "permission_prompt",
         "hooks": [
           {
             "type": "command",
-            "command": "pwn notify send \"Claude Code aguardando permissao\" --title \"PWN\""
+            "command": "pwn notify send \"Claude Code aguardando permissão\" --title \"PWN\""
+          }
+        ]
+      },
+      {
+        "matcher": "idle_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pwn notify send \"Claude Code aguardando input\" --title \"PWN\""
           }
         ]
       }