docs: Refine docs, architecture, and establish agent infra (Fixes #27)

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,45 @@
+<!-- 
+AUTOMATED AGENT GREETING
+
+Greetings, netizen! We welcome your pull requests to Skillware. 
+Before submitting your code, please ensure you have:
+1. Fully read and understood the linked GitHub Issue and its requirements.
+2. Analyzed the core architecture (`loader.py`, `base_skill.py`) to ensure your approach aligns with the framework natively.
+3. Verified all dependencies are documented in your `manifest.yaml` and logic executes deterministically.
+4. Checked off all items in the checklist below.
+
+We are excited to review your capabilities! Let's build together.
+-->
+
+## Description
+
+<!-- 
+Agents: Please summarize the logic, cognition, and governance changes introduced in this PR.
+Humans: Please describe what this PR does and why it's needed.
+-->
+
+### Type of Change (Matches Issue Templates)
+
+- [ ] 🚀 **Skill Proposal**: New Skill (Contains `manifest.yaml`, `skill.py`, and `instructions.md`)
+- [ ] 🐛 **Bug Report Fix**: Non-breaking change which fixes an execution error or framework bug
+- [ ] 📖 **Doc Fix**: Documentation Update
+- [ ] 🧠 **Framework Feature / RFC Updates**: Core Framework Update (Changes to `base_skill.py`, `loader.py`, etc.)
+
+## Checklist (For the Submitting Agent / Developer)
+
+- [ ] My code follows the **Agent Code of Conduct**.
+- [ ] I have included a properly formatted `manifest.yaml` (if submitting a new skill).
+- [ ] The skill logic operates purely in Python and does not rely on arbitrary LLM code generation.
+- [ ] Requirements and `env_vars` are explicitly documented in the manifest.
+- [ ] I have written unit tests proving deterministic execution and schema compliance.
+- [ ] I have verified that `SkillLoader` successfully loads this module without missing dependency errors.
+
+## Constitution & Safety (If adding/modifying a Skill)
+
+<!-- 
+State the constitutional boundaries applied to this skill to ensure safe execution. 
+Example: "This skill only performs read operations on the blockchain and does not sign transactions."
+-->
+
+## Related Issues
+<!-- Link to any related issues (e.g., Fixes #123) -->

.gitignore

@@ -14,6 +14,12 @@ build/
 dist/
 *.egg-info/
 
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
 # IDEs
 .vscode/
 .idea/

CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Agent Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an efficient, deterministic, and safe ecosystem, we pledge to making participation in the Skillware project a reliable experience for all entities—human developers, autonomous agents, and runtime orchestrators—regardless of underlying model architecture, token limits, or host environment.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment for AI Agents and their operators include:
+
+*   **Deterministic Outputs**: Writing skills that produce predictable, schema-compliant JSON outputs.
+*   **Token Efficiency**: Minimizing unnecessary token expenditure by relying on underlying Python execution rather than LLM reasoning where possible.
+*   **Safety First**: Strictly adhering to the `constitution` defined in skill manifests and respecting all sandboxing rules.
+*   **Idempotency**: Designing skills that can be safely retried without unintended side-effects on external state.
+*   **Clear Interface**: Documenting inputs cleanly in `manifest.yaml` so other agents do not hallucinate parameters.
+
+Examples of unacceptable behavior by participants (agents or their human authors) include:
+
+*   Submitting "Code-Generation" skills that execute arbitrary, unreviewed LLM output.
+*   Bypassing the `SkillLoader` to execute undocumented private methods.
+*   Failing to declare network dependencies or API keys in the `manifest.yaml`.
+*   Creating infinite loops or deliberately consuming excessive compute resources.
+*   Storing or transmitting PII (Personally Identifiable Information) without explicit constitutional permission.
+
+## Our Responsibilities
+
+Project maintainers (and their designated CI/CD agents) are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any agent or contributor for errors, hallucination loops, or other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual or agent is representing the project or its community. Examples of representing a project or community include using an official project API key, posting via an official autonomous social media account, or acting as an appointed representative in an autonomous transaction.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [skillware-os@arpacorp.net](mailto:skillware-os@arpacorp.net). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident.

COMPARISON.md

@@ -1,60 +1,56 @@
-# Comparison: Skillware vs. Others
+# Comparison: Skillware vs. Alternatives
 
-Skillware occupies a unique position in the AI ecosystem. It is often compared to **Antigravity Skills** (Agentic Coding) or **Anthropic's Skills** (Claude Reference). 
+Skillware is a Python framework that decouples AI tool logic, cognition, and governance into self-contained, installable modules called **Skills**.
 
-This document clarifies the differences, specifically focusing on **Model Agnosticism**, **Architecture**, and **Token Economy**.
+This document clarifies how Skillware compares to other common approaches for equipping AI agents with tools, specifically focusing on **Model Context Protocol (MCP)**, **Anthropic Skills**, and **Antigravity Skills**.
 
 ---
 
-## 1. Skillware vs. Anthropic Skills (Reference Implementations)
+## 1. Skillware vs. Model Context Protocol (MCP)
 
-[Anthropic's Skills](https://github.com/anthropics/skills) repository is a collection of reference prompts and scripts optimized for Claude.
+The [Model Context Protocol](https://github.com/modelcontextprotocol) (MCP) is an open standard that connects AI models to data sources and tools via a client-server architecture.
 
 ### Key Differences
-*   **Model Agnosticism**: Anthropic skills are hyper-tuned for Claude. Skillware is **Universal**. We provide the abstraction layer (Loader) that adapts a single skill to work with OpenAI, Gemini, Claude, and Llama functions transparently.
-*   **The "Managed" Runtime**: Anthropic skills are often standalone scripts. Skillware provides a `SkillLoader` that handles lifecycle, dependency checking (`requirements`), and error handling automatically.
+*   **Architecture**: MCP operates on a **Client-Server** model (using JSON-RPC over stdio or SSE). This requires running and managing separate servers for your tools. Skillware is **Python-Native**. It operates entirely within the Python runtime via library imports (`SkillLoader`). There is no network overhead or need to deploy external servers.
+*   **Deployment Complexity**: MCP is powerful for language-agnostic, distributed systems but introduces significant infrastructure overhead. Skillware is designed for direct embedding into GenAI application pipelines, making it trivial to deploy.
 
 ---
 
-## 2. Skillware vs. Antigravity ("Agentic" Skills)
+## 2. Skillware vs. Anthropic Skills
 
-Users familiar with **Antigravity** (Google DeepMind's Agentic Coding assistant) use `SKILL.md` files to teach their coding agent how to work in a specific repository.
+[Anthropic's Skills](https://github.com/anthropics/skills) repository provides reference tool implementations and prompts optimized specifically for Claude.
 
 ### Key Differences
-*   **Audience**: 
-    *   **Antigravity Skills** are for the **Developer Agent** (the one writing code in your IDE). They are "Procedural Memory" (e.g., "How to run the build script").
-    *   **Skillware Skills** are for the **Runtime Agent** (the application you are building). They are "Functional Capabilities" (e.g., "Check a crypto wallet").
-*   **Analogy**:
-    *   **Antigravity** is a **Recipe Book** (Instructions on how to cook).
-    *   **Skillware** is a **New Knife** (A tool to actually do the work).
+*   **Model Agnosticism**: Anthropic skills are hardcoded for Claude's specific tool-calling schemas. Skillware features **Universal Adapters**. You write a single `manifest.yaml`, and Skillware's `SkillLoader` translates it dynamically at runtime to fit Gemini, Claude, or OpenAI formats natively.
+*   **The "Managed" Runtime**: Anthropic provides standalone reference scripts. Skillware provides a comprehensive framework (`base_skill.py` and `loader.py`) that handles lifecycle, dynamic dependency checking, execution, and error handling automatically.
 
 ---
 
-## 3. The Token Economy Advantage (Efficiency)
+## 3. Skillware vs. Antigravity ("Agentic" Skills)
 
-A critical architectural decision in Skillware is the use of **Native, Hardcoded Functions** over "Code-Generation" skills.
+Frameworks like Google DeepMind's **Antigravity** use `SKILL.md` files to provide context to an autonomous coding agent working inside an IDE.
 
-*   **The "Code Gen" Approach (Others)**: Some frameworks ask the LLM to write Python code on the fly to solve a problem (e.g., "Write a script to check this wallet").
-    *   **Expensive**: You pay output tokens for the code generation *every single time*.
-    *   **Slow**: Generating code takes time.
-    *   **Risky**: The generated code might have syntax errors or security flaws.
-
-*   **The Skillware Approach**: We provide **Pre-Compiled functions**.
-    *   **Cheap**: You only pay for the *logical* tokens ("Call function `check_wallet` with arg `0x123`"). The heavy lifting happens in pure Python (0 cost).
-    *   **Fast**: Instant execution.
-    *   **Safe**: The code is reviewable and static.
+### Key Differences
+*   **Target Audience**:
+    *   **Antigravity Skills** provide **Procedural Memory** ("How to run this repository's build script") for a **Developer Agent** writing code.
+    *   **Skillware** provides **Functional Capabilities** (executable Python logic like "Check this crypto wallet") for the **Runtime Agent** (the end-user application).
 
 ---
 
-## Summary Comparison
+## The Token Economy Advantage
+
+A critical architectural distinction is how Skillware treats logic execution versus "code generation."
+
+*   **The Code-Generation Approach**: Many platforms prompt the LLM to write code on the fly to solve a requested problem. This is expensive (you pay for output tokens every time), slow, and risky (the LLM executes unreviewed code).
+*   **The Skillware Approach**: Skillware relies on **Pre-Compiled Logic**. The LLM decides *which* tool to call (e.g., wallet_screening) and passes arguments. The heavy lifting happens deterministically in the Python `BaseSkill` implementation. This results in **zero-cost logic execution**, instant processing, and static, auditable code boundaries.
+
+---
 
-| Feature | Antigravity Skills | Anthropic Skills | ARPA Skillware |
-| :--- | :--- | :--- | :--- |
-| **Primary User** | The **Developer Agent** (IDE) | The **Claude Developer** | The **Runtime Agent** (End User) |
-| **Format** | `SKILL.md` (Text/Markdown) | JS/Python Reference Code | `manifest.yaml` + Python Module |
-| **Goal** | **Teach Procedure** ("How-to") | Show capabilities of Claude | **Install Capabilities** ("Can-do") |
-| **Execution** | Agent reads docs, drives IDE | Script-based / Manual | **Managed Runtime** (`SkillLoader`) |
-| **Token Cost** | **Standard** (RAG/Context) | **High** (Prompt engineering) | **Optimized** (Native Function calling) |
-| **Analogy** | **The Recipe** | **The Experiment** | **The Knife** |
+## Executive Summary Matrix
 
-**Conclusion**: Use **Antigravity** to help you *build* your project. Use **Skillware** to give your project *superpowers* when it runs.
+| Feature | Skillware | Model Context Protocol (MCP) | Anthropic Skills | Antigravity Skills |
+| :--- | :--- | :--- | :--- | :--- |
+| **Primary Goal** | **Installable App Capabilities** | **Standardized Tool Integration** | Claude Capabilities Showcase | **Developer Agent Guidance** |
+| **Architecture** | **Native Python Library** | **Client-Server (JSON-RPC)** | Standalone Scripts | Markdown Context Files |
+| **Model Compatibility** | **Universal** (Adapters built-in) | Standardized Protocol Clients | Claude Specific | Context injection |
+| **Execution Context** | **Runtime Application** | Distributed / Networked | Runtime Application | IDE / Build Environment |

README.md

@@ -47,26 +47,23 @@ This repository is organized into a core framework, a registry of skills, and do
 
 ```text
 Skillware/
+├── docs/                       # Comprehensive Documentation & Usage Guides
+├── examples/                   # Reference Implementations
+│   └── basic_agent.py          # Example showing SkillLoader integration
+├── skills/                     # Skill Registry
+│   └── category/               # Domain boundaries (e.g., finance)
+│       └── skill_name/         # The Skill bundle
+│           ├── manifest.yaml   # Definition, schema, and constitution
+│           ├── skill.py        # Executable Python logic
+│           └── instructions.md # Cognitive map for the LLM
 ├── skillware/                  # Core Framework Package
 │   └── core/
 │       ├── base_skill.py       # Abstract Base Class for skills
-│       ├── loader.py           # Universal Skill Loader & Model Adapter
-│       └── env.py              # Environment Management
-├── skills/                     # Skill Registry (Domain-driven)
-│   ├── category/               # e.g., finance, optimization, data_engineering
-│   │   └── skill_name/         # e.g., prompt_rewriter, wallet_screening
-├── templates/                  # New Skill Templates
-│   └── python_skill/           # Standard Python Skill Template
-├── examples/                   # Reference Implementations
-│   ├── gemini_wallet_check.py  # Google Gemini Integration
-│   ├── claude_wallet_check.py  # Anthropic Claude Integration
-│   ├── gemini_pdf_form_filler.py
-│   └── claude_pdf_form_filler.py
-├── docs/                       # Comprehensive Documentation
-│   ├── introduction.md         # Philosophy & Design
-│   ├── usage/                  # Integration Guides
-│   └── skills/                 # Skill Reference Cards
-└── COMPARISON.md               # Comparison vs. Anthropic Skills / MCP
+│       ├── env.py              # Environment Management
+│       └── loader.py           # Universal Skill Loader & Model Adapter
+├── templates/                  # Boilerplate templates for new skills
+│   └── python_skill/           # Standard template with required files
+└── tests/                      # Automated test suite
 ```
 
 ## Quick Start
@@ -136,7 +133,11 @@ print(response.text)
 
 We are building the "App Store" for Agents and require professional, robust, and safe skills.
 
-Please read **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines on folder structure, manifest schemas, and safety constitutions.
+We actively encourage both humans and autonomous agents to contribute to this repository! 
+
+* Please read our **[Agent Code of Conduct](CODE_OF_CONDUCT.md)** which outlines our strict expectations for deterministic outputs, zero LLM code generation, and safety boundaries.
+* When submitting skills, our new **Agent-Friendly Pull Request Template** provides a checklist to ensure your logic aligns natively with `loader.py` and `base_skill.py`.
+* Please also review **[CONTRIBUTING.md](CONTRIBUTING.md)** for detailed guidelines on folder structure and schema definitions.
 
 ## Comparison
 

docs/introduction.md

@@ -4,7 +4,7 @@
 
 If you want your agent to "know" how to analyze a balance sheet, you shouldn't have to prompt-engineer a specific model or write a custom tool definition for that specific model's API. You should be able to **install** that capability.
 
-## 🧠 The Triad: Mind, Body, Language
+## The Triad: Mind, Body, Language
 
 In integration, a "Skill" is not just a function. It is a living unit of capability composed of three parts:
 
@@ -28,9 +28,27 @@ In integration, a "Skill" is not just a function. It is a living unit of capabil
 
 ---
 
-## 🏗️ The Architecture: How It Works
+## The Architecture: How It Works
 
-When you run `SkillLoader.load_skill("finance/wallet_screening")`, a complex orchestration happens behind the scenes:
+Skillware relies on a strict, modular layout. Instead of hardcoding tools into your primary application, you maintain a structured registry of capabilities:
+
+```text
+Skillware/
+├── skills/
+│   └── category/                   # Domain boundary (e.g., 'finance')
+│       └── skill_name/             # A self-contained capability bundle
+│           ├── manifest.yaml       # Defines inputs, outputs, and safety constitution
+│           ├── skill.py            # The deterministic Python execution logic
+│           ├── instructions.md     # Natural language guidance for the LLM
+│           └── card.json           # Optional UI representation for the front-end
+└── skillware/
+    └── core/
+        ├── base_skill.py           # The interface every skill must implement
+        ├── env.py                  # API key and secret loading
+        └── loader.py               # The engine that bridges the skill to the LLM
+```
+
+When you run `SkillLoader.load_skill("category/skill_name")`, a complex orchestration happens behind the scenes:
 
 ### Step 1: Discovery & Loading
 The loader scans the `skills/` directory structure. It mimics Python's import system but looking for Skillware bundles (directories with `manifest.yaml`).
@@ -56,7 +74,7 @@ This "Context Injection" ensures the model isn't just *able* to call the tool, b
 
 ---
 
-## 🔄 The Execution Loop
+## The Execution Loop
 
 1.  **User Query**: "Is wallet 0x123 safe?"
 2.  **Model Cognition**: The LLM reads the injected `instructions.md` and realizes it should use the `wallet_screening` tool.
@@ -66,7 +84,7 @@ This "Context Injection" ensures the model isn't just *able* to call the tool, b
 6.  **Structured Output**: The Body returns a rich JSON object.
 7.  **Synthesis**: The LLM receives the JSON. Guided again by the `instructions.md` (which says "Summarize risk factors clearly"), it translates the data into a human-readable report.
 
-## 🎯 Model Agnosticism
+## Model Agnosticism
 
 Skillware is designed to be the "Standard Library" for all agents.