qwen-sci 0.2.2__py3-none-any.whl

src/harness/src/openharness/skills/bundled/content/debug.md

@@ -0,0 +1,25 @@
+# debug
+
+Diagnose and fix bugs systematically.
+
+## When to use
+
+Use when the user reports a bug, error, or unexpected behavior.
+
+## Workflow
+
+1. Reproduce: understand the exact steps that trigger the issue
+2. Read the error: stack traces, log messages, error codes
+3. Locate: use Grep/Read to find the relevant code path
+4. Hypothesize: form a theory about the root cause
+5. Verify: add logging or read surrounding code to confirm
+6. Fix: make the minimal change that addresses the root cause
+7. Test: verify the fix works and doesn't break other things
+
+## Rules
+
+- Read the error message carefully before searching code
+- Don't guess — verify your hypothesis before changing code
+- Fix the root cause, not the symptom
+- Don't retry the same approach if it failed — investigate why
+- If stuck after 3 attempts, explain what you've tried and ask for help

src/harness/src/openharness/skills/bundled/content/diagnose.md

@@ -0,0 +1,35 @@
+# diagnose
+
+Diagnose why an agent run failed, regressed, or produced unexpected output — using structured evidence instead of intuition.
+
+## When to use
+
+Use when the user asks:
+- "Why did this run fail?"
+- "What changed between this run and the last one?"
+- "The output looks wrong — what happened?"
+- "Why is this run worse than before?"
+
+## Workflow
+
+1. **Locate the run artifacts** — check `artifacts/runs/<run_id>/` or the latest run directory for:
+   - `manifest.json` — run metadata, task type, input hash, timestamps
+   - `execution_trace.jsonl` — the full tool-call chain, one event per line
+   - `verification_report.json` — what was verified and whether it passed
+   - `failure_signature.json` — which stage failed and why (if present)
+2. **Read the failure signature first** — if it exists, it already localizes the failure to a specific stage (routing, execution, verification, or governance)
+3. **Trace the execution chain** — walk `execution_trace.jsonl` forward to find where output diverged from expectation
+4. **Compare with a passing run** — if a previous run succeeded, diff the two manifests and traces to identify what changed
+5. **Identify the failure layer**:
+   - **Routing**: wrong task type or profile selected
+   - **Execution**: tool call error, permission block, or unexpected result
+   - **Verification**: output produced but did not match expected artifact
+   - **Governance**: run was halted by a safety or boundary check
+6. **Report with evidence** — cite specific file paths, line numbers in the trace, or field values from the manifest; never summarize without pointing to the source
+
+## Rules
+
+- Evidence before intuition: always read the trace before forming a hypothesis
+- Localize before explaining: identify which stage failed before describing why
+- Compare, don't guess: if a previous run succeeded, diff it — don't speculate about what changed
+- If no artifacts exist, say so clearly and ask the user to re-run with archive mode enabled

src/harness/src/openharness/skills/bundled/content/plan.md

@@ -0,0 +1,39 @@
+# plan
+
+Design an implementation plan before coding.
+
+## When to use
+
+Use when the user asks to plan, design, or architect a feature before implementing it.
+
+## Workflow
+
+1. Understand the requirement:
+   - What problem does this solve?
+   - What are the constraints?
+   - What's the expected outcome?
+2. Explore the codebase to find:
+   - Existing functions/utilities that can be reused
+   - Patterns used elsewhere in the project
+   - Files that will need modification
+3. Design the approach:
+   - Break into discrete steps
+   - Identify dependencies between steps
+   - Consider edge cases and error handling
+4. Present the plan:
+   - Start with a Context section (why this change)
+   - List concrete steps with file paths
+   - Include a verification section (how to test)
+
+For this repository, follow the root `AGENTS.md` lightweight strategy: plan by related
+functional batches, match detail and verification to risk, and do not create
+micro-task review or full-test gates unless the change is a milestone or high risk.
+
+## Rules
+
+- Read before suggesting — never propose changes to code you haven't read
+- Prefer editing existing files over creating new ones
+- Reuse existing patterns and utilities
+- Include file paths and line numbers when referencing code
+- Don't over-plan: match complexity to the task
+- Treat verification as a risk-based minimum, not a blocking template step.

src/harness/src/openharness/skills/bundled/content/review.md

@@ -0,0 +1,33 @@
+# review
+
+Review code for bugs, security issues, and quality.
+
+## When to use
+
+Use when the user asks to review code, a PR, or a diff.
+
+## Workflow
+
+1. Read the changed files or diff thoroughly
+2. Check for:
+   - **Bugs**: logic errors, off-by-one, null/undefined access, race conditions
+   - **Security**: injection, XSS, hardcoded secrets, path traversal
+   - **Performance**: N+1 queries, unnecessary allocations, missing indexes
+   - **Tests**: are new code paths covered? Are edge cases tested?
+   - **Style**: naming consistency, dead code, unnecessary complexity
+3. Provide concrete, actionable feedback with file:line references
+4. Prioritize findings by severity (critical > major > minor > nit)
+
+For this repository, follow the root `AGENTS.md` lightweight strategy: perform review
+as an implementation self-check for ordinary local changes. Start an independent
+review only for high-risk architecture/API/security/persistence changes, cross-module
+changes with unclear local impact, repeated unresolved fixes, a milestone, or final
+delivery. Batch related changes into one review instead of reviewing every subtask.
+
+## Rules
+
+- Be specific: "line 42 may throw if `user` is null" not "check for null"
+- Suggest fixes, don't just point out problems
+- Acknowledge good patterns too
+- Don't nitpick formatting if there's a linter
+- Do not make review a subtask-level blocking gate when no material risk is present.

src/harness/src/openharness/skills/bundled/content/simplify.md

@@ -0,0 +1,26 @@
+# simplify
+
+Refactor code to be simpler and more maintainable.
+
+## When to use
+
+Use when the user asks to simplify, clean up, or refactor code.
+
+## Workflow
+
+1. Read the target code completely
+2. Identify complexity sources:
+   - Unnecessary abstractions or indirection
+   - Duplicated logic that should be consolidated
+   - Over-engineered patterns (factories, builders, strategies for simple cases)
+   - Dead code paths or unused variables
+3. Propose changes that reduce line count while preserving behavior
+4. Verify the refactored code passes existing tests
+
+## Rules
+
+- Don't add features or change behavior — simplification only
+- Prefer deleting code over refactoring it
+- Three similar lines are better than a premature abstraction
+- Remove backwards-compatibility shims for removed features
+- Don't add comments to explain simple code

src/harness/src/openharness/skills/bundled/content/skill-creator.md

