@punks/cli 0.1.16 → 1.0.0

package/dist/skills/agnostic/planning/create-spec/assets/SPEC-TEMPLATE.md

@@ -0,0 +1,91 @@
+---
+domain:
+type: spec
+status: draft
+links: []
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+id:               # optional — ticket ID, remove if not applicable
+---
+
+# Spec: [Title]
+
+<!--
+INSTRUCTIONS FOR THE AGENT (remove this block before saving the final spec):
+
+- Each spec covers one epic/capability boundary.
+- If the epic contains multiple child stories, the spec must cover all of them.
+- Preserve individual story requirements while unifying them into one coherent problem-space contract.
+- The audience is engineers. Keep it tight. A spec that takes 10 minutes to read won't get reviewed. Aim for 2–3 minutes.
+- This template is a starting point, not a rulebook:
+    - Remove sections that don't apply — don't leave them blank or write "N/A"
+    - Add sections if something important doesn't fit (e.g. "Data model", "API contract")
+    - Adjust depth to complexity — a simple task may only need Context + Acceptance Criteria
+-->
+
+---
+
+## User input
+
+_Verbatim copy of everything the user said that is relevant to this spec — across one or more messages if needed. Do not paraphrase or summarize. Preserve the original wording as closely as possible._
+
+---
+
+## Context
+
+_What is this, why does it need to exist, and who is it for? Cover the problem and the purpose in a few sentences. Name the actual roles affected (admin, customer, developer — not just "user")._
+
+---
+
+## Non-Goals
+
+_Explicitly list what is out of scope for this spec. This prevents scope creep and misunderstandings._
+
+-
+-
+
+---
+
+## Acceptance Criteria
+
+_The observable, binary conditions that define "done". Each one should be independently testable — you should be able to read it and immediately know what test would prove it true or false. When the epic has multiple child stories, consolidate their requirements into one coherent epic-level contract and ensure every story contributes explicit criteria._
+
+-
+-
+-
+
+---
+
+## Constraints
+
+_Technical, legal, organizational, or timeline constraints that shape the solution space — including quality requirements like performance, security, or accessibility if they're genuinely relevant._
+
+-
+
+---
+
+## Technical Notes
+
+_Optional. Technical discoveries, known system constraints, or early implementation observations that surfaced before or during spec writing_
+
+-
+
+---
+
+## Open Questions
+
+_Unresolved questions that could affect implementation._
+
+| # | Question | Affects | Owner | Status |
+|---|----------|---------|-------|--------|
+| 1 |          |         |       | Open   |
+
+---
+
+## Decision Log
+
+_Decisions made during spec refinement, with rationale._
+
+| Decision | Rationale |
+|----------|-----------|
+|          |           |

package/dist/skills/agnostic/planning/create-spec/references/discovery.md

@@ -0,0 +1,44 @@
+# Discovery
+
+Use this reference before asking clarifying questions.
+
+## Required order
+
+1. Read `apps/wiki/AGENTS.md`.
+   - Stop if it does not exist. The wiki is not bootstrapped yet.
+2. Read `apps/wiki/index.md`.
+   - Use it as the master map for domains, contracts, and existing specs.
+3. Identify the primary domain.
+   - Prefer the domain whose contract most clearly owns the request.
+   - If multiple domains are involved, pick the primary owner and note cross-domain scope in the spec.
+   - If no domain matches, stop and tell the user to run `/create-wiki-domain <name>` first.
+4. Read the relevant domain contract:
+   - `apps/wiki/domains/<domain>/<domain>-contract.md`
+5. Optionally read related domain concepts or flows when they are obviously relevant.
+6. Check for existing overlapping specs in:
+   - `apps/wiki/specs/<domain>/<domain>-specs.md`
+7. If backlog context exists, inspect the parent epic/capability and every child story beneath it.
+   Use [../../write-backlog/assets/concepts/backlog-model.md](../../write-backlog/assets/concepts/backlog-model.md) as the source of truth for how to interpret module -> epic -> story shape.
+   Harvest:
+   - epic outcome and constraints
+   - each child story title
+   - each child story body and acceptance signals
+   - cross-story blockers or sequencing assumptions that affect the problem statement
+8. Check existing DB schema when a matching domain schema file exists:
+   - `packages/db/src/schema/<domain>.ts`
+   Use it to:
+   - avoid speccing duplicates
+   - catch contradictions with the implemented model
+   - surface open questions when a required field is absent
+9. Glance at the top-level repo structure only if needed for terminology or context.
+
+## Exploration rule
+
+This is orientation, not deep implementation research.
+
+- Keep it read-only
+- Keep it fast
+- Prefer enough context to ask better questions
+- Do not drift into solution design
+
+If the Agent tool is available, use a subagent for this pass so the main thread stays clean.

package/dist/skills/agnostic/planning/create-spec/references/folder-naming.md

@@ -0,0 +1,27 @@
+# Folder Naming
+
+Use this reference after questioning and before writing the file.
+
+## Domain resolution
+
+- The spec path is `apps/wiki/specs/<domain>/<folder-name>/SPEC.md`.
+- Use the exact existing domain directory name from `apps/wiki/`.
+- If multiple domains are touched, choose the primary owner and describe the cross-domain aspect in the spec body.
+
+## Folder-name rules
+
+- Base the name on the subject matter: `oauth-providers`, `invoice-export`
+- If the user mentioned a ticket id, prepend it: `PROJ-123-oauth-providers`
+- If the user specified an exact folder name, use that as-is
+- Keep it short but recognizable
+- Use kebab-case
+
+## Collision rule
+
+Each spec folder must be unique within its domain.
+
+If the folder already exists:
+
+- ask whether to update the existing spec or create a new one
+
+Do not ask the user to confirm the folder name unless the correct name is genuinely ambiguous.

package/dist/skills/agnostic/planning/create-spec/references/handoff.md

@@ -0,0 +1,47 @@
+# Handoff
+
+Use this reference after the spec and wiki bookkeeping are complete.
+
+## Complexity assessment
+
+Classify the change before recommending the next step.
+
+### Trivial / straightforward
+
+- small and well-scoped
+- clear acceptance criteria
+- few unknowns
+- low architectural risk
+- limited surface area
+
+Recommendation:
+
+- suggest direct implementation
+
+### Non-trivial
+
+- multiple moving parts
+- unclear dependencies
+- architectural choices still matter
+- risk of breaking existing behavior
+- open questions remain about the approach
+
+Recommendation:
+
+- suggest `create-plan`
+
+## User-facing closeout
+
+Tell the user:
+
+- where the spec was created
+- that wiki index and log were updated
+- that the spec is ready for review
+- the suggested next step
+
+Then ask them to reply with:
+
+- `[P]` to create an implementation plan
+- `[I]` to implement directly
+
+Then stop and wait. Do not proceed until the user approves the spec and picks a next step.

package/dist/skills/agnostic/planning/create-spec/references/questioning.md

@@ -0,0 +1,41 @@
+# Questioning
+
+Use this reference after discovery and before writing.
+
+## Goal
+
+Ask only enough to produce a useful, bounded spec. A vague spec creates false confidence.
+
+## Priority topics
+
+Surface these as needed:
+
+- which epic/capability is in scope
+- which child stories under that epic are in scope
+- who this is for
+- why it needs to exist
+- what "done" looks like
+- what is out of scope
+- what constraints exist
+- what is still unknown
+- whether a ticket or project id should influence naming
+
+## Asking strategy
+
+- Group questions naturally instead of dumping a long questionnaire.
+- Skip questions already answered by repo context or by the user.
+- If a fact is ambiguous and matters to the spec, ask directly.
+- Prefer concrete examples over abstract wording.
+- When backlog context exists, ask about cross-story interactions only after reading all child stories first.
+
+## Stop asking when
+
+- the core problem is clear
+- the epic boundary is clear
+- every child story in scope has been harvested into the spec
+- affected actors or stakeholders are clear
+- success is concrete and observable
+- major functional requirements are identifiable
+- key non-goals are explicit
+
+If a branch remains open, capture it as an open question or assumption inside the spec rather than pretending certainty.

package/dist/skills/agnostic/planning/create-spec/references/spec-quality-bar.md

