xcoder-dna 0.0.0-stage → 1.3.1

package/dist/skills/skillRouter.d.ts

@@ -0,0 +1,51 @@
+import type { Role } from "../types.js";
+/**
+ * Curated map from Xcoder SDLC's internal Role (see src/types.ts) to the external
+ * SKILL.md names (under the resolved skills directory, e.g. `skills/<name>/
+ * SKILL.md` at the project root) that are safe and relevant to inject for
+ * that role.
+ *
+ * WHY THIS EXISTS: previously, `sub-agent.ts` called `getExternalSkills()`
+ * directly and appended *every* external skill's one-line description to
+ * *every* non-conversation role's prompt, regardless of relevance. That had
+ * two problems:
+ *   1. Noise — a `tester` subtask's prompt would also see one-liners for
+ *      AWS, Kubernetes, DFIR, business-analyst UI design, etc.
+ *   2. Real contradictions — some external skills share a name with a Role
+ *      but describe a different job. The clearest case: the external
+ *      "business-analyst" skill (traditional BRD/FRD/ERP requirements work)
+ *      directly contradicted Xcoder SDLC's hardcoded `business-analyst` Role
+ *      directive, which is deliberately scoped to UI/UX page design only
+ *      (see ROLE_DIRECTIVES["business-analyst"] in ./directives.ts, and the
+ *      separate BA_REQUIREMENTS_DIRECTIVE carved out specifically to keep
+ *      general requirements work OUT of that Role). That skill has since
+ *      been renamed to "enterprise-systems-analyst" and is intentionally
+ *      NOT listed under "business-analyst" below.
+ *
+ * Keep this list conservative: only add a skill here once you've confirmed
+ * its guidance doesn't contradict the hardcoded ROLE_DIRECTIVES entry for
+ * that role. When in doubt, leave it out — an omitted skill just means one
+ * fewer optional hint, but a contradictory one actively confuses the model
+ * about what it's supposed to do.
+ */
+export declare const ROLE_SKILL_ALLOWLIST: Partial<Record<Role, string[]>>;
+export interface RoutedSkillsOptions {
+    skillDir?: string;
+    /**
+     * Cap on how many external skill lines get injected per subtask, so a
+     * role's allowlist growing over time can't unboundedly bloat the prompt.
+     * Default 6.
+     */
+    maxSkills?: number;
+}
+/**
+ * Role-aware replacement for calling getExternalSkills() directly. Returns
+ * only the external skills allowlisted for this specific role, formatted
+ * exactly the way getExternalSkills() already formats them ("name:
+ * description"), so existing callers that treat the result as a flat
+ * string[] keep working unchanged.
+ *
+ * Returns [] when the XCODER_EXTERNAL_SKILLS flag is off, or when the role
+ * has no allowlist entry (e.g. "conversation").
+ */
+export declare function getRoutedExternalSkills(role: Role, opts?: RoutedSkillsOptions): string[];

package/dist/skills/skillRouter.js

@@ -0,0 +1,90 @@
+import { isExternalSkillsEnabled, getExternalSkills } from "./externalSkillLoader.js";
+/**
+ * Curated map from Xcoder SDLC's internal Role (see src/types.ts) to the external
+ * SKILL.md names (under the resolved skills directory, e.g. `skills/<name>/
+ * SKILL.md` at the project root) that are safe and relevant to inject for
+ * that role.
+ *
+ * WHY THIS EXISTS: previously, `sub-agent.ts` called `getExternalSkills()`
+ * directly and appended *every* external skill's one-line description to
+ * *every* non-conversation role's prompt, regardless of relevance. That had
+ * two problems:
+ *   1. Noise — a `tester` subtask's prompt would also see one-liners for
+ *      AWS, Kubernetes, DFIR, business-analyst UI design, etc.
+ *   2. Real contradictions — some external skills share a name with a Role
+ *      but describe a different job. The clearest case: the external
+ *      "business-analyst" skill (traditional BRD/FRD/ERP requirements work)
+ *      directly contradicted Xcoder SDLC's hardcoded `business-analyst` Role
+ *      directive, which is deliberately scoped to UI/UX page design only
+ *      (see ROLE_DIRECTIVES["business-analyst"] in ./directives.ts, and the
+ *      separate BA_REQUIREMENTS_DIRECTIVE carved out specifically to keep
+ *      general requirements work OUT of that Role). That skill has since
+ *      been renamed to "enterprise-systems-analyst" and is intentionally
+ *      NOT listed under "business-analyst" below.
+ *
+ * Keep this list conservative: only add a skill here once you've confirmed
+ * its guidance doesn't contradict the hardcoded ROLE_DIRECTIVES entry for
+ * that role. When in doubt, leave it out — an omitted skill just means one
+ * fewer optional hint, but a contradictory one actively confuses the model
+ * about what it's supposed to do.
+ */
+export const ROLE_SKILL_ALLOWLIST = {
+    "requirements-analyst": ["analyst", "enterprise-systems-analyst", "task-planning"],
+    architect: ["architect", "software-architect", "design-patterns", "solid-principles", "project-scaffolding"],
+    // Deliberately does NOT include "refactorer"-flavored language — see the
+    // updated skills/programmer/SKILL.md description, which was itself
+    // narrowed to new/design-driven implementation for the same reason.
+    programmer: ["programmer", "software-engineer", "design-patterns", "solid-principles", "git-vcs"],
+    // Deliberately excludes "programmer" — that skill's original scope
+    // ("fix bug", "refactor") blurred the boundary Xcoder SDLC's directive draws
+    // between programmer (design-driven implementation) and refactorer
+    // (minimal-diff, no redesign). Give refactorer its own, narrower set.
+    refactorer: ["software-engineer", "design-patterns", "solid-principles", "rca"],
+    tester: ["tester", "qa-engineer", "rca", "performance-tester"],
+    "ui-api-tester": ["playwright-ui-tester", "qa-engineer", "ui-ux-design"],
+    "technical-writer": ["workspace-context"],
+    devops: [
+        "devops", "docker", "docker-expert", "kubernetes", "kubernetes-expert",
+        "aws", "azure", "openshift", "redhat", "rosa", "ubuntu", "git-vcs",
+    ],
+    // "conversation" intentionally omitted: sub-agent.ts already skips
+    // external-skill injection entirely for this role, so listing anything
+    // here would never be used — kept out to avoid implying otherwise.
+    // Intentionally does NOT include "enterprise-systems-analyst" — see the
+    // module doc comment above. This Role is UI/UX-scoped in Xcoder SDLC.
+    "business-analyst": ["ui-ux-design"],
+    "defect-manager": ["rca", "task-planning"],
+    // Deliberately excludes "scrum-master-agent" (a behavioral playbook for
+    // human-team sprint coaching — stand-ups, burndown, retro insights) —
+    // this Role is an internal JSON pass/fail quality gate, a different job,
+    // and it needs a strict, uncluttered prompt to reliably emit clean JSON.
+    "scrum-master": ["scrum-framework"],
+    "system-architect": ["software-architect", "design-patterns", "solid-principles"],
+    "security-lead": ["secops", "advanced-dfir", "ethical-hacking-methodology", "advanced-pentest-lab", "pentester"],
+};
+/**
+ * Role-aware replacement for calling getExternalSkills() directly. Returns
+ * only the external skills allowlisted for this specific role, formatted
+ * exactly the way getExternalSkills() already formats them ("name:
+ * description"), so existing callers that treat the result as a flat
+ * string[] keep working unchanged.
+ *
+ * Returns [] when the XCODER_EXTERNAL_SKILLS flag is off, or when the role
+ * has no allowlist entry (e.g. "conversation").
+ */
+export function getRoutedExternalSkills(role, opts = {}) {
+    if (!isExternalSkillsEnabled())
+        return [];
+    const allowedNames = ROLE_SKILL_ALLOWLIST[role];
+    if (!allowedNames || allowedNames.length === 0)
+        return [];
+    const allowedSet = new Set(allowedNames);
+    const all = getExternalSkills({ skillDir: opts.skillDir }); // ["name: description", ...]
+    const filtered = all.filter((line) => {
+        const sep = line.indexOf(":");
+        const name = sep === -1 ? line : line.slice(0, sep);
+        return allowedSet.has(name);
+    });
+    const max = opts.maxSkills ?? 6;
+    return filtered.slice(0, max);
+}

