@punks/cli 0.1.16 → 1.0.0

package/dist/skills/agnostic/requirements/write-backlog/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: write-backlog
+description: Turns a large requirements discussion into a canonical backlog hierarchy of module/milestone -> epic/capability -> story and documents provider-specific issue creation payloads. Use when structuring backlog from discovery, breaking requirements into milestones/epics/stories, consuming `requirements-grill` artifacts like `*-grill-log.md` and `*-grill-status.md`, or preparing Linear, GitHub Issues, or Azure DevOps issue creation payloads.
+---
+
+# Write Backlog
+
+## Quick start
+
+1. Read [REFERENCE.md](REFERENCE.md) and [assets/concepts/backlog-model.md](assets/concepts/backlog-model.md).
+2. If `requirements-grill` artifacts exist, read `*-grill-status.md` first and `*-grill-log.md` second.
+3. Derive modules first, then epics, then stories.
+4. Make story ordering explicit with native dependency primitives when the provider supports them.
+5. Keep epic and story bodies product-facing.
+6. Read the matching provider payload asset before generating or syncing create payloads.
+7. Stop after the backlog structure and create payload guidance are complete.
+
+## Workflows
+
+### From a large requirements discussion
+
+1. Normalize the input into durable modules.
+2. Turn each module into a milestone or provider-equivalent container.
+3. Create epic/capability items that each map to one future `SPEC.md`.
+4. Break each epic into independently observable child stories.
+5. Add native blockers between stories when order matters.
+
+### From `requirements-grill` artifacts
+
+1. Read `docs/<topic>-grill-status.md` first.
+2. Read `docs/<topic>-grill-log.md` second.
+3. Use the status file to identify:
+   - active branches
+   - branch completion
+   - locked direction
+   - still-open items
+   - parked branches
+4. Use the log to extract:
+   - accepted decisions
+   - superseded decisions
+   - canonical terms
+   - branch closure notes
+5. Derive backlog only from locked direction and accepted decisions.
+6. Treat parked branches and still-open items as explicit backlog notes or deferred follow-up, not silently resolved scope.
+
+### From an existing messy backlog
+
+1. Read the current hierarchy and item bodies first.
+2. Collapse technical chores back into product-facing stories when possible.
+3. Rebuild module -> epic -> story structure.
+4. Keep execution detail out of epic and story bodies.
+
+### Provider payload selection
+
+1. Read the provider payload asset:
+   - [Linear](assets/providers/linear-create-payload.md)
+   - [GitHub Issues](assets/providers/github-issues-create-payload.md)
+   - [Azure DevOps](assets/providers/azure-devops-create-payload.md)
+2. Use the raw provider request shape documented there.
+3. Do not invent provider fields from memory when the asset already defines them.
+
+## Advanced features
+
+- Canonical hierarchy and handoff contract: see [REFERENCE.md](REFERENCE.md)
+- Backlog model and body ownership: see [assets/concepts/backlog-model.md](assets/concepts/backlog-model.md)
+- Epic/story body shape: see [assets/concepts/story-shape.md](assets/concepts/story-shape.md)
+- Provider create payloads: see [assets/providers/](assets/providers/)
+- `requirements-grill` artifact ingestion: see [REFERENCE.md](REFERENCE.md)

package/dist/skills/agnostic/requirements/write-backlog/assets/concepts/backlog-model.md

@@ -0,0 +1,69 @@
+# Backlog Model
+
+## Canonical hierarchy
+
+- module
+- epic
+- story
+
+Provider mapping:
+
+- module -> milestone or equivalent grouping
+- epic -> parent issue / capability item
+- story -> child issue / sub-issue / child work item
+
+## Ownership boundaries
+
+- backlog owns product-facing coordination
+- `SPEC.md` owns the full problem-space contract for one epic
+- `PLAN.md` owns execution decomposition
+
+## Epic contract
+
+One epic:
+
+- maps to one future `SPEC.md`
+- groups the stories that share one coherent capability boundary
+- can include cross-story scope and constraints
+
+One epic must not:
+
+- become an execution board
+- duplicate the whole future `PLAN.md`
+- be reduced to a pure label/container with no capability meaning
+
+## Story contract
+
+One story:
+
+- is independently observable
+- describes one user-visible slice or system behavior slice
+- stays product-facing
+- can be ordered relative to other stories with native blockers
+
+One story must not:
+
+- become a plan task
+- carry TDD or file-level detail
+- be phrased as a technical chore
+
+## Order contract
+
+Use native provider relations for ordering when available.
+
+Preferred primitives:
+
+- `blockedBy`
+- `blocks`
+- native parent/child
+
+Do not encode story order only in prose when the provider can store it natively.
+
+## `create-spec` reading contract
+
+When `create-spec` reads backlog items:
+
+- the parent epic is the spec anchor
+- all child stories under that epic are source material
+- the resulting `SPEC.md` must include the combined scope of those stories
+- no child story requirement should remain only in the backlog and not appear in the spec

package/dist/skills/agnostic/requirements/write-backlog/assets/concepts/story-shape.md

@@ -0,0 +1,66 @@
+# Epic And Story Shape
+
+## Epic body
+
+Use a short bounded body.
+
+Recommended sections:
+
+```md
+## Outcome
+
+[What capability this epic delivers and why it matters]
+
+## Scope
+
+- ...
+
+## Constraints
+
+- ...
+
+## Links
+
+- `SPEC.md` once it exists
+```
+
+Epic bodies may summarize the capability boundary, but should not re-copy every child story verbatim once the child stories exist.
+
+## Story body
+
+Keep stories product-facing and independently understandable.
+
+Recommended sections:
+
+```md
+## Outcome
+
+[What this story enables]
+
+## Acceptance signals
+
+- [ ] ...
+- [ ] ...
+
+## Non-goals
+
+- ...
+
+## Links
+
+- Parent epic
+- `SPEC.md` once it exists and matters
+```
+
+## Body anti-patterns
+
+Do not put these in epic or story bodies:
+
+- `Plan task: T123`
+- `TDD target`
+- `Validation`
+- file paths
+- package names as pseudo-scope
+- worker handoff notes
+
+Those belong in `PLAN.md`, execution comments, or implementation notes instead.

package/dist/skills/agnostic/requirements/write-backlog/assets/providers/azure-devops-create-payload.md

@@ -0,0 +1,63 @@
+# Azure DevOps Create Payload
+
+Official source:
+
+- Work items create API: [learn.microsoft.com/en-us/rest/api/azure/devops/wit/work-items/create?view=azure-devops-rest-7.1](https://learn.microsoft.com/en-us/rest/api/azure/devops/wit/work-items/create?view=azure-devops-rest-7.1)
+
+## Transport
+
+- endpoint: `POST https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/${type}?api-version=7.1`
+- headers:
+  - `Content-Type: application/json-patch+json`
+  - `Authorization: Bearer <TOKEN>`
+
+## Raw request body
+
+Azure DevOps creates work items with a JSON Patch document.
+
+```json
+[
+  {
+    "op": "add",
+    "path": "/fields/System.Title",
+    "value": "Lead manages unassigned submissions"
+  },
+  {
+    "op": "add",
+    "path": "/fields/System.Description",
+    "value": "<h2>Outcome</h2><p>...</p><h2>Acceptance signals</h2><ul><li>...</li></ul>"
+  },
+  {
+    "op": "add",
+    "path": "/fields/System.Tags",
+    "value": "workflow;review"
+  }
+]
+```
+
+## Required path inputs
+
+- `{organization}`
+- `{project}`
+- `${type}`
+- `api-version=7.1`
+
+## Common field operations
+
+- `/fields/System.Title`
+- `/fields/System.Description`
+- `/fields/System.Tags`
+- `/fields/System.AreaPath`
+- `/fields/System.IterationPath`
+
+## Repo mapping
+
+- module -> area/iteration or team-specific planning container
+- epic -> work item type chosen by your process, often `Epic` or `Feature`
+- story -> work item type chosen by your process, often `User Story`, `Product Backlog Item`, or `Task`
+
+## Notes
+
+- Azure DevOps create requests are process-dependent. The exact work item type names available in `{type}` depend on the project template and process.
+- This asset documents the raw create payload shape, not a universal field catalog for every process.
+- Parent/child and dependency relations may require additional relation operations or follow-up requests depending on your process conventions. Keep those separate from the minimal create-only contract documented here.

package/dist/skills/agnostic/requirements/write-backlog/assets/providers/github-issues-create-payload.md

@@ -0,0 +1,48 @@
+# GitHub Issues Create Payload
+
+Official source:
+
+- REST issues API: [docs.github.com/en/rest/issues/issues](https://docs.github.com/en/rest/issues/issues?apiVersion=2022-11-28)
+
+## Transport
+
+- endpoint: `POST https://api.github.com/repos/{owner}/{repo}/issues`
+- headers:
+  - `Accept: application/vnd.github+json`
+  - `Authorization: Bearer <TOKEN>`
+  - `X-GitHub-Api-Version: 2022-11-28`
+
+## Raw request body
+
+```json
+{
+  "title": "Lead manages unassigned submissions",
+  "body": "## Outcome\n\n...\n\n## Acceptance signals\n\n- [ ] ...",
+  "assignees": ["octocat"],
+  "milestone": 1,
+  "labels": ["workflow", "review"]
+}
+```
+
+## Required fields
+
+- `title`
+
+## Common optional fields
+
+- `body`
+- `assignees`
+- `milestone`
+- `labels`
+
+## Repo mapping
+
+- module -> repository milestone
+- epic -> GitHub issue
+- story -> GitHub issue
+
+## Notes
+
+- GitHub’s create-issue payload does not natively express parent/sub-issue or blocker relations in the same create body documented here.
+- If you use GitHub as the provider, treat hierarchy and dependency setup as follow-up work outside this create-only asset.
+- Because of that limitation, keep the canonical module -> epic -> story model explicit in your own backlog logic instead of silently flattening it.

package/dist/skills/agnostic/requirements/write-backlog/assets/providers/linear-create-payload.md

@@ -0,0 +1,76 @@
+# Linear Create Payload
+
+Official sources:
+
+- GraphQL getting started: [linear.app/developers/graphql](https://linear.app/developers/graphql)
+- Issue creation overview: [linear.app/docs/creating-issues](https://linear.app/docs/creating-issues)
+
+## Transport
+
+- endpoint: `POST https://api.linear.app/graphql`
+- headers:
+  - `Content-Type: application/json`
+  - `Authorization: Bearer <ACCESS_TOKEN>`
+
+## Minimum documented mutation
+
+```graphql
+mutation IssueCreate($input: IssueCreateInput!) {
+  issueCreate(input: $input) {
+    success
+    issue {
+      id
+      identifier
+      title
+      url
+    }
+  }
+}
+```
+
+```json
+{
+  "query": "mutation IssueCreate($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier title url } } }",
+  "variables": {
+    "input": {
+      "teamId": "TEAM_UUID",
+      "title": "Lead manages unassigned submissions",
+      "description": "## Outcome\n\n...\n\n## Acceptance signals\n\n- [ ] ...",
+      "projectId": "PROJECT_UUID",
+      "parentId": "EPIC_UUID",
+      "priority": 2,
+      "labelIds": ["LABEL_UUID"],
+      "stateId": "STATE_UUID",
+      "dueDate": "2026-05-01"
+    }
+  }
+}
+```
+
+## Required fields
+
+- `teamId`
+- `title`
+
+## Common optional fields for backlog creation
+
+- `description`
+- `projectId`
+- `parentId`
+- `priority`
+- `labelIds`
+- `stateId`
+- `dueDate`
+
+## Repo mapping
+
+- module -> Linear project milestone
+- epic -> top-level issue
+- story -> child issue created with `parentId`
+
+## Notes
+
+- Linear issues belong to a single team.
+- If `stateId` is omitted, Linear assigns the team’s default backlog or triage state.
+- Linear’s GraphQL schema is introspectable. If you need a workspace-specific or newly-added create field, inspect `IssueCreateInput` before hardcoding it.
+- Project milestone assignment is part of project-backed issue creation in Linear. Treat the current schema or SDK types as the source of truth for the exact milestone input field name in your workspace version.

package/dist/skills/agnostic/research/improve-codebase-architecture/REFERENCE.md

@@ -0,0 +1,78 @@
+# Reference
+
+## Dependency Categories
+
+When assessing a candidate for deepening, classify its dependencies:
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — just merge the modules and test directly.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (e.g., PGLite for Postgres, in-memory filesystem). Deepenable if the test substitute exists. The deepened module is tested with the local stand-in running in the test suite.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a port (interface) at the module boundary. The deep module owns the logic; the transport is injected. Tests use an in-memory adapter. Production uses the real HTTP/gRPC/queue adapter.
+
+Recommendation shape: "Define a shared interface (port), implement an HTTP adapter for production and an in-memory adapter for testing, so the logic can be tested as one deep module even though it's deployed across a network boundary."
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. Mock at the boundary. The deepened module takes the external dependency as an injected port, and tests provide a mock implementation.
+
+## Testing Strategy
+
+The core principle: **replace, don't layer.**
+
+- Old unit tests on shallow modules are waste once boundary tests exist — delete them
+- Write new tests at the deepened module's interface boundary
+- Tests assert on observable outcomes through the public interface, not internal state
+- Tests should survive internal refactors — they describe behavior, not implementation
+
+## Issue Template
+
+<issue-template>
+
+## Problem
+
+Describe the architectural friction:
+
+- Which modules are shallow and tightly coupled
+- What integration risk exists in the seams between them
+- Why this makes the codebase harder to navigate and maintain
+
+## Proposed Interface
+
+The chosen interface design:
+
+- Interface signature (types, methods, params)
+- Usage example showing how callers use it
+- What complexity it hides internally
+
+## Dependency Strategy
+
+Which category applies and how dependencies are handled:
+
+- **In-process**: merged directly
+- **Local-substitutable**: tested with [specific stand-in]
+- **Ports & adapters**: port definition, production adapter, test adapter
+- **Mock**: mock boundary for external services
+
+## Testing Strategy
+
+- **New boundary tests to write**: describe the behaviors to verify at the interface
+- **Old tests to delete**: list the shallow module tests that become redundant
+- **Test environment needs**: any local stand-ins or adapters required
+
+## Implementation Recommendations
+
+Durable architectural guidance that is NOT coupled to current file paths:
+
+- What the module should own (responsibilities)
+- What it should hide (implementation details)
+- What it should expose (the interface contract)
+- How callers should migrate to the new interface
+
+</issue-template>

package/dist/skills/agnostic/research/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: improve-codebase-architecture
+description: Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.
+---
+
+# Improve Codebase Architecture
+
+Explore a codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors as GitHub issue RFCs.
+
+A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside.
+
+## Process
+
+### 1. Explore the codebase
+
+Use the Agent tool with subagent_type=Explore to navigate the codebase naturally. Do NOT follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small files?
+- Where are modules so shallow that the interface is nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
+- Where do tightly-coupled modules create integration risk in the seams between them?
+- Which parts of the codebase are untested, or hard to test?
+
+The friction you encounter IS the signal.
+
+### 2. Present candidates
+
+Present a numbered list of deepening opportunities. For each candidate, show:
+
+- **Cluster**: Which modules/concepts are involved
+- **Why they're coupled**: Shared types, call patterns, co-ownership of a concept
+- **Dependency category**: See [REFERENCE.md](REFERENCE.md) for the four categories
+- **Test impact**: What existing tests would be replaced by boundary tests
+
+Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+
+### 3. User picks a candidate
+
+### 4. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would need to rely on
+- A rough illustrative code sketch to make the constraints concrete — this is not a proposal, just a way to ground the constraints
+
+Show this to the user, then immediately proceed to Step 5. The user reads and thinks about the problem while the sub-agents work in parallel.
+
+### 5. Design multiple interfaces
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category, what's being hidden). This brief is independent of the user-facing explanation in Step 4. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1-3 entry points max"
+- Agent 2: "Maximize flexibility — support many use cases and extension"
+- Agent 3: "Optimize for the most common caller — make the default case trivial"
+- Agent 4 (if applicable): "Design around the ports & adapters pattern for cross-boundary dependencies"
+
+Each sub-agent outputs:
+
+1. Interface signature (types, methods, params)
+2. Usage example showing how callers use it
+3. What complexity it hides internally
+4. Dependency strategy (how deps are handled — see [REFERENCE.md](REFERENCE.md))
+5. Trade-offs
+
+Present designs sequentially, then compare them in prose.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not just a menu.
+
+### 6. User picks an interface (or accepts recommendation)
+
+### 7. Create GitHub issue
+
+Create a refactor RFC as a GitHub issue using `gh issue create`. Use the template in [REFERENCE.md](REFERENCE.md). Do NOT ask the user to review before creating — just create it and share the URL.

package/dist/skills/agnostic/research/parallel-research/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: parallel-research
+description: Coordinate aggressive parallel subagent fan-out for readonly work. Use when Codex is researching, auditing, updating docs, investigating multiple hypotheses, or exploring unrelated code paths without writing code. Do not use for code-writing tasks, tightly coupled edits, or work that is faster to finish locally on the critical path.
+---
+
+# Parallel Research
+
+Use this skill only for readonly workflows. Goal: widen coverage fast, keep prompts clean, then synthesize before acting.
+
+## Decide Fast
+
+1. Confirm the task is readonly.
+2. Confirm the work can be split into independent questions or areas.
+3. Keep the immediate blocking step local. Delegate only sidecar work that can run in parallel.
+4. Skip this skill for code writing, patching, rebases, commits, or tightly coupled debugging that needs one continuous thread.
+
+## Split Cleanly
+
+- Split by hypothesis, subsystem, artifact set, or question.
+- Give each subagent one concrete ask.
+- Avoid overlap. Two agents should not answer the same unresolved question unless cross-checking is the explicit goal.
+- Prefer small batches, usually 2-4 subagents.
+
+## Prompt Minimally
+
+- Pass raw artifacts, paths, errors, or files.
+- Do not leak your preferred answer, suspected fix, or private conclusions unless the task truly requires them.
+- Ask for findings, evidence, and file references.
+- For validation passes, make the prompt look like a normal user request, not a hidden test of the skill.
+
+## Run In Parallel
+
+1. Spawn subagents once the split is clear.
+2. Keep working locally while they run. Synthesize, inspect source, or prepare follow-up questions.
+3. Wait only when their output is needed for the next step.
+4. Reuse an existing agent for related follow-ups instead of spawning duplicates.
+
+## Synthesize Before Acting
+
+- Compare outputs against the repo, docs, or other primary artifacts.
+- Resolve disagreements with evidence, not majority vote.
+- Extract the few facts that matter, then decide locally.
+- Close agents that are no longer needed.
+
+## Good Fits
+
+- Auditing separate features for regressions
+- Researching several code paths before planning
+- Checking multiple hypotheses for a bug without editing code
+- Updating docs after parallel fact-gathering
+- Reading unrelated subsystems to build context quickly
+
+## Bad Fits
+
+- Implementing production code
+- Writing tests or making repo edits
+- One small question that is faster to answer locally
+- Work where every step depends tightly on the previous sub-step
+- Delegation that would just duplicate your own immediate next action
+
+## Output Contract
+
+Return:
+- what each subagent covered
+- the evidence worth trusting
+- conflicts or uncertainty
+- the synthesized conclusion
+- the next local action

package/dist/skills/agnostic/research/parallel-research/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Parallel Research"
+  short_description: "Parallelize readonly subagent exploration"
+  default_prompt: "Use $parallel-research to fan out readonly research and synthesize the results."