skillware 0.3.2__tar.gz → 0.3.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.3.2
+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"
@@ -81,9 +82,9 @@ Dynamic: license-file
   <a href="#architecture">Architecture</a> •
   <a href="#quick-start">Quick Start</a> •
   <a href="#documentation">Documentation</a> •
-  <a href="CHANGELOG.md">Changelog</a> •
   <a href="#contributing">Contributing</a> •
   <a href="#comparison">Comparison</a> •
+  <a href="CHANGELOG.md">Changelog</a> •
   <a href="#contact">Contact</a>
 </div>
 
@@ -95,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
 
@@ -238,30 +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) |
-| Changelog | [CHANGELOG.md](CHANGELOG.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.
@@ -274,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.2 → skillware-0.3.3}/README.md

@@ -19,9 +19,9 @@
   <a href="#architecture">Architecture</a> •
   <a href="#quick-start">Quick Start</a> •
   <a href="#documentation">Documentation</a> •
-  <a href="CHANGELOG.md">Changelog</a> •
   <a href="#contributing">Contributing</a> •
   <a href="#comparison">Comparison</a> •
+  <a href="CHANGELOG.md">Changelog</a> •
   <a href="#contact">Contact</a>
 </div>
 
@@ -33,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
 
@@ -176,30 +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) |
-| Changelog | [CHANGELOG.md](CHANGELOG.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.
@@ -212,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.2 → skillware-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillware"
-version = "0.3.2"
+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.2 → 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.2 → 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."}

{skillware-0.3.2 → skillware-0.3.3}/skills/dev_tools/issue_resolver/test_skill.py

@@ -43,6 +43,7 @@ def test_manifest_name(skill, manifest):
 def test_manifest_version(skill, manifest):
     """Skill internal manifest version must match manifest.yaml."""
     assert skill.manifest["version"] == manifest["version"]
+    assert manifest["version"] == "0.2.0"
 
 
 def test_manifest_has_real_issuer(manifest):
@@ -68,11 +69,14 @@ def test_card_issuer_matches_manifest(manifest, card):
 
 
 def test_missing_issue_url_returns_error(skill):
-    """execute() must return a structured error when issue_url is absent."""
+    """prepare requires issue_url."""
     result = skill.execute({})
     assert result["status"] == "error"
     assert "issue_url" in result["message"].lower()
 
+    result = skill.execute({"action": "prepare"})
+    assert result["status"] == "error"
+
 
 def test_empty_issue_url_returns_error(skill):
     """execute() must return a structured error when issue_url is empty string."""
@@ -183,3 +187,60 @@ def test_next_step_present(skill):
     assert "next_step" in result
     assert isinstance(result["next_step"], str)
     assert len(result["next_step"]) > 0
+
+
+def test_prepare_includes_workflow_version(skill):
+    result = skill.execute({"issue_url": VALID_URL})
+    assert result["workflow_version"] == "0.2"
+    assert result["action"] == "prepare"
+
+
+def test_workflow_overview(skill):
+    result = skill.execute({"action": "workflow_overview"})
+    assert result["status"] == "ready"
+    assert result["action"] == "workflow_overview"
+    assert len(result["stage_order"]) == 9
+    assert result["stage_order"][0] == "discover_issue"
+
+
+def test_stage_checklist_discover_issue(skill):
+    result = skill.execute({"action": "stage_checklist", "stage": "discover_issue"})
+    assert result["status"] == "ready"
+    assert result["stage"] == "discover_issue"
+    assert result["steps"]
+    assert result["conditionals"]
+    assert result["next_stage"] == "discover_repository"
+
+
+def test_stage_checklist_unknown_stage(skill):
+    result = skill.execute({"action": "stage_checklist", "stage": "not_a_stage"})
+    assert result["status"] == "error"
+
+
+def test_validate_commit_message_rejects_ai_coauthor(skill):
+    result = skill.execute(
+        {
+            "action": "validate_commit_message",
+            "message": "Fix bug\n\nCo-authored-by: Cursor <cursoragent@cursor.com>",
+        }
+    )
+    assert result["status"] == "rejected"
+    assert result["ok"] is False
+    assert result["violations"]
+
+
+def test_validate_commit_message_accepts_clean_message(skill):
+    result = skill.execute(
+        {
+            "action": "validate_commit_message",
+            "message": "Fix null handling in parser\n\nFixes #143",
+        }
+    )
+    assert result["status"] == "ready"
+    assert result["ok"] is True
+    assert result["violations"] == []
+
+
+def test_unknown_action(skill):
+    result = skill.execute({"action": "fly"})
+    assert result["status"] == "error"