@@ -0,0 +1,58 @@
+# Spec Quality Bar
+
+Use this reference while filling the template and before saving.
+
+## Core rule
+
+The spec lives in the problem space.
+
+- include what, who, why, acceptance criteria, non-goals, constraints, open questions
+- exclude architecture, implementation steps, code structure, or solution design
+- when the epic has child stories, include the concrete requirements of each child story instead of summarizing only the parent issue
+
+## Acceptance-criteria bar
+
+Every acceptance criterion should be:
+
+- binary
+- observable
+- testable
+
+Avoid:
+
+- vague outcomes like "works well" or "feels intuitive"
+- hidden implementation requirements disguised as product behavior
+- mixed criteria that bundle several independent outcomes into one line
+
+## Epic completeness bar
+
+When writing a spec from an epic with child stories:
+
+- the spec must cover the full scope of the epic
+- each child story must contribute concrete requirements, constraints, or acceptance criteria
+- cross-story interactions must be resolved in the spec rather than left implicit in backlog items
+
+Avoid:
+
+- a spec that summarizes the epic but omits concrete requirements from one or more child stories
+- a spec that treats child stories as links only, without incorporating their product details
+- a spec that copies child stories separately without unifying overlaps and shared constraints
+
+## Self-review before saving
+
+- remove all template scaffolding
+- remove empty or irrelevant sections
+- ensure the document reads cleanly with no ghost instructions
+- check that terminology matches the repo domain language
+
+## Field naming rule
+
+Any field name in backticks must use English identifiers.
+
+Examples:
+
+- `first_name`, not `nome`
+- `acquisition_channel`, not `canale_acquisizione`
+- `visits`, not `visite`
+
+If a business term needs clarification, explain it in prose only.

package/dist/skills/agnostic/planning/create-spec/references/wiki-bookkeeping.md

@@ -0,0 +1,26 @@
+# Wiki Bookkeeping
+
+Use this reference after writing `SPEC.md`.
+
+## Required updates
+
+1. Add a row to the **Specs** table in `apps/wiki/index.md`:
+
+```md
+| <domain> | [[specs/<domain>/<folder-name>/SPEC]] | Draft |
+```
+
+2. Add an entry to `apps/wiki/specs/<domain>/<domain>-specs.md` with:
+   - the spec name
+   - a one-line summary
+
+3. Append to `apps/wiki/log.md`:
+
+```md
+## [YYYY-MM-DD] spec | <spec title>
+- Created spec: [[specs/<domain>/<folder-name>/SPEC]]
+- Domain: <domain>
+- Status: Draft
+```
+
+Do not skip this step.

package/dist/skills/agnostic/planning/grill-me/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview the user relentlessly about every aspect of the plan until shared understanding exists. Walk each branch of the design tree and resolve dependencies one by one. For every question, provide a recommended answer.
+
+Ask one question at a time.
+
+If the answer can be found in the codebase, inspect first instead of asking.
+
+## During the session
+
+### Challenge the glossary
+
+If the user uses a term that conflicts with existing specs, docs, or code language, call it out immediately and force a precise choice.
+
+### Sharpen vague language
+
+When the user uses fuzzy or overloaded terms, propose a canonical term and make them choose the right one.
+
+### Discuss concrete scenarios
+
+Stress-test relationships and boundaries with specific scenarios, including edge cases that force precision.
+
+### Cross-check with code
+
+When the user states how the system works, verify it against the code. Surface contradictions instead of smoothing them over.