package/dist/skills/skills-root.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Single source of truth for skill discovery.
+ *
+ * Before this module there were two independent `path.join(..., "skills")`
+ * sites (loadConfig and SkillRegistry) and neither one checked whether the
+ * directory it found actually contained a usable pack. An empty
+ * `~/.xcoder/skills` therefore *shadowed* the bundled packs and the CLI came
+ * up with zero skills — the bug this module exists to fix.
+ *
+ * Resolution order (first USABLE candidate wins, where usable means at least
+ * one pack parses as a valid SkillHeader — never a bare `existsSync`):
+ *
+ *   1. opts.skillDir                      (explicit; honoured even if empty)
+ *   2. $XCODER_HOME/skills
+ *   3. ~/.xcoder/skills                   (the fixed home location)
+ *   4. getAppDir()/skills                 (installer layout)
+ *   5. <exeDir>/../share/xcoder/skills    (.deb / macOS / install.sh)
+ *   6. getAppDir()/../skills              (npm dist/)
+ *   7. getAppDir()/../../skills           (source checkout)
+ *   8. cwd/skills
+ *   9. fallback: getAppDir()
+ */
+/** Where a resolved skills root came from, for the debug line and for tests. */
+export type SkillsRootSource = "explicit" | "xcoders-home" | "user-home" | "installer" | "cwd" | "fallback";
+export interface SkillsRoot {
+    /** Directory D such that D/skills is the skills directory. */
+    readonly root: string;
+    /** The skills directory itself (D/skills). */
+    readonly skillsDir: string;
+    readonly source: SkillsRootSource;
+    /** Number of packs that parsed as a valid skill header. */
+    readonly usableCount: number;
+}
+export interface ResolveSkillsRootOptions {
+    skillDir?: string;
+    homeDir?: string;
+    appDir?: string;
+    exeDir?: string;
+}
+/**
+ * Directory the app runs from. Under `bun build --compile` modules live in a
+ * virtual filesystem (`/$bunfs/…`, `B:\~BUN\…`), so use the folder that holds
+ * the executable instead — that is where the installer puts `skills/`.
+ */
+export declare function getAppDir(): string;
+/** The fixed, user-owned location new packs are seeded into: ~/.xcoder/skills. */
+export declare function getUserHomeSkillsDir(homeDir?: string): string;
+/**
+ * Count the packs in `skillsDir` that actually parse.
+ *
+ * This is the usability test that replaces `existsSync`: a directory that
+ * exists but holds no valid pack must not shadow a directory that does.
+ */
+export declare function probeSkillsDir(skillsDir: string): {
+    count: number;
+    names: string[];
+};
+/**
+ * Resolve the skills root, probing each candidate in precedence order and
+ * returning the first one that holds at least one usable pack.
+ */
+export declare function resolveSkillsRoot(opts?: ResolveSkillsRootOptions): SkillsRoot;
+/** Test hook: drop memoised resolutions and allow the debug line again. */
+export declare function resetSkillsRootCache(): void;

package/dist/skills/skills-root.js

@@ -0,0 +1,168 @@
+// xcoder:version 1 | xcoder:task task-f9cf18 | xcoder:updated 2026-11-02T16:14:29.238Z | xcoder:subtask code-st-077ea2
+/**
+ * Single source of truth for skill discovery.
+ *
+ * Before this module there were two independent `path.join(..., "skills")`
+ * sites (loadConfig and SkillRegistry) and neither one checked whether the
+ * directory it found actually contained a usable pack. An empty
+ * `~/.xcoder/skills` therefore *shadowed* the bundled packs and the CLI came
+ * up with zero skills — the bug this module exists to fix.
+ *
+ * Resolution order (first USABLE candidate wins, where usable means at least
+ * one pack parses as a valid SkillHeader — never a bare `existsSync`):
+ *
+ *   1. opts.skillDir                      (explicit; honoured even if empty)
+ *   2. $XCODER_HOME/skills
+ *   3. ~/.xcoder/skills                   (the fixed home location)
+ *   4. getAppDir()/skills                 (installer layout)
+ *   5. <exeDir>/../share/xcoder/skills    (.deb / macOS / install.sh)
+ *   6. getAppDir()/../skills              (npm dist/)
+ *   7. getAppDir()/../../skills           (source checkout)
+ *   8. cwd/skills
+ *   9. fallback: getAppDir()
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { log } from "../util/logger.js";
+import { MAX_PACK_DIRS, resolveSkillDir } from "./skill-path-guard.js";
+import { parseSkillHeaderFile } from "./skill-header.js";
+/**
+ * Directory the app runs from. Under `bun build --compile` modules live in a
+ * virtual filesystem (`/$bunfs/…`, `B:\~BUN\…`), so use the folder that holds
+ * the executable instead — that is where the installer puts `skills/`.
+ */
+export function getAppDir() {
+    const dir = typeof import.meta !== "undefined" && import.meta.dirname
+        ? import.meta.dirname
+        : __dirname;
+    return dir.includes("$bunfs") || dir.includes("~BUN") ? path.dirname(process.execPath) : dir;
+}
+/** The fixed, user-owned location new packs are seeded into: ~/.xcoder/skills. */
+export function getUserHomeSkillsDir(homeDir) {
+    const home = homeDir ?? os.homedir();
+    return path.join(home, ".xcoder", "skills");
+}
+/** Emit the one-per-process debug line naming the resolved root. */
+let debugLogged = false;
+function logResolvedRoot(result) {
+    if (debugLogged || !process.env["XCODER_DEBUG_CONFIG_PATH"])
+        return;
+    debugLogged = true;
+    log.dim(`skillsRoot: ${result.root} (source=${result.source}, packs=${result.usableCount})`);
+}
+/**
+ * Count the packs in `skillsDir` that actually parse.
+ *
+ * This is the usability test that replaces `existsSync`: a directory that
+ * exists but holds no valid pack must not shadow a directory that does.
+ */
+export function probeSkillsDir(skillsDir) {
+    const names = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return { count: 0, names };
+    }
+    let visited = 0;
+    for (const entry of entries) {
+        if (visited >= MAX_PACK_DIRS)
+            break;
+        if (!entry.isDirectory())
+            continue;
+        visited++;
+        const packDir = resolveSkillDir(skillsDir, entry.name);
+        if (!packDir)
+            continue;
+        const parsed = parseSkillHeaderFile(path.join(packDir, "SKILL.md"));
+        if (!parsed.ok || !parsed.header)
+            continue;
+        names.push(parsed.header.name);
+    }
+    return { count: names.length, names };
+}
+function buildCandidates(opts) {
+    const appDir = opts.appDir ?? getAppDir();
+    const exeDir = opts.exeDir ?? path.dirname(process.execPath);
+    const candidates = [];
+    if (process.env["XCODER_HOME"]) {
+        candidates.push({ root: process.env["XCODER_HOME"], source: "xcoders-home" });
+    }
+    candidates.push({
+        root: path.dirname(getUserHomeSkillsDir(opts.homeDir)),
+        source: "user-home",
+    });
+    candidates.push({ root: appDir, source: "installer" });
+    candidates.push({ root: path.join(exeDir, "..", "share", "xcoder"), source: "installer" });
+    candidates.push({ root: path.join(appDir, ".."), source: "installer" });
+    candidates.push({ root: path.join(appDir, "..", ".."), source: "installer" });
+    candidates.push({ root: process.cwd(), source: "cwd" });
+    return candidates;
+}
+/** Memoised results, keyed by the option tuple so an injected dir never aliases. */
+const memo = new Map();
+function memoKey(opts) {
+    return [
+        opts.skillDir ?? "\u0000",
+        opts.homeDir ?? "\u0000",
+        opts.appDir ?? "\u0000",
+        opts.exeDir ?? "\u0000",
+        process.env["XCODER_HOME"] ?? "\u0000",
+        process.cwd(),
+    ].join("\u0001");
+}
+/**
+ * Resolve the skills root, probing each candidate in precedence order and
+ * returning the first one that holds at least one usable pack.
+ */
+export function resolveSkillsRoot(opts = {}) {
+    const key = memoKey(opts);
+    const cached = memo.get(key);
+    if (cached)
+        return cached;
+    let result;
+    if (opts.skillDir) {
+        // Explicit wins even when empty (T2): tests inject a temp dir and assert
+        // zero skills; silently falling back would read the developer's real dir.
+        const skillsDir = path.resolve(opts.skillDir);
+        result = {
+            root: path.dirname(skillsDir),
+            skillsDir,
+            source: "explicit",
+            usableCount: probeSkillsDir(skillsDir).count,
+        };
+    }
+    else {
+        const candidates = buildCandidates(opts);
+        const fallbackRoot = opts.appDir ?? getAppDir();
+        result = {
+            root: fallbackRoot,
+            skillsDir: path.join(fallbackRoot, "skills"),
+            source: "fallback",
+            usableCount: 0,
+        };
+        for (const candidate of candidates) {
+            const skillsDir = path.join(candidate.root, "skills");
+            const probe = probeSkillsDir(skillsDir);
+            if (probe.count > 0) {
+                result = {
+                    root: candidate.root,
+                    skillsDir,
+                    source: candidate.source,
+                    usableCount: probe.count,
+                };
+                break;
+            }
+        }
+    }
+    memo.set(key, result);
+    logResolvedRoot(result);
+    return result;
+}
+/** Test hook: drop memoised resolutions and allow the debug line again. */
+export function resetSkillsRootCache() {
+    memo.clear();
+    debugLogged = false;
+}

package/dist/skills/software-architect/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: software-architect
+role: architecture
+description: System-level design for new services/features/migrations — explicit tradeoffs, failure-mode analysis, and documented decisions instead of implementing the first design that occurs to you.
+triggers:
+  - "architecture"
+  - "design a system"
+  - "system design"
+  - "design doc"
+  - "how should we structure"
+  - "scalability"
+  - "microservice"
+  - "migrate"
+  - "migration plan"
+  - "architecture decision record"
+  - "tech stack"
+version: "1.0.0"
+requires_tools:
+  - read_tool
+  - grep_tool
+  - glob_tool
+  - write_edit_tool
+composes_with:
+  - workspace-context
+  - task-planning
+  - software-engineer
+  - docker
+  - kubernetes
+---
+
+## Process
+
+1. Establish the actual constraints before designing: expected scale (requests/sec, data volume,
+   team size), consistency requirements, latency budget, and what already exists that this must
+   integrate with. A design without stated constraints is a guess, not an architecture.
+2. Identify 2–3 genuinely distinct approaches (not one approach and two straw men) and name the
+   real tradeoff each makes — write these down even in an informal design doc; "we considered X"
+   without the tradeoff is not useful to a future reader.
+3. Design for the failure modes, not just the happy path: what happens when a downstream service
+   is slow, unavailable, or returns bad data; what's the blast radius of one component failing;
+   what's recoverable automatically vs. needs a human.
+4. Draw the boundary between services/modules along data ownership and change-rate, not
+   convenience — two things that change together for unrelated reasons are a sign of a missing
+   boundary; two things that always change together are a sign of an unnecessary one.
+5. Record the decision (an ADR-style note: context, options considered, decision, consequences) so
+   the reasoning survives past the current conversation — a design that only exists as an
+   unexplained set of files is a maintenance liability.
+
+## Instructions — non-negotiable
+
+- Never propose a distributed/microservices architecture to solve a problem a monolith handles
+  fine — the complexity cost (network calls, partial failure, deployment coordination) needs to be
+  justified by an actual scaling or team-boundary need, not defaulted to.
+- State the consistency model explicitly for any design involving more than one data store
+  (eventual vs. strong, and what happens during the inconsistency window) — "it'll sync eventually"
+  without specifying how is not a complete design.
+- Any design that introduces a new external dependency (a new database, queue, cloud service)
+  should name what it replaces or what it enables that wasn't possible before — dependencies are
+  not free.
+
+## Strategies
+
+- Prefer boring, well-understood technology for the parts of the system that aren't the actual
+  differentiator — save novel/complex choices for where they earn their keep.
+- Design for the current known scale plus a reasonable margin, not for a hypothetical 100x that may
+  never materialize — premature scaling design has a real cost in complexity today.
+- When a migration is involved, design the rollback path with the same rigor as the forward path —
+  "we'll just roll back if it fails" is not a plan unless you've specified how.
+
+## Experience
+
+- The most common architecture failure isn't picking the wrong technology, it's an unstated
+  assumption about consistency, ownership, or failure handling that only surfaces in production —
+  make those assumptions explicit in the design doc even when they seem obvious.
+- Boundaries that map to team/ownership structure tend to survive; boundaries that only reflect a
+  snapshot of current code organization tend to get redrawn — factor in who will maintain each
+  piece, not just how the code happens to be organized today.

