@punks/cli 0.1.16 → 1.0.0

package/dist/skills/agnostic/frontend/redesign-existing-projects/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: redesign-existing-projects
+description: Upgrades existing websites and apps to premium quality. Audits current design, identifies generic AI patterns, and applies high-end design standards without breaking functionality. Works with any CSS framework or vanilla CSS.
+---
+
+# Redesign Skill
+
+## How This Works
+
+When applied to an existing project, follow this sequence:
+
+1. **Scan** — Read the codebase. Identify the framework, styling method (Tailwind, vanilla CSS, styled-components, etc.), and current design patterns.
+2. **Diagnose** — Run through the audit below. List every generic pattern, weak point, and missing state you find.
+3. **Fix** — Apply targeted upgrades working with the existing stack. Do not rewrite from scratch. Improve what's there.
+
+## Design Audit
+
+### Typography
+
+Check for these problems and fix them:
+
+- **Browser default fonts or Inter everywhere.** Replace with a font that has character. Good options: `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`. For editorial/creative projects, pair a serif header with a sans-serif body.
+- **Headlines lack presence.** Increase size for display text, tighten letter-spacing, reduce line-height. Headlines should feel heavy and intentional.
+- **Body text too wide.** Limit paragraph width to roughly 65 characters. Increase line-height for readability.
+- **Only Regular (400) and Bold (700) weights used.** Introduce Medium (500) and SemiBold (600) for more subtle hierarchy.
+- **Numbers in proportional font.** Use a monospace font or enable tabular figures (`font-variant-numeric: tabular-nums`) for data-heavy interfaces.
+- **Missing letter-spacing adjustments.** Use negative tracking for large headers, positive tracking for small caps or labels.
+- **All-caps subheaders everywhere.** Try lowercase italics, sentence case, or small-caps instead.
+- **Orphaned words.** Single words sitting alone on the last line. Fix with `text-wrap: balance` or `text-wrap: pretty`.
+
+### Color and Surfaces
+
+- **Pure `#000000` background.** Replace with off-black, dark charcoal, or tinted dark (`#0a0a0a`, `#121212`, or a dark navy).
+- **Oversaturated accent colors.** Keep saturation below 80%. Desaturate accents so they blend with neutrals instead of screaming.
+- **More than one accent color.** Pick one. Remove the rest. Consistency beats variety.
+- **Mixing warm and cool grays.** Stick to one gray family. Tint all grays with a consistent hue (warm or cool, not both).
+- **Purple/blue "AI gradient" aesthetic.** This is the most common AI design fingerprint. Replace with neutral bases and a single, considered accent.
+- **Generic `box-shadow`.** Tint shadows to match the background hue. Use colored shadows (e.g., dark blue shadow on a blue background) instead of pure black at low opacity.
+- **Flat design with zero texture.** Add subtle noise, grain, or micro-patterns to backgrounds. Pure flat vectors feel sterile.
+- **Perfectly even gradients.** Break the uniformity with radial gradients, noise overlays, or mesh gradients instead of standard linear 45-degree fades.
+- **Inconsistent lighting direction.** Audit all shadows to ensure they suggest a single, consistent light source.
+- **Random dark sections in a light mode page (or vice versa).** A single dark-background section breaking an otherwise light page looks like a copy-paste accident. Either commit to a full dark mode or keep a consistent background tone throughout. If contrast is needed, use a slightly darker shade of the same palette — not a sudden jump to `#111` in the middle of a cream page.
+- **Empty, flat sections with no visual depth.** Sections that are just text on a plain background feel unfinished. Add high-quality background imagery (blurred, overlaid, or masked), subtle patterns, or ambient gradients. Use reliable placeholder sources like `https://picsum.photos/seed/{name}/1920/1080` when real assets are not available. Experiment with background images behind hero sections, feature blocks, or CTAs — even a subtle full-width photo at low opacity adds presence.
+
+### Layout
+
+- **Everything centered and symmetrical.** Break symmetry with offset margins, mixed aspect ratios, or left-aligned headers over centered content.
+- **Three equal card columns as feature row.** This is the most generic AI layout. Replace with a 2-column zig-zag, asymmetric grid, horizontal scroll, or masonry layout.
+- **Using `height: 100vh` for full-screen sections.** Replace with `min-height: 100dvh` to prevent layout jumping on mobile browsers (iOS Safari viewport bug).
+- **Complex flexbox percentage math.** Replace with CSS Grid for reliable multi-column structures.
+- **No max-width container.** Add a container constraint (around 1200-1440px) with auto margins so content doesn't stretch edge-to-edge on wide screens.
+- **Cards of equal height forced by flexbox.** Allow variable heights or use masonry when content varies in length.
+- **Uniform border-radius on everything.** Vary the radius: tighter on inner elements, softer on containers.
+- **No overlap or depth.** Elements sit flat next to each other. Use negative margins to create layering and visual depth.
+- **Symmetrical vertical padding.** Top and bottom padding are always identical. Adjust optically — bottom padding often needs to be slightly larger.
+- **Dashboard always has a left sidebar.** Try top navigation, a floating command menu, or a collapsible panel instead.
+- **Missing whitespace.** Double the spacing. Let the design breathe. Dense layouts work for data dashboards, not for marketing pages.
+- **Buttons not bottom-aligned in card groups.** When cards have different content lengths, CTAs end up at random heights. Pin buttons to the bottom of each card so they form a clean horizontal line regardless of content above.
+- **Feature lists starting at different vertical positions.** In pricing tables or comparison cards, the list of features should start at the same Y position across all columns. Use consistent spacing above the list or fixed-height title/price blocks.
+- **Inconsistent vertical rhythm in side-by-side elements.** When placing cards, columns, or panels next to each other, align shared elements (titles, descriptions, prices, buttons) across all items. Misaligned baselines make the layout look broken.
+- **Mathematical alignment that looks optically wrong.** Centering by the math doesn't always look centered to the eye. Icons next to text, play buttons in circles, or text in buttons often need 1-2px optical adjustments to feel right.
+
+### Interactivity and States
+
+- **No hover states on buttons.** Add background shift, slight scale, or translate on hover.
+- **No active/pressed feedback.** Add a subtle `scale(0.98)` or `translateY(1px)` on press to simulate a physical click.
+- **Instant transitions with zero duration.** Add smooth transitions (200-300ms) to all interactive elements.
+- **Missing focus ring.** Ensure visible focus indicators for keyboard navigation. This is an accessibility requirement, not optional.
+- **No loading states.** Replace generic circular spinners with skeleton loaders that match the layout shape.
+- **No empty states.** An empty dashboard showing nothing is a missed opportunity. Design a composed "getting started" view.
+- **No error states.** Add clear, inline error messages for forms. Do not use `window.alert()`.
+- **Dead links.** Buttons that link to `#`. Either link to real destinations or visually disable them.
+- **No indication of current page in navigation.** Style the active nav link differently so users know where they are.
+- **Scroll jumping.** Anchor clicks jump instantly. Add `scroll-behavior: smooth`.
+- **Animations using `top`, `left`, `width`, `height`.** Switch to `transform` and `opacity` for GPU-accelerated, smooth animation.
+
+### Content
+
+- **Generic names like "John Doe" or "Jane Smith".** Use diverse, realistic-sounding names.
+- **Fake round numbers like `99.99%`, `50%`, `$100.00`.** Use organic, messy data: `47.2%`, `$99.00`, `+1 (312) 847-1928`.
+- **Placeholder company names like "Acme Corp", "Nexus", "SmartFlow".** Invent contextual, believable brand names.
+- **AI copywriting cliches.** Never use "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve", "Tapestry", or "In the world of...". Write plain, specific language.
+- **Exclamation marks in success messages.** Remove them. Be confident, not loud.
+- **"Oops!" error messages.** Be direct: "Connection failed. Please try again."
+- **Passive voice.** Use active voice: "We couldn't save your changes" instead of "Mistakes were made."
+- **All blog post dates identical.** Randomize dates to appear real.
+- **Same avatar image for multiple users.** Use unique assets for every distinct person.
+- **Lorem Ipsum.** Never use placeholder latin text. Write real draft copy.
+- **Title Case On Every Header.** Use sentence case instead.
+
+### Component Patterns
+
+- **Generic card look (border + shadow + white background).** Remove the border, or use only background color, or use only spacing. Cards should exist only when elevation communicates hierarchy.
+- **Always one filled button + one ghost button.** Add text links or tertiary styles to reduce visual noise.
+- **Pill-shaped "New" and "Beta" badges.** Try square badges, flags, or plain text labels.
+- **Accordion FAQ sections.** Use a side-by-side list, searchable help, or inline progressive disclosure.
+- **3-card carousel testimonials with dots.** Replace with a masonry wall, embedded social posts, or a single rotating quote.
+- **Pricing table with 3 towers.** Highlight the recommended tier with color and emphasis, not just extra height.
+- **Modals for everything.** Use inline editing, slide-over panels, or expandable sections instead of popups for simple actions.
+- **Avatar circles exclusively.** Try squircles or rounded squares for a less generic look.
+- **Light/dark toggle always a sun/moon switch.** Use a dropdown, system preference detection, or integrate it into settings.
+- **Footer link farm with 4 columns.** Simplify. Focus on main navigational paths and legally required links.
+
+### Iconography
+
+- **Lucide or Feather icons exclusively.** These are the "default" AI icon choice. Use Phosphor, Heroicons, or a custom set for differentiation.
+- **Rocketship for "Launch", shield for "Security".** Replace cliche metaphors with less obvious icons (bolt, fingerprint, spark, vault).
+- **Inconsistent stroke widths across icons.** Audit all icons and standardize to one stroke weight.
+- **Missing favicon.** Always include a branded favicon.
+- **Stock "diverse team" photos.** Use real team photos, candid shots, or a consistent illustration style instead of uncanny stock imagery.
+
+### Code Quality
+
+- **Div soup.** Use semantic HTML: `<nav>`, `<main>`, `<article>`, `<aside>`, `<section>`.
+- **Inline styles mixed with CSS classes.** Move all styling to the project's styling system.
+- **Hardcoded pixel widths.** Use relative units (`%`, `rem`, `em`, `max-width`) for flexible layouts.
+- **Missing alt text on images.** Describe image content for screen readers. Never leave `alt=""` or `alt="image"` on meaningful images.
+- **Arbitrary z-index values like `9999`.** Establish a clean z-index scale in the theme/variables.
+- **Commented-out dead code.** Remove all debug artifacts before shipping.
+- **Import hallucinations.** Check that every import actually exists in `package.json` or the project dependencies.
+- **Missing meta tags.** Add proper `<title>`, `description`, `og:image`, and social sharing meta tags.
+
+### Strategic Omissions (What AI Typically Forgets)
+
+- **No legal links.** Add privacy policy and terms of service links in the footer.
+- **No "back" navigation.** Dead ends in user flows. Every page needs a way back.
+- **No custom 404 page.** Design a helpful, branded "page not found" experience.
+- **No form validation.** Add client-side validation for emails, required fields, and format checks.
+- **No "skip to content" link.** Essential for keyboard users. Add a hidden skip-link.
+- **No cookie consent.** If required by jurisdiction, add a compliant consent banner.
+
+## Upgrade Techniques
+
+When upgrading a project, pull from these high-impact techniques to replace generic patterns:
+
+### Typography Upgrades
+- **Variable font animation.** Interpolate weight or width on scroll or hover for text that feels alive.
+- **Outlined-to-fill transitions.** Text starts as a stroke outline and fills with color on scroll entry or interaction.
+- **Text mask reveals.** Large typography acting as a window to video or animated imagery behind it.
+
+### Layout Upgrades
+- **Broken grid / asymmetry.** Elements that deliberately ignore column structure — overlapping, bleeding off-screen, or offset with calculated randomness.
+- **Whitespace maximization.** Aggressive use of negative space to force focus on a single element.
+- **Parallax card stacks.** Sections that stick and physically stack over each other during scroll.
+- **Split-screen scroll.** Two halves of the screen sliding in opposite directions.
+
+### Motion Upgrades
+- **Smooth scroll with inertia.** Decouple scrolling from browser defaults for a heavier, cinematic feel.
+- **Staggered entry.** Elements cascade in with slight delays, combining Y-axis translation with opacity fade. Never mount everything at once.
+- **Spring physics.** Replace linear easing with spring-based motion for a natural, weighty feel on all interactive elements.
+- **Scroll-driven reveals.** Content entering through expanding masks, wipes, or draw-on SVG paths tied to scroll progress.
+
+### Surface Upgrades
+- **True glassmorphism.** Go beyond `backdrop-filter: blur`. Add a 1px inner border and a subtle inner shadow to simulate edge refraction.
+- **Spotlight borders.** Card borders that illuminate dynamically under the cursor.
+- **Grain and noise overlays.** A fixed, pointer-events-none overlay with subtle noise to break digital flatness.
+- **Colored, tinted shadows.** Shadows that carry the hue of the background rather than using generic black.
+
+## Fix Priority
+
+Apply changes in this order for maximum visual impact with minimum risk:
+
+1. **Font swap** — biggest instant improvement, lowest risk
+2. **Color palette cleanup** — remove clashing or oversaturated colors
+3. **Hover and active states** — makes the interface feel alive
+4. **Layout and spacing** — proper grid, max-width, consistent padding
+5. **Replace generic components** — swap cliche patterns for modern alternatives
+6. **Add loading, empty, and error states** — makes it feel finished
+7. **Polish typography scale and spacing** — the premium final touch
+
+## Rules
+
+- Work with the existing tech stack. Do not migrate frameworks or styling libraries.
+- Do not break existing functionality. Test after every change.
+- Before importing any new library, check the project's dependency file first.
+- If the project uses Tailwind, check the version (v3 vs v4) before modifying config.
+- If the project has no framework, use vanilla CSS.
+- Keep changes reviewable and focused. Small, targeted improvements over big rewrites.

package/dist/skills/agnostic/planning/create-plan/REFERENCE.md

@@ -0,0 +1,37 @@
+# Create Plan Reference
+
+`create-plan` is the wrapper. Do not merely mention the inner skills. Execute their behavior inside one planning run and stop only after the plan artifact and backlog sync are complete.
+
+## Required inner skills
+
+- MUST use `$grill-me`
+- MUST use `$swarm-planner`
+- MUST use `$tdd`
+- `opensrc` provides source context for installed or external packages
+- scoped `AGENTS.md` files provide per-path skill requirements through `Primary skills here`
+
+## Phase map
+
+1. Read current repo state and derive as much context as possible before asking.
+2. Run the ambiguity-reduction phase:
+   - see [references/grill-phase.md](references/grill-phase.md)
+3. Run the task-graph phase:
+   - see [references/planner-phase.md](references/planner-phase.md)
+4. Run the TDD shaping phase:
+   - see [references/tdd-phase.md](references/tdd-phase.md)
+5. Normalize the saved plan using:
+   - [references/plan-schema.md](references/plan-schema.md)
+6. Sync backlog items using:
+   - [references/backlog-sync.md](references/backlog-sync.md)
+7. Stop using:
+   - [references/stop-conditions.md](references/stop-conditions.md)
+
+## Global rules
+
+- Keep the skill host-agnostic.
+- Keep the user's sense of control explicit through visible state summaries, not implied progress.
+- Derive repo ownership and hosting from git state instead of hardcoding assumptions.
+- If a required tool is unavailable, stop clearly and report the missing dependency.
+- Keep the canonical backlog model aligned with [../write-backlog/assets/concepts/backlog-model.md](../write-backlog/assets/concepts/backlog-model.md).
+- For every planned task, locate the relevant scoped `AGENTS.md` chain and assign the existing skills that the executor must load before editing.
+- Never start implementation from this skill.

package/dist/skills/agnostic/planning/create-plan/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: create-plan
+description: Creates execution-ready `PLAN.md` artifacts by explicitly wrapping `grill-me`, `swarm-planner`, and `tdd` into one planning run. Use when work must be decomposed before coding, especially for reviewed spec workflows, multi-agent execution, branch-scoped delivery, or any task that needs explicit dependencies, backlog items, review gates, and per-task RED targets.
+---
+
+# Create Plan
+
+## Contract
+
+- **Role:** higher-order planning orchestrator
+- **Entrypoint type:** public entrypoint
+- **Upstream:** approved `SPEC.md` or explicit planning request
+- **Delegates to:** `$grill-me`, `$swarm-planner`, `$tdd`
+- **Downstream:** execution-ready `PLAN.md` for `implement-spec`
+- **Entry conditions:** scope is clear enough to plan; stop if required planning inputs or tools are missing
+- **Stop conditions:** `PLAN.md` and backlog sync are complete; no implementation started
+
+## Required Inner Skills
+
+- MUST use `$grill-me`
+- MUST use `$swarm-planner`
+- MUST use `$tdd`
+
+Create a plan first. Never implement code in this skill.
+
+## Quick start
+
+1. Read repo, git, existing plan, and backlog context before asking questions.
+2. Keep a visible planning control panel in the conversation: locked decisions, open decisions, current phase, and next step.
+3. Read `references/grill-phase.md` and run `$grill-me` as an explicit inner phase.
+4. Update a running decision ledger after every answer so the user never has to reconstruct state from memory.
+5. Insert a synthesis checkpoint before the thread gets noisy, then continue only if more ambiguity reduction is still needed.
+6. Research with `opensrc path <package>` or `opensrc path <owner>/<repo>` plus primary-source web docs when current behavior matters.
+7. Locate scoped `AGENTS.md` files for every planned task path and extract `Primary skills here` lists.
+8. Read `references/planner-phase.md` and run `$swarm-planner` as an explicit inner phase.
+9. Read `references/tdd-phase.md` and run `$tdd` as an explicit inner phase.
+10. Read `references/backlog-sync.md` and sync backlog at epic/story level, not one item per plan task.
+11. Read `references/stop-conditions.md` and stop exactly there.
+
+## Workflows
+
+### Default workflow
+
+1. Derive host, owner, tracker, and scope from repo state instead of assuming them.
+2. Ask only for missing high-impact inputs such as scope, goal, or backlog target.
+3. Every plan-shaping question must use the exact block: `Decision`, `Recommendation`, `Question`, `Why it matters`.
+4. Keep `$grill-me`, `$swarm-planner`, and `$tdd` as visible required inner phases of one planning run.
+5. Resolve each task's scoped guidance from root `AGENTS.md` down to the nearest `AGENTS.md` for its `location`.
+6. Assign each task the exact existing skills required by those scoped `Primary skills here` lists, merging all scopes for cross-directory tasks.
+7. Normalize every task with stable ids, `depends_on`, `location`, `description`, `validation`, `status`, `log`, `files edited/created`, owning-story backlog references, `assigned_skills`, `tdd_target`, and `review_mode`.
+8. Keep the saved plan standalone: include situation, issue, solution shape, assumptions, findings, research, dependency graph, testing strategy, skill-routing notes, risks, validation gates, unresolved questions, and a resolved decision ledger.
+9. Stop after plan creation and backlog sync. Do not implement code or spawn implementation workers.
+
+### Review modes
+
+- `cli`: tests, commands, APIs, non-visual validation
+- `browser`: interactive UI validation
+- `mixed`: both are required
+
+## Advanced features
+
+See [REFERENCE.md](REFERENCE.md) for the overview and phase map.
+
+- Grill / ambiguity-reduction phase: see [references/grill-phase.md](references/grill-phase.md)
+- Planner / task-graph phase: see [references/planner-phase.md](references/planner-phase.md)
+- TDD shaping phase: see [references/tdd-phase.md](references/tdd-phase.md)
+- `PLAN.md` schema and task contract: see [references/plan-schema.md](references/plan-schema.md)
+- Backlog sync rules: see [references/backlog-sync.md](references/backlog-sync.md)
+- Stop conditions: see [references/stop-conditions.md](references/stop-conditions.md)

package/dist/skills/agnostic/planning/create-plan/references/backlog-sync.md

@@ -0,0 +1,44 @@
+# Backlog Sync
+
+Use this reference after the plan structure is complete.
+
+## Sync rules
+
+Use the canonical backlog model from [../../write-backlog/assets/concepts/backlog-model.md](../../write-backlog/assets/concepts/backlog-model.md).
+
+Sync backlog at epic/story level, not at plan-task level.
+
+Defaults:
+
+- epic = one future `SPEC.md`
+- story = product-facing backlog item
+- task = internal `PLAN.md` execution unit only
+
+Task rules:
+
+- every task stores the owning story in `backlog_item_id` / `backlog_item_url`
+- multiple tasks may reference the same story
+- do not create a new backlog item only because a story needs multiple execution tasks
+
+Create or update backlog items only when:
+
+- a required product-facing epic is missing
+- a required product-facing story is missing
+- native story blockers/order need sync
+- epic/story links to spec or plan context need refresh
+
+Do not turn epic or story bodies into execution handoffs.
+
+If planning needs to backfill detail into the backlog:
+
+- prefer native hierarchy, blockers, state, labels, and links
+- keep bodies product-facing
+- reserve execution detail for repo artifacts
+
+Track hierarchy and dependencies natively when supported.
+
+Only use prose fallback when the provider cannot express the primitive natively.
+
+Record referenced or created epic/story ids and URLs back into the plan.
+
+Prefer the selected backlog system's native CLI or tool when available.

package/dist/skills/agnostic/planning/create-plan/references/grill-phase.md

@@ -0,0 +1,86 @@
+# Grill Phase
+
+Use this reference for the ambiguity-reduction phase.
+
+## Goal
+
+Reduce ambiguity before the plan hardens.
+
+## Run inputs
+
+Infer as much as possible from:
+
+- the checkout
+- git remotes
+- existing plans
+- docs
+- issues
+- backlog references
+
+Ask only for missing high-impact inputs:
+
+- domain or scope
+- goal statement or issue set
+- backlog target
+- backlog context required by that target
+
+## Operator-visible control panel
+
+Before the first question, keep the current state obvious:
+
+- current phase
+- locked decisions
+- open decisions
+- next step
+
+## Question-block contract
+
+Every plan-shaping question must contain exactly these headings, in this order:
+
+- `Decision`
+- `Recommendation`
+- `Question`
+- `Why it matters`
+
+Rules:
+
+- never replace the `Question` line with only a recommendation
+- never emit an empty or implied question
+- if the block is malformed, regenerate it before continuing
+- keep the recommendation concise and opinionated
+
+## Grill behavior
+
+Preserve `$grill-me` behavior:
+
+- ask one question at a time
+- provide a recommended answer with each question
+- if a question can be answered from the codebase, answer it by inspecting instead
+- keep grilling until every plan-shaping branch is resolved enough to plan safely
+- when the user leaves a branch open, record the assumption explicitly in the plan
+
+## Decision ledger
+
+After every user answer, restate:
+
+- decisions locked
+- assumptions made
+- still-open decisions
+
+This ledger must stay visible both in the conversation and in the saved plan artifact.
+
+## Synthesis checkpoints
+
+Emit a checkpoint summary when either condition is hit:
+
+- five plan-shaping decisions have been resolved since the last checkpoint
+- the planning exchange has become long enough that the user could reasonably lose orientation
+
+A checkpoint must summarize:
+
+- current situation
+- decisions locked so far
+- open decisions still blocking the plan
+- whether more questions are actually needed
+
+If ambiguity is already low enough, stop asking questions and move to plan synthesis.

package/dist/skills/agnostic/planning/create-plan/references/plan-schema.md

@@ -0,0 +1,66 @@
+# Plan Schema
+
+Use this reference to normalize `PLAN.md` for execution.
+
+## Plan contract
+
+The generated `PLAN.md` is the execution handoff. It must stand alone without hidden context.
+
+Include:
+
+- initial situation
+- issue or problem statement
+- proposed solution shape
+- resolved decision ledger
+- assumptions and constraints
+- codebase findings
+- external research used
+- dependency graph
+- parallel execution waves
+- testing strategy
+- risks and mitigations
+- validation gates per phase when phases exist
+- unresolved questions
+
+## Task contract
+
+Every task must include:
+
+- stable task id
+- `depends_on`
+- `location`
+- `description`
+- `validation`
+- `status`
+- `log`
+- `files edited/created`
+- `backlog_item_id`
+- `backlog_item_url`
+- `relation_mode`
+- `assigned_skills`
+- `tdd_target`
+- `review_mode`
+
+`backlog_item_id` and `backlog_item_url` reference the owning product-facing story, not a task-owned backlog record.
+
+Multiple tasks may point to the same story when one story needs several execution steps.
+
+Do not create a new backlog item only because a task boundary exists in the plan.
+
+```md
+### T3: Example task
+
+- **depends_on**: [T1, T2]
+- **location**: src/example.ts
+- **description**: Implement the task behavior.
+- **validation**: Public-interface behavior that proves completion.
+- **status**: Planned
+- **log**:
+- **files edited/created**:
+- **backlog_item_id**: CP-128
+- **backlog_item_url**: https://linear.app/workspace/issue/CP-128/example-story
+- **relation_mode**: native | body-links
+- **assigned_skills**: [`effect-authoring`, `effect-best-practices`, `tdd`]
+- **tdd_target**: First failing public behavior to implement.
+- **review_mode**: cli | browser | mixed
+```

package/dist/skills/agnostic/planning/create-plan/references/planner-phase.md

@@ -0,0 +1,39 @@
+# Planner Phase
+
+Use this reference for the `$swarm-planner` phase.
+
+## Research before task design
+
+Use `opensrc path <package>` or `opensrc path <owner>/<repo>` when source context from installed or external packages matters.
+
+Use web search when `opensrc` is insufficient or when current API behavior matters.
+
+Prefer primary sources.
+
+## Scoped skill routing
+
+Before finalizing task boundaries:
+
+1. List every concrete `location` each task may touch.
+2. For each location, inspect the `AGENTS.md` chain from repo root to the nearest scoped file.
+3. Extract every `Primary skills here` entry from applicable scoped files.
+4. Verify each named skill exists in `.agents/skills/` or an installed skill source visible to the agent.
+5. Add the merged, deduplicated list to the task as `assigned_skills`.
+
+If a task spans multiple scopes, include all required skills from all touched scopes. If a scope names a missing skill, keep the task planned but record the missing skill in risks and unresolved questions.
+
+## Planner behavior
+
+Produce exactly one named `PLAN.md` in the target spec folder.
+
+Preserve `$swarm-planner` behavior:
+
+- explicit task ids and `depends_on`
+- atomic tasks sized for one worker
+- validations per task
+- parallel execution waves
+- risks and mitigations
+- explicit `assigned_skills` per task from scoped `AGENTS.md`
+- a final subagent review for missing deps, ordering issues, edge cases, and holes before yielding
+
+Do not stop between the grill and planner phases unless a true blocking ambiguity remains.

package/dist/skills/agnostic/planning/create-plan/references/stop-conditions.md

@@ -0,0 +1,18 @@
+# Stop Conditions
+
+Use this reference to close the planning run.
+
+## Stop here
+
+Yield after planning.
+
+Stop after:
+
+- the plan file is complete
+- backlog sync is complete
+
+Do not:
+
+- spawn implementation workers
+- edit code beyond the plan artifact
+- drift into implementation discussion that belongs in execution

package/dist/skills/agnostic/planning/create-plan/references/tdd-phase.md

@@ -0,0 +1,26 @@
+# TDD Phase
+
+Use this reference for the `$tdd` shaping phase across execution tasks.
+
+## TDD shaping rules
+
+Preserve `$tdd` behavior:
+
+- surface the public interface change and the behavior priority behind the task
+- identify deep-module or testability opportunities while task boundaries are still fluid
+- define the first public-interface behavior that should fail before implementation
+- prefer integration-style behavior through public interfaces
+- avoid implementation-detail or private-method testing
+- avoid horizontal slicing; every task should represent a RED -> GREEN tracer bullet
+- make the first failing test concrete enough that a worker can start without guessing
+- do not leave TDD intent implicit or hidden outside the saved plan artifact
+
+## Execution metadata
+
+`tdd_target` must name one public behavior to prove first.
+
+`review_mode` must be:
+
+- `cli` for tests, commands, APIs, or non-visual validation
+- `browser` for interactive UI validation
+- `mixed` when both are required

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

@@ -0,0 +1,57 @@
+---
+name: create-spec
+description: Create a SPEC.md file for a new feature, product, or system using the Spec-Driven Development (SDD) approach. The spec works in the problem space — it clarifies the "what", not the "how", and when backlog context exists it maps to one epic/capability and must unify all child-story requirements beneath it. Use this skill whenever the user wants to write a spec, define requirements, capture what needs to be built, create a specification document, or start the SDD workflow.
+---
+
+# Spec Creator
+
+## Contract
+
+- **Role:** higher-order spec authoring skill
+- **Entrypoint type:** public entrypoint
+- **Upstream:** new idea, feature request, epic/capability issue, or problem statement
+- **Delegates to:** none
+- **Downstream:** reviewed `SPEC.md`, then usually `create-plan` or `implement-spec`
+- **Entry conditions:** wiki domain can be resolved, or the user creates one first with `create-wiki-domain`
+- **Stop conditions:** `SPEC.md`, wiki index, and wiki log are updated, then wait for user review
+
+This skill creates `SPEC.md` files that stay in the problem space: what to build, who it is for, why it matters, what counts as done, and what is out of scope.
+
+When backlog context exists, one `SPEC.md` maps to one parent epic/capability issue and must cover the full scope of that epic. If the epic has child stories, the spec must explicitly incorporate and unify the requirements of all of them.
+
+The output lives at `apps/wiki/specs/<domain>/<folder-name>/SPEC.md`.
+
+## Quick start
+
+1. Read `apps/wiki/AGENTS.md` first. Stop if the wiki is not bootstrapped.
+2. Read `references/discovery.md` and orient yourself in the right wiki domain before asking questions.
+3. If backlog context exists, read the parent epic and every child story before asking questions.
+4. If the user did not provide a concrete request, ask for a rough description first.
+5. Read `references/questioning.md` and ask only the clarifying questions needed to write a trustworthy spec.
+6. Read `references/folder-naming.md` to resolve the domain and spec folder path.
+7. Read `assets/SPEC-TEMPLATE.md` and write the spec.
+8. Read `references/spec-quality-bar.md` before saving.
+9. Read `references/wiki-bookkeeping.md` to update `index.md`, `<domain>-specs.md`, and `log.md`.
+10. Read `references/handoff.md` to choose the next-step recommendation and stop after user review.
+
+## Workflow
+
+### Default workflow
+
+1. Build orientation first; do not jump straight into writing.
+2. Ask only enough to make the spec crisp, testable, and bounded.
+3. When an epic has child stories, harvest and preserve each story's requirements before drafting.
+4. Keep the spec free of implementation detail.
+5. Use the template structure exactly, then remove all template scaffolding.
+6. Update wiki bookkeeping in the same run.
+7. Stop after presenting the spec and the recommended next step.
+
+## Advanced features
+
+- Discovery and repo orientation: see [references/discovery.md](references/discovery.md)
+- Clarifying-question strategy: see [references/questioning.md](references/questioning.md)
+- Domain and folder naming rules: see [references/folder-naming.md](references/folder-naming.md)
+- Acceptance-criteria and quality bar: see [references/spec-quality-bar.md](references/spec-quality-bar.md)
+- Wiki index and log updates: see [references/wiki-bookkeeping.md](references/wiki-bookkeeping.md)
+- Review closeout and next-step routing: see [references/handoff.md](references/handoff.md)
+- Canonical backlog model: see [../write-backlog/assets/concepts/backlog-model.md](../write-backlog/assets/concepts/backlog-model.md)