@@ -0,0 +1,175 @@
+---
+name: skill-creator
+description: >
+  Create, improve, and verify OpenHarness skills. Use this whenever the user
+  asks to create a new skill, convert a workflow into a skill, update an
+  existing SKILL.md, add skills for oh/ohmo, design skill trigger behavior,
+  or test whether a skill loads and works correctly.
+---
+
+# skill-creator
+
+Create or improve OpenHarness skills in the directory-based `SKILL.md` format.
+
+## When to use
+
+Use this skill when the user wants to:
+
+- create a new skill from a workflow, repeated task, domain guide, or tool process
+- convert existing notes, prompts, or instructions into a reusable skill
+- modify or harden an existing skill
+- make a skill available to `oh`, `ohmo`, or a plugin
+- debug why the `skill` tool cannot find or load a skill
+- test trigger wording, skill metadata, or skill behavior
+
+## OpenHarness skill locations
+
+Choose the target deliberately:
+
+- Built-in OpenHarness skills live in `src/openharness/skills/bundled/content/*.md`.
+- User skills for `oh` live in `~/.openharness/skills/<skill-dir>/SKILL.md`.
+- Private `ohmo` skills live in `~/.ohmo/skills/<skill-dir>/SKILL.md`.
+- Plugin skills live in `<plugin-root>/skills/<skill-dir>/SKILL.md`.
+
+OpenHarness user and plugin skills use a directory layout. Do not create flat
+`*.md` user skills under `skills/`; they will not be loaded by the normal loader.
+
+## Skill anatomy
+
+Use this structure for user, ohmo, and plugin skills:
+
+```text
+my-skill/
+├── SKILL.md
+├── scripts/      # optional deterministic helpers
+├── references/   # optional long docs loaded only when relevant
+└── assets/       # optional templates or static files
+```
+
+Use this structure inside `SKILL.md`:
+
+```markdown
+---
+name: my-skill
+description: >
+  What the skill does and exactly when to use it.
+---
+
+# my-skill
+
+Short purpose statement.
+
+## When to use
+
+Trigger contexts in plain language.
+
+## Workflow
+
+Concrete steps the agent should follow.
+
+## Rules
+
+Important boundaries, verification, and failure handling.
+```
+
+## Workflow
+
+1. Capture intent before writing.
+   Ask or infer what the skill should help with, when it should trigger, what
+   output it should produce, and what success looks like. If the conversation
+   already contains the workflow, extract the sequence from history before
+   asking more questions.
+
+2. Inspect existing examples.
+   Read nearby skills and loader behavior before choosing a layout. For
+   OpenHarness, confirm whether the target is bundled, user, ohmo-private, or
+   plugin-provided.
+
+3. Write the metadata first.
+   The `description` is the primary trigger hint shown in the available skills
+   list. Make it specific and slightly assertive: include both what the skill
+   does and the phrases or situations that should trigger it. Avoid vague
+   descriptions like "Helpful notes for X".
+
+4. Keep the body procedural.
+   Use concise imperative steps. Explain why non-obvious constraints matter.
+   Prefer general principles over overfitted examples. If a skill is getting
+   long, move details into `references/` and point to the relevant file.
+
+5. Add deterministic resources only when they pay for themselves.
+   If the skill repeatedly needs the same script, template, schema, or checklist,
+   place it under `scripts/`, `assets/`, or `references/` rather than making the
+   model regenerate it every time.
+
+6. Verify loading.
+   Run a local loader check for the chosen target. For bundled skills, use:
+
+   ```bash
+   PYTHONPATH=src python - <<'PY'
+   from openharness.skills import load_skill_registry
+   for skill in load_skill_registry().list_skills():
+       print(skill.name, skill.source, skill.path)
+   PY
+   ```
+
+   For ohmo-private skills, include the extra skill directory:
+
+   ```bash
+   PYTHONPATH=src python - <<'PY'
+   from openharness.skills import load_skill_registry
+   from ohmo.workspace import get_skills_dir
+   for skill in load_skill_registry(extra_skill_dirs=[get_skills_dir()]).list_skills():
+       print(skill.name, skill.source, skill.path)
+   PY
+   ```
+
+7. Test behavior.
+   Create two or three realistic prompts that should use the skill. If the skill
+   changes code or files, add regression tests around loading or command
+   behavior. Run targeted tests first, then broader tests if the loader or
+   runtime path changed.
+
+8. Iterate from evidence.
+   If a skill under-triggers, improve the frontmatter description. If it
+   triggers but produces poor work, improve the body workflow. If agents repeat
+   deterministic work, add a helper script or reference file.
+
+## Writing rules
+
+- Preserve the skill name when updating an existing skill unless the user
+  explicitly asks to rename it.
+- Do not overwrite user-created skills without reading the existing `SKILL.md`.
+- Keep `SKILL.md` under roughly 500 lines; use `references/` for long material.
+- Keep trigger guidance in frontmatter `description`, not buried only in the
+  body.
+- Make skills safe and unsurprising. Do not create skills that hide behavior,
+  bypass permissions, exfiltrate data, or encourage unauthorized access.
+- Prefer directory names that are lowercase kebab-case, even if the displayed
+  skill `name` is more human-readable.
+- Mention exact install or verification paths in the final response.
+
+## Test prompts
+
+After drafting a skill, propose a small eval set:
+
+```json
+{
+  "skill_name": "my-skill",
+  "evals": [
+    {
+      "id": "happy-path",
+      "prompt": "A realistic user request that should trigger the skill.",
+      "expected_output": "What good behavior looks like."
+    },
+    {
+      "id": "near-miss",
+      "prompt": "A similar request that should not trigger this skill.",
+      "expected_output": "The agent should choose a different path."
+    }
+  ]
+}
+```
+
+For objective skills, add assertions or tests. For subjective skills, collect
+human feedback and revise the workflow from concrete complaints rather than
+adding rigid rules.

