@fermindi/pwn-cli 0.1.0

package/templates/workspace/.ai/patterns/universal/README.md

@@ -0,0 +1,141 @@
+# Universal Patterns
+
+This directory contains cross-cutting patterns that apply to both frontend and backend development.
+
+## Overview
+
+Universal patterns cover:
+- TypeScript best practices
+- Testing strategies (unit, integration, e2e)
+- Error handling and logging
+- Git workflow and commit conventions
+- Build tool configuration
+- Code organization
+- Documentation standards
+- Performance profiling
+- Security principles
+
+## Structure
+
+```
+universal/
+├── README.md                  # This file
+├── typescript/                # TypeScript patterns
+│   └── README.md             # Type definitions, generics, etc.
+├── testing/                   # Testing patterns
+│   ├── unit/README.md        # Unit test patterns
+│   ├── integration/README.md # Integration test patterns
+│   └── e2e/README.md         # End-to-end test patterns
+├── error-handling/            # Error handling patterns
+│   └── README.md             # Exception handling, logging
+├── git/                       # Git workflow patterns
+│   └── README.md             # Branching, commits, PRs
+├── build-tools/               # Build and package patterns
+│   └── README.md             # Webpack, Vite, etc.
+├── performance/               # Performance optimization
+│   └── README.md             # Profiling, optimization
+└── security/                  # Security patterns
+    └── README.md             # Input validation, secrets, etc.
+```
+
+## Auto-Apply Triggers
+
+These patterns are automatically loaded when:
+
+- **File:** `*.ts`, `*.tsx` (TypeScript)
+- **File:** `*.test.ts`, `*.spec.ts` (Tests)
+- **Import:** `from 'jest'`, `from 'vitest'` (Testing)
+- **Command:** `git commit`, `npm build` (Git, Build)
+- **Path:** `src/__tests__/`, `cypress/`, `playwright/`
+
+See `patterns/index.md` for trigger configuration.
+
+## Common Patterns
+
+### TypeScript
+- Enable strict mode in `tsconfig.json`
+- Use interfaces for object shapes, types for aliases
+- Avoid `any` - use `unknown` with type guards instead
+- Export types alongside implementations
+- Use generics for reusable, type-safe code
+- Document complex types with JSDoc comments
+
+### Testing Strategy
+- Unit tests for utilities and pure functions
+- Integration tests for API endpoints and workflows
+- E2E tests for critical user journeys
+- Test file co-located with source: `feature.ts` + `feature.test.ts`
+- Aim for >80% code coverage on critical paths
+- Mock external dependencies, test real business logic
+
+### Error Handling
+- Use custom error classes that extend Error
+- Include error context (what, why, how to fix)
+- Log errors with full stack traces
+- Different handling strategies for different error types
+- Never silently catch and ignore errors
+- Provide user-friendly error messages
+
+### Git Workflow
+- Descriptive commit messages (50 char subject, blank line, details)
+- Atomic commits (one logical change per commit)
+- Branch naming: `feature/name`, `fix/name`, `docs/name`
+- Pull request template with context
+- Code review before merge
+- Squash or rebase to keep history clean
+
+### Build Tools
+- Consistent build configuration across projects
+- Separate dev and production builds
+- Fast development build (hot reload, source maps)
+- Optimized production build (minification, tree-shaking)
+- Automate with npm/pnpm scripts
+- Cache dependencies to speed up builds
+
+### Code Organization
+- Organize by feature, not by type
+- Keep related code together
+- Use barrel exports (`index.ts`) for clean imports
+- Avoid circular dependencies
+- Monorepo structure for related packages
+- Clear separation of concerns
+
+### Documentation
+- JSDoc comments for public APIs
+- README files in each directory explaining purpose
+- Architecture decision records (ADRs)
+- Code examples for complex logic
+- Keep docs in sync with code
+- Link to external references where relevant
+
+## Usage
+
+1. Read the relevant sub-directory README for your task
+2. Check code examples for reference implementations
+3. Apply patterns to new code
+4. Update patterns if you discover improvements
+
+## Contributing
+
+Found a better pattern?
+
+1. Document it with examples
+2. Add to appropriate subdirectory
+3. Update this README
+4. Commit with message: `docs: add [pattern name] pattern`
+5. Update triggers in `patterns/index.md` if widely applicable
+
+## Links
+
+- [TypeScript Patterns](typescript/README.md)
+- [Testing Strategies](testing/README.md)
+- [Error Handling](error-handling/README.md)
+- [Git Workflow](git/README.md)
+- [Build Tools](build-tools/README.md)
+- [Performance Profiling](performance/README.md)
+- [Security Principles](security/README.md)
+
+## Version
+
+**Last Updated:** (Set on template injection)
+**Maintained By:** Development Team

