skillware 0.2.7__tar.gz → 0.2.9__tar.gz

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

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.2.7
+Version: 0.2.9
 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
@@ -35,15 +35,29 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests
 Requires-Dist: pyyaml
-Requires-Dist: anthropic
-Requires-Dist: google-generativeai
-Requires-Dist: pymupdf
+Requires-Dist: python-dotenv
 Requires-Dist: beautifulsoup4
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
 Requires-Dist: black; extra == "dev"
+Provides-Extra: cli
+Requires-Dist: rich>=13.0; extra == "cli"
+Provides-Extra: gemini
+Requires-Dist: google-generativeai; extra == "gemini"
+Provides-Extra: claude
+Requires-Dist: anthropic; extra == "claude"
+Provides-Extra: openai
+Requires-Dist: openai; extra == "openai"
+Provides-Extra: office
+Requires-Dist: pymupdf; extra == "office"
+Provides-Extra: all
+Requires-Dist: rich>=13.0; extra == "all"
+Requires-Dist: google-generativeai; extra == "all"
+Requires-Dist: anthropic; extra == "all"
+Requires-Dist: openai; extra == "all"
+Requires-Dist: pymupdf; extra == "all"
 Dynamic: license-file
 
 <div align="center">
@@ -106,6 +120,7 @@ Skillware/
 │           ├── instructions.md # Cognitive map for the LLM
 │           └── test_skill.py   # Unit tests & schema validation
 ├── skillware/                  # Core Framework Package
+│   ├── cli.py                  # Command-line interface
 │   └── core/
 │       ├── base_skill.py       # Abstract Base Class for skills
 │       ├── env.py              # Environment Management
@@ -135,7 +150,16 @@ pip install -e .
 
 > **Note**: Individual skills may have their own dependencies. The `SkillLoader` validates `manifest.yaml` and warns of missing packages (e.g., `requests`, `pandas`) upon loading a skill.
 
-### 2. Configuration
+### 2. Verify your installation
+
+```bash
+pip install "skillware[cli]"
+skillware list
+```
+
+This prints a table of all locally available skills and confirms the install and path resolution are working.
+
+### 3. Configuration
 
 Create a `.env` file with your API keys (e.g., Google Gemini API Key):
 
@@ -143,7 +167,7 @@ Create a `.env` file with your API keys (e.g., Google Gemini API Key):
 GOOGLE_API_KEY="your_key"
 ```
 
-### 3. Usage Example (Gemini)
+### 4. Usage Example (Gemini)
 
 ```python
 import google.generativeai as genai
@@ -184,6 +208,7 @@ print(response.text)
 *   **[Usage Guide: Ollama](docs/usage/ollama.md)**: Native integration for local models via Ollama.
 *   **[API Keys for Skills](docs/usage/api_keys.md)**: Environment variables, cloud/CI setup, and security for skills that call external APIs.
 *   **[Skill Library](docs/skills/README.md)**: Available capabilities.
+*   **[CLI Reference](docs/usage/cli.md)**: Discover and inspect locally installed skills from the terminal.
 
 ## Contributing
 

{skillware-0.2.7 → skillware-0.2.9}/README.md

@@ -58,6 +58,7 @@ Skillware/
 │           ├── instructions.md # Cognitive map for the LLM
 │           └── test_skill.py   # Unit tests & schema validation
 ├── skillware/                  # Core Framework Package
+│   ├── cli.py                  # Command-line interface
 │   └── core/
 │       ├── base_skill.py       # Abstract Base Class for skills
 │       ├── env.py              # Environment Management
@@ -87,7 +88,16 @@ pip install -e .
 
 > **Note**: Individual skills may have their own dependencies. The `SkillLoader` validates `manifest.yaml` and warns of missing packages (e.g., `requests`, `pandas`) upon loading a skill.
 
-### 2. Configuration
+### 2. Verify your installation
+
+```bash
+pip install "skillware[cli]"
+skillware list
+```
+
+This prints a table of all locally available skills and confirms the install and path resolution are working.
+
+### 3. Configuration
 
 Create a `.env` file with your API keys (e.g., Google Gemini API Key):
 
@@ -95,7 +105,7 @@ Create a `.env` file with your API keys (e.g., Google Gemini API Key):
 GOOGLE_API_KEY="your_key"
 ```
 
-### 3. Usage Example (Gemini)
+### 4. Usage Example (Gemini)
 
 ```python
 import google.generativeai as genai
@@ -136,6 +146,7 @@ print(response.text)
 *   **[Usage Guide: Ollama](docs/usage/ollama.md)**: Native integration for local models via Ollama.
 *   **[API Keys for Skills](docs/usage/api_keys.md)**: Environment variables, cloud/CI setup, and security for skills that call external APIs.
 *   **[Skill Library](docs/skills/README.md)**: Available capabilities.
+*   **[CLI Reference](docs/usage/cli.md)**: Discover and inspect locally installed skills from the terminal.
 
 ## Contributing
 

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

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillware"
-version = "0.2.7"
+version = "0.2.9"
 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" }
@@ -20,13 +20,14 @@ classifiers = [
 dependencies = [
     "requests",
     "pyyaml",
-    "anthropic",
-    "google-generativeai",
-    "pymupdf",
+    "python-dotenv",
     "beautifulsoup4",
 ]
 requires-python = ">=3.10"
 
+[project.scripts]
+skillware = "skillware.cli:main"
+
 [project.optional-dependencies]
 dev = [
     "pytest",
@@ -34,6 +35,28 @@ dev = [
     "flake8",
     "black",
 ]
+cli = [
+    "rich>=13.0",
+]
+gemini = [
+    "google-generativeai",
+]
+claude = [
+    "anthropic",
+]
+openai = [
+    "openai",
+]
+office = [
+    "pymupdf",
+]
+all = [
+    "rich>=13.0",
+    "google-generativeai",
+    "anthropic",
+    "openai",
+    "pymupdf",
+]
 
 [tool.setuptools]
 include-package-data = true

skillware-0.2.9/skills/dev_tools/__init__.py

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

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

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

skillware-0.2.9/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.9/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.9/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.9/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."
+            ),
+        }