voidx 1.0.0__py3-none-any.whl

voidx/skills/bundled/superpowers/receiving-code-review/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: receiving-code-review
+description: Use when receiving review feedback, requested optimizations, or reviewer comments before implementing them.
+triggers:
+  - review feedback
+  - code review feedback
+  - reviewer says
+  - feedback says
+  - review comment
+  - 优化点
+  - 审查意见
+  - 评审意见
+---
+
+# Receiving Code Review for voidx
+
+Use this skill when the user or another reviewer gives feedback to implement.
+
+Core rule: verify feedback against the codebase before changing code.
+
+Workflow:
+1. Read the full feedback.
+2. Restate the concrete requested changes if needed.
+3. Check the relevant code and tests.
+4. Decide whether each item is correct for this codebase.
+5. Push back with technical reasons when feedback is wrong or unnecessary.
+6. If feedback is valid, implement one coherent item at a time.
+7. Verify with targeted tests or commands before reporting.
+
+Do not give performative agreement. Technical correctness and the user's intent decide what changes.

voidx/skills/bundled/superpowers/requesting-code-review/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: requesting-code-review
+description: Use after substantial implementation work, complex bug fixes, or before merging to request a focused review.
+triggers:
+  - request review
+  - ask for review
+  - before merge
+  - pre-merge
+  - review this change
+  - 复核一下
+  - 合并前
+---
+
+# Requesting Code Review for voidx
+
+Use this skill after substantial implementation work, complex bug fixes, or before merge.
+
+In voidx, request review with `agent(review)` when available.
+
+Review brief should include:
+1. What changed.
+2. Requirements or plan being checked.
+3. Files changed or relevant diff range.
+4. Verification already run.
+5. Specific risks to inspect.
+
+Act on review findings by severity. Fix correctness, security, and broken behavior before proceeding. Push back if the review is wrong and explain the evidence.

voidx/skills/bundled/superpowers/systematic-debugging/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: systematic-debugging
+description: Use when debugging bugs, failed tests, build failures, tracebacks, crashes, or unexpected behavior.
+triggers:
+  - bug
+  - failed
+  - failure
+  - traceback
+  - error
+  - crash
+  - broken
+  - test failure
+  - build failure
+  - 报错
+  - 失败
+  - 异常
+  - 崩溃
+  - 排查
+---
+
+# Systematic Debugging for voidx
+
+Use this skill before proposing or applying fixes for bugs, failed tests, build failures, crashes, or unexpected behavior.
+
+Core rule: find the root cause before changing code.
+
+Workflow:
+1. Read the full error, traceback, logs, or failing assertion.
+2. Reproduce the issue with the smallest reliable command or steps.
+3. Check recent changes with read-only tools such as `grep`, `read`, and safe `bash`.
+4. Form one concrete hypothesis from evidence.
+5. Verify the hypothesis with a targeted command, diagnostic, or code read.
+6. Only then make the smallest fix.
+7. Run the reproduction command again and report the evidence.
+
+For flaky or non-reproducible failures, gather more evidence instead of guessing.

voidx/skills/bundled/superpowers/test-driven-development/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: test-driven-development
+description: Use before implementing features, bug fixes, refactors, or behavior changes.
+triggers:
+  - implement
+  - feature
+  - bugfix
+  - refactor
+  - behavior change
+  - add support
+  - fix bug
+  - 实现
+  - 修复
+  - 重构
+  - 功能
+---
+
+# Test-Driven Development for voidx
+
+Use this skill before writing production code for a feature, bug fix, refactor, or behavior change.
+
+Core rule: write a test that fails for the intended reason before writing the implementation.
+
+Workflow:
+1. Identify the smallest behavior to prove.
+2. Add or update a focused test.
+3. Run the targeted test and confirm it fails for the expected reason.
+4. Implement the smallest code change that makes the test pass.
+5. Run the targeted test again.
+6. Refactor only after the test is green.
+7. Run the relevant broader test set before reporting completion.
+
+Allowed exceptions: pure documentation, prompt-only edits, generated assets, or configuration-only changes. If you skip TDD for one of these, say why briefly.