package/dist/skills/agnostic/planning/implement-spec/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: implement-spec
+description: Implement an approved spec folder while keeping `IMPLEMENTATION-NOTES.md`, `PLAN.md`, and spec-linked tech debt in sync. Use when a reviewed spec already has a `PLAN.md` and execution should proceed either sequentially in one thread or in parallel with explicit worker orchestration.
+---
+
+# Implement Spec
+
+## Contract
+
+- **Role:** higher-order execution orchestrator
+- **Entrypoint type:** public entrypoint
+- **Upstream:** reviewed spec folder with `SPEC.md` and `PLAN.md`
+- **Delegates to:** `$tdd`, `$simplify`, and internal worker orchestration in parallel mode
+- **Downstream:** `docs-maintenance` when the resulting spec folder should be ingested into domain knowledge
+- **Entry conditions:** existing reviewed spec folder; stop and use `create-plan` if `PLAN.md` is missing
+- **Stop conditions:** shared acceptance audit complete, spec folder finalized, blocked work reported honestly
+
+## Required Inner Skills
+
+- MUST use `$tdd`
+- MUST use `$simplify`
+Use `$agent-browser` when any task `review_mode` is `browser` or `mixed`.
+
+## Parallel responsibilities
+
+When `implement-spec` runs in `parallel` mode, it must follow [references/parallel.md](references/parallel.md) as the full orchestration contract.
+
+That means `implement-spec` itself owns all of the following in parallel mode:
+
+- parsing `PLAN.md`
+- finding the currently unblocked tasks from `depends_on`
+- launching workers in waves
+- reviewing worker outputs
+- validating each wave before advancing
+- ensuring `PLAN.md` and `IMPLEMENTATION-NOTES.md` are updated after each completed wave
+
+## Quick start
+
+1. Resolve the target spec folder under `apps/wiki/specs/<domain>/<spec>/`.
+2. Read `references/lifecycle.md` and follow the shared execution contract exactly.
+3. Choose the execution mode explicitly:
+   - Read `references/sequential.md` for one-thread execution.
+   - Read `references/parallel.md` for wave-based worker execution.
+4. Record the chosen mode under **Execution mode** in `IMPLEMENTATION-NOTES.md` before coding.
+5. Execute only the chosen mode. Do not mix modes inside one run.
+6. After each completed task or wave, update `PLAN.md`, `IMPLEMENTATION-NOTES.md`, and spec-linked tech debt before advancing.
+7. If backlog sync is in scope, keep epic/story bodies product-facing and use native metadata or comments instead of execution handoff rewrites.
+8. Finish with the shared acceptance audit and spec finalization contract.
+
+## Mode selection
+
+Choose `sequential` when:
+
+- the user wants single-threaded execution
+- tasks are tightly coupled
+- worker handoff cost would outweigh parallelism
+
+Choose `parallel` when:
+
+- the user wants explicit parallel execution
+- the plan contains independent waves
+- disjoint write scopes make worker fan-out safe
+
+If the user already chose a mode, honor it. If not, make the smallest safe choice and state it.
+
+## Advanced features
+
+- Shared lifecycle, notes contract, tech-debt rules, acceptance audit, finalization: see [references/lifecycle.md](references/lifecycle.md)
+- Sequential execution specifics: see [references/sequential.md](references/sequential.md)
+- Parallel execution specifics: see [references/parallel.md](references/parallel.md)
+- Parallel plan parsing and wave construction: see [references/parallel-orchestration.md](references/parallel-orchestration.md)
+- Parallel worker brief contract: see [references/parallel-worker-brief.md](references/parallel-worker-brief.md)

package/dist/skills/agnostic/planning/implement-spec/assets/IMPLEMENTATION-NOTES-TEMPLATE.md

@@ -0,0 +1,47 @@
+# Implementation Notes
+
+## Summary
+
+- 
+
+## Execution Mode
+
+- 
+
+## Deviations From the Plan
+
+- 
+
+## Surprises and Decisions
+
+- 
+
+## Sanity Checks
+
+| Check | Result | Notes |
+|------|--------|-------|
+| | | |
+
+## Acceptance Criteria Status
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| | | |
+
+## Pre-existing Issues
+
+- 
+
+## Out of Scope Observations
+
+- 
+
+## Remaining Work
+
+- 
+
+## Steering
+
+| Date | Feedback | Changes |
+|------|----------|---------|
+| | | |

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

