devcouncil 0.1.0 → 0.2.0

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,330 @@
+"""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 os
+import re
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field
+
+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)."""
+        front = yaml.safe_dump(
+            {"name": self.name, "description": self.description},
+            sort_keys=False,
+            default_flow_style=False,
+            allow_unicode=True,
+        ).strip()
+        return f"---\n{front}\n---\n\n{self.body.strip()}\n"
+
+
+def _split_frontmatter(text: str) -> tuple[dict, str]:
+    if text.startswith("---"):
+        parts = text.split("---", 2)
+        if len(parts) == 3:
+            meta = yaml.safe_load(parts[1]) or {}
+            return (meta if isinstance(meta, dict) else {}), parts[2].lstrip("\n")
+    return {}, text
+
+
+def _skill_from_file(path: Path) -> Skill:
+    meta, body = _split_frontmatter(path.read_text(encoding="utf-8"))
+    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 _is_skill_file(path: Path) -> bool:
+    """A markdown file is a skill only if it has frontmatter with a name."""
+    try:
+        meta, _ = _split_frontmatter(path.read_text(encoding="utf-8"))
+    except OSError:
+        return False
+    return bool(meta.get("name"))
+
+
+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 or not _is_skill_file(path):
+                continue
+            seen.add(resolved)
+            found.append(_skill_from_file(path))
+    return found
+
+
+def load_skills(library_dir: Path = LIBRARY_DIR, project_root: Path | None = None) -> list[Skill]:
+    """Load skills: the packaged library plus, when ``project_root`` is given, the
+    repo's own skills. Repo-local skills override packaged ones with the same name.
+
+    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")):
+            if _is_skill_file(path):
+                skill = _skill_from_file(path)
+                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
+    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 (useful in long-running processes/tests)."""
+    _basename_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()
+    matched = [s for s in skills if s.matches(goal, repo_files)]
+    # Rank by relevance so the most applicable domain skill survives the inline budget
+    # on a polyglot repo, instead of whichever happened to load first / sort alphabetically.
+    # always-on skills keep their leading position (highest score); ties break by name.
+    scored = [(s, s.relevance_score(goal, repo_files)) for s in matched]
+    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