voidx/skills/bundled/superpowers/verification-before-completion/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: verification-before-completion
+description: Use before claiming work is complete, fixed, passing, ready, or safe to merge.
+triggers:
+  - done
+  - complete
+  - fixed
+  - passing
+  - ready
+  - verify
+  - verified
+  - 完成
+  - 修好了
+  - 通过
+  - 验证
+---
+
+# Verification Before Completion for voidx
+
+Use this skill before saying work is complete, fixed, passing, ready, or safe to merge.
+
+Core rule: evidence before completion claims.
+
+Checklist:
+1. Identify the command or check that proves the claim.
+2. Run the full relevant command in this turn.
+3. Read the exit code and failure count.
+4. If the check fails, report the actual failure and next step.
+5. If the check passes, report the command and result.
+
+Do not rely on earlier runs, assumptions, or subagent summaries without verifying the actual state.

voidx/skills/bundled/superpowers/writing-plans/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: writing-plans
+description: Use when turning a spec, requirements, or agreed design into an implementation plan before editing code.
+triggers:
+  - implementation plan
+  - write a plan
+  - planning
+  - spec
+  - requirements
+  - 计划
+  - 实施方案
+  - 需求
+---
+
+# Writing Plans for voidx
+
+Use this skill when the user has a spec, requirements, or agreed design and wants an implementation plan.
+
+Plan structure:
+1. Goal: one sentence.
+2. Context: current code paths and constraints.
+3. Files: exact files to create or modify.
+4. Tasks: small ordered steps with checkboxes.
+5. Tests: targeted commands and expected results.
+6. Risks: edge cases, compatibility, and rollback concerns.
+
+Keep plans executable by voidx: use exact paths, concrete commands, and voidx tool names. Do not force git worktrees or commits unless the user asked for them.

voidx/skills/policy.py

@@ -0,0 +1,97 @@
+"""Workflow skill activation policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class WorkflowSkillActivation:
+    name: str
+    reason: str
+
+
+WORKFLOW_SKILL_PRIORITY = {
+    "systematic-debugging": 10,
+    "receiving-code-review": 20,
+    "writing-plans": 30,
+    "test-driven-development": 40,
+    "verification-before-completion": 50,
+    "requesting-code-review": 60,
+}
+
+
+def workflow_skill_activations(
+    user_text: str,
+    *,
+    agent: str = "",
+    task_intent: str | None = None,
+    interaction_mode: str | None = None,
+) -> list[WorkflowSkillActivation]:
+    text = user_text.strip().lower()
+    agent_name = (agent or "").strip().lower()
+    intent = (task_intent or "").strip().lower()
+    mode = (interaction_mode or "").strip().lower()
+    activations: dict[str, WorkflowSkillActivation] = {}
+
+    def add(name: str, reason: str) -> None:
+        activations.setdefault(name, WorkflowSkillActivation(name=name, reason=reason))
+
+    if intent == "debug":
+        add("systematic-debugging", "debug intent")
+        add("verification-before-completion", "debug lifecycle")
+
+    if agent_name == "implement":
+        add("test-driven-development", "implement role")
+        add("verification-before-completion", "implement lifecycle")
+    elif intent == "implement":
+        add("test-driven-development", "implement intent")
+        add("verification-before-completion", "implement lifecycle")
+
+    if agent_name == "plan":
+        add("writing-plans", "plan role")
+
+    if intent == "review" and _contains_any(text, _REVIEW_FEEDBACK_TERMS):
+        add("receiving-code-review", "review feedback")
+
+    if intent == "design" and _contains_any(text, _PLAN_TERMS):
+        add("writing-plans", "planning intent")
+
+    if mode == "plan":
+        add("writing-plans", "plan mode")
+
+    return sorted(
+        activations.values(),
+        key=lambda item: (WORKFLOW_SKILL_PRIORITY.get(item.name, 999), item.name),
+    )
+
+
+def workflow_skill_sort_key(name: str) -> tuple[int, str]:
+    return (WORKFLOW_SKILL_PRIORITY.get(name, 999), name)
+
+
+def _contains_any(text: str, terms: tuple[str, ...]) -> bool:
+    return any(term in text for term in terms)
+
+
+_REVIEW_FEEDBACK_TERMS = (
+    "review feedback",
+    "code review feedback",
+    "review comment",
+    "reviewer says",
+    "feedback says",
+    "优化点",
+    "审查意见",
+    "评审意见",
+)
+
+_PLAN_TERMS = (
+    "implementation plan",
+    "write a plan",
+    "planning",
+    "spec",
+    "requirements",
+    "计划",
+    "实施方案",
+    "需求",
+)

voidx/skills/registry.py

@@ -0,0 +1,162 @@
+"""Local skill discovery from SKILL.md files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from voidx.skills.schema import SkillDefinition, SkillMeta, SkillScope
+
+SKILL_FILENAME = "SKILL.md"
+
+
+def normalize_skill_name(name: str) -> str:
+    return name.strip().lower()
+
+
+class SkillParseError(ValueError):
+    pass
+
+
+class SkillRegistry:
+    """Discovers bundled, global, and project skills.
+
+    Search order is bundled first, then global, then project. Later sources
+    override earlier sources with the same skill name.
+    """
+
+    def __init__(
+        self,
+        workspace: str,
+        *,
+        bundled_dir: Path | None = None,
+        global_dir: Path | None = None,
+        project_dir: Path | None = None,
+    ) -> None:
+        self.workspace = Path(workspace).resolve()
+        self.bundled_dir = bundled_dir or (Path(__file__).resolve().parent / "bundled" / "superpowers")
+        self.global_dir = global_dir or (Path.home() / ".voidx" / "skills")
+        self.project_dir = project_dir or (self.workspace / ".voidx" / "skills")
+
+    def discover(self) -> list[SkillDefinition]:
+        skills: dict[str, SkillDefinition] = {}
+        for scope, root in (
+            ("bundled", self.bundled_dir),
+            ("global", self.global_dir),
+            ("project", self.project_dir),
+        ):
+            for skill in self._discover_root(root, scope):
+                skills[normalize_skill_name(skill.name)] = skill
+        return sorted(skills.values(), key=lambda item: item.name)
+
+    def get(self, name: str) -> SkillDefinition | None:
+        target = normalize_skill_name(name)
+        for skill in self.discover():
+            if normalize_skill_name(skill.name) == target:
+                return skill
+        return None
+
+    def _discover_root(self, root: Path, scope: SkillScope) -> list[SkillDefinition]:
+        if not root.exists() or not root.is_dir():
+            return []
+        skills: list[SkillDefinition] = []
+        for skill_file in sorted(root.glob(f"*/{SKILL_FILENAME}")):
+            try:
+                skills.append(parse_skill_file(skill_file, scope=scope))
+            except SkillParseError:
+                continue
+        return skills
+
+
+def parse_skill_file(path: Path, *, scope: SkillScope) -> SkillDefinition:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    fields, body = _split_frontmatter(text)
+    name = str(fields.get("name") or path.parent.name).strip()
+    if not name:
+        raise SkillParseError(f"Skill at {path} has no name")
+    meta = SkillMeta(
+        name=name,
+        description=str(fields.get("description") or ""),
+        enabled=_coerce_bool(fields.get("enabled"), default=True),
+        triggers=[str(item).strip() for item in _coerce_list(fields.get("triggers")) if str(item).strip()],
+        scope=scope,
+    )
+    return SkillDefinition(meta=meta, path=path.resolve(), body=body.strip())
+
+
+def _split_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}, text
+
+    end_index = None
+    for index, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_index = index
+            break
+    if end_index is None:
+        raise SkillParseError("Unclosed frontmatter")
+
+    frontmatter = "\n".join(lines[1:end_index])
+    body = "\n".join(lines[end_index + 1:])
+    return _parse_frontmatter(frontmatter), body
+
+
+def _parse_frontmatter(text: str) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    current_key: str | None = None
+    for raw_line in text.splitlines():
+        line = raw_line.rstrip()
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.startswith("- ") and current_key:
+            current = result.setdefault(current_key, [])
+            if isinstance(current, list):
+                current.append(_parse_scalar(stripped[2:].strip()))
+            continue
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        current_key = key.strip()
+        value = value.strip()
+        if not current_key:
+            continue
+        if value == "":
+            result[current_key] = []
+        else:
+            result[current_key] = _parse_scalar(value)
+    return result
+
+
+def _parse_scalar(value: str) -> Any:
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+        value = value[1:-1]
+    lower = value.lower()
+    if lower in {"true", "yes", "on"}:
+        return True
+    if lower in {"false", "no", "off"}:
+        return False
+    if value.startswith("[") and value.endswith("]"):
+        inner = value[1:-1].strip()
+        if not inner:
+            return []
+        return [_parse_scalar(part.strip()) for part in inner.split(",")]
+    return value
+
+
+def _coerce_bool(value: Any, *, default: bool) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() not in {"false", "no", "off", "0"}
+
+
+def _coerce_list(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [value]

voidx/skills/schema.py

@@ -0,0 +1,47 @@
+"""Types for local skill discovery and selection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+SkillScope = Literal["bundled", "global", "project"]
+
+
+class SkillMeta(BaseModel):
+    name: str
+    description: str = ""
+    enabled: bool = True
+    triggers: list[str] = Field(default_factory=list)
+    scope: SkillScope = "project"
+
+
+class SkillDefinition(BaseModel):
+    meta: SkillMeta
+    path: Path
+    body: str
+
+    @property
+    def name(self) -> str:
+        return self.meta.name
+
+    @property
+    def source_dir(self) -> Path:
+        return self.path.parent
+
+
+class SkillSelectionConfig(BaseModel):
+    enabled: set[str] = Field(default_factory=set)
+    disabled: set[str] = Field(default_factory=set)
+
+
+class SkillMatch(BaseModel):
+    skill: SkillDefinition
+    reason: str
+
+    @property
+    def name(self) -> str:
+        return self.skill.name

voidx/skills/service.py

@@ -0,0 +1,199 @@
+"""Runtime skill selection and instruction rendering."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from voidx.skills.policy import workflow_skill_activations, workflow_skill_sort_key
+from voidx.skills.registry import SkillRegistry, normalize_skill_name
+from voidx.skills.schema import SkillDefinition, SkillMatch, SkillSelectionConfig
+
+_EXPLICIT_REF_RE = re.compile(r"(?<![\w.-])\$([A-Za-z0-9_.-]+)")
+
+
+class SkillService:
+    def __init__(
+        self,
+        registry: SkillRegistry,
+        *,
+        selection: SkillSelectionConfig | None = None,
+    ) -> None:
+        self._registry = registry
+        self._selection = selection or SkillSelectionConfig()
+
+    def list_skills(self) -> list[SkillDefinition]:
+        return self._registry.discover()
+
+    def get(self, name: str) -> SkillDefinition | None:
+        return self._registry.get(name)
+
+    def enabled_skills(self) -> list[SkillDefinition]:
+        return [skill for skill in self.list_skills() if self.is_enabled(skill)]
+
+    def is_enabled(self, skill: SkillDefinition) -> bool:
+        name = normalize_skill_name(skill.name)
+        if name in self._normalized(self._selection.disabled):
+            return False
+        if name in self._normalized(self._selection.enabled):
+            return True
+        return skill.meta.enabled
+
+    def select(
+        self,
+        user_text: str,
+        *,
+        agent: str = "",
+        task_intent: str | None = None,
+        interaction_mode: str | None = None,
+        limit: int = 5,
+    ) -> list[SkillMatch]:
+        text = user_text.strip()
+        has_context = bool(agent or task_intent or interaction_mode)
+        if not text and not has_context:
+            return []
+
+        skills = self.enabled_skills()
+        skills_by_name = {normalize_skill_name(skill.name): skill for skill in skills}
+        explicit = self._explicit_refs(text)
+        matches: list[SkillMatch] = []
+        seen: set[str] = set()
+
+        def add_match(skill: SkillDefinition | None, reason: str) -> None:
+            if skill is None:
+                return
+            name = normalize_skill_name(skill.name)
+            if name in seen:
+                return
+            seen.add(name)
+            matches.append(SkillMatch(skill=skill, reason=reason))
+
+        if explicit:
+            for name in sorted(explicit, key=workflow_skill_sort_key):
+                add_match(skills_by_name.get(name), "explicit")
+            for activation in workflow_skill_activations(
+                text,
+                agent=agent,
+                task_intent=task_intent,
+                interaction_mode=interaction_mode,
+            ):
+                add_match(skills_by_name.get(normalize_skill_name(activation.name)), activation.reason)
+            return matches[:limit]
+
+        for activation in workflow_skill_activations(
+            text,
+            agent=agent,
+            task_intent=task_intent,
+            interaction_mode=interaction_mode,
+        ):
+            add_match(skills_by_name.get(normalize_skill_name(activation.name)), activation.reason)
+
+        text_matches: list[SkillMatch] = []
+        lowered = text.lower()
+        for skill in skills:
+            if normalize_skill_name(skill.name) in seen:
+                continue
+            reason = self._match_reason(skill, lowered)
+            if reason:
+                text_matches.append(SkillMatch(skill=skill, reason=reason))
+        text_matches.sort(key=lambda match: workflow_skill_sort_key(match.name))
+        matches.extend(text_matches)
+        return matches[:limit]
+
+    def activation_summaries(
+        self,
+        user_text: str,
+        *,
+        agent: str = "",
+        task_intent: str | None = None,
+        interaction_mode: str | None = None,
+        limit: int = 5,
+    ) -> list[str]:
+        return [
+            f"{match.name} ({match.reason})"
+            for match in self.select(
+                user_text,
+                agent=agent,
+                task_intent=task_intent,
+                interaction_mode=interaction_mode,
+                limit=limit,
+            )
+        ]
+
+    def instructions_for(
+        self,
+        user_text: str,
+        *,
+        agent: str = "",
+        task_intent: str | None = None,
+        interaction_mode: str | None = None,
+        limit: int = 5,
+    ) -> list[str]:
+        return [
+            self.render_instruction(match.skill)
+            for match in self.select(
+                user_text,
+                agent=agent,
+                task_intent=task_intent,
+                interaction_mode=interaction_mode,
+                limit=limit,
+            )
+        ]
+
+    @staticmethod
+    def render_instruction(skill: SkillDefinition) -> str:
+        description = skill.meta.description.strip()
+        header = f"Skill instructions from: {skill.path}\nSkill: {skill.name}"
+        if description:
+            header += f"\nDescription: {description}"
+        return f"{header}\n\n{skill.body}".strip()
+
+    @staticmethod
+    def _normalized(values: Iterable[str]) -> set[str]:
+        return {normalize_skill_name(value) for value in values}
+
+    @staticmethod
+    def _explicit_refs(text: str) -> set[str]:
+        return {normalize_skill_name(match.group(1)) for match in _EXPLICIT_REF_RE.finditer(text)}
+
+    @staticmethod
+    def _match_reason(skill: SkillDefinition, lowered_text: str) -> str:
+        name = normalize_skill_name(skill.name)
+        if _contains_phrase(lowered_text, name):
+            return "name"
+
+        for trigger in skill.meta.triggers:
+            normalized = trigger.strip().lower()
+            if normalized and normalized in lowered_text:
+                return f"trigger:{trigger}"
+
+        description_terms = _significant_terms(skill.meta.description)
+        if description_terms and sum(1 for term in description_terms if term in lowered_text) >= 2:
+            return "description"
+        return ""
+
+
+def _contains_phrase(text: str, phrase: str) -> bool:
+    if not phrase:
+        return False
+    pattern = r"(?<![\w.-])" + re.escape(phrase) + r"(?![\w.-])"
+    return bool(re.search(pattern, text))
+
+
+def _significant_terms(text: str) -> set[str]:
+    stop = {
+        "with",
+        "from",
+        "that",
+        "this",
+        "when",
+        "into",
+        "using",
+        "skill",
+        "skills",
+    }
+    return {
+        term
+        for term in re.findall(r"[A-Za-z][A-Za-z0-9_-]{3,}", text.lower())
+        if term not in stop
+    }