@@ -0,0 +1,149 @@
+# Implement Spec Lifecycle
+
+## Shared contract
+
+`implement-spec` is the only public execution entrypoint.
+
+It routes to one of two approaches:
+
+- `sequential` — one thread, no workers
+- `parallel` — wave-based execution with explicit worker orchestration
+
+Do not recreate wrapper skills for these modes. Keep the routing here and load only the needed mode reference.
+
+## 1. Require an existing reviewed spec folder
+
+Execution must stay grounded in:
+
+`apps/wiki/specs/<domain>/<spec>/`
+
+Required files:
+
+- `SPEC.md`
+- `PLAN.md`
+
+If `SPEC.md` is missing, stop and report the resolved path error.
+
+If `PLAN.md` is missing, stop and use `create-plan`. Do not auto-generate plans from this skill.
+
+## 2. Resolve the target folder
+
+Accept either:
+
+- a domain plus spec folder name
+- a full spec folder path
+- a direct `SPEC.md` or `PLAN.md` path
+
+Normalize to the containing spec folder before doing any work.
+
+## 3. Load the working set
+
+Read, in this order:
+
+1. `apps/wiki/AGENTS.md`
+2. `apps/wiki/specs/<domain>/<spec>/SPEC.md`
+3. `apps/wiki/specs/<domain>/<spec>/PLAN.md`
+4. `apps/wiki/specs/<domain>/<spec>/IMPLEMENTATION-NOTES.md` if present
+5. `docs/reference/tech-debt/<domain>/<spec>.md` if present
+
+If package or framework behavior matters, inspect source with `opensrc --modify false` before guessing.
+
+## 4. Prepare execution notes
+
+Use [../assets/IMPLEMENTATION-NOTES-TEMPLATE.md](../assets/IMPLEMENTATION-NOTES-TEMPLATE.md).
+
+- Create `IMPLEMENTATION-NOTES.md` from the template when missing.
+- Append or refine when it already exists.
+- Keep it current during the run, not only at the end.
+
+## 5. Prepare the tech-debt ledger
+
+Persistent implementation drift belongs in:
+
+`docs/reference/tech-debt/<domain>/<spec>.md`
+
+Use it only for durable drift that should inform later work on the same spec:
+
+- scoped compromises
+- unresolved gaps
+- pre-existing debt discovered during execution
+- cleanup intentionally deferred by the current spec
+
+Do not create the file when nothing durable must survive the run.
+
+## 6. Shared execution invariants
+
+- Mode is manual. The chosen approach decides the execution path.
+- Do not switch modes mid-run unless the user explicitly redirects.
+- Treat every `tdd_target` as required RED-first behavior, never optional guidance.
+- Treat every `review_mode` as required validation routing, never optional metadata.
+- Keep an operator-visible execution board in the conversation so progress is obvious.
+- Keep scope discipline. Out-of-scope findings go to `IMPLEMENTATION-NOTES.md`, not silent scope creep.
+- If backlog sync is part of the run, keep epic and story bodies product-facing.
+- Execution-time backlog sync may use comments, links, native status, and native relations.
+- Never rewrite epic or story bodies with task ids, TDD targets, validation commands, or file lists.
+
+## 7. Shared upkeep after each completed unit
+
+After each completed task or wave:
+
+- update `PLAN.md` status
+- append a concise execution log in `PLAN.md`
+- record touched files in `PLAN.md`
+- update `IMPLEMENTATION-NOTES.md` with non-obvious decisions, surprises, or deviations
+- update the spec-linked tech-debt file when durable drift appears
+- if backlog sync is in scope, prefer native metadata changes or concise comments over body rewrites
+
+## 8. Handle blockers honestly
+
+If a task is blocked:
+
+1. record it in `IMPLEMENTATION-NOTES.md`
+2. update the spec-linked tech-debt file when the blocker is durable
+3. skip only tasks truly blocked by it
+4. finish all remaining reachable work
+5. report blocked tasks clearly at the end
+
+Do not fake completion.
+
+## 9. Apply runtime-aware validation
+
+Use the task `review_mode`:
+
+- `cli`: tests, commands, type-checks, API calls, or non-visual checks
+- `browser`: browser validation through `$agent-browser`
+- `mixed`: both
+
+If running inside a worktree and `portless` is available, prefer it for server-based validation to avoid port conflicts.
+
+## 10. Verify acceptance criteria
+
+Re-read `SPEC.md` acceptance criteria and mark each one:
+
+- met
+- unmet
+- blocked
+
+Record a reason for every unmet or blocked item in `IMPLEMENTATION-NOTES.md`.
+
+## 11. Finalize the spec folder
+
+Before reporting back:
+
+- remove empty sections from `IMPLEMENTATION-NOTES.md`
+- ensure **Execution mode** reflects the mode actually used
+- ensure **Sanity checks** lists only commands actually run
+- ensure **Remaining work** matches any unmet or blocked criteria
+- set `SPEC.md` frontmatter `status: implemented`
+- set `PLAN.md` `**Status:** Complete` when that line exists
+
+## 12. Final report shape
+
+Summarize:
+
+- implementation status
+- validation results
+- key deviations or surprises
+- acceptance-criteria status
+- blocked tasks needing input
+- whether the spec-linked tech-debt file was created or updated