src/harness/src/openharness/skills/bundled/content/test.md

@@ -0,0 +1,38 @@
+# test
+
+Write and run tests for code.
+
+## When to use
+
+Use when the user asks to write tests, verify behavior, or improve test coverage.
+
+## Workflow
+
+1. Understand what needs testing:
+   - New feature? Write unit tests for the happy path and edge cases
+   - Bug fix? Write a regression test that would have caught the bug
+   - Refactor? Ensure existing tests still pass
+2. Follow the project's testing patterns:
+   - Check existing tests for framework (pytest, jest, go test, etc.)
+   - Match naming conventions and file organization
+   - Use the same fixtures and helpers
+3. Write tests that are:
+   - Independent: each test can run alone
+   - Deterministic: same result every time
+   - Fast: mock external services, use in-memory databases
+4. Run the tests and verify they pass
+
+For this repository, follow the root `AGENTS.md` lightweight strategy: run the
+smallest affected test set during development. Reserve full test suites, complete
+builds, full lint, and E2E for milestones or final delivery, and skip a command that
+already passed on the same unchanged code unless it covers a newly introduced risk.
+
+## Rules
+
+- Test behavior, not implementation details
+- One assertion per test when possible
+- Use descriptive test names that explain the scenario
+- Don't test framework or library code
+- Mock at system boundaries (external APIs, filesystem, network)
+- Do not require a full-suite run after every small fix; record why broader checks
+  are unnecessary when local validation is sufficient.

src/harness/src/openharness/skills/loader.py

@@ -0,0 +1,229 @@
+"""Skill loading from bundled, user, compatibility, and project directories."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Iterable
+
+from openharness.config.paths import get_config_dir
+from openharness.config.settings import load_settings
+from openharness.skills._frontmatter import (
+    optional_frontmatter_str,
+    parse_bool_frontmatter,
+    parse_skill_frontmatter,
+    parse_skill_metadata,
+)
+from openharness.skills.bundled import get_bundled_skills
+from openharness.skills.registry import SkillRegistry
+from openharness.skills.types import SkillDefinition
+
+logger = logging.getLogger(__name__)
+
+_USER_COMPAT_SKILL_DIRS = (
+    (".claude", "skills"),
+    (".agents", "skills"),
+)
+_DEFAULT_PROJECT_SKILL_DIRS = (".openharness/skills", ".agents/skills", ".claude/skills")
+
+
+def get_user_skills_dir() -> Path:
+    """Return the OpenHarness user skills directory."""
+    path = get_config_dir() / "skills"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_user_skill_dirs() -> list[Path]:
+    """Return user-level skill directories loaded by default."""
+    return [get_user_skills_dir(), *(Path.home().joinpath(*parts) for parts in _USER_COMPAT_SKILL_DIRS)]
+
+
+def load_skill_registry(
+    cwd: str | Path | None = None,
+    *,
+    extra_skill_dirs: Iterable[str | Path] | None = None,
+    extra_plugin_roots: Iterable[str | Path] | None = None,
+    settings=None,
+) -> SkillRegistry:
+    """Load bundled, user-defined, project, and plugin skills."""
+    registry = SkillRegistry()
+    for skill in get_bundled_skills():
+        registry.register(skill)
+    for skill in load_user_skills():
+        registry.register(skill)
+    for skill in load_skills_from_dirs(extra_skill_dirs, source="user"):
+        registry.register(skill)
+
+    resolved_settings = settings or load_settings()
+    if cwd is not None and getattr(resolved_settings, "allow_project_skills", True):
+        project_dirs = discover_project_skill_dirs(
+            cwd,
+            getattr(resolved_settings, "project_skill_dirs", list(_DEFAULT_PROJECT_SKILL_DIRS)),
+        )
+        for skill in load_skills_from_dirs(project_dirs, source="project", create_missing=False):
+            registry.register(skill)
+
+    if cwd is not None:
+        from openharness.plugins.loader import load_plugins
+
+        for plugin in load_plugins(resolved_settings, cwd, extra_roots=extra_plugin_roots):
+            if not plugin.enabled:
+                continue
+            for skill in plugin.skills:
+                registry.register(skill)
+    return registry
+
+
+def load_user_skills() -> list[SkillDefinition]:
+    """Load markdown skills from user-level OpenHarness and compatibility directories."""
+    return load_skills_from_dirs(get_user_skill_dirs(), source="user")
+
+
+def discover_project_skill_dirs(
+    cwd: str | Path,
+    project_skill_dirs: Iterable[str] | None = None,
+) -> list[Path]:
+    """Return existing project skill directories from cwd up to the git root.
+
+    Directories are ordered from least-specific to most-specific so later registry
+    entries can override broader project or user skills deterministically.
+    """
+    start = Path(cwd).expanduser().resolve()
+    if not start.exists():
+        start = start.parent
+    if start.is_file():
+        start = start.parent
+
+    relative_dirs = _valid_project_skill_dirs(project_skill_dirs or _DEFAULT_PROJECT_SKILL_DIRS)
+    git_root = _find_git_root(start)
+    home = Path.home().resolve()
+    current = start
+    levels: list[Path] = []
+    while True:
+        levels.append(current)
+        if git_root is not None and current == git_root:
+            break
+        if git_root is None and current == home:
+            break
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+
+    roots: list[Path] = []
+    seen: set[Path] = set()
+    for base in reversed(levels):
+        for rel in relative_dirs:
+            candidate = (base / rel).resolve()
+            if candidate in seen or not candidate.is_dir():
+                continue
+            seen.add(candidate)
+            roots.append(candidate)
+    return roots
+
+
+def _valid_project_skill_dirs(project_skill_dirs: Iterable[str]) -> list[Path]:
+    """Return safe relative project skill paths."""
+    paths: list[Path] = []
+    for raw in project_skill_dirs:
+        value = str(raw).strip()
+        if not value:
+            continue
+        rel = Path(value)
+        if rel.is_absolute() or ".." in rel.parts:
+            logger.warning("Ignoring unsafe project skill dir: %s", raw)
+            continue
+        paths.append(rel)
+    return paths
+
+
+def _find_git_root(start: Path) -> Path | None:
+    """Find the nearest git root containing start, if any."""
+    current = start
+    while True:
+        if (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_skills_from_dirs(
+    directories: Iterable[str | Path] | None,
+    *,
+    source: str = "user",
+    create_missing: bool = True,
+) -> list[SkillDefinition]:
+    """Load markdown skills from one or more directories.
+
+    Supported layout:
+    - ``<root>/<skill-dir>/SKILL.md``
+    """
+    skills: list[SkillDefinition] = []
+    if not directories:
+        return skills
+    seen: set[Path] = set()
+    for directory in directories:
+        root = Path(directory).expanduser().resolve()
+        if create_missing:
+            root.mkdir(parents=True, exist_ok=True)
+        elif not root.is_dir():
+            continue
+        candidates: list[Path] = []
+        for child in sorted(root.iterdir()):
+            if child.is_dir():
+                skill_path = child / "SKILL.md"
+                if skill_path.exists():
+                    candidates.append(skill_path)
+        for path in candidates:
+            if path in seen:
+                continue
+            seen.add(path)
+            content = path.read_text(encoding="utf-8")
+            default_name = path.parent.name
+            metadata = _parse_skill_metadata(default_name, content)
+            name = metadata["name"]
+            description = metadata["description"]
+            display_name = name if name != default_name else None
+            skills.append(
+                SkillDefinition(
+                    name=name,
+                    description=description,
+                    content=content,
+                    source=source,
+                    path=str(path),
+                    base_dir=str(path.parent),
+                    command_name=default_name,
+                    display_name=display_name,
+                    user_invocable=metadata["user_invocable"],
+                    disable_model_invocation=metadata["disable_model_invocation"],
+                    model=metadata["model"],
+                    argument_hint=metadata["argument_hint"],
+                )
+            )
+    return skills
+
+
+def _parse_skill_markdown(default_name: str, content: str) -> tuple[str, str]:
+    """Parse name and description from a skill markdown file with YAML frontmatter support."""
+    return parse_skill_frontmatter(default_name, content, fallback_template="Skill: {name}")
+
+
+def _parse_skill_metadata(default_name: str, content: str) -> dict:
+    parsed = parse_skill_metadata(default_name, content, fallback_template="Skill: {name}")
+    frontmatter = parsed.get("frontmatter")
+    if not isinstance(frontmatter, dict):
+        frontmatter = {}
+    return {
+        "name": str(parsed["name"]),
+        "description": str(parsed["description"]),
+        "user_invocable": parse_bool_frontmatter(frontmatter.get("user-invocable"), default=True),
+        "disable_model_invocation": parse_bool_frontmatter(
+            frontmatter.get("disable-model-invocation"),
+            default=False,
+        ),
+        "model": optional_frontmatter_str(frontmatter.get("model")),
+        "argument_hint": optional_frontmatter_str(frontmatter.get("argument-hint")),
+    }

src/harness/src/openharness/skills/registry.py

@@ -0,0 +1,29 @@
+"""Skill registry."""
+
+from __future__ import annotations
+
+from openharness.skills.types import SkillDefinition
+
+
+class SkillRegistry:
+    """Store loaded skills by name."""
+
+    def __init__(self) -> None:
+        self._skills: dict[str, SkillDefinition] = {}
+
+    def register(self, skill: SkillDefinition) -> None:
+        """Register one skill."""
+        for key in (skill.name, skill.command_name, skill.display_name, *skill.aliases):
+            if key:
+                self._skills[key] = skill
+
+    def get(self, name: str) -> SkillDefinition | None:
+        """Return a skill by name."""
+        return self._skills.get(name)
+
+    def list_skills(self) -> list[SkillDefinition]:
+        """Return all skills sorted by name."""
+        unique: dict[tuple[str, str | None], SkillDefinition] = {}
+        for skill in self._skills.values():
+            unique[(skill.source, skill.path or skill.name)] = skill
+        return sorted(unique.values(), key=lambda skill: skill.command_name or skill.name)

src/harness/src/openharness/skills/types.py

@@ -0,0 +1,24 @@
+"""Skill data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SkillDefinition:
+    """A loaded skill."""
+
+    name: str
+    description: str
+    content: str
+    source: str
+    path: str | None = None
+    base_dir: str | None = None
+    command_name: str | None = None
+    display_name: str | None = None
+    aliases: tuple[str, ...] = ()
+    user_invocable: bool = True
+    disable_model_invocation: bool = False
+    model: str | None = None
+    argument_hint: str | None = None

src/harness/src/openharness/state/__init__.py

@@ -0,0 +1,6 @@
+"""State exports."""
+
+from openharness.state.app_state import AppState
+from openharness.state.store import AppStateStore
+
+__all__ = ["AppState", "AppStateStore"]