chore: restructured specification into separate files

Author: spazyCZ

.github/workflows/gh-pages.yml

@@ -0,0 +1,26 @@
+name: Deploy MkDocs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install MkDocs and dependencies
+        run: pip install mkdocs-material
+
+      - name: Build and deploy
+        run: mkdocs gh-deploy --force

.gitignore

@@ -0,0 +1,10 @@
+work/
+.vscode
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.db
+*.sqlite3  
+*.log

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0-draft] — 2026-02-22
+
+### Added
+- Skill testing: `tests/` directory with deterministic assert runner (§4 Skills)
+- Hook testing: `tests/` directory with fixtures and assert runner (§8 Hooks)
+- Evals system: top-level `evals/` with agent sandbox execution model (§2 Package Format)
+- Two-tier testing model: `tests/` (assert, CI-safe, $0) vs `evals/` (LLM-judged, agent sandbox)
+- `aam test` and `aam eval` CLI commands
+
+## [0.4.0-draft] — 2026-02-19
+
+### Added
+- Initial specification covering package format, manifest, skills, commands, prompts, agents, rules, hooks, MCP, compatibility matrix, migration guides, packaging & distribution, dependency resolution, signing & verification, governance, validation rules, security considerations, glossary, and appendix.
+- MkDocs-based documentation site with Material theme.
+- GitHub Actions workflow for automated GitHub Pages deployment.

README.md

@@ -1,6 +1,6 @@
 # 📦 UAAPS — Universal Agentic Artifact Package Specification
 
-> **Version:** 0.4.0-draft  |  **Status:** 🌐 Open Standard, seeking collaborators
+> **Version:** 0.5.0-draft  |  **Status:** 🌐 Open Standard, seeking collaborators
 
 ✍️ **Write once. Deploy to any agent platform.**
 
@@ -19,6 +19,7 @@ Managing AI agent artifacts at scale is a structural mess:
 - 💥 **No composability** — loading multiple packages causes silent instruction conflicts with no namespacing.
 - ⚙️ **No lifecycle management** — platforms lack hooks for events like `pre-tool-use` or `permission-request` that deterministic agent validation requires.
 - 🔄 **No update management** — there is no standard mechanism to propagate fixes or new versions of skills across projects; every consumer must update manually and in isolation.
+- 🧪 **No testability** — there is no standard way to verify that a skill or hook works correctly. Scripts lack test harnesses, and LLM-driven behavior has no eval framework — breakage is discovered in production.
 - 🛡️ **Uncontrolled duplication creates security risk** — skills are copy-pasted across repositories with no traceability. Since skills can contain executable scripts, a single compromised or outdated copy can go undetected across dozens of projects, expanding the attack surface with every duplicate.
 
 ### 🤔 Why "Hacking" npm Is Not Enough
@@ -77,6 +78,7 @@ A single `package.agent.json` manifest declares your artifact and makes it consu
 | 🔒 **Deterministic Resolution** | Lock files guarantee reproducible agent behavior in CI |
 | 🧩 **Composability** | Namespaced skills prevent conflicts between packages |
 | 📁 **Filesystem-First** | No databases, no APIs required — just files |
+| 🧪 **Testability** | Two-tier testing: deterministic `tests/` for CI + LLM-judged `evals/` for integration |
 
 ---
 
@@ -95,7 +97,7 @@ To prove the standard works, a reference implementation and management layer are
 
 ## 📖 Full Specification
 
-The complete specification is in [docs/SPECIFICATION.md](docs/SPECIFICATION.md). It covers:
+The specification is published at **[uaaps.github.io/uaaps_docs](https://uaaps.github.io/uaaps_docs/)** and covers:
 
 - 📄 Package manifest schema (`package.agent.json`)
 - 🗂️ Directory structure conventions
@@ -106,6 +108,13 @@ The complete specification is in [docs/SPECIFICATION.md](docs/SPECIFICATION.md).
 - 🧪 Quality / eval definitions
 - 🔌 Vendor extension points (`x-claude`, `x-cursor`, …)
 
+The spec source lives in [`docs/spec/`](docs/spec/) — each chapter is a separate Markdown file. To build and preview locally:
+
+```bash
+pip install mkdocs-material
+mkdocs serve
+```
+
 ---
 
 ## 🤝 Call for Collaboration
@@ -133,7 +142,7 @@ Let's stop building silos and start building a standard. 🌱
 
 ## 🔬 Research & Background
 
-Additional context and prior-art analysis is available in [docs/research_list_of_sources.md](docs/research_list_of_sources.md).
+Additional context and prior-art analysis is available in [work/research_list_of_sources.md](docs/research_list_of_sources.md).
 
 ---
 

VERSION

@@ -0,0 +1 @@
+0.5.0-draft