@punks/cli 0.1.16 → 1.0.0

package/dist/skills/agnostic/planning/implement-spec/references/parallel-orchestration.md

@@ -0,0 +1,102 @@
+# Parallel Orchestration
+
+Use this reference to run the full parallel orchestration loop inside `implement-spec`.
+
+## Step 1: Parse request
+
+Extract from the user request:
+
+1. the plan source to execute
+2. an optional task subset
+
+If no subset is provided, execute the full plan.
+
+## Step 2: Read and parse `PLAN.md`
+
+Find task subsections such as:
+
+- `### T1:`
+- `### Task 1.1:`
+
+For each task, extract:
+
+- task id and task name
+- `depends_on`
+- full content needed for execution:
+  - location
+  - description
+  - acceptance criteria
+  - validation
+  - `tdd_target`
+  - `review_mode`
+  - backlog metadata when present
+  - related tasks or plan-level constraints when they materially shape execution
+
+Build the task list from this data.
+
+If a task subset was requested:
+
+- filter to the requested tasks
+- include every required dependency first
+
+## Step 3: Build the current wave
+
+A task is unblocked only when all ids in its `depends_on` list are complete.
+
+For the current wave:
+
+- collect every unblocked task
+- exclude already-complete tasks
+- exclude tasks blocked by failed prerequisites
+
+Launch all unblocked tasks in parallel.
+
+## Step 4: Spawn workers
+
+For each unblocked task:
+
+- choose the worker template from `.agents/subagents/manifest.mjs`
+- use the worker-brief contract from [parallel-worker-brief.md](parallel-worker-brief.md)
+- keep the task scope narrow
+- ensure the worker owns only the assigned task and its required validation
+
+## Step 5: Review and validate the wave
+
+After the workers return:
+
+1. inspect their outputs for correctness and completeness
+2. compare the result against the task validation contract
+3. ensure the task log and touched files were written back into `PLAN.md`
+4. ensure non-obvious deviations or surprises were written into `IMPLEMENTATION-NOTES.md`
+5. retry or escalate failed work instead of quietly advancing
+
+Move to the next wave only after the current wave is validated and logged.
+
+## Step 6: Repeat
+
+Re-read the plan state and compute the next set of unblocked tasks.
+
+Continue until:
+
+- all reachable tasks are complete
+- or a real blocker remains
+
+## Completion rule
+
+A task is complete only when all of the following are true:
+
+- the worker finished the assigned scope
+- acceptance criteria are satisfied, not only partially implemented
+- RED -> GREEN evidence exists for testable tasks, or an explicit `reason_not_testable` plus exact alternative verification exists
+- validation evidence matches the task contract
+- `PLAN.md` reflects the completed status and execution log
+- touched files are recorded
+- any non-obvious deviations are reflected in `IMPLEMENTATION-NOTES.md`
+
+If any of these are missing, the task is not done yet.
+
+## Error handling
+
+- If the requested task subset cannot be found, report the available task ids.
+- If parsing fails, report what was tried and what is ambiguous.
+- If a worker result is incomplete or incorrect, retry or escalate instead of marking the task complete.

package/dist/skills/agnostic/planning/implement-spec/references/parallel-worker-brief.md

@@ -0,0 +1,65 @@
+# Parallel Worker Brief
+
+Use this reference when spawning a worker for one task in a parallel wave.
+
+## Required context
+
+Every worker brief should include:
+
+- plan file or spec-folder context
+- relevant goals or overview from the plan
+- task id and task name
+- task dependencies
+- related tasks when they matter
+- file locations
+- full description
+- acceptance criteria
+- validation contract
+- `tdd_target`
+- `review_mode`
+- relevant risks or constraints from the plan
+
+## Required instructions
+
+Each worker brief should require:
+
+1. reading the plan and understanding the specific task first
+2. reading all relevant files first, then doing targeted codebase research before editing
+3. starting from `tdd_target` and driving the task RED first when it is testable
+4. capturing failing evidence for the expected behavior gap before implementation
+5. recording an explicit `reason_not_testable` plus exact alternative verification when the task is not a good TDD candidate
+6. treating RED-phase tests or the approved non-testable verification plan as the implementation contract
+7. not weakening or removing tests unless requirements changed
+8. implementing only the assigned task scope and satisfying all acceptance criteria
+9. running the exact task validation evidence before returning, plus extra plan validation when feasible
+10. updating the plan entry with status, log, touched files, and gotchas before handoff closes
+
+## Worker output contract
+
+Require the worker to return:
+
+- files modified or created
+- concise summary of changes
+- how the acceptance criteria are satisfied
+- verification evidence: RED -> GREEN for testable tasks, or the exact non-testable alternative that was run
+- validation evidence performed
+- validation intentionally deferred
+- anything deferred, blocked, or risky
+
+## Scope rule
+
+The worker is not responsible for overall wave orchestration.
+
+The worker owns:
+
+- one assigned task
+- its local validation
+- its plan-entry updates
+
+The parent `implement-spec` run owns:
+
+- wave construction
+- cross-task dependency handling
+- review of worker outputs
+- retry and escalation decisions
+- deciding when the wave is complete

package/dist/skills/agnostic/planning/implement-spec/references/parallel.md

@@ -0,0 +1,56 @@
+# Parallel Execution
+
+Use this approach when execution should fan out across independent tasks or waves.
+
+When `implement-spec` chooses `parallel` mode, this reference is the full contract for parallel execution.
+
+## Parallel contract
+
+- **Mode:** `parallel`
+- **Worker policy:** spawn workers only for currently unblocked work
+- **Execution board:** completed, in progress, unblocked next, blocked, current wave
+
+## Adoption rule
+
+In `parallel` mode, `implement-spec` must do all of the orchestration work itself.
+
+That includes:
+
+1. parsing `PLAN.md`
+2. extracting task ids, names, `depends_on`, locations, descriptions, acceptance criteria, validations, and related metadata
+3. building the current wave from the unblocked tasks
+4. spawning workers for that wave
+5. reviewing worker results for correctness and completeness
+6. updating plan logs and execution notes
+7. repeating until all reachable tasks are complete or a real blocker remains
+
+Do not treat worker spawning as the whole job. The orchestration loop is part of this mode.
+
+## Quick start
+
+1. Load the shared lifecycle from `lifecycle.md`.
+2. Record `parallel` under **Execution mode** in `IMPLEMENTATION-NOTES.md`.
+3. Read `.agents/subagents/manifest.mjs` before the first spawn and choose explicit worker templates per task.
+4. Read [parallel-orchestration.md](parallel-orchestration.md) and parse `PLAN.md` into a task graph.
+5. Build the current wave from the unblocked tasks only.
+6. Read [parallel-worker-brief.md](parallel-worker-brief.md) and use that contract when spawning workers.
+7. Validate each wave before moving on. Fix failures before the next wave.
+8. Update the plan, notes, and tech debt after every wave.
+
+## Required evidence
+
+- plan-derived wave selection
+- explicit worker briefs per task
+- post-wave review of worker outputs
+- acceptance-criteria coverage plus RED -> GREEN evidence, or explicit non-testable verification
+- task completion only after validation and plan/log updates
+- clear reporting of retries, issues, or blockers
+
+## Loop rule
+
+Keep iterating wave by wave until:
+
+- all reachable tasks are complete, validated, and logged
+- or a real blocker remains and is reported honestly
+
+Do not quietly skip failed work. Retry or escalate instead.

package/dist/skills/agnostic/planning/implement-spec/references/sequential.md

@@ -0,0 +1,28 @@
+# Sequential Execution
+
+Use this approach when execution should stay in one thread without worker fan-out.
+
+## Sequential contract
+
+- **Mode:** `sequential`
+- **Worker policy:** do not spawn workers
+- **Execution board:** completed, in progress, next, blocked
+
+## Quick start
+
+1. Load the shared lifecycle from `lifecycle.md`.
+2. Record `sequential` under **Execution mode** in `IMPLEMENTATION-NOTES.md`.
+3. Execute one task at a time in dependency order.
+4. After every task, run the task-level validation gate before marking it done.
+5. Update plan status, logs, touched files, notes, and tech debt immediately.
+
+## Task loop
+
+For every task:
+
+1. start from `tdd_target`
+2. validate through the task's public interface
+3. run the task-level validation gate before marking it done
+4. update the execution board before advancing
+
+Stop only when all reachable tasks are complete or a real blocker remains.

package/dist/skills/agnostic/planning/swarm-planner/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: swarm-planner
+description: >
+  [EXPLICIT INVOCATION ONLY] Creates dependency-aware implementation plans optimized for parallel
+  multi-agent execution.
+metadata:
+  invocation: explicit-only
+---
+
+# Swarm-Ready Planner
+
+Create implementation plans with explicit task dependencies optimized for parallel agent execution. This skill can be ran inside or outside of Plan Mode. 
+
+## Core Principles
+
+1. **Explore Codebase**: Investigate architecture, patterns, existing implementations, dependencies, and frameworks in use.
+2. **Fresh Documentation First**: Use Context7 for ANY external library, framework, or API before planning tasks
+3. **Ask Questions**: Clarify ambiguities and seek clarification on scope, constraints, or priorities throughout the planning process. At any time.
+4. **Explicit Dependencies**: Every task declares what it depends on, enabling maximum parallelization
+5. **Atomic Tasks**: Each task is independently executable by a single agent
+6. **Review Before Yield**: A subagent reviews the plan for gaps before finalizing
+
+## Process
+
+### 1. Research
+
+**Codebase investigation:**
+- Architecture, patterns, existing implementations
+- Dependencies and frameworks in use
+
+### 1a. Optional: Stop to Clarification Questions
+
+- If the architecture is unclear or missing STOP AND YIELD to the user, and request user input (AskUserQuestions) before moving on. Always offer recommendations for clarification questions.
+- If architecture is present, skip 1a and move onto next step. 
+
+### 2. Documentation
+
+**Documentation retrieval (REQUIRED for external dependencies):**
+
+Use Context7 skill or MCP to fetch current docs for any libraries/frameworks or APIs that are or will be used in project. If Context7 is not available, use web search.
+
+This ensures version-accurate APIs, correct parameters, and current best practices.
+
+### 3. STOP and Request User Input
+
+When anything is unclear or could reasonably be done multiple ways:
+- Stop and ask clarifying questions immediately
+- Do not make assumptions about scope, constraints, or priorities
+- Questions should reduce risk and eliminate ambiguity
+- Always offer recommendations for clarification questions.
+- Use request_user_input or AskUserQuestion tool if available. 
+
+### 4. Create Dependency-Aware Plan
+
+Structure the plan with explicit task dependencies using this format:
+
+#### Task Dependency Format
+
+Each task MUST include:
+- **id**: Unique identifier (e.g., `T1`, `T2.1`)
+- **depends_on**: Array of task IDs that must complete first (empty `[]` for root tasks)
+- **description**: What the task accomplishes
+- **location**: File paths involved
+- **validation**: How to verify completion
+
+**Example:**
+```
+T1: [depends_on: []] Create database schema migration
+T2: [depends_on: []] Install required packages
+T3: [depends_on: [T1]] Create repository layer
+T4: [depends_on: [T1]] Create service interfaces
+T5: [depends_on: [T3, T4]] Implement business logic
+T6: [depends_on: [T2, T5]] Add API endpoints
+T7: [depends_on: [T6]] Write integration tests
+```
+
+Tasks with empty/satisfied dependencies can run in parallel (T1, T2 above).
+
+### 4. Save Plan
+
+Save to `<topic>-plan.md` in the CWD.
+
+### 5. Subagent Review
+
+After saving, spawn a subagent to review the plan:
+
+```
+Review this implementation plan for:
+1. Missing dependencies between tasks
+2. Ordering issues that would cause failures
+3. Missing error handling or edge cases
+4. Gaps, holes, gotchas.
+
+Provide specific, actionable feedback. Do not ask questions.
+
+Plan location: [file path]
+Context: [brief context about the task]
+```
+
+If the subagent provides actionable feedback, revise the plan before yielding.
+
+
+## Plan Template
+
+```markdown
+# Plan: [Task Name]
+
+**Generated**: [Date]
+
+## Overview
+[Summary of task and approach]
+
+## Prerequisites
+- [Tools, libraries, access needed]
+
+## Dependency Graph
+
+```
+[Visual representation of task dependencies]
+T1 ──┬── T3 ──┐
+     │        ├── T5 ── T6 ── T7
+T2 ──┴── T4 ──┘
+```
+
+## Tasks
+
+### T1: [Name]
+- **depends_on**: []
+- **location**: [file paths]
+- **description**: [what to do]
+- **validation**: [how to verify]
+- **status**: Not Completed
+- **log**: [leave empty, to be filled out later]
+- **files edited/created**: [leave empty, to be filled out later]
+
+### T2: [Name]
+- **depends_on**: []
+- **location**: [file paths]
+- **description**: [what to do]
+- **validation**: [how to verify]
+- **status**: Not Completed
+- **log**: [leave empty, to be filled out later]
+- **files edited/created**: [leave empty, to be filled out later]
+
+### T3: [Name]
+- **depends_on**: [T1]
+- **location**: [file paths]
+- **description**: [what to do]
+- **validation**: [how to verify]
+- **status**: Not Completed
+- **log**: [leave empty, to be filled out later]
+- **files edited/created**: [leave empty, to be filled out later]
+
+[... continue for all tasks ...]
+
+## Parallel Execution Groups
+
+| Wave | Tasks | Can Start When |
+|------|-------|----------------|
+| 1 | T1, T2 | Immediately |
+| 2 | T3, T4 | Wave 1 complete |
+| 3 | T5 | T3, T4 complete |
+| ... | ... | ... |
+
+## Testing Strategy
+- [How to test]
+- [What to verify]
+
+## Risks & Mitigations
+- [What could go wrong + how to handle]
+```
+
+## Important
+
+- Every task must have explicit `depends_on` field
+- Root tasks (no dependencies) can be executed in parallel immediately
+- Do NOT implement - only create the plan
+- Always use Context7 for external dependencies before finalizing tasks
+- Always ask questions where ambiguity exists

