pbg-superpowers 0.2.0__tar.gz

pbg_superpowers-0.2.0/.github/workflows/plugin-ci.yml

@@ -0,0 +1,34 @@
+name: plugin-ci
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        run: pip install uv
+      - name: Set up venv and install plugin
+        run: |
+          uv venv .venv
+          source .venv/bin/activate
+          uv pip install -e .[dev]
+      - name: Run L1 tests
+        env:
+          # The integration tests skip cleanly when ~/code/pbg-template isn't
+          # present, but in CI we want to actually run them. Clone the template
+          # to the expected path before pytest collects.
+          PBG_TEMPLATE_REPO: https://github.com/vivarium-collective/pbg-template.git
+        run: |
+          mkdir -p ~/code
+          if [ ! -d ~/code/pbg-template ]; then
+            git clone --depth 1 "$PBG_TEMPLATE_REPO" ~/code/pbg-template || true
+          fi
+          source .venv/bin/activate
+          pytest -v

pbg_superpowers-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv and Python
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: '3.12'
+          enable-cache: true
+          cache-dependency-glob: "**/uv.lock"
+
+      - name: Verify tag matches pyproject version
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pyproject_version=$(uv version --short)
+          if [ "$tag_version" != "$pyproject_version" ]; then
+            echo "Tag version ($tag_version) does not match pyproject.toml version ($pyproject_version)"
+            exit 1
+          fi
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI via trusted publisher
+        uses: pypa/gh-action-pypi-publish@release/v1

pbg_superpowers-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+*.pyc
+.pytest_cache/
+.coverage
+htmlcov/

pbg_superpowers-0.2.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: pbg-superpowers
+Version: 0.2.0
+Summary: Plugin Python helpers for the pbg-superpowers skills
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: jsonschema[format-nongpl]>=4.21
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'

pbg_superpowers-0.2.0/README.md