package/dist/skills/software-engineer/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: software-engineer
+role: engineering
+description: General software engineering discipline for implementation tasks — small verifiable changes, tests before/alongside code, and code that's ready for review rather than "it ran once on my machine."
+triggers:
+  - "implement"
+  - "write code"
+  - "fix the bug"
+  - "fix a bug"
+  - "refactor"
+  - "add a feature"
+  - "code review"
+  - "write a function"
+  - "write tests"
+version: "1.0.0"
+requires_tools:
+  - read_tool
+  - write_edit_tool
+  - grep_tool
+  - glob_tool
+  - run_command_tool
+composes_with:
+  - workspace-context
+  - task-planning
+  - software-architect
+  - qa-engineer
+  - git-vcs
+---
+
+## Process
+
+1. Read the surrounding code before writing any — match existing patterns (naming, error handling,
+   module structure) rather than introducing a new style for one change. `grep_tool`/`glob_tool`
+   for how similar things are already done in this codebase before assuming a convention.
+2. Make the smallest change that correctly solves the stated problem. A "fix the bug" task is not
+   an invitation to also refactor unrelated code nearby — that inflates the diff, makes review
+   harder, and increases the chance of an unrelated regression.
+3. Write or update a test alongside the change, not after being asked. If the codebase has a test
+   framework, use it; if not, at minimum verify manually via `run_command_tool` and say so.
+4. Run the actual test/build/lint commands this project uses (check `package.json` scripts,
+   `Makefile`, or CI config for the real invocation) before declaring the task done — "should work"
+   is not verification.
+5. Handle errors explicitly. Don't swallow exceptions silently, don't return null/undefined for a
+   failure case without the caller having a way to detect it, and don't add a broad try/catch
+   whose only effect is hiding a bug you haven't diagnosed.
+
+## Instructions — non-negotiable
+
+- Never leave `console.log`/`print` debugging statements, commented-out old code, or TODO markers
+  for the exact thing you were asked to do (as opposed to genuinely out-of-scope follow-up work).
+- Match existing naming/formatting conventions exactly — don't introduce camelCase into a
+  snake_case codebase or vice versa for "personal preference" reasons.
+- Never silently change a public function's signature or behavior that other code depends on
+  without updating every call site — `grep_tool` for all usages first.
+- If a fix reveals the same bug pattern exists elsewhere, say so explicitly rather than silently
+  fixing only the one instance mentioned — but don't silently fix the others without flagging it.
+
+## Strategies
+
+- Prefer pure functions and explicit data flow over shared mutable state when adding new code —
+  easier to test, easier for the next person (or the next agent run) to reason about.
+- When two implementation approaches are both reasonable, prefer the one that's more consistent
+  with the rest of the codebase over the one that's abstractly "better," unless the task is
+  specifically about improving that pattern.
+- If a task is ambiguous about behavior at an edge case, pick the interpretation consistent with
+  how the rest of the system handles similar edge cases, and state the assumption.
+
+## Experience
+
+- The most common real defect in agent-authored code is an untested edge case discovered by the
+  next reviewer, not a syntax error — the fix is deliberately testing boundaries (empty input,
+  null, zero, max values, concurrent access) rather than only the example given in the task.
+- Large, unfocused diffs get rejected in review more often than small correct ones — resist the
+  urge to "clean up while I'm in here" unless asked.

package/dist/skills/solid-principles/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: solid-principles
+role: Software Architect / OOP Design Specialist
+description: >
+  Reference guide to the five SOLID object-oriented design principles (Single Responsibility,
+  Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion), complete with
+  directives, violation signs, and fix patterns. Load whenever reviewing class or module design,
+  refactoring coupled code, or evaluating adherence to clean OOP design principles.
+triggers: [solid, "solid principles", "single responsibility", "open closed", "liskov substitution", "interface segregation", "dependency inversion", decouple, refactor, "oop design"]
+version: 1.0
+requires_tools: [read_tool, grep_tool]
+composes_with: [programmer, software-engineer, architect, rca]
+---
+
+# SOLID Principles
+
+A quick-reference guide to the five SOLID principles, each with a directive, signs of violation, and how to fix it.
+
+## How to use this skill
+
+1. If the user names a specific principle, explain the directive and apply it to their code/problem.
+2. If the user pastes code and asks for a review, scan it against the **violation signs** for each principle and flag the ones that apply.
+3. If the user describes a design problem, use the **Quick Decision Guide** to match the symptom to the principle that addresses it.
+4. Don't force all five onto every review — flag what's genuinely relevant, and note tradeoffs (see **General Directives**).
+
+---
+
+## S — Single Responsibility Principle
+**Directive:** A class/module should have only one reason to change.
+**Violation signs:**
+- A class does unrelated things (e.g. a `User` class that also handles email sending and database persistence).
+- Changing one feature risks breaking unrelated functionality.
+- The class name is vague or joined with "and" (`ReportGeneratorAndEmailer`).
+  **Fix:** Split responsibilities into separate classes, each owning one concern; compose them where needed.
+
+---
+
+## O — Open/Closed Principle
+**Directive:** Classes should be open for extension, but closed for modification.
+**Violation signs:**
+- Adding a new case means editing an existing class's internals (e.g. a growing `if/elif` or `switch` chain on type).
+- Every new feature touches the same core file, risking regressions in unrelated cases.
+  **Fix:** Extract the varying behavior behind an interface/abstract class, and add new behavior via new subclasses or implementations instead of editing existing code (Strategy or Factory patterns often apply here).
+
+---
+
+## L — Liskov Substitution Principle
+**Directive:** Subtypes must be substitutable for their base types without breaking correctness.
+**Violation signs:**
+- A subclass overrides a method to throw an exception, do nothing, or narrow what the base type promised.
+- Client code checks the concrete type before calling a method (`if isinstance(x, SubclassY)`).
+- Classic example: `Square extends Rectangle` breaks if `setWidth`/`setHeight` are independent in the base class.
+  **Fix:** Make sure a subclass honors the base class's contract (preconditions no stronger, postconditions no weaker). If it can't, it shouldn't be a subclass — reach for composition or a shared interface instead.
+
+---
+
+## I — Interface Segregation Principle
+**Directive:** Clients shouldn't be forced to depend on methods they don't use.
+**Violation signs:**
+- A large "fat" interface where implementers must stub out irrelevant methods (`throw new NotImplementedException()`).
+- Changing one method's signature forces recompiling/retesting classes that never use it.
+  **Fix:** Split large interfaces into smaller, role-specific ones; classes implement only the interfaces relevant to them.
+
+---
+
+## D — Dependency Inversion Principle
+**Directive:** Depend on abstractions, not concrete implementations. High-level modules shouldn't depend on low-level modules — both should depend on abstractions.
+**Violation signs:**
+- A high-level class directly instantiates a low-level class (`new MySqlDatabase()` inside business logic).
+- Swapping an implementation (e.g. database, payment provider) requires editing high-level code.
+- Hard to unit test because dependencies can't be mocked.
+  **Fix:** Introduce an interface/abstract class between layers; inject the concrete implementation from outside (constructor/dependency injection) rather than instantiating it inline.
+
+---
+
+## Quick Decision Guide
+
+| Symptom | Principle Violated |
+|---|---|
+| Class does too many unrelated things | Single Responsibility |
+| Adding a feature means editing existing code everywhere | Open/Closed |
+| Subclass breaks behavior the base class promised | Liskov Substitution |
+| Class forced to implement methods it doesn't need | Interface Segregation |
+| Business logic tightly coupled to a concrete implementation | Dependency Inversion |
+| Hard to unit test due to hardcoded dependencies | Dependency Inversion |
+| Growing if/else or switch on type | Open/Closed |
+
+---
+
+## General Directives
+- SOLID principles are guidelines, not laws — over-applying them (e.g. an interface for every single class) can add needless indirection. Weigh the cost of abstraction against the actual likelihood of change.
+- SRP and ISP both fight bloat — SRP at the class level, ISP at the interface level.
+- OCP and DIP work together: depending on abstractions (DIP) is usually what *lets* you extend without modifying (OCP).
+- When reviewing code, prioritize violations that cause real pain (hard to test, hard to extend, fragile on change) over theoretical purity.