acpus 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkkyran
+
+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.

package/README.md

@@ -0,0 +1,97 @@
+<p align="center">
+  <img src="page/logo/logo-opus-mark.svg" alt="Acpus mark" width="120">
+</p>
+
+<h1 align="center">Acpus</h1>
+<p align="center" font-style="italic">Every run is an opus.</p>
+
+Acpus is a runtime-driven workflow orchestrator for ACP agents, built on the acpx agent runtime. You hand it a *workflow spec*; Acpus validates it, compiles a deterministic execution plan, conducts heterogeneous fanout across lanes, and tracks every run as a numbered, replayable execution, or say, an *opus*.
+
+## Quick Start
+
+```bash
+# Install
+npm install -g acpus
+
+# Validate a workflow spec
+acpus validate --spec workflows/examples/simple-feature.workflow.spec.json
+
+# Preview the execution plan
+acpus preview --spec workflows/examples/simple-feature.workflow.spec.json
+
+# Run the workflow
+acpus run --spec workflows/examples/simple-feature.workflow.spec.json
+
+# Follow a running workflow in real time
+acpus follow <logical-run-id>
+```
+
+## Skill
+
+```bash
+npx skills add kelvinschen/acpus --skill acpus
+```
+
+## Commands
+
+Acpus commands are grouped by four verbs.
+
+### Compose — validate, preview, save, generate
+
+| Command | Purpose |
+|---|---|
+| `acpus validate --spec <path>` | Validate a workflow spec against the schema |
+| `acpus preview --spec <path>` | Render the compiled execution plan without running |
+| `acpus save <name> --spec <path>` | Save a spec to the local store |
+| `acpus generate` | Scaffold a new workflow spec from a template |
+
+### Conduct — run, follow, monitor, resume
+
+| Command | Purpose |
+|---|---|
+| `acpus run --spec <path>` | Execute a workflow spec end-to-end |
+| `acpus follow <run-id>` | Attach to a running workflow and stream output |
+| `acpus monitor <run-id>` | Open the terminal UI for run inspection |
+| `acpus resume <run-id>` | Resume an interrupted or failed run from last checkpoint |
+
+### Recover — recover, diagnose
+
+| Command | Purpose |
+|---|---|
+| `acpus recover <run-id>` | Attempt automatic repair of a failed run |
+| `acpus diagnose <run-id> [--wait]` | Produce a structured diagnosis of a completed or running run |
+
+### Catalogue — list, show
+
+| Command | Purpose |
+|---|---|
+| `acpus list` | List saved specs and historical runs |
+| `acpus show <id>` | Display details of a saved spec or past run |
+
+## Architecture
+
+Acpus sits between the author and the acpx runtime. The main agent produces a *workflow spec*. Acpus reads it, validates it against the JSON schema, and compiles it into an *execution plan* — a deterministic sequence of stages, each containing parallel lanes that map to independent acpx sessions.
+
+Run directories live under `.acpus/runs/<id>/`. Each contains:
+
+- `workflow.spec.json` — the original workflow spec
+- `execution-plan.json` — the compiled plan
+- `input.json` — resolved inputs at launch time
+- `outputs/` — stage outputs and final artefacts
+- `attempts/` — raw attempt records with agent transcripts
+- `acpx-state/` — run-local acpx session state
+- `sessions/` — per-lane session logs
+- `events.ndjson` — timestamped event log for the entire run
+
+The orchestrator does not generate or execute ACPX flow files directly. It drives acpx through its runtime API.
+
+## Documentation
+
+- [Developer documentation](docs/README.md)
+- [Design and implementation specifications](specs/INDEX.md)
+- [CLI guide](docs/cli.md)
+- [Error code guide](docs/error-codes.md)
+
+## License
+
+MIT

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };