brunovskyoliver 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# brunovskyoliver skills
+
+Personal agent skill bundle installable with the `skills` CLI.
+
+## Install
+
+Preferred install through the `skills` CLI:
+
+```bash
+npx skills@latest add brunovskyoliver/skills --all -g --copy
+```
+
+Install only for Codex and Claude Code:
+
+```bash
+npx skills@latest add brunovskyoliver/skills -g --agent codex claude-code --skill '*' --copy -y
+```
+
+## Git-free install
+
+If Git is not installed, use the npm package installer instead. This works on macOS,
+Windows, and Linux with Node/npm only:
+
+```bash
+npx brunovskyoliver@latest
+```
+
+Install only for Codex and Claude Code:
+
+```bash
+npx brunovskyoliver@latest --agent codex claude
+```
+
+Replace existing installed skills:
+
+```bash
+npx brunovskyoliver@latest --force
+```
+
+## List available skills
+
+```bash
+npx skills@latest add brunovskyoliver/skills --list --full-depth
+```
+
+With the Git-free installer:
+
+```bash
+npx brunovskyoliver@latest --list
+```

package/bin/install-skills.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..");
+const bundledSkillsRoot = path.join(packageRoot, "skills");
+
+const args = process.argv.slice(2);
+
+function has(flag) {
+  return args.includes(flag);
+}
+
+function valuesAfter(flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return [];
+
+  const values = [];
+  for (let i = index + 1; i < args.length; i += 1) {
+    if (args[i].startsWith("-")) break;
+    values.push(args[i]);
+  }
+  return values;
+}
+
+function usage() {
+  console.log(`brunovskyoliver skill installer
+
+Usage:
+  npx brunovskyoliver@latest [options]
+
+Options:
+  --agent <agents...>   universal, codex, claude, or all
+  --skill <skills...>   Skill names to install. Defaults to all.
+  --force              Replace existing skill directories.
+  --list               List bundled skills without installing.
+  --dry-run            Show what would be installed.
+  --help               Show this help.
+
+Examples:
+  npx brunovskyoliver@latest
+  npx brunovskyoliver@latest --agent codex claude
+  npx brunovskyoliver@latest --skill ralph to-prd to-issues --force
+`);
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findSkills(dir) {
+  const found = [];
+
+  async function walk(current) {
+    const entries = await fs.readdir(current, { withFileTypes: true });
+
+    if (entries.some((entry) => entry.isFile() && entry.name === "SKILL.md")) {
+      found.push({
+        name: path.basename(current),
+        source: current,
+      });
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      await walk(path.join(current, entry.name));
+    }
+  }
+
+  await walk(dir);
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function selectedTargets() {
+  const home = os.homedir();
+  const agents = valuesAfter("--agent");
+  const requested = agents.length > 0 ? agents : ["universal", "codex", "claude"];
+  const normalized = new Set(requested.map((agent) => agent.toLowerCase()));
+
+  if (normalized.has("all")) {
+    normalized.add("universal");
+    normalized.add("codex");
+    normalized.add("claude");
+  }
+
+  const targets = [];
+
+  if (normalized.has("universal") || normalized.has("agents")) {
+    targets.push({
+      name: "universal",
+      root: path.join(home, ".agents", "skills"),
+    });
+  }
+
+  if (normalized.has("codex")) {
+    targets.push({
+      name: "codex",
+      root: path.join(process.env.CODEX_HOME || path.join(home, ".codex"), "skills"),
+    });
+  }
+
+  if (normalized.has("claude") || normalized.has("claude-code")) {
+    targets.push({
+      name: "claude",
+      root: path.join(process.env.CLAUDE_CONFIG_DIR || path.join(home, ".claude"), "skills"),
+    });
+  }
+
+  if (targets.length === 0) {
+    throw new Error(`No supported agents selected: ${requested.join(", ")}`);
+  }
+
+  return targets;
+}
+
+async function main() {
+  if (has("--help") || has("-h")) {
+    usage();
+    return;
+  }
+
+  const skills = await findSkills(bundledSkillsRoot);
+  const requestedSkills = valuesAfter("--skill");
+  const requestedSet = new Set(requestedSkills);
+  const selectedSkills = requestedSkills.length === 0 || requestedSet.has("*")
+    ? skills
+    : skills.filter((skill) => requestedSet.has(skill.name));
+
+  if (has("--list")) {
+    for (const skill of skills) console.log(skill.name);
+    return;
+  }
+
+  const missing = requestedSkills.filter((name) => name !== "*" && !skills.some((skill) => skill.name === name));
+  if (missing.length > 0) {
+    throw new Error(`Unknown skill(s): ${missing.join(", ")}`);
+  }
+
+  const targets = selectedTargets();
+  const force = has("--force");
+  const dryRun = has("--dry-run");
+  let installed = 0;
+  let skipped = 0;
+
+  for (const target of targets) {
+    await fs.mkdir(target.root, { recursive: true });
+
+    for (const skill of selectedSkills) {
+      const destination = path.join(target.root, skill.name);
+
+      if (await exists(destination)) {
+        if (!force) {
+          console.log(`skip ${target.name}:${skill.name} already exists`);
+          skipped += 1;
+          continue;
+        }
+
+        if (!dryRun) await fs.rm(destination, { recursive: true, force: true });
+      }
+
+      if (dryRun) {
+        console.log(`install ${target.name}:${skill.name} -> ${destination}`);
+      } else {
+        await fs.cp(skill.source, destination, { recursive: true });
+        console.log(`installed ${target.name}:${skill.name} -> ${destination}`);
+      }
+
+      installed += 1;
+    }
+  }
+
+  const action = dryRun ? "Would install" : "Installed";
+  console.log(`${action} ${installed} skill target(s), skipped ${skipped}.`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});
+

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "brunovskyoliver",
+  "version": "0.1.0",
+  "description": "Personal agent skill bundle for the skills CLI",
+  "type": "module",
+  "bin": {
+    "brunovskyoliver": "./bin/install-skills.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brunovskyoliver/skills.git"
+  }
+}

package/skills/deprecated/README.md

@@ -0,0 +1,8 @@
+# Deprecated
+
+Skills I no longer use.
+
+- **[design-an-interface](./design-an-interface/SKILL.md)** — Generate multiple radically different interface designs for a module using parallel sub-agents.
+- **[qa](./qa/SKILL.md)** — Interactive QA session where user reports bugs conversationally and the agent files GitHub issues.
+- **[request-refactor-plan](./request-refactor-plan/SKILL.md)** — Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue.
+- **[ubiquitous-language](./ubiquitous-language/SKILL.md)** — Extract a DDD-style ubiquitous language glossary from the current conversation.

package/skills/deprecated/design-an-interface/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: design-an-interface
+description: Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".
+---
+
+# Design an Interface
+
+Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
+
+## Workflow
+
+### 1. Gather Requirements
+
+Before designing, understand:
+
+- [ ] What problem does this module solve?
+- [ ] Who are the callers? (other modules, external users, tests)
+- [ ] What are the key operations?
+- [ ] Any constraints? (performance, compatibility, existing patterns)
+- [ ] What should be hidden inside vs exposed?
+
+Ask: "What does this module need to do? Who will use it?"
+
+### 2. Generate Designs (Parallel Sub-Agents)
+
+Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
+
+```
+Prompt template for each sub-agent:
+
+Design an interface for: [module description]
+
+Requirements: [gathered requirements]
+
+Constraints for this design: [assign a different constraint to each agent]
+- Agent 1: "Minimize method count - aim for 1-3 methods max"
+- Agent 2: "Maximize flexibility - support many use cases"
+- Agent 3: "Optimize for the most common case"
+- Agent 4: "Take inspiration from [specific paradigm/library]"
+
+Output format:
+1. Interface signature (types/methods)
+2. Usage example (how caller uses it)
+3. What this design hides internally
+4. Trade-offs of this approach
+```
+
+### 3. Present Designs
+
+Show each design with:
+
+1. **Interface signature** - types, methods, params
+2. **Usage examples** - how callers actually use it in practice
+3. **What it hides** - complexity kept internal
+
+Present designs sequentially so user can absorb each approach before comparison.
+
+### 4. Compare Designs
+
+After showing all designs, compare them on:
+
+- **Interface simplicity**: fewer methods, simpler params
+- **General-purpose vs specialized**: flexibility vs focus
+- **Implementation efficiency**: does shape allow efficient internals?
+- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
+- **Ease of correct use** vs **ease of misuse**
+
+Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
+
+### 5. Synthesize
+
+Often the best design combines insights from multiple options. Ask:
+
+- "Which design best fits your primary use case?"
+- "Any elements from other designs worth incorporating?"
+
+## Evaluation Criteria
+
+From "A Philosophy of Software Design":
+
+**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
+
+**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
+
+**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
+
+**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
+
+## Anti-Patterns
+
+- Don't let sub-agents produce similar designs - enforce radical difference
+- Don't skip comparison - the value is in contrast
+- Don't implement - this is purely about interface shape
+- Don't evaluate based on implementation effort

package/skills/deprecated/qa/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: qa
+description: Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions "QA session".
+---
+
+# QA Session
+
+Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language.
+
+## For each issue the user raises
+
+### 1. Listen and lightly clarify
+
+Let the user describe the problem in their own words. Ask **at most 2-3 short clarifying questions** focused on:
+
+- What they expected vs what actually happened
+- Steps to reproduce (if not obvious)
+- Whether it's consistent or intermittent
+
+Do NOT over-interview. If the description is clear enough to file, move on.
+
+### 2. Explore the codebase in the background
+
+While talking to the user, kick off an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal is NOT to find a fix — it's to:
+
+- Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)
+- Understand what the feature is supposed to do
+- Identify the user-facing behavior boundary
+
+This context helps you write a better issue — but the issue itself should NOT reference specific files, line numbers, or internal implementation details.
+
+### 3. Assess scope: single issue or breakdown?
+
+Before filing, decide whether this is a **single issue** or needs to be **broken down** into multiple issues.
+
+Break down when:
+
+- The fix spans multiple independent areas (e.g. "the form validation is wrong AND the success message is missing AND the redirect is broken")
+- There are clearly separable concerns that different people could work on in parallel
+- The user describes something that has multiple distinct failure modes or symptoms
+
+Keep as a single issue when:
+
+- It's one behavior that's wrong in one place
+- The symptoms are all caused by the same root behavior
+
+### 4. File the GitHub issue(s)
+
+Create issues with `gh issue create`. Do NOT ask the user to review first — just file and share URLs.
+
+Issues must be **durable** — they should still make sense after major refactors. Write from the user's perspective.
+
+#### For a single issue
+
+Use this template:
+
+```
+## What happened
+
+[Describe the actual behavior the user experienced, in plain language]
+
+## What I expected
+
+[Describe the expected behavior]
+
+## Steps to reproduce
+
+1. [Concrete, numbered steps a developer can follow]
+2. [Use domain terms from the codebase, not internal module names]
+3. [Include relevant inputs, flags, or configuration]
+
+## Additional context
+
+[Any extra observations from the user or from codebase exploration that help frame the issue — e.g. "this only happens when using the Docker layer, not the filesystem layer" — use domain language but don't cite files]
+```
+
+#### For a breakdown (multiple issues)
+
+Create issues in dependency order (blockers first) so you can reference real issue numbers.
+
+Use this template for each sub-issue:
+
+```
+## Parent issue
+
+#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"
+
+## What's wrong
+
+[Describe this specific behavior problem — just this slice, not the whole report]
+
+## What I expected
+
+[Expected behavior for this specific slice]
+
+## Steps to reproduce
+
+1. [Steps specific to THIS issue]
+
+## Blocked by
+
+- #<issue-number> (if this issue can't be fixed until another is resolved)
+
+Or "None — can start immediately" if no blockers.
+
+## Additional context
+
+[Any extra observations relevant to this slice]
+```
+
+When creating a breakdown:
+
+- **Prefer many thin issues over few thick ones** — each should be independently fixable and verifiable
+- **Mark blocking relationships honestly** — if issue B genuinely can't be tested until issue A is fixed, say so. If they're independent, mark both as "None — can start immediately"
+- **Create issues in dependency order** so you can reference real issue numbers in "Blocked by"
+- **Maximize parallelism** — the goal is that multiple people (or agents) can grab different issues simultaneously
+
+#### Rules for all issue bodies
+
+- **No file paths or line numbers** — these go stale
+- **Use the project's domain language** (check UBIQUITOUS_LANGUAGE.md if it exists)
+- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws on line 42"
+- **Reproduction steps are mandatory** — if you can't determine them, ask the user
+- **Keep it concise** — a developer should be able to read the issue in 30 seconds
+
+After filing, print all issue URLs (with blocking relationships summarized) and ask: "Next issue, or are we done?"
+
+### 5. Continue the session
+
+Keep going until the user says they're done. Each issue is independent — don't batch them.

