@punks/cli 0.1.15 → 1.0.0

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

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/dist/skills/agnostic/requirements/requirements-grill/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: requirements-grill
+description: Runs rigorous requirements grilling, persists branch decisions, and optionally synthesizes high-level wiki knowledge. Use when the user wants a long design interview, product/architecture requirements discovery, branch-by-branch decision closure, compaction-safe grill logs/status updates, or wiki synthesis from grilled requirements.
+---
+
+# Requirements Grill
+
+Use this skill to turn uncertain product, architecture, or implementation ideas into pinned requirements that can feed backlog/user-story creation.
+
+This skill has three scoped references:
+
+- Live grilling behavior: see [references/grilling-flow.md](references/grilling-flow.md)
+- Durable grill artifacts: see [references/artifact-output.md](references/artifact-output.md)
+- Wiki synthesis from closed grill branches: see [references/wiki-output.md](references/wiki-output.md)
+
+## Quick Routing
+
+Use active grilling when the user is still iterating on requirements, terminology, tradeoffs, branch closure, or status percentages. During a serious grilling session, load both `grilling-flow` and `artifact-output`; the interview and durable artifacts move together.
+
+Use wiki synthesis when the user asks to persist closed grill decisions into `apps/wiki`, extract high-level flows/concepts, or sync domain knowledge from grill artifacts.
+
+Both workflows can happen in one long session, but keep the responsibilities distinct:
+
+- `docs/<topic>-grill-log.md` and `docs/<topic>-grill-status.md` are the detailed requirements record
+- `apps/wiki/domains/` is synthesized domain knowledge
+- backlog/user-story creation is the next phase after the grill gate, outside this skill's scope
+
+## Core Behavior
+
+- Ask one question at a time by default.
+- For every question, provide a recommended answer and the reason for it.
+- Inspect code/docs first when the answer can be found locally.
+- Challenge conflicting glossary, vague terms, and hidden tradeoffs immediately.
+- Prefer conservative defaults once enough context exists.
+- If the user authorizes auto-pinning defaults, close obvious remaining decisions without needless extra questions.
+- Treat parked branches as preserved knowledge, not deleted scope.
+
+## Handoff
+
+At the end, report branch percentages, parked branches, remaining non-design validation work, and the recommended next planning direction.
+
+If all active branches are `100%`, say the requirements grill is done and the likely next direction is backlog/user-story creation.

package/dist/skills/agnostic/requirements/requirements-grill/references/artifact-output.md

@@ -0,0 +1,73 @@
+# Artifact Output
+
+Use this reference to maintain the durable grill artifacts.
+
+This workflow is always paired with [grilling-flow.md](grilling-flow.md) during a serious grilling session.
+
+## Durable Artifacts
+
+At the start of a serious grilling session, create or reuse:
+
+- `docs/<topic>-grill-log.md`
+- `docs/<topic>-grill-status.md`
+
+The log is the durable decision record.
+The status file is the current branch dashboard.
+
+## Grill Log Contract
+
+The log is structured, not a raw transcript.
+
+Record accepted decisions as:
+
+```md
+### Q<N>
+
+Question:
+<question asked>
+
+Accepted answer:
+- <locked answer>
+```
+
+Group related decisions under branch headings.
+
+When the user changes an earlier decision, add a new entry that explicitly supersedes the old one.
+
+## Status File Contract
+
+Maintain a compact branch dashboard with:
+
+- branch name
+- completion percentage
+- locked direction
+- still-open items
+- parked branches
+
+Completion percentages are working signals:
+
+- `0-50%`: branch discovered but unsettled
+- `50-85%`: major direction set, important questions remain
+- `85-99%`: mostly closed, only constants/schema/naming remain
+- `100%`: design closed; remaining work is implementation/tuning
+- `parked`: preserved for later, out of current scope
+
+## Branch Closure
+
+When a branch closes:
+
+1. Update the grill log with final accepted decisions.
+2. Update the status file percentage and open items.
+3. If the branch changes durable domain/product knowledge, run the wiki-output workflow.
+4. Say exactly what changed and which artifacts were updated.
+
+## Final Handoff
+
+At the end, report:
+
+- branch percentages
+- parked branches
+- remaining non-design validation work
+- recommended next planning direction
+
+If all active branches are `100%`, say the requirements grill is done and the likely next direction is backlog/user-story creation.

