satchel-agent 0.1.0__tar.gz

satchel_agent-0.1.0/.agents/plugins/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "satchel-marketplace",
+  "interface": {
+    "displayName": "Satchel"
+  },
+  "plugins": [
+    {
+      "name": "satchel",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/parkerhancock/satchel.git",
+        "ref": "main"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

satchel_agent-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://docs.claude.com/schemas/claude-plugin-marketplace-v1.json",
+  "name": "satchel-marketplace",
+  "description": "Build agent plugin manifests from one product-agnostic source package.",
+  "plugins": [
+    {
+      "name": "satchel",
+      "source": {
+        "source": "github",
+        "repo": "parkerhancock/satchel",
+        "ref": "main"
+      },
+      "description": "Build agent plugin manifests from one product-agnostic source package.",
+      "version": "0.1.0",
+      "displayName": "Satchel",
+      "author": {
+        "name": "Parker Hancock",
+        "url": "https://github.com/parkerhancock"
+      },
+      "homepage": "https://github.com/parkerhancock/satchel",
+      "repository": "https://github.com/parkerhancock/satchel",
+      "license": "MIT",
+      "keywords": [
+        "agents",
+        "plugins",
+        "codex",
+        "claude",
+        "copilot",
+        "antigravity",
+        "skills",
+        "mcp"
+      ],
+      "category": "Productivity",
+      "skills": [
+        "./skills/satchel"
+      ]
+    }
+  ],
+  "owner": {
+    "name": "Parker Hancock",
+    "url": "https://github.com/parkerhancock"
+  }
+}

satchel_agent-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "satchel",
+  "displayName": "Satchel",
+  "version": "0.1.0",
+  "description": "Build agent plugin manifests from one product-agnostic source package.",
+  "author": {
+    "name": "Parker Hancock",
+    "url": "https://github.com/parkerhancock"
+  },
+  "homepage": "https://github.com/parkerhancock/satchel",
+  "repository": "https://github.com/parkerhancock/satchel",
+  "license": "MIT",
+  "keywords": [
+    "agents",
+    "plugins",
+    "codex",
+    "claude",
+    "copilot",
+    "antigravity",
+    "skills",
+    "mcp"
+  ],
+  "skills": "./skills/"
+}

satchel_agent-0.1.0/.codex-plugin/plugin.json

@@ -0,0 +1,44 @@
+{
+  "name": "satchel",
+  "version": "0.1.0",
+  "description": "Build agent plugin manifests from one product-agnostic source package.",
+  "author": {
+    "name": "Parker Hancock",
+    "url": "https://github.com/parkerhancock"
+  },
+  "homepage": "https://github.com/parkerhancock/satchel",
+  "repository": "https://github.com/parkerhancock/satchel",
+  "license": "MIT",
+  "keywords": [
+    "agents",
+    "plugins",
+    "codex",
+    "claude",
+    "copilot",
+    "antigravity",
+    "skills",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Satchel",
+    "shortDescription": "Build agent plugins from one source package.",
+    "developerName": "Parker Hancock",
+    "category": "Productivity",
+    "longDescription": "Product-agnostic authoring tools for agent extensions. Satchel keeps satchel.yaml as the source of truth, then generates host-specific plugin files and checks generated-file drift.",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/parkerhancock/satchel",
+    "defaultPrompt": [
+      "Use Satchel to add or validate a product-agnostic agent plugin package."
+    ],
+    "brandColor": "#e5a82f",
+    "composerIcon": "./assets/logo.svg",
+    "logo": "./assets/logo.svg",
+    "screenshots": [
+      "./assets/cover.svg"
+    ]
+  }
+}

satchel_agent-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,36 @@
+name: Bug Report
+description: Report a Satchel bug.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What went wrong?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Include a minimal satchel.yaml when possible.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Satchel Version
+

satchel_agent-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: true
+

satchel_agent-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature Request
+description: Suggest a target, component, or workflow improvement.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What user workflow should Satchel make simpler?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed Design
+    validations:
+      required: true
+  - type: dropdown
+    id: target
+    attributes:
+      label: Target
+      options:
+        - Cross-target
+        - Codex
+        - Claude
+        - GitHub Copilot
+        - Antigravity
+        - Other
+

satchel_agent-0.1.0/.github/plugin/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "name": "satchel-marketplace",
+  "metadata": {
+    "description": "Build agent plugin manifests from one product-agnostic source package.",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "satchel",
+      "description": "Build agent plugin manifests from one product-agnostic source package.",
+      "version": "0.1.0",
+      "source": {
+        "type": "github",
+        "repo": "parkerhancock/satchel",
+        "ref": "main"
+      },
+      "category": "Productivity"
+    }
+  ],
+  "owner": {
+    "name": "Parker Hancock",
+    "url": "https://github.com/parkerhancock"
+  }
+}

satchel_agent-0.1.0/.github/plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "satchel",
+  "version": "0.1.0",
+  "description": "Build agent plugin manifests from one product-agnostic source package.",
+  "author": {
+    "name": "Parker Hancock",
+    "url": "https://github.com/parkerhancock"
+  },
+  "homepage": "https://github.com/parkerhancock/satchel",
+  "repository": "https://github.com/parkerhancock/satchel",
+  "license": "MIT",
+  "keywords": [
+    "agents",
+    "plugins",
+    "codex",
+    "claude",
+    "copilot",
+    "antigravity",
+    "skills",
+    "mcp"
+  ],
+  "skills": "./skills/"
+}

satchel_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run pytest
+      - run: uv run satchel check .
+      - run: uv run satchel smoke .
+

satchel_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run pytest
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+

satchel_agent-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/

satchel_agent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to Satchel
+
+Satchel is a small Python project with generated plugin outputs. Keep changes
+deterministic, source-first, and easy to validate.
+
+## Setup
+
+```bash
+uv sync
+uv run satchel report examples/basic
+```
+
+## Development Flow
+
+Edit `satchel.yaml`, source code, fixtures, or docs first. Generated host files
+should be updated with `satchel generate`, not hand-edited.
+
+Run the local checks before opening a pull request:
+
+```bash
+uv run ruff check .
+uv run pytest
+uv run satchel check .
+uv run satchel smoke .
+```
+
+Use host validators when the host CLIs are installed:
+
+```bash
+uv run satchel check . --host
+uv run satchel smoke . --host
+```
+
+## Fixtures
+
+The `fixtures/` directory is the conformance suite. Add or update a fixture when
+you add a target, component, or portability rule.
+
+## Generated Outputs
+
+The repository root is itself a Satchel package. If you change `satchel.yaml`,
+`skills/`, or target adapters, regenerate the root outputs:
+
+```bash
+uv run satchel generate .
+```
+
+Do the same for examples that commit generated host output.
+

satchel_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parker Hancock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

satchel_agent-0.1.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: satchel-agent
+Version: 0.1.0
+Summary: Product-agnostic build tooling for agent plugin packages.
+Project-URL: Homepage, https://github.com/parkerhancock/satchel
+Project-URL: Repository, https://github.com/parkerhancock/satchel
+Project-URL: Issues, https://github.com/parkerhancock/satchel/issues
+Project-URL: Documentation, https://github.com/parkerhancock/satchel#readme
+Author-email: Parker Hancock <parker@hancock.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,antigravity,claude,codex,copilot,mcp,plugins,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo.svg" alt="Satchel logo" width="112" />
+</p>
+
+<p align="center">
+  <img src="assets/cover.svg" alt="Satchel builds multi-target agent plugin outputs from one satchel.yaml source package" width="760" />
+</p>
+
+<h1 align="center">Satchel</h1>
+
+<p align="center">
+  <strong>Satchel lets agent plugin authors build multi-target extensions from one source package.</strong>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> |
+  <a href="#features">Features</a> |
+  <a href="#usage">Usage</a> |
+  <a href="#release-readiness">Release Readiness</a>
+</p>
+
+> Status: public alpha candidate. Satchel can generate and check Codex,
+> Claude, and GitHub Copilot plugin manifests and marketplace files today.
+> Antigravity output is available as an experimental target while its host
+> install flow stabilizes.
+
+## Why Satchel
+
+Modern agent plugins share useful building blocks: skills, `SKILL.md`
+metadata, supporting files, MCP configuration, hooks, and subagent definitions.
+Their manifests and marketplace catalogs are different enough that multi-target
+plugin repos can drift.
+
+Satchel makes `satchel.yaml` the source of truth. Authors edit one portable
+package, then generate host-specific files and fail CI when generated outputs
+are stale.
+
+## Quick Start
+
+```bash
+git clone https://github.com/parkerhancock/satchel.git
+cd satchel
+uv run satchel init my-plugin
+uv run satchel generate my-plugin
+uv run satchel check my-plugin
+uv run satchel smoke my-plugin
+```
+
+The generated files live at:
+
+```text
+my-plugin/.codex-plugin/plugin.json
+my-plugin/.claude-plugin/plugin.json
+my-plugin/.github/plugin/plugin.json
+my-plugin/.github/plugin/marketplace.json
+```
+
+## Plugin Install
+
+Satchel is packaged with Satchel. The repository root contains `satchel.yaml`,
+the generated host manifests, generated marketplace files, and a shared
+`skills/satchel/SKILL.md`.
+
+Claude Code:
+
+```bash
+claude plugin marketplace add parkerhancock/satchel
+claude plugin install satchel@satchel-marketplace
+```
+
+Codex:
+
+```bash
+codex plugin marketplace add parkerhancock/satchel
+```
+
+Then restart Codex, open the plugin directory, choose the Satchel marketplace,
+and install the Satchel plugin. Codex can also read the generated repo
+marketplace at `.agents/plugins/marketplace.json`, which points back to the
+Git-backed Satchel plugin source.
+
+GitHub Copilot CLI:
+
+```bash
+copilot plugin marketplace add parkerhancock/satchel
+copilot plugin install satchel@satchel-marketplace
+```
+
+Antigravity support is experimental. The adapter can generate a local package
+layout under `.agents/plugins/`, but install and marketplace behavior should be
+verified against the current Antigravity CLI or IDE before relying on it.
+
+## Features
+
+| Feature | What it does |
+| --- | --- |
+| **Neutral manifest** | Reads `satchel.yaml` as the package source of truth. |
+| **Target adapters** | Emits deterministic Codex, Claude, Copilot, and experimental Antigravity outputs through pluggable adapters. |
+| **Drift checks** | Fails when generated outputs are missing or stale. |
+| **Smoke tests** | Copies a package to a temporary directory, regenerates output, and validates the clean copy. |
+| **Host validation** | Runs non-mutating host validators where available, including `claude plugin validate`. |
+| **Path safety** | Rejects component and output paths that escape the package root. |
+| **Skill validation** | Checks each skill directory for `SKILL.md`, `name`, and `description`. |
+| **Fixture suite** | Exercises skills-only, MCP, target-rich, Antigravity, and unsupported-target packages. |
+| **Portability report** | Summarizes target support and shared components. |
+
+## Usage
+
+Create a package:
+
+```bash
+uv run satchel init my-plugin
+```
+
+Generate host manifests:
+
+```bash
+uv run satchel generate my-plugin
+```
+
+Check source validity and generated-file drift:
+
+```bash
+uv run satchel check my-plugin
+```
+
+Run host-aware validation when the host CLIs are installed:
+
+```bash
+uv run satchel check my-plugin --host
+```
+
+Run a clean-copy smoke test:
+
+```bash
+uv run satchel smoke my-plugin
+```
+
+Print a portability report:
+
+```bash
+uv run satchel report my-plugin
+```
+
+## Manifest
+
+Minimal `satchel.yaml`:
+
+```yaml
+schema: satchel/v0
+name: my-plugin
+version: 0.1.0
+description: Shared agent extension.
+author:
+  name: Your Team
+
+components:
+  skills:
+    path: ./skills
+  mcp:
+    path: ./.mcp.json
+
+targets:
+  codex:
+    enabled: true
+    manifest: ./.codex-plugin/plugin.json
+    interface:
+      displayName: My Plugin
+      shortDescription: Shared agent extension.
+      category: Productivity
+      capabilities:
+        - Read
+
+  claude:
+    enabled: true
+    manifest: ./.claude-plugin/plugin.json
+    displayName: My Plugin
+
+  copilot:
+    enabled: true
+    manifest: ./.github/plugin/plugin.json
+    marketplace:
+      path: ./.github/plugin/marketplace.json
+
+  antigravity:
+    enabled: false
+    experimental: true
+    output: ./.agents/plugins/my-plugin
+```
+
+## Output Model
+
+| Source | Codex | Claude | Copilot | Antigravity |
+| --- | --- | --- | --- | --- |
+| `name`, `version`, `description` | `.codex-plugin/plugin.json` | `.claude-plugin/plugin.json` | `.github/plugin/plugin.json` | `plugin.json` in the generated package root |
+| `components.skills.path` | `skills` field | `skills` field | `skills` field | copied to `skills/` |
+| `components.mcp.path` | `mcpServers` field | default `.mcp.json` | `mcpServers` field | copied to `mcp_config.json` |
+| `components.hooks.path` | `hooks` field | default `hooks/hooks.json` | `hooks` field | copied to `hooks.json` |
+| `targets.codex.interface` | `interface` object | not emitted | not emitted | not emitted |
+| `targets.claude.displayName` | not emitted | `displayName` | not emitted | not emitted |
+| target marketplace config | `.agents/plugins/marketplace.json` | `.claude-plugin/marketplace.json` | `.github/plugin/marketplace.json` | not supported yet |
+
+Generated manifests should be treated as build outputs. Edit `satchel.yaml`
+instead.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `satchel init <path>` | Create a minimal package with `satchel.yaml` and one skill. |
+| `satchel generate <path>` | Generate enabled host manifests. |
+| `satchel check <path>` | Validate source and fail on stale generated files. |
+| `satchel check <path> --host` | Add non-mutating host validators when available. |
+| `satchel smoke <path>` | Validate a regenerated temporary copy without mutating the source tree. |
+| `satchel report <path>` | Print a simple portability report. |
+
+## Release Readiness
+
+The repo now includes the release-readiness pieces needed for a public alpha:
+
+| Area | Status |
+| --- | --- |
+| Host validation | `satchel check --host` runs `claude plugin validate` when available and structural validators for generated Codex, Claude, Copilot, and Antigravity outputs. |
+| Clean smoke tests | `satchel smoke` regenerates and validates a temporary package copy. |
+| CI | `.github/workflows/ci.yml` runs lint, tests, `satchel check`, and `satchel smoke`. |
+| Packaging | `pyproject.toml` has public package metadata and `.github/workflows/publish.yml` supports trusted PyPI publishing from GitHub releases. |
+| Project hygiene | `CONTRIBUTING.md`, `SECURITY.md`, `ROADMAP.md`, and issue templates are present. |
+| Schema docs | `docs/schema.md` and `schemas/satchel.schema.json` document the manifest. |
+| Fixtures | `fixtures/` covers skills-only, skills-and-MCP, Claude-rich, Codex-rich, Copilot-rich, Antigravity-rich, and unsupported-target packages. |
+| Demo | `examples/release-auditor/` is a non-trivial generated multi-target plugin. |
+
+Operational release steps are documented in `docs/release.md`: configure PyPI
+trusted publishing, cut a GitHub release, then verify
+`uv tool install satchel-agent` or `pipx install satchel-agent` after
+publishing. The installed CLI command is still `satchel`.
+
+Good follow-up work after public alpha:
+
+- generated marketplace patch mode
+- `satchel pack --target codex|claude|copilot|antigravity`
+- `satchel smoke --target codex|claude|copilot|antigravity`
+- optional `plugin-scanner verify` integration
+- generated docs from `schemas/satchel.schema.json`
+
+## Development
+
+```bash
+uv run ruff check .
+uv run pytest
+uv run satchel check .
+uv run satchel smoke .
+uv run satchel report examples/basic
+```
+
+## License
+
+Satchel is released under the [MIT License](LICENSE).