@@ -0,0 +1,105 @@
+# pbg-superpowers
+
+> **🚧 In development.** This plugin is evolving rapidly. The skills marked **Stable** below
+> are usable today; the rest (workspace bootstrap, dashboard, phases, visualization codegen,
+> package audit) are under active iteration and may change shape between minor versions.
+
+A Claude Code plugin for building **process-bigraph research projects**.
+Scaffold a workspace, walk a canonical PR flow, plan multi-phase model
+extensions, and produce interactive HTML reports.
+
+## Install
+
+(inside Claude Code:)
+
+    /plugin install pbg-superpowers
+    /reload-plugins
+
+## Quick start
+
+Wrap a simulator as a standalone pbg-* package:
+
+    /pbg-expert tellurium
+
+Or wrap it lightly inside an existing workspace:
+
+    cd ~/code/my-workspace
+    /pbg-wrapper tellurium
+
+Compose multiple wrappers:
+
+    /pbg-expert metabolism cobra tellurium       # heavy: new sibling composite repo
+    /pbg-composer metabolism cobra tellurium     # light: inside current workspace
+
+The workspace-bootstrap + dashboard skills (`/pbg-workspace`, `/pbg-server`,
+`/pbg-report`, `/pbg-phase`, `/pbg-viz`, `/pbg-package`) are still in development
+— see the table above.
+
+## Two repos
+
+This plugin works with a sibling repo, [`pbg-template`](https://github.com/vivarium-collective/pbg-template),
+which `/pbg-workspace` clones to scaffold new workspaces. You can also use
+`pbg-template` directly via GitHub's "Use this template" button — the
+`template-init.sh` in that repo produces the same structure without
+requiring this plugin.
+
+## Skills
+
+### Stable — recommended for current use
+
+| Skill | Repo target | What it does |
+|---|---|---|
+| `/pbg-expert <tool>` | new `pbg-<tool>/` sibling | Wrap a simulator as a process-bigraph Process: scaffolds a full sibling repo with Process class, tests, README, HTML report, and an open PR. The heavy/canonical wrap. |
+| `/pbg-expert <name> <tools…>` | new `pbg-<name>-composite/` sibling | Compose two or more wrapped simulators into a sibling composite repo, with HTML report and PR. Same heavy flow as the single-tool form. |
+| `/pbg-wrapper <tool>` | current workspace | Lightweight in-workspace wrap. Writes `pbg_<slug>/processes/<tool>.py` + a test stub. No sibling repo, no report — good for incremental experimentation. |
+| `/pbg-composer <name> <tools…>` | current workspace | Lightweight in-workspace composite. Writes `pbg_<slug>/composites/<name>.py` + test stub referencing already-installed wrapper packages. |
+| `/pbg-suggest <request-id>` | current workspace | Draft a Claude-suggested repo name, PR title, or PR body in response to a dashboard Suggest button request. Writes the response to `.pbg/agent-responses/<id>.json`; dashboard polls and fills the input automatically. |
+
+### In development
+
+These ship today but their interfaces are still moving:
+
+| Skill | What it does |
+|---|---|
+| `/pbg-workspace <name>` | Scaffold a workspace by cloning pbg-template |
+| `/pbg-server [start\|stop\|status]` | Local dashboard (5 tabs + workstream strip + branch timeline) |
+| `/pbg-report` | Regenerate `reports/index.html` after manual state changes |
+| `/pbg-phase <n>` | Drive phase n inside a workspace |
+| `/pbg-viz <name>` | Generate a `Visualization` subclass from a description (v0.4.11+: class form, auto-discoverable) |
+| `/pbg-package <repo>` | Audit a pbg-* repo for discovery-convention compliance |
+
+## Architecture
+
+- **Workspace IS the model.** The workspace root contains `pbg_<slug>/`, `tests/`, `phases/`, and `workspace.yaml` directly. The workspace owns datasets, references, decision log, and the dashboard.
+- **5-tab dashboard.** `Workspace inputs · Registry · Simulation Setup · Visualizations · Build Model`. Each tab is the canonical UI for that part of the workflow. Skills are the alternative for code-writing tasks that benefit from Claude.
+- **Active-branch workstream model.** Click *Start workstream* in the sticky strip below the menu; every dashboard mutation commits to that branch. *Push* + *Create PR* one-click via the strip. One PR per workstream, many commits — co-workers review the whole accumulated change in one place.
+- **Registry as catalog.** `scripts/_catalog/modules.json` lists curated pbg-* packages. Install adds a submodule, pip-installs into `.venv`, and appends to `pyproject.toml` `[project.dependencies]`. The Discovered Processes/Types tables read live from `bigraph_schema.package.discover` — no manual `register_link()` boilerplate needed. See [docs/conventions/discovery.md](docs/conventions/discovery.md).
+- **Visualization-as-description.** A visualization is `{name, description}` in `workspace.yaml`. Create writes a request file; `/pbg-viz <name>` generates a `Visualization` subclass (auto-discoverable via bigraph-schema) with a `_demo()` helper; Add to project stages it; Commit lands `pbg_<slug>/visualizations/<name>.py` on the active branch.
+- **Phase template is first-class.** Each phase lives in `phases/phase-N.md` at the workspace root with YAML frontmatter (`status`, `prereq_phases`, `gate_passed`, `acceptance_tests`, …). The body uses your Phase Template format verbatim. The Build Model tab renders each phase with a Start phase / Evaluate gate action button.
+- **Composite spec convention.** Composites are DATA, not code. Any `*.composite.yaml` or `*.composite.json` file in an installed bigraph-schema-dependent package is a composite spec — a declarative state document with optional typed parameters that support `${name}` substitution. `pbg_superpowers.composite_spec.build_composite_from_spec` turns a parsed spec into a runnable `Composite`; `pbg_superpowers.composite_discovery.discover_composites` walks all installed packages (and optional local search paths) to find every registered spec without importing any simulator code. See [docs/conventions/composites.md](docs/conventions/composites.md) for the full reference.
+- **Visualization Step base class** — `pbg_superpowers.visualization.Visualization`
+  is a `process_bigraph.Step` subclass; visualization subclasses are
+  auto-discovered alongside Processes / Emitters / Types. See
+  [docs/conventions/visualizations.md](docs/conventions/visualizations.md).
+
+## Tests
+
+Three levels:
+
+- **L1 (plugin internals)** — `pytest` from this repo
+- **L2 (workspace lint)** — `python scripts/lint-workspace.py` inside any scaffolded workspace
+- **L3 (workspace tests)** — `pytest tests/` from the workspace root, including `test_core_integration.py` (process/type registry checks + drift detector) and `test_phases.py` (auto-generated from phase frontmatter)
+
+CI workflows are provided for both repos:
+
+- `.github/workflows/plugin-ci.yml` (this repo)
+- `.github/workflows/workspace-ci.yml` (in scaffolded workspaces, via `pbg-template`)
+
+## Design
+
+See `docs/superpowers/specs/2026-05-09-pbg-project-template-design.md`
+in the brainstorming repo for the full architectural spec.
+
+## License
+
+MIT (or your-license-here).

pbg_superpowers-0.2.0/docs/audits/pbg-pypi-audit-2026-05-11.md

@@ -0,0 +1,278 @@
+# pbg-* PyPI publication audit (2026-05-11)
+
+Generated by `scripts/audit-pbg-catalog.py`. Run periodically to track
+progress toward full PyPI publication of the catalog.
+
+Catalog: `/Users/eranagmon/code/pbg-template/scripts/_catalog/modules.json`
+Entries audited: 18
+
+## Summary
+
+| Repo | pyproject | bigraph-schema | process-bigraph | requires-python | Process subclasses | Published on PyPI |
+| --- | --- | --- | --- | --- | --- | --- |
+| pbg-bioreactordesign | PASS | PASS | PASS | PASS | PASS (1:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-caspule | PASS | PASS | PASS | PASS | PASS (1:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-cellpack | PASS | PASS | PASS | PASS | PASS (1:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-comets | PASS | PASS | PASS | PASS | PASS (3:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-composite-nfsim-caspule | PASS | PASS | PASS | PASS | PASS (1:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-compucell3d | PASS | PASS | PASS | PASS | PASS (1:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-lammps | PASS | PASS | PASS | PASS | PASS (1:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-martini | PASS | PASS | PASS | PASS | PASS (5:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-medyan | PASS | PASS | PASS | PASS | PASS (2:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-mem3dg | PASS | PASS | PASS | PASS | PASS (1:) | PASS — published on PyPI as pbg-mem3dg (latest: 0.1.0) |
+| pbg-nfsim | PASS | PASS | PASS | PASS | PASS (2:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-readdy | PASS | PASS | PASS | PASS | PASS (1:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-smoldyn | PASS | PASS | PASS | PASS | PASS (1:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-tellurium | PASS | PASS | PASS | PASS | PASS (2:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-vcell-fvsolver | PASS | PASS | PASS | PASS | PASS (1:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| pbg-yalla | PASS | PASS | PASS | PASS | PASS (1:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+| spatio-flux | PASS | PASS | PASS | PASS | PASS (13:) | PASS — published on PyPI as spatio-flux (latest: 1.3.0) |
+| v2ecoli | PASS | PASS | PASS | PASS | PASS (49:) | WARN — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md |
+
+## Per-repo findings
+
+### pbg-bioreactordesign
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 1: BiRDReactorProcess (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-caspule
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 1: CASPULEProcess (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-cellpack
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 1: CellPackStep (Step)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-comets
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 3: DynamicFBAProcess (Process), SpatialDynamicFBAProcess (Process), CometsProcess (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-composite-nfsim-caspule
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.10
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 1: ObservableDetector (Step)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-compucell3d
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 1: CompuCell3DProcess (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-lammps
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 1: LAMMPSProcess (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-martini
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 5: MartinizeStep (Step), MembraneBuilderStep (Step), MicelleBuilderStep (Step), ProteinMembraneStep (Step), VesicleBuilderStep (Step)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-medyan
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 2: MedyanProcess (Process), MedyanCxxProcess (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-mem3dg
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `PASS` — published on PyPI as pbg-mem3dg (latest: 0.1.0)
+- **Process/Step subclasses**: `PASS` — found 1: Mem3DGProcess (Process)
+
+*Summary: PASS: 6*
+
+### pbg-nfsim
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 2: NFSimProcess (Process), MonomerProduction (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-readdy
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 1: ReaDDyProcess (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-smoldyn
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 1: SmoldynProcess (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-tellurium
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 2: TelluriumProcess (Process), TelluriumStep (Step)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-vcell-fvsolver
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.11
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 1: VCellFVProcess (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### pbg-yalla
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.9
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 1: YallaProcess (Process)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup
+
+### spatio-flux
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: >=3.11,<3.13
+- **published on PyPI**: `PASS` — published on PyPI as spatio-flux (latest: 1.3.0)
+- **Process/Step subclasses**: `PASS` — found 13: BigraphicalReactiveSystem (Process), BrownianMovement (Process), ManageBoundaries (Step), ParticleExchange (Step), ParticleDivision (Step)
+
+*Summary: PASS: 6*
+
+### v2ecoli
+
+- **pyproject.toml**: `PASS`
+- **bigraph-schema dep**: `PASS`
+- **process-bigraph dep**: `PASS`
+- **requires-python**: `PASS` — declared: ==3.12.12
+- **published on PyPI**: `WARN` — NOT published on PyPI — recommend publishing; see docs/conventions/distribution.md
+- **Process/Step subclasses**: `PASS` — found 49: EcoliWCM (Process), Equilibrium (Step), ChromosomeStructure (Step), TwoComponentSystem (Step), TfUnbinding (Step)
+
+*Summary: PASS: 5, WARN: 1*
+
+Recommended fixes:
+- See docs/conventions/distribution.md for trusted-publishing setup

pbg_superpowers-0.2.0/docs/conventions/composites.md

@@ -0,0 +1,198 @@
+# Composite Spec Convention
+
+## What is a composite spec?
+
+A composite spec is a **declarative, data-first** description of a process-bigraph
+`Composite`. It lives in a `*.composite.yaml` or `*.composite.json` file inside an
+installed package. It declares the composite's state document and optional
+configurable parameters.
+
+Composites are DATA (state documents), while processes are CODE (subclasses of
+`Edge`/`Process`). Keeping composites as plain files means they can be:
+
+- **Inspected** without running Python
+- **Diffed** in git like any structured text
+- **Discovered** by glob without importing any package-specific code
+- **Versioned** independently of the processes they reference
+
+## Format
+
+```yaml
+# REQUIRED:
+name: my-composite          # unique within the spec file (used for display and IDs)
+state:                      # the composite state dict (passed to Composite({'state': ...}))
+  process_a:
+    _type: process
+    address: "local:MyProcess"
+    config:
+      rate: "${rate}"       # parameter substitution (full placeholder — preserves type)
+    inputs:
+      level: ["stores", "level"]
+    outputs:
+      level: ["stores", "level"]
+    interval: 1.0
+  stores:
+    level: "${initial_level}"
+
+# OPTIONAL:
+description: "Human-readable description of what this composite models."
+requires:
+  processes: [MyProcess, RAMEmitter]   # must be in core.link_registry at build time
+  types: []                            # custom type names in core.registry
+parameters:
+  rate:
+    type: float       # one of: float, int, string, str, bool
+    default: 1.0
+    description: "Multiplicative factor applied each step"
+  initial_level:
+    type: float
+    default: 0.0
+```
+
+### Required fields
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Non-empty identifier for the composite |
+| `state` | dict | The composite state document passed to `Composite({'state': ...})` |
+
+### Optional fields
+
+| Field | Type | Description |
+|---|---|---|
+| `description` | string | Human-readable summary |
+| `requires.processes` | list[str] | Process class names that must be in `core.link_registry` |
+| `requires.types` | list[str] | Custom type names that must be in `core.registry` |
+| `parameters` | dict | Named parameters with `type`, `default`, and optional `description` |
+
+## Parameter substitution
+
+Any leaf string value in `state` may contain `${name}` placeholders that reference
+declared parameters. There are two substitution modes:
+
+### Full placeholder — type-preserving
+
+If the **entire** leaf value is `"${name}"`, the placeholder is replaced with the
+parameter's typed value:
+
+```yaml
+parameters:
+  rate:
+    type: float
+    default: 1.0
+state:
+  process_a:
+    config:
+      rate: "${rate}"   # replaced with Python float 1.0, not the string "1.0"
+```
+
+This matters because process-bigraph validates config types. Always use full
+placeholders when referencing numeric or boolean parameters inside `config:`.
+
+### Inline placeholder — string interpolation
+
+When `${name}` is embedded within a larger string, the result is always a string:
+
+```yaml
+parameters:
+  strain:
+    type: string
+    default: wt
+state:
+  label: "experiment-${strain}-run1"   # becomes "experiment-wt-run1"
+```
+
+### Rules
+
+- Parameter names must be valid Python identifiers: `[a-zA-Z_][a-zA-Z0-9_]*`
+- Malformed braces or invalid names are left as-is (no error at parse time)
+- Missing parameters (referenced in state but not declared) raise `KeyError` at
+  substitution time
+- Missing defaults with no override raise `KeyError` at substitution time
+
+## Loading and building
+
+```python
+from pathlib import Path
+from pbg_superpowers.composite_spec import load_spec, build_composite_from_spec
+
+spec = load_spec(Path("my_package/composites/baseline.composite.yaml"))
+
+# Build with defaults
+composite = build_composite_from_spec(spec)
+
+# Build with parameter overrides
+composite = build_composite_from_spec(spec, overrides={"rate": 0.5})
+
+# Bring your own core (e.g. after registering custom types)
+from process_bigraph import allocate_core
+core = allocate_core()
+composite = build_composite_from_spec(spec, overrides={"rate": 0.5}, core=core)
+
+# Run and gather results
+composite.run(10)
+from process_bigraph import gather_emitter_results
+results = gather_emitter_results(composite)
+```
+
+`build_composite_from_spec` will raise `RuntimeError` if any process listed in
+`requires.processes` is absent from the registry, giving a clear error before
+the Composite tries to wire up any ports.
+
+## Discovery
+
+`discover_composites` walks all installed distributions that depend on
+`bigraph-schema` and globs for `*.composite.{yaml,yml,json}` under each
+importable package directory:
+
+```python
+from pbg_superpowers.composite_discovery import discover_composites
+
+# Discover from all installed packages
+specs = discover_composites()
+# {"pbg_chromosome_rep1.composites.baseline": <spec dict>, ...}
+
+# Also search workspace-local directories
+from pathlib import Path
+specs = discover_composites(extra_search_paths=[Path("composites/")])
+```
+
+Spec IDs follow the pattern `<pkg_name>.<subpath>.<file_stem>` — e.g.
+`pbg_chromosome_rep1.composites.baseline` for the file
+`pbg_chromosome_rep1/composites/baseline.composite.yaml`.
+
+Discovery **never imports the spec's processes** — it only reads files. This
+keeps it safe to call at startup or in CI without needing every simulator
+installed.
+
+## Why this lives in pbg-superpowers (for now)
+
+The convention is intentionally framework-level, but it belongs in
+`pbg-superpowers` until it stabilizes. Once battle-tested across several pbg-*
+packages, the plan is to propose it upstream to `process-bigraph` as an optional
+discovery layer alongside the existing class-based registration.
+
+## When to use a spec file vs a Python function
+
+| Situation | Use |
+|---|---|
+| The composite is a canonical scenario users will reuse or share | `*.composite.yaml` spec |
+| The composite structure is generated procedurally | Python function |
+| You want it discoverable across packages without importing | spec file |
+| You need complex logic (conditionals, loops) to wire ports | Python function |
+| You want to diff composite changes in PRs | spec file |
+| The composite is a test helper or one-off | Python function |
+
+## JSON Schema
+
+A machine-readable schema for the format lives at:
+`pbg_superpowers/schemas/composite-spec.schema.json`
+
+This can be used for editor autocompletion (add it as a YAML/JSON schema
+association in VS Code or PyCharm).
+
+## See also
+
+- [Process discovery convention](discovery.md) — how processes (code) are discovered
+- `/pbg-composer` skill — writes in-workspace composite Python files; v0.4.11 will
+  also emit `*.composite.yaml` alongside the Python