package/dist/skills/agnostic/requirements/requirements-grill/references/grilling-flow.md

@@ -0,0 +1,57 @@
+# Grilling Flow
+
+Use this reference during live requirements iteration.
+
+This workflow is always paired with [artifact-output.md](artifact-output.md) during a serious grilling session.
+
+## Session Behavior
+
+Interview the user relentlessly about every aspect of the plan until shared understanding exists.
+
+Walk the design tree branch by branch until each branch is:
+
+- closed
+- parked
+- explicitly deferred
+
+## Questioning Rules
+
+- Ask one question at a time by default.
+- Always include a recommended answer.
+- Explain why the recommendation is preferred.
+- If multiple interpretations exist, force a precise choice.
+- When the answer can be found in code/docs, inspect first instead of asking.
+- When the user authorizes auto-pinning, close obvious defaults without needless extra questions.
+
+## Pressure Tests
+
+Challenge glossary:
+
+- If a term conflicts with existing specs, docs, or code language, call it out.
+- Propose the canonical term.
+- Make the user choose.
+
+Sharpen vague language:
+
+- Identify overloaded words.
+- Replace fuzzy language with explicit states, enum values, ownership boundaries, or lifecycle rules.
+
+Discuss concrete scenarios:
+
+- Use edge cases to expose unclear boundaries.
+- Stress-test state transitions, ownership, persistence, and failure behavior.
+
+Cross-check with code:
+
+- Verify user claims against local code when possible.
+- Surface contradictions instead of smoothing them over.
+
+## Conservative Closure
+
+When the user asks to reduce scope or stop widening the design:
+
+- choose the smallest already-justified model
+- avoid new tables, modes, enum values, services, or abstractions
+- keep future branches parked instead of partially designing them
+- prefer app-layer projections before DB views or materialized layers
+- prefer ordinary text/enforced-in-code enums before DB-native enum churn

package/dist/skills/agnostic/requirements/requirements-grill/references/wiki-output.md

@@ -0,0 +1,94 @@
+# Wiki Output From Grill Artifacts
+
+Use this reference when closed grill branches should be reflected in `apps/wiki`.
+
+## Inputs
+
+Use the grill artifacts as source:
+
+- `docs/<topic>-grill-status.md`
+- `docs/<topic>-grill-log.md`
+
+Read status first to understand:
+
+- active and parked branches
+- branch completion
+- current locked direction
+- remaining non-design validation work
+
+Read log second to extract:
+
+- accepted decisions
+- superseded decisions
+- branch closure notes
+- exact canonical terms
+
+## Ownership
+
+`requirements-grill` owns wiki synthesis from grilled requirements.
+
+`docs-maintenance` owns formal spec ingest and ordinary docs upkeep.
+
+## What Belongs In Wiki
+
+Write durable domain/product knowledge into wiki pages.
+
+Good wiki targets:
+
+- product scope
+- user-visible modes and behaviors
+- high-level features
+- conversation model
+- lifecycle concepts
+- memory model
+- data model boundaries
+- multi-step user or system flows
+- major decisions whose rationale should stand alone
+
+Usually keep out of wiki:
+
+- retry constants
+- wire-frame field lists
+- DDL naming polish
+- exact indexes
+- low-level timeout values
+- model artifact ids unless they change product capability
+
+## Page Selection
+
+Create or update concept pages for stable entities, terms, and invariants.
+
+Create or update flow pages for sequences with:
+
+- trigger
+- actors
+- ordered steps
+- decision points
+- terminal outcome
+
+Create or update decision pages only when:
+
+- a major tradeoff was resolved
+- future maintainers will likely ask why an alternative was rejected
+- the rationale would clutter a concept page
+
+## Boundary
+
+Keep `docs/` as the detailed design record.
+
+Use `apps/wiki/domains/` for synthesized domain knowledge.
+
+Do not duplicate the full grill log in wiki pages.
+Summarize stable meaning and link back to source docs when useful.
+
+## Bookkeeping
+
+After wiki changes:
+
+- update the domain index page
+- update root wiki index counts if pages were added
+- append a concise entry to `apps/wiki/log.md`
+- preserve existing frontmatter
+- update `updated`
+
+Do not mark grill docs as `ingested` unless they have frontmatter designed for ingest tracking.

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

@@ -0,0 +1,67 @@
+# Write Backlog Examples
+
+## From discussion to backlog
+
+Input:
+
+> We need a workflow module for intake and review. Coordinators should capture submissions, reviewers should assess and route them, reassignment should preserve context, and archived records must remain visible for auditing.
+
+Output shape:
+
+- Module / milestone: `Intake and review`
+- Epic: `Submission lifecycle management`
+- Stories:
+  - Coordinator creates a new submission from external intake
+  - Reviewer updates notes and attached evidence
+  - Reviewer views the full submission timeline
+  - Lead reassigns ownership to another reviewer
+  - Lead manages unassigned submissions
+  - Lead imports historical submissions
+  - System marks submissions unassigned when a reviewer is deactivated
+
+Native order:
+
+- `Lead manages unassigned submissions` is blocked by:
+  - `Lead reassigns ownership to another reviewer`
+  - `Lead imports historical submissions`
+  - `System marks submissions unassigned when a reviewer is deactivated`
+
+## From `requirements-grill` artifacts to backlog
+
+Input artifacts:
+
+- `docs/submission-lifecycle-grill-status.md`
+- `docs/submission-lifecycle-grill-log.md`
+
+Read status first:
+
+- branch `ownership-transfer` = `100%`
+- branch `unassigned-queue` = `100%`
+- branch `historical-import` = `100%`
+- branch `deactivation-handling` = `100%`
+- recommended next direction = backlog/user-story creation
+
+Read log second:
+
+- accepted decisions define ownership visibility, unassigned handling, and import behavior
+- superseded decisions are ignored in favor of the latest locked answer
+
+Output shape:
+
+- Module / milestone: `Intake and review`
+- Epic: `Submission lifecycle management`
+- Stories:
+  - Lead reassigns ownership to another reviewer
+  - Lead manages unassigned submissions
+  - Lead imports historical submissions
+  - System marks submissions unassigned when a reviewer is deactivated
+
+## Story-shape reminder
+
+Good story:
+
+`As a team lead, I want to view and manage unassigned submissions so I can restore ownership quickly without losing context`
+
+Bad story:
+
+`Add queue table and reassignment mutation`

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

@@ -0,0 +1,253 @@
+# Write Backlog Reference
+
+## Purpose
+
+`write-backlog` is the canonical backlog-authoring skill for this repo.
+
+It turns a large requirements discussion into:
+
+- modules
+- epics
+- stories
+- native ordering relations
+
+It does not write specs, plans, or execution handoffs.
+
+Downstream contract:
+
+- one epic maps to one future `SPEC.md`
+- child stories remain the product-facing slices beneath that epic
+- `PLAN.md` later decomposes execution without replacing the backlog model
+
+## Supported inputs
+
+`write-backlog` can work from:
+
+- a raw requirements discussion
+- an existing messy backlog
+- `requirements-grill` artifacts from `/Users/stefan/Desktop/repos/wearedevpunks-multiplai/.agents/skills/requirements-grill`
+
+When grill artifacts exist, treat them as the highest-signal structured source for backlog derivation.
+
+## `requirements-grill` artifact contract
+
+Expected inputs:
+
+- `docs/<topic>-grill-status.md`
+- `docs/<topic>-grill-log.md`
+
+Read order:
+
+1. status file first
+2. log file second
+
+Use the status file to extract:
+
+- branch names
+- completion percentages
+- locked direction
+- still-open items
+- parked branches
+
+Use the log file to extract:
+
+- accepted decisions
+- superseded decisions
+- canonical terms
+- branch closure notes
+
+Backlog derivation rules from grill artifacts:
+
+- derive backlog from locked direction and accepted decisions
+- do not promote unresolved still-open items into committed story scope without marking them explicitly
+- preserve parked branches as deferred scope, follow-up epic candidates, or backlog notes when relevant
+- if two decisions conflict, the latest explicit superseding decision wins
+
+Good handoff signal from `requirements-grill`:
+
+- active branches are `100%`
+- remaining work is non-design validation
+- recommended next direction is backlog/user-story creation
+
+If the grill is still materially open:
+
+- keep backlog conservative
+- reflect the unresolved branch as an open scope note instead of pretending closure
+
+## Canonical model
+
+Use this hierarchy:
+
+- module
+- epic
+- story
+
+Provider mapping:
+
+- module -> milestone or provider-equivalent grouping
+- epic -> parent issue/work item/capability record
+- story -> child issue/sub-issue/work item
+
+Rules:
+
+- every story must be independently understandable
+- every story must describe product behavior, not implementation chores
+- one epic may contain multiple stories
+- one epic maps to one future `SPEC.md`
+- one story does not imply one future `SPEC.md`
+
+## Body ownership
+
+Backlog bodies stay product-facing.
+
+Epic bodies may include:
+
+- outcome
+- scope
+- cross-story constraints
+- links
+
+Story bodies may include:
+
+- outcome
+- acceptance signals
+- non-goals
+- links
+
+Do not put these in epic or story bodies:
+
+- plan task ids
+- TDD targets
+- file paths
+- validation commands
+- worker handoffs
+- code-structure notes
+
+## Ordering rules
+
+Implementation order belongs in the backlog only through native dependency primitives when supported.
+
+Preferred order signal:
+
+- native `blockedBy` / `blocks`
+
+Avoid:
+
+- prose-only dependency paragraphs
+- fake ordering labels when native blockers exist
+- using plan tasks as backlog children
+
+## Derivation workflow
+
+### 1. Derive modules
+
+Split the requirements discussion into durable capability groups that would still make sense if implementation order changed.
+
+Good module:
+
+- intake and review
+- account lifecycle
+- notifications
+
+Bad module:
+
+- backend foundation
+- frontend polish
+
+### 2. Derive epics
+
+Within each module, create epics/capabilities that will later justify one coherent spec.
+
+Good epic:
+
+- submission lifecycle management
+- account onboarding and activation
+
+Bad epic:
+
+- database schema
+- API routes
+
+### 3. Derive stories
+
+Break each epic into stories only when the slice is product-facing and independently observable.
+
+Good story:
+
+- coordinator creates a new submission from external intake
+- lead reassigns ownership to another reviewer
+
+Bad story:
+
+- add column and router
+- create mutation and form hook
+
+### 4. Add native order
+
+Only add blockers when one story truly depends on another story outcome.
+
+Use blockers for:
+
+- foundational product slices
+- gating flows
+- prerequisite user-visible capability
+
+Do not add blockers for:
+
+- internal code layering preferences
+- one engineer wanting to implement one file before another
+
+## Using grill artifacts during derivation
+
+When the source is a grill status/log pair:
+
+- use branch names and locked direction to identify likely module boundaries
+- use accepted decisions to define epic boundaries
+- use branch closure notes and concrete accepted answers to derive stories
+- use still-open items only as:
+  - explicit open questions for the backlog author
+  - deferred scope notes
+  - follow-up epic/story candidates when the source already frames them that way
+
+Do not:
+
+- turn every grill question into a story
+- treat partially closed branches as committed epic scope by default
+- ignore canonical terminology captured in the grill log
+
+## Handoff to `create-spec`
+
+When `create-spec` is given a backlog-backed epic:
+
+- the epic is the spec anchor
+- every child story is mandatory source material
+- the resulting `SPEC.md` must cover all child stories under that epic
+- the spec must preserve per-story requirements while unifying them into one coherent problem-space contract
+
+## Provider policy
+
+This skill documents raw provider create payloads only.
+
+In scope:
+
+- create issue/work item payload shapes
+- required vs optional fields
+- how module/epic/story intent appears at creation time
+
+Out of scope:
+
+- update payloads
+- comment payloads
+- completion-time execution sync
+
+If a provider cannot express part of the canonical model in the create payload alone:
+
+- document the limitation explicitly
+- do not silently reshape the model
+
+## Anti-patterns
+
+- one backlog item per implementation task
+- one `SPEC.md` per child story when the epic is the real capability boundary
+- milestone descriptions that duplicate entire epic bodies
+- story bodies rewritten into execution handoffs after planning