Rosspeili/fix 319 doc anatomy consolidation

.github/PULL_REQUEST_TEMPLATE.md

@@ -37,12 +37,12 @@ Skip unless this PR adds or changes files under `skills/`.
 - [ ] `manifest.yaml`: `name` (full ID), `version`, `description`, `parameters`, `constitution`, real `issuer`
 - [ ] Optional: `short_description`, `issuer.github`, `issuer.org`, `requirements`, `env_vars`
 
-### Logic, cognition, tests
+### Effect, Directive, Assurance
 
-- [ ] Deterministic `skill.py` (no ad-hoc LLM-generated execution paths)
-- [ ] `instructions.md` explains when and how to use the skill
-- [ ] `card.json` issuer matches manifest when present
-- [ ] `test_skill.py` covers execution and schema expectations
+- [ ] Deterministic `skill.py` (Effect; no ad-hoc LLM-generated execution paths)
+- [ ] `instructions.md` (Directive) explains when and how to use the skill
+- [ ] `card.json` (Presentation) issuer matches manifest when present
+- [ ] `test_skill.py` (Assurance) covers execution and schema expectations
 - [ ] `SkillLoader.load_skill("<category>/<skill_name>")` succeeds (or deps documented)
 
 ### Documentation and catalog

CHANGELOG.md

@@ -16,6 +16,7 @@ Contributors add user-facing entries under `[Unreleased]` in the same PR. Mainta
 
 ### Changed
 
+- **Docs:** Adopt **Skill anatomy** (Contract, Effect, Directive, Assurance, Corpus, Reference, Presentation, Interface) across introduction, README Mission, CONTRIBUTING, provider guides, catalog pages, and contributor templates (#319).
 - **Docs:** Document `issuer.org` design-ownership policy; align ARPA-driven registry skills (`prompt_injection_firewall`, `bg_remover`, `novelty_extractor`) and catalog Issuer lines (#295).
 
 ### Fixed

CODE_OF_CONDUCT.md

@@ -12,7 +12,7 @@ Examples of behavior that contributes to creating a positive environment for AI
 *   **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 following the project's [security and trust guidelines](docs/security/skill-trust-model.md).
 *   **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.
+*   **Clear tool contract**: Document inputs cleanly in `manifest.yaml` (**Contract**; see [Skill anatomy](docs/introduction.md#skill-anatomy)).
 
 Examples of unacceptable behavior by participants (agents or their human authors) include:
 

COMPARISON.md

@@ -1,6 +1,6 @@
 # Comparison: Skillware vs. Alternatives
 
-Skillware is a Python framework that decouples AI tool logic, cognition, and governance into self-contained, installable modules called **Skills**. For the project story and roadmap, see [docs/vision.md](docs/vision.md).
+Skillware is a Python framework that decouples **Effect**, **Directive**, and **Contract** into self-contained, installable modules called **Skills**. For the project story and roadmap, see [docs/vision.md](docs/vision.md).
 
 This document clarifies how Skillware compares to other common approaches for equipping AI agents with tools, including **Model Context Protocol (MCP)**, **Agent Skills (SKILL.md)**, **LangChain Tools**, **AutoGen**, and others.
 

CONTRIBUTING.md

@@ -219,7 +219,24 @@ Skills you submit are reviewed for origin and quality, not sandboxed at runtime
 
 Every registry skill lives in `skills/<category>/<skill_name>/` and **must** include the files below. This is the detailed standard for the **skill** contribution type.
 
-### 1. `manifest.yaml` (metadata and governance)
+### Skill anatomy (vocabulary)
+
+Checklists below use **file names**; each file implements a **role**. The [README Mission](README.md#mission) summarizes the core roles; full reference: [docs/introduction.md — Skill anatomy](docs/introduction.md#skill-anatomy).
+
+| Role | v0 file(s) | Required |
+| :--- | :--- | :---: |
+| **Contract** | `manifest.yaml` | Yes |
+| **Effect** | `skill.py` (+ effect modules in the same folder) | Yes |
+| **Directive** | `instructions.md` | Yes |
+| **Assurance** | `test_skill.py` | Yes (registry) |
+| **Presentation** | `card.json` | Optional |
+| **Corpus** | `kb/`, `data/`, bundled knowledge files | Optional |
+| **Reference** | `schemas/`, maps, in-bundle spec fixtures | Optional |
+| **Interface** | `skillware/core/loader.py` adapters | Framework (not in bundle) |
+
+**Effect modules** (for example `workflow.py`, `budget.py`) are imported by `skill.py`—implementation detail, not a separate required file. **Corpus tooling** (for example `maintenance/`) refreshes Corpus offline and is not loaded by `execute()`.
+
+### 1. `manifest.yaml` (Contract)
 
 Defines the tool interface, safety constitution, dependencies, and issuer attribution.
 
@@ -263,7 +280,7 @@ requirements:
   - requests
 ```
 
-### 2. `skill.py` (logic)
+### 2. `skill.py` (Effect)
 
 - Define **exactly one** concrete subclass of `BaseSkill` per skill file. `SkillLoader.load_skill()` discovers it automatically as `bundle["class"]` (see `SkillLoader.get_skill_class()`).
 - Implement deterministic Python logic; inherit from `BaseSkill`.
@@ -273,7 +290,7 @@ requirements:
 - Do **not** embed open-ended LLM code generation as the skill implementation.
 - When you change the JSON shape returned by `execute()`, update `card.json` output fields (if present) and the matching fixture under `tests/fixtures/card_ui_schema/` in the same PR.
 
-### 3. `instructions.md` (cognition)
+### 3. `instructions.md` (Directive)
 
 The primary guide for the host LLM. Skill instructions should be a concise, append-only block focusing on this skill's context rather than assigning an overarching persona (host agents and LLMs already have their own system prompts).
 
@@ -283,15 +300,15 @@ The primary guide for the host LLM. Skill instructions should be a concise, appe
 - **Avoid persona starters**: Avoid opening with "You are an agent equipped with...", "You are an expert...", or narrative personality instructions that can conflict when multiple skills are appended to context.
 - Keep prompts and persona here, not in `skill.py`.
 
-### 4. `card.json` (presentation)
+### 4. `card.json` (Presentation)
 
 - Optional but recommended for user-facing agents and catalog UIs.
 - Describes UI presentation (`name`, `description`, `icon`, `ui_schema`, and similar).
 - When present, include an `issuer` object that matches `manifest.yaml` (`name` and `email` at minimum; copy `github` and `org` when used).
 - For output cards (`ui_schema.type` = `card`), each `ui_schema.fields[].key` must be a dot path into the JSON returned by `execute()` (for example `metadata.wallet_address`, `preview.you_pay`). Update `card.json` in the same PR when you change the output shape.
 - Add or refresh a representative output fixture at `tests/fixtures/card_ui_schema/<category>__<skill_name>.json` (one object or a `{"samples": [...]}` list when multiple execute paths surface different fields). CI validates keys via `tests/test_card_ui_schema.py` (#199).
 
-### 5. `test_skill.py` (bundle test)
+### 5. `test_skill.py` (Assurance)
 
 - **Required** for every new registry skill (template: `templates/python_skill/test_skill.py`; enforced by `tests/test_skill_issuer.py`).
 - Unit tests for schema compliance and deterministic execution paths (offline; mock externals).
@@ -300,6 +317,15 @@ The primary guide for the host LLM. Skill instructions should be a concise, appe
 - Optional extra depth for maintainers: `tests/skills/<category>/test_<skill_name>.py` — see [TESTING.md](docs/TESTING.md).
 - Mock network calls and first-run model downloads in bundle tests.
 
+### Optional bundle assets
+
+Not required for every skill. When present, document them on the catalog page under **Bundle layout** (see [skill usage template](docs/usage/skill_usage_template.md)).
+
+- **Corpus** — `kb/`, `data/`, or other versioned knowledge files the Effect reads at runtime.
+- **Reference** — `schemas/`, terminology maps, or in-bundle fixtures that define the public contract or demos.
+- **Effect modules** — additional `.py` files imported only by `skill.py` (not separate registry roles).
+- **Corpus tooling** — offline maintenance scripts (not loaded by `execute()`); keep out of the Effect import path unless intentional.
+
 ### Packaging (PyPI and `pip install`)
 
 Registry skills are shipped inside the `skillware` wheel. Per-skill layout uses `manifest.yaml` and packaging hooks below — not per-skill edits to CI.
@@ -417,7 +443,7 @@ When a new top-level category lands under `skills/`, update this table and the c
 | [Agent Contribution Workflow](docs/contributing/ai_native_workflow.md) | Workflow written for contributing agents; operators supervise |
 | [TESTING.md](docs/TESTING.md) | Black, Flake8, Pytest, local CI parity |
 | [Agent Code of Conduct](CODE_OF_CONDUCT.md) | Behavioral expectations for humans and agents |
-| [docs/introduction.md](docs/introduction.md) | Architecture: Mind, Body, Conscience |
+| [docs/introduction.md](docs/introduction.md) | Skill anatomy: Contract / Effect / Directive (+ Assurance, Corpus, Interface) |
 | [docs/vision.md](docs/vision.md) | Project story, roadmap, and agent discoverability |
 | [docs/skills/README.md](docs/skills/README.md) | Published skill catalog |
 | [templates/python_skill/](templates/python_skill/) | Boilerplate for new skills |

README.md

@@ -41,10 +41,13 @@ The AI ecosystem is fragmented. Developers often re-invent tool definitions, sys
 
 A **Skill** in this framework provides everything an Agent needs to master a domain:
 
-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.
+1. **Contract**: Constitution, safety boundaries, and typed I/O baked into the bundle.
+2. **Effect**: Executable Python so agents run real work, not guess it.
+3. **Directive**: System instructions and cognitive maps so any host uses the capability as intended.
+4. **Assurance**: Offline tests that Effect honors Contract before a skill joins the registry.
+5. **Interface**: Standardized tool schemas for any LLM or agent runtime.
+
+Optional **Corpus**, **Reference**, and **Presentation** assets extend bundles when needed. Full reference: [Introduction — Skill anatomy](docs/introduction.md#skill-anatomy).
 
 ### Skill library
 
@@ -55,12 +58,10 @@ Browse capabilities by category in the [Skill library](docs/skills/README.md) or
 ```mermaid
 flowchart LR
     Registry[Registry] -->|Load| Loader[Loader]
-    Loader -->|Adapt| Host[Host]
-    Host -->|Prompt + Tools| LogicalSystems([Logical Systems])
-    LogicalSystems -->|Tool Call| Host
+    Loader -->|Adapt| Host[Any Host]
 ```
 
-Install the registry once. Skillware loads a bundle and adapts it to your model's tool format — you run the loop. For details on how the loader turns the manifest into a tool, see the [Introduction](docs/introduction.md).
+Install the registry once. Skillware loads a bundle, adapts it to your host's tool format, and your app runs the agent loop (Gemini, Claude, Ollama, custom scripts, …). For details on how the loader turns the manifest into a tool, see the [Introduction](docs/introduction.md).
 
 ## Architecture
 
@@ -75,11 +76,11 @@ Skillware/
 ├── 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
-│           ├── card.json       # Optional UI presentation metadata
-│           └── test_skill.py   # Bundle test (required for new skills; see docs/TESTING.md)
+│           ├── manifest.yaml   # Contract: schema, constitution, issuer
+│           ├── skill.py        # Effect: deterministic execution
+│           ├── instructions.md # Directive: host guidance
+│           ├── card.json       # Presentation (optional)
+│           └── test_skill.py   # Assurance (required for registry skills)
 ├── skillware/                  # Core Framework Package
 │   ├── cli.py                  # Command-line interface
 │   └── core/
@@ -186,7 +187,7 @@ skill = skill_bundle["class"](
 # 2. Client & Tool Setup
 client = genai.Client()
 tool = SkillLoader.to_gemini_tool(skill_bundle)       # The "Adapter"
-system_instruction = skill_bundle['instructions']     # The "Mind"
+system_instruction = skill_bundle['instructions']     # Directive
 
 # 3. Agent Loop
 response = client.models.generate_content(

docs/TESTING.md

@@ -51,8 +51,9 @@ pip install -r requirements.txt
 | **Maintainer skill test** | `tests/skills/<category>/test_<name>.py` | No (clone only) | Yes when present |
 | **Usage example** | `examples/*.py` | No | Smoke only for local scripts; no for live loops |
 
-### Skill bundle test
+### Skill bundle test (Assurance role)
 
+- Implements the bundle **Assurance** role (`test_skill.py`); see [Skill anatomy](../introduction.md#skill-anatomy).
 - Lives **inside the skill bundle**; ships with `pip install skillware`.
 - **Required** for every new registry skill (see `templates/python_skill/test_skill.py`).
 - Offline and mockable: manifest consistency, validation, deterministic `execute()` paths — no live network.
@@ -91,7 +92,7 @@ pip install -r requirements.txt
 
 | You are testing… | Put it here | Example in this repo |
 | :--- | :--- | :--- |
-| Manifest + execute contract for one skill | Bundle test | `skills/compliance/tos_evaluator/test_skill.py` |
+| Manifest + execute contract for one skill | Bundle test (Assurance) | `skills/compliance/tos_evaluator/test_skill.py` |
 | Loader path + mocked externals (optional depth) | Maintainer test | `tests/skills/compliance/test_tos_evaluator.py` |
 | Loader, CLI, registry issuer rules, param validation, manifest requirement pins, config and path discovery | Framework test | `tests/test_loader.py`, `tests/test_cli.py`, `tests/test_config.py`, `tests/test_discovery.py`, `tests/test_requirements_check.py`, `tests/test_skill_issuer.py`, `tests/test_validate_params.py`, `tests/test_registry_docs.py`, `tests/test_card_ui_schema.py`, `tests/test_registry_identity.py` |
 | End-to-end provider demo script | Usage example | `examples/gemini_tos_evaluator.py` |