skillware 0.2.7__tar.gz → 0.2.8__tar.gz

{skillware-0.2.7/skillware.egg-info → skillware-0.2.8}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.2.7
+Version: 0.2.8
 Summary: A framework for modular, self-contained AI skills.
-Author-email: ARPA Hellenic Logic Systems <skillware-os@arpacorp.net>
+Author-email: ARPA Hellenic Logical Systems <skillware-os@arpacorp.net>
 License: MIT License
         
         Copyright (c) 2026 ARPA Hellenic Logical Systems

{skillware-0.2.7 → skillware-0.2.8}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillware"
-version = "0.2.7"
+version = "0.2.8"
 description = "A framework for modular, self-contained AI skills."
 readme = "README.md"
 authors = [
-  { name = "ARPA Hellenic Logic Systems", email = "skillware-os@arpacorp.net" },
+  { name = "ARPA Hellenic Logical Systems", email = "skillware-os@arpacorp.net" },
 ]
 urls = { "Homepage" = "https://arpacorp.net", "Repository" = "https://github.com/arpahls/skillware" }
 license = { file = "LICENSE" }

skillware-0.2.8/skills/dev_tools/__init__.py

@@ -0,0 +1 @@
+# dev_tools skill category.

skillware-0.2.8/skills/dev_tools/issue_resolver/__init__.py

@@ -0,0 +1 @@
+# Issue Resolver skill package.

skillware-0.2.8/skills/dev_tools/issue_resolver/card.json

@@ -0,0 +1,33 @@
+{
+    "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.",
+    "issuer": {
+        "name": "Ross Peili",
+        "email": "vpeilivanidis@gmail.com",
+        "github": "rosspeili",
+        "org": "ARPAHLS"
+    },
+    "icon": "git-pull-request",
+    "color": "#6E57E0",
+    "ui_schema": {
+        "type": "card",
+        "fields": [
+            {
+                "key": "status",
+                "label": "Status"
+            },
+            {
+                "key": "issue.number",
+                "label": "Issue"
+            },
+            {
+                "key": "issue.repo",
+                "label": "Repository"
+            },
+            {
+                "key": "auth.token_provided",
+                "label": "Authenticated"
+            }
+        ]
+    }
+}

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

@@ -0,0 +1,104 @@
+# 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 begin resolving it. The skill applies to any public GitHub repository. It is model-agnostic and does not assume any particular project's conventions.
+
+## 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.
+
+## Workflow you must follow after receiving the skill payload
+
+The skill's `execute()` call returns a `status: ready` payload containing pre-computed URLs. Use those URLs with your available tools to carry out the following stages in order. Do not skip stages.
+
+### Stage 1 — Fetch the issue
+
+Using the `issue.api_url` from the payload:
+
+1. Fetch the issue via the GitHub API. If `auth.token_provided` is true, include the `Authorization: Bearer <token>` header.
+2. Extract: title, body, labels, state, assignees, milestone.
+3. Fetch any linked comments (`issue.api_url/comments`) and skim for decisions, constraints, or acceptance criteria that are not in the body.
+4. Check for linked pull requests or referenced issues in the body.
+
+### Stage 2 — Understand the repository
+
+Using the `repository` URLs from the payload:
+
+1. Fetch and read `repository.readme_url`. Identify: project purpose, tech stack, install instructions, any stated conventions.
+2. Fetch and read `repository.contributing_url` if it exists (do not fail if it returns 404). Identify: contribution workflow, code style, PR requirements, any skill or module standards.
+3. Fetch the directory tree via `repository.tree_api_url`. Identify the top-level structure: key source directories, test directories, docs directories, CI configuration, and any existing analogues to what the issue requests.
+4. If the issue references specific files or directories, fetch and inspect their current contents.
+
+### Stage 3 — Analyse
+
+Produce a structured internal analysis covering:
+
+- **Problem statement**: what the issue is actually asking for, including unstated implications.
+- **Acceptance criteria**: verifiable bullets extracted or inferred from the issue body and comments.
+- **Affected files**: every path likely to change — source, tests, documentation, CI, changelogs, configuration. Only list paths you have confirmed exist or have strong reason to expect.
+- **Ripple effects**: downstream files, dependent modules, or external consumers that may be affected even if not directly changed.
+- **Options**: up to three distinct implementation approaches with honest trade-off analysis (complexity, risk, alignment with project conventions, reversibility).
+- **Recommendation**: one approach with a clear rationale.
+- **Out of scope**: what you will not do in this resolution cycle and why.
+- **Caveats**: required dependencies, breaking changes, security concerns, or prerequisites.
+
+### Stage 4 — Produce the resolution plan
+
+Format your output as a structured plan. Present it clearly to the user before writing any code. Include:
+
+1. Issue summary (2-4 sentences).
+2. Acceptance criteria (bulleted list).
+3. Affected files table (path, change type: new / modify / delete, rationale).
+4. Implementation options (ranked 1-3, each with title, approach, rationale, estimated complexity: low / medium / high).
+5. Recommended option with rationale.
+6. Caveats (bulleted list).
+7. Out of scope (bulleted list).
+
+Wait for explicit user approval of the plan before proceeding to implementation.
+
+### Stage 5 — Implementation (only after approval)
+
+Proceed only if the user explicitly approves a plan option. Then:
+
+- Implement only what the approved plan describes. Do not refactor unrelated code.
+- Follow project conventions observed in Stage 2.
+- After implementing, verify your work against every acceptance criterion.
+- Report verification results to the user with evidence.
+
+## 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.
+- If `CONTRIBUTING.md` returns 404, note the absence and rely on directory structure and code conventions instead.
+- If the repository is private and no token is provided, report the authentication requirement clearly and stop.
+
+## Output contract
+
+When presenting the 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", "..."]
+}
+```
+
+Do not include emojis in any output field.

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

@@ -0,0 +1,55 @@
+name: "dev_tools/issue_resolver"
+version: "0.1.0"
+description: "Analyzes any GitHub issue against its target repository and produces a structured resolution plan with ranked implementation options, affected files, and caveats."
+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:
+    issue_url:
+      type: string
+      description: "Full GitHub issue URL, e.g. https://github.com/owner/repo/issues/42"
+    extra_instructions:
+      type: string
+      description: "Optional free-text instructions appended to the analysis prompt. Use this to inject project-specific context, style constraints, or scope limits."
+    github_token:
+      type: string
+      description: "Optional GitHub Personal Access Token passed at runtime. Takes precedence over the GITHUB_TOKEN environment variable."
+  required:
+    - issue_url
+outputs:
+  issue_summary:
+    type: string
+    description: "Plain-language summary of what the issue is asking for, including unstated implications."
+  affected_files:
+    type: array
+    description: "Paths of files likely to be touched, including source, tests, docs, and CI."
+  implementation_plans:
+    type: array
+    description: "Up to three ranked approaches. Each entry contains: rank, title, approach, rationale, estimated_complexity."
+  recommended_plan:
+    type: integer
+    description: "Rank (1-based) of the recommended implementation plan."
+  caveats:
+    type: array
+    description: "Dependencies, breaking changes, security concerns, or out-of-scope items the implementing agent must be aware of."
+constitution: |
+  1. Read the full issue body, labels, and any linked comments or PRs before forming an opinion.
+  2. Inspect the repository README, CONTRIBUTING guide, and top-level directory structure to understand project conventions before proposing changes.
+  3. Never fabricate file paths; only list paths that can be confirmed from the repository structure you observed.
+  4. Rank implementation options honestly based on complexity, risk, and alignment with existing project patterns.
+  5. Surface caveats explicitly rather than burying them inside plan prose.
+  6. Keep output deterministic and JSON-serializable; do not embed conversational filler in structured fields.
+  7. Do not write or propose actual implementation code; this skill produces analysis and planning output only.
+  8. Respect any extra_instructions provided by the caller, but do not let them override points 1-7 of this constitution.
+presentation:
+  icon: "git-pull-request"
+  color: "#6E57E0"

skillware-0.2.8/skills/dev_tools/issue_resolver/skill.py

@@ -0,0 +1,138 @@
+import os
+import re
+from typing import Any, Dict
+
+from skillware.core.base_skill import BaseSkill
+
+
+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.
+
+    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.
+    """
+
+    _GITHUB_ISSUE_RE = re.compile(
+        r"https?://github\.com/(?P<owner>[^/]+)/(?P<repo>[^/]+)/issues/(?P<number>\d+)"
+    )
+
+    @property
+    def manifest(self) -> Dict[str, Any]:
+        manifest_path = os.path.join(os.path.dirname(__file__), "manifest.yaml")
+        if os.path.exists(manifest_path):
+            import yaml
+
+            with open(manifest_path, "r", encoding="utf-8") as f:
+                return yaml.safe_load(f)
+        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(
+                f"issue_url does not match the expected GitHub issue URL pattern: {url!r}. "
+                "Expected format: https://github.com/<owner>/<repo>/issues/<number>"
+            )
+        owner = match.group("owner")
+        repo = match.group("repo")
+        number = match.group("number")
+        return {
+            "owner": owner,
+            "repo": repo,
+            "number": number,
+            "api_url": f"https://api.github.com/repos/{owner}/{repo}/issues/{number}",
+            "raw_url": url.strip(),
+            "repo_api_url": f"https://api.github.com/repos/{owner}/{repo}",
+            "repo_html_url": f"https://github.com/{owner}/{repo}",
+        }
+
+    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 = (
+                self.config.get("GITHUB_TOKEN") or os.environ.get("GITHUB_TOKEN") or ""
+            )
+        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.
+        """
+        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.",
+            }
+
+        try:
+            parsed = self._parse_issue_url(issue_url)
+        except ValueError as exc:
+            return {"status": "error", "message": str(exc)}
+
+        token = self._resolve_token(params)
+        extra_instructions = (params.get("extra_instructions") or "").strip()
+
+        auth_header_note = (
+            "Include the Authorization header: Bearer <GITHUB_TOKEN>."
+            if token
+            else (
+                "No GITHUB_TOKEN is configured. The GitHub API will apply the "
+                "unauthenticated rate limit (60 requests per hour). For private "
+                "repositories or high-volume usage, set GITHUB_TOKEN."
+            )
+        )
+
+        return {
+            "status": "ready",
+            "issue": {
+                "url": parsed["raw_url"],
+                "api_url": parsed["api_url"],
+                "owner": parsed["owner"],
+                "repo": parsed["repo"],
+                "number": parsed["number"],
+            },
+            "repository": {
+                "html_url": parsed["repo_html_url"],
+                "api_url": parsed["repo_api_url"],
+                "readme_url": (
+                    f"https://raw.githubusercontent.com/{parsed['owner']}"
+                    f"/{parsed['repo']}/HEAD/README.md"
+                ),
+                "contributing_url": (
+                    f"https://raw.githubusercontent.com/{parsed['owner']}"
+                    f"/{parsed['repo']}/HEAD/CONTRIBUTING.md"
+                ),
+                "tree_api_url": (
+                    f"https://api.github.com/repos/{parsed['owner']}/{parsed['repo']}"
+                    "/git/trees/HEAD?recursive=1"
+                ),
+            },
+            "auth": {
+                "token_provided": bool(token),
+                "note": auth_header_note,
+            },
+            "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."
+            ),
+        }

skillware-0.2.8/skills/dev_tools/issue_resolver/test_skill.py

@@ -0,0 +1,185 @@
+import json
+import unittest.mock as mock
+import os
+
+import pytest
+import yaml
+
+from .skill import IssueResolverSkill
+
+
+@pytest.fixture
+def skill():
+    """Initialise the skill with no config (mirrors production load)."""
+    return IssueResolverSkill()
+
+
+@pytest.fixture
+def manifest():
+    """Load manifest.yaml for schema validation."""
+    manifest_path = os.path.join(os.path.dirname(__file__), "manifest.yaml")
+    with open(manifest_path, "r", encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+@pytest.fixture
+def card():
+    """Load card.json for issuer consistency checks."""
+    card_path = os.path.join(os.path.dirname(__file__), "card.json")
+    with open(card_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+# ---------------------------------------------------------------------------
+# Manifest integrity
+# ---------------------------------------------------------------------------
+
+
+def test_manifest_name(skill, manifest):
+    """Skill internal manifest name must match manifest.yaml."""
+    assert skill.manifest["name"] == manifest["name"]
+
+
+def test_manifest_version(skill, manifest):
+    """Skill internal manifest version must match manifest.yaml."""
+    assert skill.manifest["version"] == manifest["version"]
+
+
+def test_manifest_has_real_issuer(manifest):
+    """manifest.yaml issuer must have non-placeholder name and email."""
+    issuer = manifest.get("issuer", {})
+    assert issuer.get("name"), "issuer.name is required"
+    assert issuer.get("email"), "issuer.email is required"
+    assert issuer["name"].lower() != "your name"
+    assert issuer["email"].lower() != "you@example.com"
+
+
+def test_card_issuer_matches_manifest(manifest, card):
+    """card.json issuer name and email must match manifest.yaml."""
+    m_issuer = manifest.get("issuer", {})
+    c_issuer = card.get("issuer", {})
+    assert c_issuer.get("name", "").strip() == m_issuer.get("name", "").strip()
+    assert c_issuer.get("email", "").strip() == m_issuer.get("email", "").strip()
+
+
+# ---------------------------------------------------------------------------
+# Input validation
+# ---------------------------------------------------------------------------
+
+
+def test_missing_issue_url_returns_error(skill):
+    """execute() must return a structured error when issue_url is absent."""
+    result = skill.execute({})
+    assert result["status"] == "error"
+    assert "issue_url" in result["message"].lower()
+
+
+def test_empty_issue_url_returns_error(skill):
+    """execute() must return a structured error when issue_url is empty string."""
+    result = skill.execute({"issue_url": "  "})
+    assert result["status"] == "error"
+
+
+def test_malformed_url_returns_error(skill):
+    """A URL that is not a GitHub issue URL must produce a structured error."""
+    result = skill.execute({"issue_url": "https://example.com/not-an-issue"})
+    assert result["status"] == "error"
+    assert "issue_url" in result["message"].lower()
+
+
+def test_non_issue_github_url_returns_error(skill):
+    """A GitHub URL pointing to a PR or repo root must be rejected."""
+    result = skill.execute({"issue_url": "https://github.com/owner/repo/pull/42"})
+    assert result["status"] == "error"
+
+
+# ---------------------------------------------------------------------------
+# Happy-path execution
+# ---------------------------------------------------------------------------
+
+
+VALID_URL = "https://github.com/ARPAHLS/skillware/issues/56"
+
+
+def test_valid_url_returns_ready(skill):
+    """A well-formed GitHub issue URL must produce status: ready."""
+    result = skill.execute({"issue_url": VALID_URL})
+    assert result["status"] == "ready"
+
+
+def test_result_contains_issue_fields(skill):
+    """Ready result must include all issue sub-fields."""
+    result = skill.execute({"issue_url": VALID_URL})
+    issue = result["issue"]
+    assert issue["owner"] == "ARPAHLS"
+    assert issue["repo"] == "skillware"
+    assert issue["number"] == "56"
+    assert issue["api_url"].startswith(
+        "https://api.github.com/repos/ARPAHLS/skillware/issues/56"
+    )
+    assert issue["url"] == VALID_URL
+
+
+def test_result_contains_repository_fields(skill):
+    """Ready result must include pre-computed repository URL fields."""
+    result = skill.execute({"issue_url": VALID_URL})
+    repo = result["repository"]
+    assert repo["html_url"] == "https://github.com/ARPAHLS/skillware"
+    assert repo["api_url"].startswith("https://api.github.com/repos/ARPAHLS/skillware")
+    assert repo["readme_url"].startswith(
+        "https://raw.githubusercontent.com/ARPAHLS/skillware"
+    )
+    assert repo["readme_url"].endswith("README.md")
+    assert repo["tree_api_url"].startswith(
+        "https://api.github.com/repos/ARPAHLS/skillware"
+    )
+    assert "trees" in repo["tree_api_url"]
+
+
+def test_no_token_auth_note(skill):
+    """When no token is provided, auth.token_provided must be False."""
+    env_without_token = {k: v for k, v in os.environ.items() if k != "GITHUB_TOKEN"}
+    with mock.patch.dict(os.environ, env_without_token, clear=True):
+        skill.config = {}
+        result = skill.execute({"issue_url": VALID_URL})
+    assert result["auth"]["token_provided"] is False
+    assert "rate limit" in result["auth"]["note"].lower()
+
+
+def test_runtime_token_takes_precedence(skill):
+    """A token passed in params must be recognised over env vars."""
+    result = skill.execute({"issue_url": VALID_URL, "github_token": "ghp_test_token"})
+    assert result["auth"]["token_provided"] is True
+    assert "Authorization" in result["auth"]["note"]
+
+
+def test_extra_instructions_propagated(skill):
+    """extra_instructions must be present in the payload when provided."""
+    result = skill.execute(
+        {
+            "issue_url": VALID_URL,
+            "extra_instructions": "Focus only on test coverage gaps.",
+        }
+    )
+    assert result["extra_instructions"] == "Focus only on test coverage gaps."
+
+
+def test_no_extra_instructions_is_none(skill):
+    """extra_instructions must be None in the payload when not provided."""
+    result = skill.execute({"issue_url": VALID_URL})
+    assert result["extra_instructions"] is None
+
+
+def test_result_is_json_serializable(skill):
+    """execute() output must be fully JSON-serializable."""
+    result = skill.execute({"issue_url": VALID_URL})
+    serialized = json.dumps(result)
+    assert isinstance(serialized, str)
+
+
+def test_next_step_present(skill):
+    """Ready result must include a next_step hint for the calling agent."""
+    result = skill.execute({"issue_url": VALID_URL})
+    assert "next_step" in result
+    assert isinstance(result["next_step"], str)
+    assert len(result["next_step"]) > 0

{skillware-0.2.7 → skillware-0.2.8/skillware.egg-info}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.2.7
+Version: 0.2.8
 Summary: A framework for modular, self-contained AI skills.
-Author-email: ARPA Hellenic Logic Systems <skillware-os@arpacorp.net>
+Author-email: ARPA Hellenic Logical Systems <skillware-os@arpacorp.net>
 License: MIT License
         
         Copyright (c) 2026 ARPA Hellenic Logical Systems

{skillware-0.2.7 → skillware-0.2.8}/skillware.egg-info/SOURCES.txt

@@ -27,6 +27,13 @@ skills/data_engineering/synthetic_generator/card.json
 skills/data_engineering/synthetic_generator/instructions.md
 skills/data_engineering/synthetic_generator/manifest.yaml
 skills/data_engineering/synthetic_generator/skill.py
+skills/dev_tools/__init__.py
+skills/dev_tools/issue_resolver/__init__.py
+skills/dev_tools/issue_resolver/card.json
+skills/dev_tools/issue_resolver/instructions.md
+skills/dev_tools/issue_resolver/manifest.yaml
+skills/dev_tools/issue_resolver/skill.py
+skills/dev_tools/issue_resolver/test_skill.py
 skills/finance/__init__.py
 skills/finance/wallet_screening/__init__.py
 skills/finance/wallet_screening/card.json