package/skills/deprecated/request-refactor-plan/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: request-refactor-plan
+description: Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
+---
+
+This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Ask whether they have considered other options, and present other options to them.
+
+4. Interview the user about the implementation. Be extremely detailed and thorough.
+
+5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
+
+6. Look in the codebase to check for test coverage of this area of the codebase. If there is insufficient test coverage, ask the user what their plans for testing are.
+
+7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working."
+
+8. Create a GitHub issue with the refactor plan. Use the following template for the issue description:
+
+<refactor-plan-template>
+
+## Problem Statement
+
+The problem that the developer is facing, from the developer's perspective.
+
+## Solution
+
+The solution to the problem, from the developer's perspective.
+
+## Commits
+
+A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.
+
+## Decision Document
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this refactor.
+
+## Further Notes (optional)
+
+Any further notes about the refactor.
+
+</refactor-plan-template>

package/skills/deprecated/ubiquitous-language/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ubiquitous-language
+description: Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
+disable-model-invocation: true
+---
+
+# Ubiquitous Language
+
+Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to a local file.
+
+## Process
+
+1. **Scan the conversation** for domain-relevant nouns, verbs, and concepts
+2. **Identify problems**:
+   - Same word used for different concepts (ambiguity)
+   - Different words used for the same concept (synonyms)
+   - Vague or overloaded terms
+3. **Propose a canonical glossary** with opinionated term choices
+4. **Write to `UBIQUITOUS_LANGUAGE.md`** in the working directory using the format below
+5. **Output a summary** inline in the conversation
+
+## Output Format
+
+Write a `UBIQUITOUS_LANGUAGE.md` file with this structure:
+
+```md
+# Ubiquitous Language
+
+## Order lifecycle
+
+| Term        | Definition                                              | Aliases to avoid      |
+| ----------- | ------------------------------------------------------- | --------------------- |
+| **Order**   | A customer's request to purchase one or more items      | Purchase, transaction |
+| **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request |
+
+## People
+
+| Term         | Definition                                  | Aliases to avoid       |
+| ------------ | ------------------------------------------- | ---------------------- |
+| **Customer** | A person or organization that places orders | Client, buyer, account |
+| **User**     | An authentication identity in the system    | Login, account         |
+
+## Relationships
+
+- An **Invoice** belongs to exactly one **Customer**
+- An **Order** produces one or more **Invoices**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed. A single **Order** can produce multiple **Invoices** if items ship in separate **Shipments**."
+> **Dev:** "So if a **Shipment** is cancelled before dispatch, no **Invoice** exists for it?"
+> **Domain expert:** "Exactly. The **Invoice** lifecycle is tied to the **Fulfillment**, not the **Order**."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — these are distinct concepts: a **Customer** places orders, while a **User** is an authentication identity that may or may not represent a **Customer**.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously in the conversation, call it out in the "Flagged ambiguities" section with a clear recommendation.
+- **Only include terms relevant for domain experts.** Skip the names of modules or classes unless they have meaning in the domain language.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include domain terms.** Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
+- **Group terms into multiple tables** when natural clusters emerge (e.g. by subdomain, lifecycle, or actor). Each group gets its own heading and table. If all terms belong to a single cohesive domain, one table is fine — don't force groupings.
+- **Write an example dialogue.** A short conversation (3-5 exchanges) between a dev and a domain expert that demonstrates how the terms interact naturally. The dialogue should clarify boundaries between related concepts and show terms being used precisely.
+
+<example>
+
+## Example dialogue
+
+> **Dev:** "How do I test the **sync service** without Docker?"
+
+> **Domain expert:** "Provide the **filesystem layer** instead of the **Docker layer**. It implements the same **Sandbox service** interface but uses a local directory as the **sandbox**."
+
+> **Dev:** "So **sync-in** still creates a **bundle** and unpacks it?"
+
+> **Domain expert:** "Exactly. The **sync service** doesn't know which layer it's talking to. It calls `exec` and `copyIn` — the **filesystem layer** just runs those as local shell commands."
+
+</example>
+
+## Re-running
+
+When invoked again in the same conversation:
+
+1. Read the existing `UBIQUITOUS_LANGUAGE.md`
+2. Incorporate any new terms from subsequent discussion
+3. Update definitions if understanding has evolved
+4. Re-flag any new ambiguities
+5. Rewrite the example dialogue to incorporate new terms