devcouncil 0.1.1 → 0.3.0

package/src/devcouncil/skills/library/security.md

@@ -0,0 +1,48 @@
+---
+name: security
+title: Application Security / Secure Coding Intake
+description: Before writing security-sensitive code or assessing a vulnerability, retrieve current guidance for the relevant class (injection, authn/z, crypto, deserialization), the project's existing controls, and the right scanning/test commands — like a senior application-security engineer briefing themselves.
+triggers:
+  keywords: [security, vulnerability, "secure coding", hardening, "security audit", pentest, "penetration test", owasp, xss, csrf, ssrf, "sql injection", sqli, rce, deserialization, "path traversal", cryptography, encryption, "threat model", sast, dast, cve, sandbox, "least privilege", "input validation"]
+  globs: [".semgrep.yml", ".semgrep.yaml", "bandit.yaml", ".bandit", "*.nuclei.yaml", "trivy.yaml", ".snyk"]
+---
+
+# Application Security / Secure Coding Intake
+
+Do this **before** writing security-sensitive code or judging a vulnerability. Don't rely on
+training data — attack techniques and recommended mitigations evolve, and a plausible-looking
+fix can be incomplete or introduce a new hole. Confirm against current guidance (OWASP, the
+framework's security docs, the relevant CVE/advisory) and the project's existing controls.
+
+## Establish current state first
+
+1. **Trust boundaries & data flow** — where untrusted input enters and where it reaches a sink
+   (DB, shell, filesystem, deserializer, template, HTTP). Map the path this change touches.
+2. **Vulnerability class & correct mitigation** — identify the class precisely and use the
+   *current* canonical defense: parameterized queries (not escaping) for SQLi; context-aware
+   output encoding for XSS; allow-lists + canonicalization for path/SSRF; safe deserializers;
+   constant-time comparison for secrets. Avoid blacklist/regex "sanitizers."
+3. **AuthN / AuthZ** — every new entry point authenticates and authorizes (object-level too —
+   no IDOR); sessions/tokens follow the project's scheme; deny by default.
+4. **Secrets & crypto** — secrets from a vault/env, never committed or logged; use vetted
+   libraries and current algorithms/parameters (no home-rolled crypto, no MD5/SHA1 for security).
+5. **Dependencies & config** — check for known-vulnerable dependencies and insecure defaults
+   (CORS, headers, TLS, file permissions). Note anything in scope.
+
+## Build & CLI tools
+
+- Static/secret scanning: `semgrep`, `bandit` (Python), `gosec`, `npm audit`/`pip-audit`,
+  `gitleaks`/`trufflehog`, `trivy`/`grype` for images and deps.
+- Dynamic/dependency: the project's DAST/`snyk`/`nuclei` flow where present.
+- Add or update a test that *proves* the vulnerability is closed (a failing-then-passing case),
+  not just that the happy path still works.
+
+## What to record before coding
+
+- The vulnerability class, the trust boundary, and the exact sink involved.
+- The current canonical mitigation chosen (and why a weaker one was rejected).
+- The authz/secret/crypto requirements the change must satisfy.
+- The scan/test commands and the regression test that prove the issue is fixed.
+
+Stay surgical: fix the specific weakness without unrelated refactors, and never weaken an
+existing control as a side effect (see core-engineering).

package/src/devcouncil/skills/library/systems.md

@@ -0,0 +1,48 @@
+---
+name: systems
+title: Systems / Embedded / Native Intake
+description: Before writing native, systems, or embedded code, retrieve current toolchain/standard versions, memory and concurrency rules, undefined-behavior and safety guidance, and the right build/flash/test commands — like a senior systems engineer briefing themselves.
+triggers:
+  keywords: [embedded, firmware, rtos, freertos, zephyr, microcontroller, "bare metal", "bare-metal", no_std, kernel, "device driver", "systems programming", cmake, "c++", cpp, stm32, esp32, arduino, "memory safety", "undefined behavior", simd, mmap, syscall]
+  globs: ["CMakeLists.txt", "*.cpp", "*.cc", "*.hpp", "*.ino", "platformio.ini", "*.ld", "Kconfig", "prj.conf", "sdkconfig", "*.dts"]
+---
+
+# Systems / Embedded / Native Intake
+
+Do this **before** writing or changing native/systems/embedded code. Don't rely on training
+data — toolchains, language standards, and platform constraints change, and a memory or
+concurrency bug here is often silent until it corrupts state or crashes in the field. Confirm
+against the toolchain/standard docs and the project's own build config.
+
+## Establish current state first
+
+1. **Toolchain & standard in use** — read the build config (`CMakeLists.txt`, `Cargo.toml`,
+   `platformio.ini`, `Makefile`): compiler + version, language standard (C11/C++20/Rust edition),
+   target triple/MCU, and `no_std`/freestanding vs hosted. Match what's already there.
+2. **Memory & ownership** — allocation strategy (heap vs static/stack, arenas, no-alloc on
+   embedded), ownership/lifetime rules, and buffer-bounds discipline. Avoid undefined behavior:
+   no use-after-free, no data races, no signed overflow, no aliasing violations.
+3. **Concurrency & interrupts** — what runs in ISR vs task context, shared state and its locking
+   (or lock-free/atomics), `volatile` for MMIO, and memory-ordering requirements.
+4. **Platform constraints** — flash/RAM budget, alignment and endianness, real-time deadlines,
+   and the ABI/calling convention if crossing language or FFI boundaries.
+5. **Safety tooling** — what's available and expected: sanitizers (ASan/UBSan/TSan), static
+   analysis (clang-tidy, cppcheck), `cargo clippy`/`miri`, and valgrind on hosted targets.
+
+## Build & CLI tools
+
+- Build: `cmake --build`, `make`, `cargo build --target ...`, `west build`, `idf.py`,
+  `platformio run`. Use the project's presets/wrapper.
+- Test/verify: `ctest`, `cargo test`/`clippy`/`miri`, unit tests on host, and on-target/HIL or
+  an emulator (QEMU/Renode) when hardware isn't available.
+- Flash/debug: the project's `openocd`/`gdb`/`probe-rs`/`idf.py flash` flow.
+
+## What to record before coding
+
+- The toolchain/standard/target and the exact build config you will use.
+- The memory/ownership and concurrency model for the code you touch, and the UB you must avoid.
+- The platform budget/constraints relevant to the change.
+- The build/sanitizer/test commands (and on-target or emulator run) that prove correctness.
+
+Don't broaden the change beyond the task — no incidental toolchain bumps or refactors across
+unrelated modules (see the surgical-changes rule in core-engineering).

package/src/devcouncil/skills/library/web.md

@@ -0,0 +1,47 @@
+---
+name: web
+title: Web / Frontend Development Intake
+description: Before writing web code, retrieve current framework versions, runtime/build tooling, deprecations, and recommended patterns — like a senior web engineer briefing themselves on the stack.
+triggers:
+  keywords: [web, website, frontend, react, next, nextjs, vue, svelte, angular, typescript, javascript, vite, tailwind, node]
+  globs: ["package.json", "tsconfig.json", "*.tsx", "*.jsx", "*.vue", "*.svelte", "next.config.*", "vite.config.*", "tailwind.config.*"]
+---
+
+# Web / Frontend Development Intake
+
+Do this **before** writing or changing web code. The JS/TS ecosystem moves quickly
+and major versions change defaults and APIs. Confirm against the framework's official
+docs and the project's `package.json` — not from memory.
+
+## Establish current state first
+
+1. **Framework & versions** — read `package.json` (and lockfile): the framework
+   (React/Next, Vue/Nuxt, Svelte/SvelteKit, Angular), its major version, the build
+   tool (Vite, Next, Webpack), the package manager (npm/pnpm/yarn/bun), and the Node
+   version (`engines`, `.nvmrc`). Match what's already in use.
+2. **Latest stable & major-version shifts** — current stable major and any defaults
+   that changed (e.g. React Server Components / the App Router, Vue 3 Composition API,
+   Svelte 5 runes, ESM-only packages). Note what gates this task.
+3. **Deprecations** — APIs/patterns deprecated in the project's major version (e.g.
+   legacy lifecycle methods, `getInitialProps`, options API where composition is
+   preferred). List the ones this change touches and their replacements.
+4. **Recommended patterns** — TypeScript strictness, data-fetching/caching model,
+   state management, styling approach (CSS modules, Tailwind, CSS-in-JS), and
+   accessibility (semantic HTML, ARIA only where needed, keyboard support).
+5. **Guidelines** — performance budgets (Core Web Vitals), accessibility (WCAG), and
+   SSR/CSR/SSG choice relevant to the change.
+
+## Build & CLI tools
+
+- Package manager scripts (`npm run build`/`test`/`lint`, or pnpm/yarn/bun equivalents).
+- The framework CLI (`next`, `vite`, `ng`, `svelte-kit`) for dev/build.
+- `eslint`/`prettier`/`tsc --noEmit` and the test runner (Vitest/Jest/Playwright) if configured.
+
+## What to record before coding
+
+- Framework + major version, build tool, package manager, and Node version.
+- Deprecated patterns to avoid and their modern replacements.
+- The build/test/lint commands you will run so the change is verifiable.
+
+Don't introduce a second styling system or state library when one is already in use,
+and don't bump a major framework version as a side effect of an unrelated task.

package/src/devcouncil/skills/library/windows.md

@@ -0,0 +1,47 @@
+---
+name: windows
+title: Windows App Development Intake
+description: Before writing Windows desktop code, retrieve current .NET/WinUI/WPF versions, supported targets, deprecations, recommended frameworks, and the right CLI/build tools — like a senior Windows engineer.
+triggers:
+  keywords: [windows, wpf, winui, winforms, uwp, win32, dotnet, ".net", csharp, "c#", xaml, maui, msix]
+  globs: ["*.csproj", "*.sln", "*.xaml", "*.cs", "Directory.Build.props", "global.json", "*.vcxproj"]
+---
+
+# Windows App Development Intake
+
+Do this **before** writing or changing Windows desktop code. Confirm against
+Microsoft Learn, the .NET release notes, and the project files — the Windows app
+stack has several overlapping UI frameworks and the right choice depends on targets.
+
+## Establish current state first
+
+1. **Toolchain & targets** — read `*.csproj` / `global.json` / `Directory.Build.props`:
+   `TargetFramework(s)` (e.g. `net8.0-windows`), .NET SDK version, and the UI stack in
+   use (WPF, WinUI 3 / Windows App SDK, WinForms, UWP, or .NET MAUI). Identify which one
+   this file belongs to and stay in it.
+2. **Latest .NET & runtime** — current LTS/STS .NET release and whether the project
+   should target it; note Windows version / Windows App SDK minimums.
+3. **Deprecations & migrations** — UWP is in maintenance; new desktop work generally
+   targets WinUI 3 (Windows App SDK) or WPF on modern .NET. `.NET Framework` (4.x) is
+   legacy — don't introduce it for new code. Note any deprecated APIs the change touches.
+4. **Recommended frameworks** — packaging via MSIX; MVVM (e.g. CommunityToolkit.Mvvm);
+   dependency injection via `Microsoft.Extensions.DependencyInjection`; async/await over
+   blocking calls. Confirm current recommended packages and versions on NuGet.
+5. **Guidelines** — Fluent design, accessibility (UI Automation), and packaging/signing
+   requirements relevant to the change.
+
+## Build & CLI tools
+
+- `dotnet build` / `dotnet test` / `dotnet publish`; `msbuild` for full solutions.
+- `winget` for tooling; `nuget`/`dotnet add package` for dependencies.
+- Visual Studio diagnostics for profiling.
+
+## What to record before coding
+
+- Target framework(s), .NET SDK version, and which UI stack the change belongs to.
+- Deprecated APIs/frameworks to avoid and their modern replacements.
+- The build/test commands you will run (`dotnet test`, `dotnet build -c Release`) so
+  the change is verifiable.
+
+Don't migrate a project between UI frameworks (e.g. WinForms → WinUI) as a side
+effect of an unrelated task.

package/src/devcouncil/skills/registry.py

@@ -0,0 +1,408 @@
+"""DevCouncil skills library: load, select, and scaffold reusable agent skills.
+
+A *skill* is a markdown file with YAML frontmatter describing when it applies. The
+``core-engineering`` skill is always selected; domain skills (android, ios, windows,
+web, ai-training, ...) are selected when the goal text or the repository's files match
+their triggers. Selected skills can be rendered into an agent prompt preamble or
+scaffolded into a target repo's ``.claude/skills/`` directory.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import functools
+import os
+import re
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from devcouncil.knowledge.frontmatter import build_frontmatter_markdown, split_frontmatter
+
+LIBRARY_DIR = Path(__file__).resolve().parent / "library"
+
+
+def _keyword_in_text(keyword: str, text_lower: str) -> bool:
+    """Whether a trigger keyword appears in already-lowercased goal text.
+
+    Plain alphanumeric keywords ("gin", "unity", "flutter") match on word
+    boundaries so a short framework name can't fire on an unrelated word it
+    happens to sit inside ("gin" in "engine", "echo" in "echoes", "go" in
+    "logo"). Keywords that contain spaces or punctuation ("react native",
+    ".net", "c#", "c++", "ci/cd") are distinctive enough to match as substrings.
+    """
+    kw = keyword.lower().strip()
+    if not kw:
+        return False
+    if kw.isalnum():
+        return re.search(rf"(?<![a-z0-9]){re.escape(kw)}(?![a-z0-9])", text_lower) is not None
+    return kw in text_lower
+
+# Directories never worth walking when matching file-based triggers.
+_PRUNE_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", ".venv", "venv", "__pycache__",
+    ".devcouncil", ".idea", ".gradle", "build", "dist", ".mypy_cache",
+    ".pytest_cache", ".ruff_cache", "DerivedData", "Pods",
+}
+_MAX_WALK_FILES = 20_000
+
+
+class SkillTriggers(BaseModel):
+    keywords: list[str] = Field(default_factory=list)
+    globs: list[str] = Field(default_factory=list)
+
+
+class Skill(BaseModel):
+    name: str
+    title: str = ""
+    description: str = ""
+    always: bool = False
+    triggers: SkillTriggers = Field(default_factory=SkillTriggers)
+    body: str = ""
+    source_path: Path | None = None
+
+    def matches(self, goal: str, repo_files_present: "set[str] | None" = None) -> bool:
+        """True if this skill applies to the given goal text / repo file basenames."""
+        if self.always:
+            return True
+        goal_lower = goal.lower()
+        if any(_keyword_in_text(keyword, goal_lower) for keyword in self.triggers.keywords):
+            return True
+        if repo_files_present:
+            for pattern in self.triggers.globs:
+                pat = pattern.lower()
+                if any(fnmatch.fnmatch(name, pat) for name in repo_files_present):
+                    return True
+        return False
+
+    def relevance_score(self, goal: str, repo_files_present: "set[str] | None" = None) -> int:
+        """How strongly this skill applies — used to rank which skills ride inline before
+        the size budget truncates. Goal-text keyword hits weigh more than file-glob
+        presence; always-on skills sort first regardless."""
+        if self.always:
+            return 1_000_000
+        goal_lower = goal.lower()
+        score = 2 * sum(1 for keyword in self.triggers.keywords if _keyword_in_text(keyword, goal_lower))
+        if repo_files_present:
+            score += sum(
+                1 for pattern in self.triggers.globs
+                if any(fnmatch.fnmatch(name, pattern.lower()) for name in repo_files_present)
+            )
+        return score
+
+    def to_skill_md(self) -> str:
+        """Render as a Claude-Code-style SKILL.md (name + description frontmatter + body)."""
+        return build_frontmatter_markdown(
+            {"name": self.name, "description": self.description},
+            self.body,
+        )
+
+
+# Frontmatter parsing lives in devcouncil.knowledge.frontmatter so skills and the OKF /
+# design.md formats share one implementation; kept aliased here for existing callers.
+_split_frontmatter = split_frontmatter
+
+
+def _skill_from_meta(path: Path, meta: dict, body: str) -> Skill:
+    triggers = meta.get("triggers") or {}
+    return Skill(
+        name=str(meta.get("name") or path.stem),
+        title=str(meta.get("title") or ""),
+        description=str(meta.get("description") or ""),
+        always=bool(meta.get("always", False)),
+        triggers=SkillTriggers(
+            keywords=list(triggers.get("keywords") or []),
+            globs=list(triggers.get("globs") or []),
+        ),
+        body=body.strip(),
+        source_path=path,
+    )
+
+
+# Repo-local skill locations, scanned in addition to the packaged library so users
+# can drop their own skill markdown into a project and have it picked up.
+REPO_SKILL_DIRS = (".claude/skills", ".devcouncil/skills")
+
+
+def _try_skill_from_file(path: Path) -> Skill | None:
+    """Parse a markdown file into a Skill in a single read, or None if it isn't a skill.
+
+    A markdown file is a skill only if its frontmatter carries a ``name``; plain docs
+    (e.g. a contributor README) are ignored. Reads the file once — previously callers
+    read it twice (an ``_is_skill_file`` check followed by a separate parse)."""
+    try:
+        meta, body = _split_frontmatter(path.read_text(encoding="utf-8"))
+    except OSError:
+        return None
+    if not meta.get("name"):
+        return None
+    return _skill_from_meta(path, meta, body)
+
+
+def discover_repo_skills(project_root: Path) -> list[Skill]:
+    """Find user-authored skills in a repo (``.claude/skills/**/SKILL.md`` etc.).
+
+    Honors the same frontmatter contract as the packaged library; files without a
+    ``name`` (e.g. plain docs) are ignored.
+    """
+    found: list[Skill] = []
+    seen: set[Path] = set()
+    for rel in REPO_SKILL_DIRS:
+        base = project_root / rel
+        if not base.exists():
+            continue
+        candidates = sorted(base.rglob("SKILL.md")) + sorted(base.glob("*.md"))
+        for path in candidates:
+            resolved = path.resolve()
+            if resolved in seen:
+                continue
+            skill = _try_skill_from_file(path)
+            if skill is None:
+                continue
+            seen.add(resolved)
+            found.append(skill)
+    return found
+
+
+def load_okf_skills(project_root: Path, directory: str = ".devcouncil/knowledge") -> list[Skill]:
+    """Load skills from ingested OKF documents typed as engineering skills.
+
+    Reads every ``*.md`` under ``<project_root>/<directory>/okf/`` (recursively), parses
+    each as an :class:`~devcouncil.knowledge.okf.OKFDocument`, and keeps the ones whose
+    ``type`` marks them as a skill (the OKF->Skill conversion returns ``None`` for any
+    other node type — BigQuery tables, tasks, ...). This is how an OKF bundle ingested
+    from another repo contributes its skills to selection alongside the packaged library.
+
+    ``index.md`` files are skipped: a bundle index is navigation scaffolding, not a node.
+    The document's ``rel_path`` is set relative to the okf dir so its skill ``name`` derives
+    from the file stem (matching how the export side names ``skills/<name>.md``).
+    """
+    # Lazy import to avoid a registry <-> skill_bridge import cycle (see that module);
+    # OKFDocument is cycle-safe (knowledge.okf doesn't import skills) but kept here too
+    # to keep the OKF-ingest dependency local to the one function that uses it.
+    from devcouncil.knowledge.okf import OKFDocument
+    from devcouncil.knowledge.skill_bridge import okf_document_to_skill
+
+    okf_dir = project_root / directory / "okf"
+    if not okf_dir.exists():
+        return []
+    skills: list[Skill] = []
+    for path in sorted(okf_dir.rglob("*.md")):
+        if path.name == "index.md":
+            continue
+        rel = path.relative_to(okf_dir).as_posix()
+        doc = OKFDocument.from_markdown(path.read_text(encoding="utf-8"), rel_path=rel)
+        skill = okf_document_to_skill(doc)
+        if skill is not None:
+            skills.append(skill)
+    return skills
+
+
+@functools.lru_cache(maxsize=32)
+def load_skills(
+    library_dir: Path = LIBRARY_DIR,
+    project_root: Path | None = None,
+    include_okf: bool = True,
+) -> list[Skill]:
+    """Load skills: the packaged library plus, when ``project_root`` is given, the
+    repo's own skills and (when ``include_okf``) skills from ingested OKF documents.
+    Repo-local skills override packaged ones with the same name.
+
+    Result is cached per (library_dir, project_root, include_okf) for the lifetime of
+    the process, mirroring the repo-basename cache below: a ``dev e2e``/``repair-all``
+    run calls ``select_skills`` once per task, and re-reading+parsing the whole skill
+    tree (library glob, repo ``SKILL.md`` discovery, OKF markdown) every time is pure
+    waste since the on-disk skills don't change during a run. The returned list is
+    shared and must be treated read-only by callers (all current callers only iterate
+    it); ``clear_skill_caches()`` drops the cache when a refresh is needed.
+
+    OKF-derived skills are merged in last and only for names not already taken, so a
+    packaged library skill or a repo-local skill always wins a name conflict over an
+    ingested bundle node (the local definition is authoritative and carries richer
+    selection metadata like globs that OKF tags can't represent).
+
+    Always-on skills come first, then alphabetical. Markdown files without skill
+    frontmatter (e.g. a contributor README) are ignored.
+    """
+    by_name: dict[str, Skill] = {}
+    if library_dir.exists():
+        for path in sorted(library_dir.glob("*.md")):
+            skill = _try_skill_from_file(path)
+            if skill is not None:
+                by_name[skill.name] = skill
+    if project_root is not None:
+        for skill in discover_repo_skills(project_root):
+            base = by_name.get(skill.name)
+            if base is not None:
+                # A repo-local copy of a library skill (commonly a scaffolded
+                # passthrough whose SKILL.md frontmatter is only name+description)
+                # overrides the body/description, but must INHERIT the library's
+                # selection metadata when it doesn't declare its own — otherwise
+                # scaffolding a skill silently strips its `always`/triggers and the
+                # skill stops being selected (selection would return nothing).
+                has_own_triggers = bool(skill.triggers.keywords or skill.triggers.globs)
+                skill = skill.model_copy(update={
+                    "always": skill.always or base.always,
+                    "triggers": skill.triggers if has_own_triggers else base.triggers,
+                })
+            by_name[skill.name] = skill  # repo-local wins on name conflict
+        if include_okf:
+            # Honor a custom knowledge.directory: `dev okf ingest` and knowledge-source
+            # discovery both write/read under the configured dir, so the skill-ingest read
+            # path must too — otherwise ingested OKF skills land somewhere this never looks
+            # and silently never get selected. Best-effort; lazy import keeps app.config out
+            # of the skills package's module-load graph.
+            knowledge_dir = ".devcouncil/knowledge"
+            try:
+                from devcouncil.app.config import load_config
+                knowledge_dir = load_config(project_root).knowledge.directory
+            except Exception:
+                pass
+            for skill in load_okf_skills(project_root, directory=knowledge_dir):
+                # Only fill gaps: library + repo-local skills win on name conflict.
+                by_name.setdefault(skill.name, skill)
+    skills = list(by_name.values())
+    skills.sort(key=lambda s: (not s.always, s.name))
+    return skills
+
+
+def get_skill(name: str, library_dir: Path = LIBRARY_DIR, project_root: Path | None = None) -> Skill | None:
+    for skill in load_skills(library_dir, project_root):
+        if skill.name == name:
+            return skill
+    return None
+
+
+# Per-process cache of the repo file scan, keyed by (resolved path, root mtime).
+# Selecting skills for every task in a `dev e2e`/`repair-all` run would otherwise walk
+# the whole tree once per task. Keyed on the root dir's mtime so adding/removing a
+# top-level marker file (package.json, build.gradle, go.mod, ...) invalidates it.
+_basename_cache: dict[tuple[str, int], set[str]] = {}
+_BASENAME_CACHE_MAX = 32
+
+
+def clear_skill_caches() -> None:
+    """Drop the cached repo file scans and loaded-skill sets (useful in long-running
+    processes/tests). Fully resets module-level skill state so test isolation holds."""
+    _basename_cache.clear()
+    load_skills.cache_clear()
+
+
+def _walk_repo_basenames(project_root: Path) -> set[str]:
+    names: set[str] = set()
+    count = 0
+    for _dirpath, dirnames, filenames in os.walk(project_root):
+        dirnames[:] = [d for d in dirnames if d not in _PRUNE_DIRS]
+        for filename in filenames:
+            names.add(filename.lower())
+            count += 1
+            if count >= _MAX_WALK_FILES:
+                return names
+    return names
+
+
+def _collect_repo_basenames(project_root: Path) -> set[str]:
+    """Lowercased basenames of files in the repo, with heavy dirs pruned and a cap.
+
+    Result is cached per (resolved path, root mtime) so repeated selections within one
+    run (e.g. one prompt per task in an e2e flow) don't re-walk the tree each time.
+    """
+    try:
+        key: tuple[str, int] | None = (str(project_root.resolve()), project_root.stat().st_mtime_ns)
+    except OSError:
+        key = None
+    if key is not None:
+        cached = _basename_cache.get(key)
+        if cached is not None:
+            return cached
+    names = _walk_repo_basenames(project_root)
+    if key is not None:
+        if len(_basename_cache) >= _BASENAME_CACHE_MAX:
+            _basename_cache.clear()
+        _basename_cache[key] = names
+    return names
+
+
+def select_skills(
+    goal: str = "",
+    project_root: Path | None = None,
+    library_dir: Path = LIBRARY_DIR,
+) -> list[Skill]:
+    """Select the skills that apply to a goal and/or repository.
+
+    Includes repo-local skills (``.claude/skills/**``) when ``project_root`` is given.
+    """
+    skills = load_skills(library_dir, project_root)
+    repo_files = _collect_repo_basenames(project_root) if project_root else set()
+    # Score each skill once and keep the ones that apply: for a Skill, matches() is exactly
+    # relevance_score() > 0 (always-on -> 1_000_000; otherwise a positive score requires a
+    # keyword/glob hit, which is what matches() tests), so a single pass replaces the old
+    # match-then-score double walk. (This equivalence is Skill-specific — do NOT copy it to
+    # KnowledgeSource, whose nonzero priority floor breaks it.)
+    # Rank by relevance so the most applicable domain skill survives the inline budget on a
+    # polyglot repo; always-on skills keep their leading position; ties break by name.
+    scored = [
+        (s, score) for s in skills if (score := s.relevance_score(goal, repo_files)) > 0
+    ]
+    scored.sort(key=lambda item: (not item[0].always, -item[1], item[0].name))
+    return [skill for skill, _ in scored]
+
+
+def render_preamble(skills: list[Skill]) -> str:
+    """Concatenate skill bodies into a single prompt preamble block."""
+    if not skills:
+        return ""
+    sections = [skill.body.strip() for skill in skills if skill.body.strip()]
+    return "\n\n---\n\n".join(sections).strip()
+
+
+def bound_skills(
+    skills: list[Skill],
+    max_skills: int = 5,
+    max_chars: int = 14000,
+) -> "tuple[list[Skill], list[Skill]]":
+    """Split selected skills into (inline, deferred) to bound prompt size.
+
+    Skills are kept in order (always-on first), so the core skill is always inline;
+    once the skill count or the cumulative body size would be exceeded, the rest are
+    deferred (their full text still lives in the scaffolded .claude/skills/ files).
+    """
+    inline: list[Skill] = []
+    total = 0
+    for skill in skills:
+        body = skill.body.strip()
+        if not body:
+            continue
+        if len(inline) >= max_skills or (inline and total + len(body) > max_chars):
+            break
+        inline.append(skill)
+        total += len(body)
+    inline_set = {id(s) for s in inline}
+    deferred = [s for s in skills if id(s) not in inline_set and s.body.strip()]
+    return inline, deferred
+
+
+def scaffold_skills(project_root: Path, skills: list[Skill]) -> list[Path]:
+    """Write the given skills into ``<project_root>/.claude/skills/<name>/SKILL.md``.
+
+    Only rewrites a file when its content changes, so re-running is a no-op.
+    """
+    written: list[Path] = []
+    skills_root = project_root / ".claude" / "skills"
+    proot = project_root.resolve()
+    for skill in skills:
+        # Don't re-materialize a skill that already lives inside this repo.
+        if skill.source_path is not None:
+            try:
+                skill.source_path.resolve().relative_to(proot)
+                continue
+            except ValueError:
+                pass
+        target = skills_root / skill.name / "SKILL.md"
+        content = skill.to_skill_md()
+        if target.exists() and target.read_text(encoding="utf-8") == content:
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        written.append(target)
+    return written