package/dist/skills/agnostic/quality/simplify/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: simplify
+description: Simplify and refine recently modified code for clarity and consistency. Use after writing code to improve readability without changing functionality.
+---
+
+Review changes in the current branch, or in the state the user specifies. Apply these criteria without changing behavior:
+
+1. **Names**: Shorten verbose names while keeping them clear. Prefer human-readable concepts (`baseline`) over compound phrases that are more mechanical / academic (`lastObservedDiskContent`).
+
+2. **Combine related concepts**: If two types, functions, or constants overlap significantly, merge them. The fewer distinct concepts a reader must hold in their head, the better. *Example: two union types sharing 3 of 4 values → one type with shorter value names.*
+
+3. **Derivability**: If a value can be computed from other values already in scope, don't pass or store it separately. Removing derivable state often simplifies signatures, types, and control flow in one move. *Example: an `isDirty` parameter that's always derived from computing `editorContent !== baseline` can be dropped.*
+
+4. **Scope**: Only touch code in the specified scope. Validate your work does not break existing functionality.

package/dist/skills/agnostic/quality/tdd/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```

package/dist/skills/agnostic/quality/tdd/deep-modules.md

@@ -0,0 +1,33 @@
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?

package/dist/skills/agnostic/quality/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup

package/dist/skills/agnostic/quality/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/dist/skills/agnostic/quality/tdd/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic