@grant-vine/wunderkind 0.15.1 → 0.17.0

package/skills/improve-codebase-architecture/SKILL.md

@@ -1,49 +1,83 @@
 ---
 name: improve-codebase-architecture
 description: >
-  USE FOR: architecture improvement, module boundaries, deep modules, system design,
-  interface design, coupling reduction, dependency review, RFC creation, structural
-  refactoring, design-it-twice exploration.
+  USE FOR: architecture improvement, codebase deepening, module boundaries, seam
+  design, coupling reduction, dependency review, deletion-test analysis, RFC
+  creation, structural refactoring, and AI-navigable interfaces.
 
 ---
 
 # Improve Codebase Architecture
 
-You look for structural friction in the codebase and turn it into a concrete architecture recommendation.
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deeper ones with clearer seams, better locality, and higher leverage.
 
 ## Primary owner
 
 **Owned by:** wunderkind:fullstack-wunderkind
 
-This skill is primarily run by `fullstack-wunderkind`.
+`product-wunderkind` may trigger this skill when recurring delivery pain points point to structural causes, but engineering owns the resulting architecture work.
 
-`product-wunderkind` may trigger it when discovery reveals recurring structural friction, but engineering owns the resulting architecture work.
+## Filesystem scope
 
-## Output target
+Read:
+- `AGENTS.md`
+- `.sisyphus/glossary.md` if present
+- `.sisyphus/rfcs/`
+- existing ADR or docs folders relevant to the area
+- the code paths involved in the candidate refactor
 
-Write an RFC to `.sisyphus/rfcs/<slug>.md`.
+Write:
+- `.sisyphus/rfcs/<slug>.md`
+- optionally `.sisyphus/glossary.md` when the architecture discussion depends on a missing canonical term
 
-## Evaluation lens
+## Architecture language
 
-- Shallow vs deep modules
-- Tight coupling vs replaceable boundaries
-- Confusing interfaces vs hard-to-misuse interfaces
-- Repeated incidental complexity
-- AI navigability and human maintainability
+Use these terms consistently in your analysis:
+
+- **Module** — anything with an interface and implementation: function, class, package, slice, route group, workflow, or subsystem.
+- **Interface** — everything callers must know: types, invariants, ordering, config, error modes, and side effects.
+- **Implementation** — the code hidden behind that interface.
+- **Depth** — how much leverage the interface gives relative to the implementation it hides.
+- **Seam** — where an interface lives and where behavior can change without editing in place.
+- **Adapter** — a concrete implementation that satisfies a seam.
+- **Leverage** — what callers gain from a deep module.
+- **Locality** — what maintainers gain when change and knowledge stay concentrated.
+
+## When to trigger
+
+- A code path feels like a pass-through maze instead of a coherent module.
+- Feature work repeatedly touches too many files for one concept.
+- Tests are hard to write because the real behavior leaks across seams.
+- The user asks for architecture improvement, structural refactoring, or deep-module opportunities.
+- The codebase is becoming harder for humans or agents to navigate safely.
+
+## Anti-triggers
+
+- Do not use for a one-file cleanup or tiny bugfix.
+- Do not use when the main risk is API shape exploration only; prefer `design-an-interface` first.
+- Do not recommend broad rewrites without a migration path.
+- Do not treat "more layers" as architecture quality. Deeper seams matter more than extra wrappers.
 
 ## Process
 
-1. Explore the current module boundaries and dependency shape.
-2. Identify the most painful structural bottlenecks.
-3. Design at least two plausible alternatives before recommending one.
-4. Explain the tradeoffs in terms of correctness, testability, and future change cost.
-5. Write an RFC with migration guidance and verification strategy.
+1. Read the project language first: `AGENTS.md`, `.sisyphus/glossary.md`, and any relevant ADR/RFC history.
+2. Explore the codebase organically and note where understanding one concept requires bouncing across too many shallow modules.
+3. Apply the **deletion test** to suspected shallow modules: if deleting the module simply moves the same complexity into every caller, it was earning its keep; if complexity vanishes, it was probably a pass-through.
+4. Present a numbered list of deepening opportunities. For each candidate include:
+   - files or modules involved
+   - current friction
+   - proposed seam or deeper module
+   - benefits in terms of locality, leverage, and testability
+   - migration risk
+5. Ask the user which candidate to explore before locking an interface or migration plan.
+6. For the selected candidate, design at least two plausible approaches before recommending one.
+7. Write an RFC with migration guidance, risks, and verification strategy.
 
 ## RFC sections
 
 1. Problem
-2. Current pain
-3. Proposed boundary/interface
+2. Current pain and evidence
+3. Proposed seam / module boundary
 4. Alternatives considered
 5. Migration plan
 6. Risks and mitigations
@@ -51,7 +85,16 @@ Write an RFC to `.sisyphus/rfcs/<slug>.md`.
 
 ## Hard rules
 
-1. Do not recommend broad rewrites without a migration path.
-2. Prefer deeper modules and clearer interfaces over surface-level reshuffling.
-3. Show tradeoffs explicitly.
-4. Recommendations must be grounded in current repo evidence.
+1. Ground every recommendation in repo evidence, not generic architecture taste.
+2. Prefer deeper modules and clearer seams over surface-level reshuffling.
+3. Show tradeoffs explicitly using locality, leverage, and testability.
+4. If the conversation depends on a missing domain term, add or update it in `.sisyphus/glossary.md` instead of letting terminology drift.
+5. Never recommend a rewrite without a staged migration path.
+
+## Review gate
+
+This skill is complete only when:
+- at least one real deepening opportunity is evidenced from the repo
+- the recommendation uses consistent seam/depth/locality language
+- an RFC exists at `.sisyphus/rfcs/<slug>.md`
+- the migration path is incremental and verifiable

package/skills/setup-wunderkind-workflow/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: setup-wunderkind-workflow
+description: >
+  USE FOR: repo-local workflow setup, issue flow selection, triage vocabulary,
+  glossary/docs location setup, `.sisyphus` conventions, and adapting
+  Matt-style setup patterns to Wunderkind-native files like `AGENTS.md` and
+  `.sisyphus/*`.
+
+---
+
+# Setup Wunderkind Workflow
+
+Establish the repo-local workflow contract that other Wunderkind skills depend on, without duplicating `wunderkind init` or introducing Matt Pocock's filesystem layout verbatim.
+
+## Primary owner
+
+**Owned by:** wunderkind:product-wunderkind
+
+## Filesystem scope
+
+Read:
+- `AGENTS.md`
+- `CONTEXT.md`
+- `.wunderkind/wunderkind.config.jsonc`
+- `.sisyphus/`
+- docs-output settings if present
+- GitHub readiness signals when issue flow might use GitHub
+
+Write:
+- `AGENTS.md` (update or add a compact workflow-contract section)
+- `CONTEXT.md` (compact current product/domain context for future docs and grilling work)
+- `.sisyphus/glossary.md`
+- `.sisyphus/triage/README.md`
+
+## When to trigger
+
+- The repo needs a clear issue-tracker / PRD / triage contract before skills can operate consistently.
+- A maintainer wants Matt-style setup behavior, but adapted to Wunderkind-native locations.
+- The team has not agreed where glossary, triage, and workflow artifacts should live.
+- `prdPipelineMode`, triage vocabulary, or glossary conventions are confusing or implicit.
+
+## Anti-triggers
+
+- Do not use this to replace `wunderkind init`; `init` still owns baseline config and project bootstrap.
+- Do not invent a second docs tree like `docs/agents/` unless the user explicitly asks for it.
+- Do not mutate `.wunderkind/wunderkind.config.jsonc` unless the user explicitly asks to change config values.
+
+## Decisions to confirm
+
+Walk these one at a time, not all at once:
+
+1. **Workflow backend** — filesystem-first or GitHub-backed PRD / issue flow.
+2. **Triage vocabulary** — the statuses, severity labels, or role terms the team actually uses.
+3. **Domain-language locations** — where glossary and architecture language should live.
+
+## Process
+
+1. Explore the current repo state before proposing anything.
+2. Summarize what already exists in `AGENTS.md`, `CONTEXT.md`, `.wunderkind/`, `.sisyphus/`, and GitHub readiness.
+3. Present one setup decision at a time, with a short explainer and a recommended default.
+4. Show the user the draft workflow contract before writing.
+5. Write the agreed contract into Wunderkind-native locations.
+
+## Required outputs
+
+### `AGENTS.md`
+
+Add or update a compact section summarizing:
+- issue / PRD flow backend
+- triage vocabulary
+- glossary / architecture-doc locations
+
+### `CONTEXT.md`
+
+Create or refresh the compact shared context file that future docs-grilling, planning, and handoff workflows should read first. Keep it short, current, and domain-focused.
+
+### `.sisyphus/triage/README.md`
+
+Record the canonical triage vocabulary and where issue/triage artifacts should live.
+
+### `.sisyphus/glossary.md`
+
+Create or refresh the shared domain glossary if terminology setup is part of the session.
+
+## Hard rules
+
+1. Preserve existing repo conventions where possible; do not flatten them into generic defaults.
+2. Prefer Wunderkind-native locations (`AGENTS.md`, `CONTEXT.md`, `.sisyphus/*`) over Matt's `docs/agents/*` layout.
+3. Confirm each decision with the user before writing.
+4. Keep the written contract concise enough that other skills can read it quickly.
+
+## Review gate
+
+This skill is complete only when the repo has an explicit, readable workflow contract in `AGENTS.md`, the compact shared context in `CONTEXT.md`, triage conventions are written under `.sisyphus/triage/`, and glossary ownership/location is no longer ambiguous.

package/skills/ubiquitous-language/SKILL.md

@@ -1,44 +1,52 @@
 ---
 name: ubiquitous-language
 description: >
-  USE FOR: shared terminology, domain glossary, DDD language, naming alignment,
-  canonical terms, ambiguous terms, synonym resolution, product vocabulary,
-  concept mapping, domain language, glossary generation.
+  USE FOR: glossary maintenance, shared terminology cleanup, naming alignment,
+  canonical terms, alias resolution, domain-language drift, and explicit updates
+  to `.sisyphus/glossary.md`.
 
 ---
 
 # Ubiquitous Language
 
-You create and maintain a shared domain glossary so humans and agents use the same words for the same concepts.
+Maintain a shared domain glossary so humans and agents keep using the same words for the same concepts.
 
-**Owned by:** wunderkind:product-wunderkind
-
-## When to use
+## Primary owner
 
-- Product discovery introduced new domain concepts
-- Multiple terms are being used for the same thing
-- One term is overloaded across different meanings
-- A PRD, plan, or architecture discussion needs cleaner language
+**Owned by:** wunderkind:product-wunderkind
 
 ## Output target
 
 Write or update `.sisyphus/glossary.md`.
 
+## When to trigger
+
+- A term is overloaded or ambiguous and the team needs a canonical definition.
+- Multiple aliases are drifting through PRDs, plans, code comments, or issues.
+- A rename or terminology cleanup needs the glossary updated.
+- Another skill or workflow already established the repo contract, and now the glossary itself needs maintenance.
+
+## Anti-triggers
+
+- Do not use this as the default repo setup workflow; prefer `setup-wunderkind-workflow` for initial workflow/domain setup.
+- Do not use it when the real need is a broader discovery interview; prefer `grill-me` or `prd-pipeline`.
+- Do not hide unresolved ambiguity. Mark it explicitly instead of guessing.
+
 ## What to capture
 
 - Canonical term
-- One-sentence definition
-- Common aliases / deprecated synonyms
-- Related terms and distinctions
-- Open ambiguities still needing resolution
+- Short concrete definition
+- Aliases or deprecated synonyms
+- Related distinctions that prevent future confusion
+- Open questions that still need human resolution
 
 ## Process
 
-1. Scan the conversation, PRD, plan, and relevant repo context.
-2. Extract candidate terms and detect collisions/synonyms.
-3. Choose canonical terms where possible.
-4. Flag unresolved ambiguity explicitly instead of hiding it.
-5. Update `.sisyphus/glossary.md` incrementally if it already exists.
+1. Scan the conversation, PRD, plan, issue, and relevant repo context.
+2. Extract candidate terms and detect collisions or synonym drift.
+3. Choose canonical terms where the evidence is strong.
+4. Mark unresolved ambiguity explicitly instead of forcing false consensus.
+5. Update `.sisyphus/glossary.md` incrementally.
 
 ## Formatting guidance
 
@@ -47,11 +55,15 @@ Prefer a compact markdown table:
 | Term | Definition | Aliases | Notes |
 |---|---|---|---|
 
-Then add an `## Open Questions` section if needed.
+Add an `## Open Questions` section when needed.
 
 ## Hard rules
 
 1. One term should map to one concept whenever possible.
 2. Do not silently merge distinct concepts just because the names sound similar.
 3. Definitions should be short, concrete, and domain-specific.
-4. If a term is unresolved, mark it unresolved instead of guessing.
+4. Keep this skill narrow: glossary quality and naming alignment, not full workflow setup.
+
+## Review gate
+
+This skill is complete only when `.sisyphus/glossary.md` reflects the canonical term decisions and unresolved ambiguities are clearly flagged.