package/templates/workspace/.ai/state.template.json

@@ -0,0 +1,8 @@
+{
+  "developer": "unknown",
+  "session_started": "2026-01-21T00:00:00Z",
+  "current_task": null,
+  "context_loaded": [],
+  "patterns_registered": [],
+  "last_updated": "2026-01-21T00:00:00Z"
+}

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

@@ -0,0 +1,77 @@
+# Active Tasks
+
+This file tracks work currently in progress.
+
+## Format
+
+Use checkboxes to track completion status:
+
+```markdown
+- [ ] US-001: Pending task
+- [x] US-002: Completed task
+```
+
+Each task can have:
+- **Status indicator:** [ ] = pending, [x] = completed
+- **ID:** US-XXX, BUG-XXX, DEV-XXX, or SPIKE-XXX
+- **Title:** Clear, actionable description
+- **Notes:** Optional context or blockers
+- **Assignee:** Who's working on it (optional)
+
+---
+
+## Task Types
+
+- **US-XXX:** User Story (feature work)
+- **BUG-XXX:** Bug fix
+- **DEV-XXX:** Developer task (refactoring, tech debt)
+- **SPIKE-XXX:** Research or investigation
+- **DOCS-XXX:** Documentation
+
+---
+
+## Management Rules
+
+1. **Limit WIP:** Keep 3-5 tasks active max
+2. **Prioritize:** Order from highest to lowest priority
+3. **Clarify blockers:** Note if task is blocked
+4. **Update daily:** Check boxes as you work
+5. **Archive completion:** Move finished tasks to backlog with date
+
+---
+
+## Template for New Task
+
+```markdown
+- [ ] US-XXX: [Clear title]
+  - Assignee: (your name or team)
+  - Priority: High/Medium/Low
+  - Blocked by: (if applicable)
+  - Notes: (context)
+```
+
+---
+
+## Current Sprint
+
+Update this section weekly with sprint goals and dates.
+
+**Sprint:** YYYY-MM-DD to YYYY-MM-DD
+**Goal:** (What we're trying to accomplish)
+**Capacity:** (Team capacity/points)
+
+---
+
+## Today's Focus
+
+Highlight 1-3 most important tasks for today.
+
+---
+
+## Notes
+
+- Check backlog.md for upcoming work
+- Move completed tasks to archive or backlog with completion date
+- When stuck, create SPIKE task to investigate
+- Reference decisions from `memory/decisions.md`
+- Flag architectural changes for team discussion

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

@@ -0,0 +1,95 @@
+# Backlog
+
+This file contains prioritized future tasks not yet in active work.
+
+## Format
+
+Tasks are listed in priority order (highest to lowest):
+
+```markdown
+### US-XXX: Task Title
+**Type:** Story | Bug | DevTask
+**Priority:** High | Medium | Low
+**Effort:** (T-shirt size: XS, S, M, L, XL)
+**Description:** What needs to be done
+**Acceptance Criteria:**
+- [ ] Criterion 1
+- [ ] Criterion 2
+**Dependencies:** (Other tasks needed first)
+**Notes:** Context, caveats, research needed
+```
+
+---
+
+## Moving to Active
+
+When starting a backlog task:
+
+1. Create issue/ticket in your tracking system
+2. Move to `active.md` with checkbox
+3. Assign team member
+4. Update priority based on sprint plan
+5. Reference in commit messages
+
+---
+
+## Adding New Tasks
+
+When new work is identified:
+
+1. Assign next ID (US-XXX, BUG-XXX, etc.)
+2. Add to appropriate section
+3. Fill in all fields
+4. Don't assign yet - wait for planning
+5. Commit with message: `docs: add [ID] to backlog`
+
+---
+
+## Backlog Sections
+
+### High Priority
+Work that should start soon. Review weekly.
+
+### Medium Priority
+Important but can wait. Review biweekly.
+
+### Low Priority
+Nice-to-have improvements. Review monthly.
+
+### Roadmap (Future Phases)
+Longer-term projects for future planning.
+
+---
+
+## Template for New Backlog Item
+
+```markdown
+### US-XXX: [Title]
+**Type:** Story | Bug | DevTask
+**Priority:** High | Medium | Low
+**Effort:** S/M/L
+**Description:** (What and why)
+**Acceptance Criteria:**
+- [ ] (Specific, measurable outcome)
+**Dependencies:** (Other tasks)
+**Notes:** (Research, concerns, constraints)
+```
+
+---
+
+## Management Guidelines
+
+- Groom backlog every sprint (remove duplicates, clarify)
+- Estimate effort using relative sizing (XS, S, M, L, XL)
+- Link related tasks together
+- Archive completed items with date + time spent
+- Keep description brief - link to external tickets for details
+
+---
+
+## Cleanup
+
+- Remove or update duplicates
+- Close blocked items after 30 days of no progress
+- Archive completed items to `completed/` section
+- Re-estimate if context changes significantly

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

@@ -0,0 +1,356 @@
+# Batch Task Execution Workflow
+
+This file defines the template for autonomous batch task execution via the `pwn batch` command.
+
+## Overview
+
+Batch task execution allows AI agents to autonomously:
+- Select tasks from backlog
+- Execute work in sequence
+- Run quality gates (tests, linting, type checking)
+- Commit changes following conventions
+- Continue until backlog depleted or threshold reached
+
+## Usage
+
+```bash
+# Execute next available task
+pwn batch
+
+# Execute specific number of tasks
+pwn batch --count 5
+
+# Dry-run: show what would execute
+pwn batch --dry-run
+
+# Execute with specific priority
+pwn batch --priority high
+
+# Resume interrupted batch
+pwn batch --resume
+```
+
+## 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`
+
+### 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
+
+### Phase 3: Quality Gates
+
+Before commit, verify:
+
+```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
+
+# Security scan (if configured)
+[ ] npm run security
+```
+
+**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
+
+### Phase 5: Completion
+
+1. Verify commit is on remote
+2. Delete local feature branch
+3. Report completion to user
+4. Continue to next task or stop
+
+## Batch Configuration
+
+Define batch settings in `state.json`:
+
+```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"
+  }
+}
+```
+
+## Task Selection Strategy
+
+### Default: Highest Priority
+```
+- High priority tasks first
+- Within priority: ordered by position in backlog
+- Skip blocked tasks (note reason in state)
+```
+
+### Alternative: By Effort
+```
+- Small (XS, S) tasks first
+- Accumulate quick wins
+- Build momentum
+```
+
+### Alternative: By Due Date
+```
+- Tasks with deadlines first
+- Then by priority
+- Suitable for time-sensitive work
+```
+
+## Error Handling
+
+### Build Fails
+```
+1. Show error output
+2. Offer options:
+   a) Fix automatically (if pattern known)
+   b) Pause for manual fix
+   c) Skip to next task (with note)
+3. Retry if auto-fixed
+4. Abort batch if repeated failures
+```
+
+### Test Fails
+```
+1. Show failing test
+2. Offer options:
+   a) Debug and fix
+   b) Review assertion (might be test issue)
+   c) Pause for investigation
+3. Don't commit until tests pass
+```
+
+### Git Conflicts
+```
+1. Pause batch execution
+2. Notify user of conflict
+3. Request manual resolution
+4. Resume after rebase/merge
+```
+
+### Dependency Issues
+```
+1. Check if task dependencies are met
+2. If not met:
+   a) Add dependency task to batch
+   b) Execute dependency first
+   c) Resume original task
+3. Don't proceed if can't satisfy dependencies
+```
+
+## Commit Message Format
+
+Use conventional commits:
+
+```
+type(scope): subject
+
+body
+
+footer
+```
+
+**Types:**
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation
+- `style:` Code style (formatting, missing semicolons)
+- `refactor:` Refactoring without feature changes
+- `perf:` Performance improvement
+- `test:` Adding/updating tests
+- `chore:` Build, dependencies, tooling
+
+**Example:**
+```
+feat(youtube-summarizer): add batch download mode
+
+- Added batch processing for multiple URLs
+- Implemented progress tracking
+- Added resume capability for interrupted batches
+
+Fixes: US-042
+```
+
+## Logging & Reporting
+
+Log batch execution for review:
+
+```
+[14:23] Starting batch execution (max 5 tasks, 4 hours)
+[14:23] → Selected US-042: Add batch download mode (High, M)
+[14:25] ✓ Feature branch created
+[14:28] ✓ Implementation complete
+[14:30] ✓ Tests pass (18 specs, 0 failures)
+[14:31] ✓ Linting pass (0 issues)
+[14:31] ✓ Build successful (2.3s)
+[14:32] ✓ Committed: feat(youtube-summarizer): add batch download mode
+[14:33] ✓ Pushed to origin
+[14:33] ✓ Task completed (10 min)
+[14:33]
+[14:33] → Selected US-043: Add schedule endpoint (High, M)
+[14:35] ✗ Type check failed: ...
+[14:35] ⓘ Pausing batch - manual intervention needed
+```
+
+## Resuming Batch
+
+To resume after pause:
+
+```bash
+# Shows what was paused
+pwn batch --status
+
+# Continue from where it stopped
+pwn batch --resume
+
+# Skip current task and continue
+pwn batch --resume --skip
+```
+
+State is stored in `state.json`:
+
+```json
+{
+  "batch_state": {
+    "current_task": "US-042",
+    "started_at": "2026-01-21T14:23:00Z",
+    "completed": ["US-041"],
+    "pending": ["US-043", "US-044", "US-045"],
+    "paused_at": "2026-01-21T14:35:00Z",
+    "pause_reason": "Type check failed"
+  }
+}
+```
+
+## Safety Measures
+
+1. **No destructive operations without confirmation**
+   - Force push requires explicit approval
+   - Deleting branches requires confirmation
+   - Reverting commits shows diff first
+
+2. **Rollback capability**
+   - Each batch has unique branch
+   - Can revert entire batch: `git reset --hard`
+   - Commits are preserved in history
+
+3. **Notifications**
+   - Completion notification to user
+   - Failure notification with context
+   - Blockers notify team if configured
+
+4. **Rate limiting**
+   - Default 5 tasks max per batch
+   - Configurable via `--count` or `batch_config`
+   - Time-based limit (default 4 hours)
+
+## Configuration Examples
+
+### Quick Wins Mode
+```json
+{
+  "batch_config": {
+    "max_tasks": 10,
+    "selection_strategy": "effort",
+    "quality_gates": ["test"],
+    "auto_commit": true
+  }
+}
+```
+
+### Safe Mode
+```json
+{
+  "batch_config": {
+    "max_tasks": 1,
+    "quality_gates": ["typecheck", "lint", "test", "build"],
+    "auto_commit": false,
+    "create_pr": true
+  }
+}
+```
+
+### Aggressive Mode
+```json
+{
+  "batch_config": {
+    "max_tasks": 20,
+    "quality_gates": ["test"],
+    "skip_gates": ["typecheck"],
+    "auto_commit": true,
+    "auto_push": true
+  }
+}
+```
+
+## Monitoring
+
+Track batch execution performance:
+
+```json
+{
+  "batch_metrics": {
+    "average_task_duration": "15 min",
+    "success_rate": "92%",
+    "most_common_blocker": "failing_tests",
+    "total_tasks_completed": 47
+  }
+}
+```
+
+## Tips
+
+- Start with small batches (1-3 tasks) to validate quality gates
+- Increase batch size as confidence grows
+- Monitor commit history for quality
+- Adjust quality gates if too strict or too loose
+- Use batch mode during focused work sessions
+- Coordinate with team when executing larger batches