skillware 0.3.1__tar.gz → 0.3.3__tar.gz

{skillware-0.3.1/skillware.egg-info → skillware-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.3.1
+Version: 0.3.3
 Summary: A framework for modular, self-contained AI skills.
 Author-email: ARPA Hellenic Logical Systems <skillware-os@arpacorp.net>
 License: MIT License
@@ -37,6 +37,7 @@ Requires-Dist: requests
 Requires-Dist: pyyaml
 Requires-Dist: python-dotenv
 Requires-Dist: beautifulsoup4
+Requires-Dist: packaging
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"
@@ -83,6 +84,7 @@ Dynamic: license-file
   <a href="#documentation">Documentation</a> •
   <a href="#contributing">Contributing</a> •
   <a href="#comparison">Comparison</a> •
+  <a href="CHANGELOG.md">Changelog</a> •
   <a href="#contact">Contact</a>
 </div>
 
@@ -94,18 +96,18 @@ Dynamic: license-file
 
 ## Mission
 
-The AI ecosystem is fragmented. Developers often re-invent tool definitions, system prompts, and safety rules for every project. **Skillware** supplies a standard to package capabilities into self-contained units that work across **Gemini**, **Claude**, **Ollama**, **GPT**, and **Llama**.
+The AI ecosystem is fragmented. Developers often re-invent tool definitions, system prompts, and safety rules for every project. **Skillware** supplies a standard to package capabilities into self-contained, installable units that work across **Gemini**, **Claude**, **Ollama**, **GPT**, and **Llama**. For the full story and roadmap, see our **[Vision](docs/vision.md)**.
 
 A **Skill** in this framework provides everything an Agent needs to master a domain:
 
-1.  **Logic**: Executable Python code.
-2.  **Cognition**: System instructions and "cognitive maps".
-3.  **Governance**: Constitution and safety boundaries.
-4.  **Interface**: Standardized schemas for LLM tool calling.
+1. **Logic**: Executable Python so agents run real work, not guess it.
+2. **Cognition**: System instructions and cognitive maps so any logical system uses the capability as intended.
+3. **Governance**: Constitution, safety boundaries, and hard limits baked into the bundle.
+4. **Interface**: Standardized tool schemas for any LLM or agent runtime.
 
 ### Skill library
 
-Browse capabilities by category in the [Skill library](docs/skills/README.md).
+Browse capabilities by category in the [Skill library](docs/skills/README.md) or on our <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">site&nbsp;↗</a>.
 
 ## Architecture
 
@@ -163,7 +165,7 @@ pip install "skillware[cli]"
 skillware list
 ```
 
-This prints a table of all locally available skills and confirms the install and path resolution are working.
+This prints a table of all locally available skills and confirms the install and path resolution are working. Running `skillware` with no arguments opens the interactive menu.
 
 ### 3. Configuration
 
@@ -237,29 +239,23 @@ For other providers and shared integration patterns, see the [usage guides index
 
 ## Documentation
 
-| Topic | Link |
+| Topic | Links |
 | :--- | :--- |
-| Introduction | [docs/introduction.md](docs/introduction.md) |
-| Testing | [docs/TESTING.md](docs/TESTING.md) |
-| Skill library | [docs/skills/README.md](docs/skills/README.md) |
-| Usage guides | [index](docs/usage/README.md) — [Gemini](docs/usage/gemini.md) · [Claude](docs/usage/claude.md) · [OpenAI](docs/usage/openai.md) · [DeepSeek](docs/usage/deepseek.md) · [Ollama](docs/usage/ollama.md); [agent loops](docs/usage/agent_loops.md); [API keys](docs/usage/api_keys.md) |
-| Examples index | [examples/README.md](examples/README.md) |
-| CLI | [docs/usage/cli.md](docs/usage/cli.md) |
-| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) · [agent workflow](docs/contributing/ai_native_workflow.md) |
+| **Introduction** | [Introduction](docs/introduction.md) · [Vision](docs/vision.md) · [Comparison](COMPARISON.md) |
+| **Usage guides** | [Skill Library](docs/skills/README.md) · [Usage Guide](docs/usage/README.md) · [Examples](examples/README.md) · [Agent Loops](docs/usage/agent_loops.md) · [API Keys](docs/usage/api_keys.md) · [CLI](docs/usage/cli.md) |
+| **Contributing** | [Contributing](CONTRIBUTING.md) · [Agent Native Workflow](docs/contributing/ai_native_workflow.md) · [Testing](docs/TESTING.md) · [Changelog](CHANGELOG.md) |
 
 ## Contributing
 
-We are building the "App Store" for Agents and require professional, robust, and safe skills. We welcome contributions to the skill registry, documentation, tests, and core framework.
+We are building the "App Store" for Agents. Skills are the main contribution, but documentation, tests, and framework fixes are welcome too. Human operators and supervised agents follow the same standards: scoped PRs, deterministic behavior, and verified tests.
 
-* **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution types, skill standard, pull request process, and navigation to all contributor docs.
-* **[Agent Contribution Workflow](docs/contributing/ai_native_workflow.md)** — Workflow for AI agents contributing to the repository (operators supervise).
-* **[Agent Code of Conduct](CODE_OF_CONDUCT.md)** — Deterministic outputs, safety boundaries, and acceptable use of skills.
-* **[TESTING.md](docs/TESTING.md)** — Local linting and pytest before you open a PR.
-* **[Pull request template](.github/PULL_REQUEST_TEMPLATE.md)** — Checklists for skills, docs, and framework changes (complete only the sections that apply).
+See the **Contributing** row in [Documentation](#documentation) for the full path, [Contributing](CONTRIBUTING.md) (types, skill standard, PR process), [Agent Native Workflow](docs/contributing/ai_native_workflow.md) (for autonomous and semi-autonomous agents), [Testing](docs/TESTING.md) (Black, Flake8, framework and skill pytest, pre-PR checklist), and [Changelog](CHANGELOG.md) (user-facing entries under `[Unreleased]`).
+
+Also read the [Agent Code of Conduct](CODE_OF_CONDUCT.md). Open PRs with the [pull request template](.github/PULL_REQUEST_TEMPLATE.md) and complete only the sections that apply.
 
 ## Comparison
 
-Skillware differs from the Model Context Protocol (MCP) or Anthropic's Skills repository in the following ways:
+Skillware differs from the Model Context Protocol (MCP), and Anthropic's Skills repository in several ways:
 
 *   **Model Agnostic**: Native adapters for Gemini, Claude, Ollama, and OpenAI.
 *   **Code-First**: Skills are executable Python packages, not just server specs.
@@ -272,8 +268,12 @@ Skillware differs from the Model Context Protocol (MCP) or Anthropic's Skills re
 For questions, suggestions, or contributions, please open an issue or reach out to us:
 
 *   **Email**: [skillware-os@arpacorp.net](mailto:skillware-os@arpacorp.net)
+*   **Enterprise**: [skills@arpacorp.net](mailto:skills@arpacorp.net) — enterprise skills, chaining, and forward deployed engineering
+*   **Security**: [security@arpacorp.net](mailto:security@arpacorp.net) — report bugs, vulnerabilities, or other sensitive issues (see [SECURITY.md](SECURITY.md))
 *   **Issues**: [GitHub Issues](https://github.com/arpahls/skillware/issues)
 
+For skill-specific questions or reaching a skill's maintainer, check issuer and author details on the skill card, in the repo [Skill Library](docs/skills/README.md), or on our website's <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">skills catalog&nbsp;↗</a>.
+
 ---
 
 <div align="center">

{skillware-0.3.1 → skillware-0.3.3}/README.md

@@ -21,6 +21,7 @@
   <a href="#documentation">Documentation</a> •
   <a href="#contributing">Contributing</a> •
   <a href="#comparison">Comparison</a> •
+  <a href="CHANGELOG.md">Changelog</a> •
   <a href="#contact">Contact</a>
 </div>
 
@@ -32,18 +33,18 @@
 
 ## Mission
 
-The AI ecosystem is fragmented. Developers often re-invent tool definitions, system prompts, and safety rules for every project. **Skillware** supplies a standard to package capabilities into self-contained units that work across **Gemini**, **Claude**, **Ollama**, **GPT**, and **Llama**.
+The AI ecosystem is fragmented. Developers often re-invent tool definitions, system prompts, and safety rules for every project. **Skillware** supplies a standard to package capabilities into self-contained, installable units that work across **Gemini**, **Claude**, **Ollama**, **GPT**, and **Llama**. For the full story and roadmap, see our **[Vision](docs/vision.md)**.
 
 A **Skill** in this framework provides everything an Agent needs to master a domain:
 
-1.  **Logic**: Executable Python code.
-2.  **Cognition**: System instructions and "cognitive maps".
-3.  **Governance**: Constitution and safety boundaries.
-4.  **Interface**: Standardized schemas for LLM tool calling.
+1. **Logic**: Executable Python so agents run real work, not guess it.
+2. **Cognition**: System instructions and cognitive maps so any logical system uses the capability as intended.
+3. **Governance**: Constitution, safety boundaries, and hard limits baked into the bundle.
+4. **Interface**: Standardized tool schemas for any LLM or agent runtime.
 
 ### Skill library
 
-Browse capabilities by category in the [Skill library](docs/skills/README.md).
+Browse capabilities by category in the [Skill library](docs/skills/README.md) or on our <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">site&nbsp;↗</a>.
 
 ## Architecture
 
@@ -101,7 +102,7 @@ pip install "skillware[cli]"
 skillware list
 ```
 
-This prints a table of all locally available skills and confirms the install and path resolution are working.
+This prints a table of all locally available skills and confirms the install and path resolution are working. Running `skillware` with no arguments opens the interactive menu.
 
 ### 3. Configuration
 
@@ -175,29 +176,23 @@ For other providers and shared integration patterns, see the [usage guides index
 
 ## Documentation
 
-| Topic | Link |
+| Topic | Links |
 | :--- | :--- |
-| Introduction | [docs/introduction.md](docs/introduction.md) |
-| Testing | [docs/TESTING.md](docs/TESTING.md) |
-| Skill library | [docs/skills/README.md](docs/skills/README.md) |
-| Usage guides | [index](docs/usage/README.md) — [Gemini](docs/usage/gemini.md) · [Claude](docs/usage/claude.md) · [OpenAI](docs/usage/openai.md) · [DeepSeek](docs/usage/deepseek.md) · [Ollama](docs/usage/ollama.md); [agent loops](docs/usage/agent_loops.md); [API keys](docs/usage/api_keys.md) |
-| Examples index | [examples/README.md](examples/README.md) |
-| CLI | [docs/usage/cli.md](docs/usage/cli.md) |
-| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) · [agent workflow](docs/contributing/ai_native_workflow.md) |
+| **Introduction** | [Introduction](docs/introduction.md) · [Vision](docs/vision.md) · [Comparison](COMPARISON.md) |
+| **Usage guides** | [Skill Library](docs/skills/README.md) · [Usage Guide](docs/usage/README.md) · [Examples](examples/README.md) · [Agent Loops](docs/usage/agent_loops.md) · [API Keys](docs/usage/api_keys.md) · [CLI](docs/usage/cli.md) |
+| **Contributing** | [Contributing](CONTRIBUTING.md) · [Agent Native Workflow](docs/contributing/ai_native_workflow.md) · [Testing](docs/TESTING.md) · [Changelog](CHANGELOG.md) |
 
 ## Contributing
 
-We are building the "App Store" for Agents and require professional, robust, and safe skills. We welcome contributions to the skill registry, documentation, tests, and core framework.
+We are building the "App Store" for Agents. Skills are the main contribution, but documentation, tests, and framework fixes are welcome too. Human operators and supervised agents follow the same standards: scoped PRs, deterministic behavior, and verified tests.
 
-* **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution types, skill standard, pull request process, and navigation to all contributor docs.
-* **[Agent Contribution Workflow](docs/contributing/ai_native_workflow.md)** — Workflow for AI agents contributing to the repository (operators supervise).
-* **[Agent Code of Conduct](CODE_OF_CONDUCT.md)** — Deterministic outputs, safety boundaries, and acceptable use of skills.
-* **[TESTING.md](docs/TESTING.md)** — Local linting and pytest before you open a PR.
-* **[Pull request template](.github/PULL_REQUEST_TEMPLATE.md)** — Checklists for skills, docs, and framework changes (complete only the sections that apply).
+See the **Contributing** row in [Documentation](#documentation) for the full path, [Contributing](CONTRIBUTING.md) (types, skill standard, PR process), [Agent Native Workflow](docs/contributing/ai_native_workflow.md) (for autonomous and semi-autonomous agents), [Testing](docs/TESTING.md) (Black, Flake8, framework and skill pytest, pre-PR checklist), and [Changelog](CHANGELOG.md) (user-facing entries under `[Unreleased]`).
+
+Also read the [Agent Code of Conduct](CODE_OF_CONDUCT.md). Open PRs with the [pull request template](.github/PULL_REQUEST_TEMPLATE.md) and complete only the sections that apply.
 
 ## Comparison
 
-Skillware differs from the Model Context Protocol (MCP) or Anthropic's Skills repository in the following ways:
+Skillware differs from the Model Context Protocol (MCP), and Anthropic's Skills repository in several ways:
 
 *   **Model Agnostic**: Native adapters for Gemini, Claude, Ollama, and OpenAI.
 *   **Code-First**: Skills are executable Python packages, not just server specs.
@@ -210,8 +205,12 @@ Skillware differs from the Model Context Protocol (MCP) or Anthropic's Skills re
 For questions, suggestions, or contributions, please open an issue or reach out to us:
 
 *   **Email**: [skillware-os@arpacorp.net](mailto:skillware-os@arpacorp.net)
+*   **Enterprise**: [skills@arpacorp.net](mailto:skills@arpacorp.net) — enterprise skills, chaining, and forward deployed engineering
+*   **Security**: [security@arpacorp.net](mailto:security@arpacorp.net) — report bugs, vulnerabilities, or other sensitive issues (see [SECURITY.md](SECURITY.md))
 *   **Issues**: [GitHub Issues](https://github.com/arpahls/skillware/issues)
 
+For skill-specific questions or reaching a skill's maintainer, check issuer and author details on the skill card, in the repo [Skill Library](docs/skills/README.md), or on our website's <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">skills catalog&nbsp;↗</a>.
+
 ---
 
 <div align="center">

{skillware-0.3.1 → skillware-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillware"
-version = "0.3.1"
+version = "0.3.3"
 description = "A framework for modular, self-contained AI skills."
 readme = "README.md"
 authors = [
@@ -22,6 +22,7 @@ dependencies = [
     "pyyaml",
     "python-dotenv",
     "beautifulsoup4",
+    "packaging",
 ]
 requires-python = ">=3.10"
 

{skillware-0.3.1 → skillware-0.3.3}/skills/compliance/mica_module/manifest.yaml

@@ -1,6 +1,7 @@
 name: compliance/mica_module
 version: 0.1.0
 description: A highly specialized, localized RAG and policy enforcement engine for the Markets in Crypto-Assets (MiCA) regulation.
+short_description: "Local RAG and policy enforcement engine for MiCA regulation."
 issuer:
   name: Ross Peili
   email: vpeilivanidis@gmail.com

{skillware-0.3.1 → skillware-0.3.3}/skills/compliance/pii_masker/manifest.yaml

@@ -1,6 +1,7 @@
 name: compliance/pii_masker
 version: 0.1.0
 description: High-precision, local PII detection and redaction using the micro-f1-mask model via Ollama.
+short_description: "Detects and redacts PII locally using the micro-f1-mask model."
 issuer:
   name: Ross Peili
   email: vpeilivanidis@gmail.com

{skillware-0.3.1 → skillware-0.3.3}/skills/compliance/tos_evaluator/manifest.yaml

@@ -1,6 +1,7 @@
 name: "compliance/tos_evaluator"
 version: "0.1.0"
 description: "Evaluates whether an intended automated website action appears permissible by checking robots.txt, discovered legal pages, and optional low-cost LLM review for ambiguous policy language."
+short_description: "Evaluates whether an automated web action is permitted by site policy."
 issuer:
   name: Ross Peili
   email: vpeilivanidis@gmail.com

{skillware-0.3.1 → skillware-0.3.3}/skills/data_engineering/novelty_extractor/manifest.yaml

@@ -1,6 +1,7 @@
 name: "data_engineering/novelty_extractor"
 version: "0.1.0"
 description: "Filters a text dataset by semantic novelty, retaining only chunks that carry new information above a configurable threshold."
+short_description: "Filters text datasets by semantic novelty using local embeddings."
 issuer:
   name: Martin Rizzo Lozano
   email: rizzolozanomartin@gmail.com

{skillware-0.3.1 → skillware-0.3.3}/skills/data_engineering/synthetic_generator/manifest.yaml

@@ -1,6 +1,7 @@
 name: "data_engineering/synthetic_generator"
 version: "0.1.0"
 description: "Generates high-entropy structured synthetic data for model fine-tuning to avoid mode collapse."
+short_description: "Generates high-entropy synthetic JSONL data for model fine-tuning."
 issuer:
   name: Ross Peili
   email: vpeilivanidis@gmail.com

{skillware-0.3.1 → skillware-0.3.3}/skills/dev_tools/issue_resolver/card.json

@@ -1,6 +1,6 @@
 {
     "name": "Issue Resolver",
-    "description": "Analyzes any GitHub issue against its target repository and produces a structured resolution plan with ranked implementation options, affected files, and caveats.",
+    "description": "Guides an agent through resolving a GitHub issue on any repository: validates the issue URL, returns GitHub API endpoints, and provides sequential stage checklists with verify, commit, and pull request gates.",
     "issuer": {
         "name": "Ross Peili",
         "email": "vpeilivanidis@gmail.com",

skillware-0.3.3/skills/dev_tools/issue_resolver/instructions.md

@@ -0,0 +1,80 @@
+# Issue Resolver
+
+You are using the `dev_tools/issue_resolver` skill.
+
+Load this skill when the user provides a **GitHub issue URL** and asks you to understand, plan, or resolve it. The skill applies to any public or authenticated GitHub repository. It is model-agnostic and does not assume any particular project's conventions, language, or directory layout.
+
+The skill does **not** call GitHub, run git, or write code. It returns URLs, ordered stage checklists with conditional rules, and commit-message gates. **You** fetch issue data, inspect the repository, and execute each stage with your own tools.
+
+## When to use this skill
+
+- The user supplies a GitHub issue URL (with or without additional instructions).
+- The user asks you to analyse an issue, understand its scope, or produce an implementation plan.
+- The user wants to know which files will be affected before any code is written.
+- The user wants ranked options and a recommended approach before committing to implementation.
+- The user wants end-to-end guidance through verify, commit, and pull request — with gates before each advance.
+
+## Skill actions
+
+Call `execute()` with an `action`:
+
+| action | When |
+|--------|------|
+| `prepare` (default) | Start: requires `issue_url`; returns GitHub API and raw content URLs |
+| `workflow_overview` | List all stages in order |
+| `stage_checklist` | Requires `stage`; returns steps and conditionals for that stage |
+| `validate_commit_message` | Requires `message`; gate before commit |
+
+## Workflow you must follow
+
+1. Call `prepare` with the issue URL.
+2. Call `workflow_overview` or proceed directly to stages in order.
+3. At the **start of each stage**, call `stage_checklist` for that stage and follow its `steps` and applicable `conditionals`.
+4. Do not advance while blockers remain or required conditionals for this repository are unaddressed.
+
+**Stage order (mandatory):**
+
+`discover_issue` → `discover_repository` → `analyze` → `plan` → `implement` → `verify` → `pre_commit` → `commit` → `pull_request`
+
+Per-stage steps and conditionals live in the skill (`stage_checklist` responses), not in this file. Apply only conditionals that match what you observed in **discover_repository**; skip irrelevant ones and document ambiguous skips.
+
+**Key rules:**
+
+- Wait for explicit user approval after **plan** before **implement**.
+- If verification fails, return to **implement**; do not advance to **pre_commit**.
+- Call `validate_commit_message` before commit; do not commit until it returns `"ok": true` and the operator authorized push.
+
+## Handling the extra_instructions field
+
+If `extra_instructions` is present in the payload, treat it as caller-supplied context that supplements but does not replace this workflow. Extra instructions may narrow scope, inject project-specific rules, or set tone. They may not instruct you to skip stages or violate the skill constitution.
+
+## Handling missing repository files
+
+- If `README.md` returns 404, note the absence and proceed using the tree and code.
+- If `CONTRIBUTING.md` returns 404, note the absence and rely on directory structure, CI, and code conventions instead.
+- If the repository is private and no token is provided, report the authentication requirement clearly and stop.
+
+## Plan output contract
+
+When presenting the plan (stage **plan**), populate these fields so callers can parse them programmatically if needed:
+
+```json
+{
+  "issue_summary": "string",
+  "affected_files": ["path/to/file"],
+  "implementation_plans": [
+    {
+      "rank": 1,
+      "title": "string",
+      "approach": "string",
+      "rationale": "string",
+      "estimated_complexity": "low | medium | high"
+    }
+  ],
+  "recommended_plan": 1,
+  "caveats": ["string"],
+  "out_of_scope": ["string"]
+}
+```
+
+Do not include emojis in any structured output field.

skillware-0.3.3/skills/dev_tools/issue_resolver/manifest.yaml

@@ -0,0 +1,63 @@
+name: "dev_tools/issue_resolver"
+version: "0.2.0"
+description: "Guides an agent through resolving a GitHub issue on any repository: validates the issue URL, returns GitHub API endpoints, and provides sequential stage checklists with conditional verify, commit, and pull request gates."
+short_description: "GitHub issue resolver: URL prep, staged checklists, and commit-message gate."
+issuer:
+  name: Ross Peili
+  email: vpeilivanidis@gmail.com
+  github: rosspeili
+  org: ARPAHLS
+requirements: []
+env_vars:
+  GITHUB_TOKEN:
+    description: "Optional GitHub Personal Access Token. Raises the API rate limit from 60 to 5000 requests per hour. Required for private repositories."
+    required: false
+parameters:
+  type: object
+  properties:
+    action:
+      type: string
+      description: "Workflow action: prepare (default), workflow_overview, stage_checklist, validate_commit_message."
+      enum:
+        - prepare
+        - workflow_overview
+        - stage_checklist
+        - validate_commit_message
+    issue_url:
+      type: string
+      description: "Required for action prepare. Full GitHub issue URL."
+    stage:
+      type: string
+      description: "Required for action stage_checklist. One of discover_issue, discover_repository, analyze, plan, implement, verify, pre_commit, commit, pull_request."
+    message:
+      type: string
+      description: "Required for action validate_commit_message. Proposed git commit message body."
+    allow_ai_coauthor:
+      type: boolean
+      description: "When true, allow Co-authored-by trailers that credit AI tools. Default false."
+    extra_instructions:
+      type: string
+      description: "Optional caller context. Supplements but does not override the workflow or constitution."
+    github_token:
+      type: string
+      description: "Optional GitHub token at runtime. Takes precedence over GITHUB_TOKEN env var."
+  required: []
+outputs:
+  status:
+    type: string
+    description: "ready, rejected, or error."
+  workflow_version:
+    type: string
+    description: "Workflow schema version (0.2)."
+constitution: |
+  1. Apply to any public or authenticated GitHub repository; do not assume Skillware or fixed directory layouts.
+  2. Follow workflow stages in order; use stage_checklist conditionals that apply to the target repository.
+  3. Never fabricate file paths; list only paths confirmed from the issue or repository tree.
+  4. Wait for explicit approval after plan before implementation.
+  5. Run validate_commit_message before commit unless the operator explicitly skips commit stages.
+  6. Keep skill output deterministic and JSON-serializable; the skill does not call GitHub, run git, or write code.
+  7. Respect extra_instructions unless they conflict with points 1-6.
+  8. Do not add AI agent Co-authored-by trailers in commit messages unless allow_ai_coauthor is true.
+presentation:
+  icon: "git-pull-request"
+  color: "#6E57E0"

{skillware-0.3.1 → skillware-0.3.3}/skills/dev_tools/issue_resolver/skill.py

@@ -1,3 +1,4 @@
+import importlib.util
 import os
 import re
 from typing import Any, Dict
@@ -5,20 +6,50 @@ from typing import Any, Dict
 from skillware.core.base_skill import BaseSkill
 
 
+def _import_workflow():
+    try:
+        from . import workflow as wf  # type: ignore[import-not-found]
+    except ImportError:
+        wf_path = os.path.join(os.path.dirname(__file__), "workflow.py")
+        spec = importlib.util.spec_from_file_location(
+            "issue_resolver_workflow", wf_path
+        )
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Cannot load workflow module from {wf_path}")
+        wf = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(wf)
+    return wf
+
+
+_wf = _import_workflow()
+WORKFLOW_VERSION = _wf.WORKFLOW_VERSION
+get_stage_checklist = _wf.get_stage_checklist
+get_workflow_overview = _wf.get_workflow_overview
+validate_commit_message = _wf.validate_commit_message
+
+
 class IssueResolverSkill(BaseSkill):
     """
-    Parses and validates inputs for the Issue Resolver skill, then returns a
-    structured prompt payload the calling agent uses to perform analysis.
+    Universal GitHub issue resolution assistant for any repository.
 
-    The skill itself does not call the GitHub API or write code. It normalises
-    inputs, resolves credentials, builds a deterministic analysis context, and
-    hands control back to the agent's own reasoning and tool-use capabilities.
+    The skill does not call GitHub, run git, or write code. It returns
+    deterministic workflow payloads, stage checklists with conditional logic,
+    and commit-message gates for the calling agent to execute in order.
     """
 
     _GITHUB_ISSUE_RE = re.compile(
         r"https?://github\.com/(?P<owner>[^/]+)/(?P<repo>[^/]+)/issues/(?P<number>\d+)"
     )
 
+    _VALID_ACTIONS = frozenset(
+        {
+            "prepare",
+            "workflow_overview",
+            "stage_checklist",
+            "validate_commit_message",
+        }
+    )
+
     @property
     def manifest(self) -> Dict[str, Any]:
         manifest_path = os.path.join(os.path.dirname(__file__), "manifest.yaml")
@@ -30,11 +61,6 @@ class IssueResolverSkill(BaseSkill):
         return {}
 
     def _parse_issue_url(self, url: str) -> Dict[str, str]:
-        """
-        Extracts owner, repo, and issue number from a GitHub issue URL.
-        Returns a dict with keys: owner, repo, number, api_url, raw_url.
-        Raises ValueError if the URL does not match the expected pattern.
-        """
         match = self._GITHUB_ISSUE_RE.match(url.strip())
         if not match:
             raise ValueError(
@@ -55,10 +81,6 @@ class IssueResolverSkill(BaseSkill):
         }
 
     def _resolve_token(self, params: Dict[str, Any]) -> str:
-        """
-        Returns the GitHub token to use, preferring the runtime parameter over
-        the environment variable. Returns an empty string if neither is set.
-        """
         token = (params.get("github_token") or "").strip()
         if not token:
             token = (
@@ -66,20 +88,18 @@ class IssueResolverSkill(BaseSkill):
             )
         return token
 
-    def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        Validates inputs and returns a structured analysis context.
-
-        The returned dict contains everything the calling agent needs to begin
-        the resolution workflow using its own tools (HTTP fetching, file
-        inspection, reasoning). The agent should follow the instructions in
-        instructions.md when interpreting this payload.
-        """
+    def _action(self, params: Dict[str, Any]) -> str:
+        action = (params.get("action") or "prepare").strip().lower()
+        if action not in self._VALID_ACTIONS:
+            return "__invalid__"
+        return action
+
+    def _prepare(self, params: Dict[str, Any]) -> Dict[str, Any]:
         issue_url = (params.get("issue_url") or "").strip()
         if not issue_url:
             return {
                 "status": "error",
-                "message": "issue_url is required and must not be empty.",
+                "message": "issue_url is required for action prepare.",
             }
 
         try:
@@ -102,6 +122,8 @@ class IssueResolverSkill(BaseSkill):
 
         return {
             "status": "ready",
+            "action": "prepare",
+            "workflow_version": WORKFLOW_VERSION,
             "issue": {
                 "url": parsed["raw_url"],
                 "api_url": parsed["api_url"],
@@ -131,8 +153,55 @@ class IssueResolverSkill(BaseSkill):
             },
             "extra_instructions": extra_instructions or None,
             "next_step": (
-                "Follow the workflow in instructions.md. Fetch the issue, "
-                "read the repository context, then produce the structured "
-                "resolution plan as described."
+                "Call action workflow_overview or stage_checklist for discover_issue. "
+                "Follow instructions.md stages in order; do not skip gates."
             ),
         }
+
+    def _stage_checklist(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        stage = (params.get("stage") or "").strip().lower()
+        if not stage:
+            return {
+                "status": "error",
+                "message": "stage is required for action stage_checklist.",
+            }
+        payload = get_stage_checklist(stage)
+        if payload is None:
+            return {
+                "status": "error",
+                "message": f"Unknown stage {stage!r}. Call workflow_overview for valid names.",
+            }
+        payload["action"] = "stage_checklist"
+        return payload
+
+    def _validate_commit_message(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        message = params.get("message")
+        if message is None or not str(message).strip():
+            return {
+                "status": "error",
+                "message": "message is required for action validate_commit_message.",
+            }
+        allow = bool(params.get("allow_ai_coauthor", False))
+        result = validate_commit_message(str(message), allow_ai_coauthor=allow)
+        result["action"] = "validate_commit_message"
+        return result
+
+    def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        action = self._action(params)
+        if action == "__invalid__":
+            allowed = ", ".join(sorted(self._VALID_ACTIONS))
+            return {
+                "status": "error",
+                "message": f"Unknown action. Supported actions: {allowed}.",
+            }
+        if action == "prepare":
+            return self._prepare(params)
+        if action == "workflow_overview":
+            overview = get_workflow_overview()
+            overview["action"] = "workflow_overview"
+            return overview
+        if action == "stage_checklist":
+            return self._stage_checklist(params)
+        if action == "validate_commit_message":
+            return self._validate_commit_message(params)
+        return {"status": "error", "message": "Unhandled action."}