@acidicsoil/portable-capabilities 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +139 -158
- package/dist-release/cli.js +13633 -0
- package/dist-release/cli.js.map +7 -0
- package/dist-release/index.js +13755 -0
- package/dist-release/index.js.map +7 -0
- package/package.json +13 -3
- package/schemas/capability-system.schema.json +14 -0
- package/schemas/evidence-ledger-1.0.schema.json +29 -0
- package/schemas/evidence-ledger.schema.json +109 -0
- package/schemas/exception.schema.json +30 -0
- package/schemas/family.schema.json +52 -0
- package/schemas/operation.schema.json +120 -0
- package/schemas/role.schema.json +204 -0
- package/schemas/runtime-profile.schema.json +305 -0
package/README.md
CHANGED
|
@@ -6,226 +6,207 @@
|
|
|
6
6
|
[](https://www.typescriptlang.org/)
|
|
7
7
|
[](.planning/STATE.md)
|
|
8
8
|
|
|
9
|
-
Define an analytical capability once, then
|
|
9
|
+
Define an analytical coding-agent capability once, then generate and install the native package for each configured runtime.
|
|
10
10
|
|
|
11
|
-
Portable Capabilities is a contract-first
|
|
11
|
+
Portable Capabilities is a contract-first compiler and CLI. A canonical capability describes its activation criteria, accepted inputs, ordered procedure, output schema, evidence requirements, and allowed effects. The compiler turns that contract into runtime-native skills, commands, agents, workflows, rules, or extensions without maintaining a separate handwritten implementation for every client.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
- OpenCode
|
|
15
|
-
- Pi
|
|
16
|
-
- Claude Code
|
|
17
|
-
- Codex
|
|
18
|
-
- Google Antigravity
|
|
19
|
-
- Deep Agents Code
|
|
13
|
+
## Review every runtime
|
|
20
14
|
|
|
21
|
-
|
|
15
|
+
Generated packages, one-line installers, and captured native outputs for all seven runtimes are available in [`review/runtime-packages`](review/runtime-packages/README.md).
|
|
22
16
|
|
|
23
|
-
|
|
17
|
+
```bash
|
|
18
|
+
bash review/runtime-packages/codex/install.sh
|
|
19
|
+
```
|
|
24
20
|
|
|
25
|
-
|
|
21
|
+
## Try it
|
|
26
22
|
|
|
27
|
-
|
|
23
|
+
Run one complete example with no configuration:
|
|
28
24
|
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
↓
|
|
32
|
-
validation + deterministic resolution
|
|
33
|
-
↓
|
|
34
|
-
runtime-neutral projection
|
|
35
|
-
↓
|
|
36
|
-
runtime adapters
|
|
37
|
-
↓
|
|
38
|
-
native packages + conformance evidence
|
|
25
|
+
```bash
|
|
26
|
+
pnpm demo
|
|
39
27
|
```
|
|
40
28
|
|
|
41
|
-
|
|
29
|
+
This builds the canonical `acceptance-criteria-synthesis` capability for Codex, installs it into a clean project, invokes it through Codex, and writes the result to `.demo/result.md`.
|
|
42
30
|
|
|
43
|
-
|
|
31
|
+
## What problem does it solve?
|
|
44
32
|
|
|
45
|
-
|
|
33
|
+
Coding-agent clients discover and activate reusable behavior differently. The same capability may require a skill directory in one client, a slash command in another, a subagent definition elsewhere, and different permission metadata in each package.
|
|
46
34
|
|
|
47
|
-
|
|
35
|
+
Maintaining those variants by hand causes:
|
|
48
36
|
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
37
|
+
- behavior drift between runtimes;
|
|
38
|
+
- duplicated instructions and schemas;
|
|
39
|
+
- missing resources after installation;
|
|
40
|
+
- undocumented permission differences;
|
|
41
|
+
- inconsistent upgrades and removals;
|
|
42
|
+
- unsupported claims that cannot be tied to execution evidence.
|
|
52
43
|
|
|
53
|
-
|
|
44
|
+
Portable Capabilities keeps one canonical behavioral definition and generates the runtime projection.
|
|
54
45
|
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
46
|
+
```text
|
|
47
|
+
canonical capability contract
|
|
48
|
+
↓
|
|
49
|
+
validation and deterministic resolution
|
|
50
|
+
↓
|
|
51
|
+
runtime-native package generation
|
|
52
|
+
↓
|
|
53
|
+
installation into a consumer project
|
|
54
|
+
↓
|
|
55
|
+
native discovery, invocation, and verification
|
|
61
56
|
```
|
|
62
57
|
|
|
63
|
-
|
|
58
|
+
## What is a capability?
|
|
64
59
|
|
|
65
|
-
|
|
66
|
-
pnpm cli -- build fixtures/tracer/system.yaml --format json
|
|
67
|
-
```
|
|
60
|
+
A capability is more than a prompt. It defines:
|
|
68
61
|
|
|
69
|
-
|
|
62
|
+
- purpose and activation criteria;
|
|
63
|
+
- accepted inputs and source precedence;
|
|
64
|
+
- an ordered analytical procedure;
|
|
65
|
+
- required and forbidden behavior;
|
|
66
|
+
- ambiguity, abstention, and stop conditions;
|
|
67
|
+
- a structured output schema;
|
|
68
|
+
- evidence and traceability requirements;
|
|
69
|
+
- filesystem, shell, network, and repository-write effects.
|
|
70
70
|
|
|
71
|
-
|
|
72
|
-
pnpm cli -- build fixtures/tracer/system.yaml --output ./generated
|
|
73
|
-
```
|
|
71
|
+
Every generated package retains a `SKILL.md` behavioral core plus its required resources, schema, integrity lock, and any runtime-native activation artifact.
|
|
74
72
|
|
|
75
|
-
|
|
73
|
+
## Runtime packages
|
|
76
74
|
|
|
77
|
-
|
|
75
|
+
The project generates packages for seven clients. Package generation is not the same as authoritative behavioral certification: the runtime profile and retained execution evidence determine whether a client is currently supported, unavailable, unsupported, or covered by an approved exception.
|
|
78
76
|
|
|
79
|
-
|
|
77
|
+
| Runtime | Native primitives | Package and verification guide |
|
|
78
|
+
| ------------------ | --------------------- | ------------------------------------------- |
|
|
79
|
+
| oh-my-pi | Skill | [oh-my-pi](docs/runtimes/oh-my-pi.md) |
|
|
80
|
+
| OpenCode | Skill, command, agent | [OpenCode](docs/runtimes/opencode.md) |
|
|
81
|
+
| Pi | Skill, extension | [Pi](docs/runtimes/pi.md) |
|
|
82
|
+
| Claude Code | Skill, command, agent | [Claude Code](docs/runtimes/claude-code.md) |
|
|
83
|
+
| Codex | Skill, agent | [Codex](docs/runtimes/codex.md) |
|
|
84
|
+
| Google Antigravity | Skill, workflow, rule | [Antigravity](docs/runtimes/antigravity.md) |
|
|
85
|
+
| Deep Agents Code | Skill | [Deep Agents Code](docs/runtimes/dcode.md) |
|
|
80
86
|
|
|
81
|
-
|
|
82
|
-
- Six capability families and nine shared operations
|
|
83
|
-
- Versioned schemas, policy evaluation, diagnostics, evidence classes, and provenance
|
|
84
|
-
- Deterministic compiler resolution and normalized file generation
|
|
85
|
-
- Seven runtime profiles and adapter packages, plus a reference adapter
|
|
86
|
-
- Structured conformance results, semantic comparison, property tests, fault injection, and regression fixtures
|
|
87
|
-
- A public CLI exposing `build`, `validate`, `test`, `diff`, `inspect`, and `invoke`
|
|
88
|
-
- CI, package verification, runtime bundle generation, clean-checkout release checks, and generated-output drift verification
|
|
87
|
+
See [Runtime usage and verification](docs/runtimes/README.md) for the shared installation flow, evidence levels, and pass criteria.
|
|
89
88
|
|
|
90
|
-
|
|
89
|
+
## CLI workflows
|
|
91
90
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
The intended public v1 distribution is `@portable-capabilities/cli`, installed with the executable:
|
|
91
|
+
The intended public executable is:
|
|
95
92
|
|
|
96
93
|
```text
|
|
97
94
|
portable-capabilities
|
|
98
95
|
```
|
|
99
96
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
| Command | Purpose |
|
|
103
|
-
| ---------- | ------------------------------------------------------------------ |
|
|
104
|
-
| `build` | Compile canonical input into generated runtime packages |
|
|
105
|
-
| `validate` | Validate canonical documents, projections, and generated artifacts |
|
|
106
|
-
| `test` | Run conformance checks |
|
|
107
|
-
| `diff` | Compare independently generated output |
|
|
108
|
-
| `inspect` | Examine resolved contracts, profiles, and projection data |
|
|
109
|
-
| `invoke` | Launch a selected runtime through the CLI boundary |
|
|
97
|
+
Install the published package globally and confirm the executable is available:
|
|
110
98
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
```text
|
|
116
|
-
canonical/
|
|
117
|
-
roles · families · operations · policies · runtime profiles
|
|
118
|
-
│
|
|
119
|
-
▼
|
|
120
|
-
packages/contracts + packages/schemas
|
|
121
|
-
│
|
|
122
|
-
▼
|
|
123
|
-
packages/compiler
|
|
124
|
-
load · validate · resolve · enforce · digest · write
|
|
125
|
-
│
|
|
126
|
-
▼
|
|
127
|
-
packages/renderer-core + packages/adapters/*
|
|
128
|
-
│
|
|
129
|
-
├── generated runtime packages
|
|
130
|
-
└── conformance evidence
|
|
131
|
-
│
|
|
132
|
-
▼
|
|
133
|
-
packages/cli
|
|
99
|
+
```bash
|
|
100
|
+
npm install -g @acidicsoil/portable-capabilities
|
|
101
|
+
portable-capabilities --help
|
|
134
102
|
```
|
|
135
103
|
|
|
136
|
-
The
|
|
104
|
+
The package installs the executable into npm's configured global binary directory. No package-specific `PATH` entry is required when that npm directory is already on `PATH`.
|
|
137
105
|
|
|
138
|
-
|
|
139
|
-
2. Contracts and schemas define the shared vocabulary.
|
|
140
|
-
3. The compiler resolves deterministic system state.
|
|
141
|
-
4. Renderer core and adapters select runtime-native representations.
|
|
142
|
-
5. The CLI exposes user workflows.
|
|
143
|
-
6. Conformance verifies structure, behavior, safety, traceability, and regression outcomes.
|
|
106
|
+
While working from this repository, replace `portable-capabilities` in the examples with `pnpm cli --`.
|
|
144
107
|
|
|
145
|
-
|
|
108
|
+
| Command | Purpose |
|
|
109
|
+
| ----------- | -------------------------------------------------------- |
|
|
110
|
+
| `build` | Compile selected capabilities for selected runtimes |
|
|
111
|
+
| `validate` | Validate contracts, projections, resources, and packages |
|
|
112
|
+
| `test` | Run conformance checks |
|
|
113
|
+
| `diff` | Detect nondeterministic generated output |
|
|
114
|
+
| `inspect` | Examine a resolved capability and runtime projection |
|
|
115
|
+
| `invoke` | Execute a verified package through the CLI boundary |
|
|
116
|
+
| `install` | Install all capabilities or an explicit subset |
|
|
117
|
+
| `status` | Inspect installation health |
|
|
118
|
+
| `upgrade` | Upgrade installer-owned capability files |
|
|
119
|
+
| `downgrade` | Restore an earlier package version |
|
|
120
|
+
| `recover` | Recover an interrupted installation transaction |
|
|
121
|
+
| `remove` | Remove installer-owned files safely |
|
|
146
122
|
|
|
147
|
-
|
|
123
|
+
Machine-readable commands support `--format json`.
|
|
148
124
|
|
|
149
|
-
|
|
150
|
-
| -------------------------------------- | ---------------------------------------------------------------- |
|
|
151
|
-
| `@portable-capabilities/contracts` | Shared readonly domain contracts |
|
|
152
|
-
| `@portable-capabilities/schemas` | JSON Schema registry and validation |
|
|
153
|
-
| `@portable-capabilities/operations` | Shared analytical operations and families |
|
|
154
|
-
| `@portable-capabilities/compiler` | Loading, resolution, policy, provenance, diagnostics, and output |
|
|
155
|
-
| `@portable-capabilities/renderer-core` | Projection IR and adapter contracts |
|
|
156
|
-
| `@portable-capabilities/adapter-*` | Runtime-specific private adapters |
|
|
157
|
-
| `@portable-capabilities/fixtures` | Deterministic fixtures and regression inputs |
|
|
158
|
-
| `@portable-capabilities/conformance` | Centralized verification implementation and tests |
|
|
159
|
-
| `@portable-capabilities/cli` | Public command-line package |
|
|
125
|
+
## Build, inspect, and install
|
|
160
126
|
|
|
161
|
-
|
|
127
|
+
Set the values for your system manifest, runtime, capability, generated bundle, and clean consumer project:
|
|
162
128
|
|
|
163
|
-
|
|
129
|
+
```bash
|
|
130
|
+
MANIFEST=/path/to/capability-system.yaml
|
|
131
|
+
RUNTIME=codex
|
|
132
|
+
CAPABILITY=<capability-id>
|
|
133
|
+
BUNDLE=/tmp/portable-capabilities-bundle
|
|
134
|
+
CONSUMER=/tmp/portable-capabilities-consumer
|
|
135
|
+
```
|
|
164
136
|
|
|
165
|
-
|
|
137
|
+
Build and inspect one runtime projection:
|
|
166
138
|
|
|
167
139
|
```bash
|
|
168
|
-
pnpm build
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
pnpm
|
|
174
|
-
|
|
140
|
+
pnpm cli -- build "$MANIFEST" \
|
|
141
|
+
--target "$RUNTIME" \
|
|
142
|
+
--role "$CAPABILITY" \
|
|
143
|
+
--output "$BUNDLE"
|
|
144
|
+
|
|
145
|
+
pnpm cli -- inspect "$MANIFEST" \
|
|
146
|
+
--target "$RUNTIME" \
|
|
147
|
+
--role "$CAPABILITY" \
|
|
148
|
+
--format json
|
|
175
149
|
```
|
|
176
150
|
|
|
177
|
-
|
|
151
|
+
Install it into a clean consumer project and verify installer health:
|
|
178
152
|
|
|
179
153
|
```bash
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
pnpm
|
|
154
|
+
mkdir -p "$CONSUMER"
|
|
155
|
+
git -C "$CONSUMER" init
|
|
156
|
+
|
|
157
|
+
pnpm cli -- install \
|
|
158
|
+
--source "$BUNDLE" \
|
|
159
|
+
--target "$CONSUMER" \
|
|
160
|
+
--runtime "$RUNTIME" \
|
|
161
|
+
--package-version 1.0.0 \
|
|
162
|
+
--capability "$CAPABILITY"
|
|
163
|
+
|
|
164
|
+
pnpm cli -- status --target "$CONSUMER" --format json
|
|
184
165
|
```
|
|
185
166
|
|
|
186
|
-
|
|
167
|
+
Then start the selected coding-agent client from `$CONSUMER` and follow its runtime guide. Each guide documents the generated paths, native invocation syntax, user smoke test, maintainer certification procedure, and current evidence status.
|
|
168
|
+
|
|
169
|
+
## Verification levels
|
|
170
|
+
|
|
171
|
+
Portable Capabilities keeps these claims separate:
|
|
187
172
|
|
|
188
|
-
|
|
173
|
+
1. **Static package validation** proves file layout, schemas, resources, primitive selection, permissions, and integrity metadata.
|
|
174
|
+
2. **Clean installation validation** proves the packed CLI can install, inspect, upgrade, recover, and remove generated packages in a disposable project.
|
|
175
|
+
3. **Native client execution** proves the real client discovered and invoked the generated primitive.
|
|
176
|
+
4. **Behavioral conformance** proves the client consumed the operational instructions, produced schema-valid output, preserved evidence requirements, and respected effects.
|
|
189
177
|
|
|
190
|
-
|
|
178
|
+
A static or simulated pass must not be reported as native behavioral support. See [Testing](docs/TESTING.md).
|
|
191
179
|
|
|
192
|
-
|
|
180
|
+
## Included analytical roles
|
|
193
181
|
|
|
194
|
-
|
|
195
|
-
- Transitive, source-independent package resource closure
|
|
196
|
-
- Runtime-specific primitive selection and native permission controls
|
|
197
|
-
- Separate CLI invocation confinement
|
|
198
|
-
- Exact compatibility baselines and authoritative runtime harnesses
|
|
199
|
-
- Four linked digest and lock layers
|
|
200
|
-
- Collision-safe `install`, `status`, `upgrade`, and `remove`
|
|
201
|
-
- Installed-artifact clean-consumer behavioral conformance
|
|
202
|
-
- Eight explicit conformance layers and seven normative regression scenarios
|
|
182
|
+
The v1 library contains sixteen analytical roles covering:
|
|
203
183
|
|
|
204
|
-
|
|
184
|
+
- exemplar generalization and target adaptation;
|
|
185
|
+
- structural pattern and convention extraction;
|
|
186
|
+
- reference traceability and implementation deltas;
|
|
187
|
+
- reusable workflow abstraction;
|
|
188
|
+
- conversation-to-specification conversion;
|
|
189
|
+
- failure-to-guardrail conversion;
|
|
190
|
+
- acceptance-criteria and evaluation-harness generation;
|
|
191
|
+
- domain-context and template-family generation;
|
|
192
|
+
- anti-pattern inversion;
|
|
193
|
+
- behavior-preserving refactor specification.
|
|
205
194
|
|
|
206
195
|
## Documentation
|
|
207
196
|
|
|
208
197
|
- [Getting Started](docs/GETTING-STARTED.md)
|
|
209
|
-
- [
|
|
210
|
-
- [Development](docs/DEVELOPMENT.md)
|
|
198
|
+
- [Runtime usage and verification](docs/runtimes/README.md)
|
|
211
199
|
- [Testing](docs/TESTING.md)
|
|
200
|
+
- [Architecture](docs/ARCHITECTURE.md)
|
|
212
201
|
- [Configuration](docs/CONFIGURATION.md)
|
|
202
|
+
- [Development](docs/DEVELOPMENT.md)
|
|
213
203
|
- [Deployment and CI](docs/DEPLOYMENT.md)
|
|
214
204
|
- [Migration](docs/MIGRATION.md)
|
|
215
205
|
- [Releasing](docs/RELEASING.md)
|
|
216
|
-
- [Product
|
|
217
|
-
- [Runtime
|
|
218
|
-
|
|
219
|
-
## Planning workflow
|
|
220
|
-
|
|
221
|
-
GSD planning and milestone evidence live under `.planning/`:
|
|
222
|
-
|
|
223
|
-
- [Project definition](.planning/PROJECT.md)
|
|
224
|
-
- [Requirements](.planning/REQUIREMENTS.md)
|
|
225
|
-
- [Roadmap](.planning/ROADMAP.md)
|
|
226
|
-
- [Current state](.planning/STATE.md)
|
|
227
|
-
- [Codebase map](.planning/codebase/)
|
|
206
|
+
- [Product requirements](docs/prd/product.md)
|
|
207
|
+
- [Runtime primitive matrix](docs/prd/runtime-primitive-matrix.md)
|
|
208
|
+
- [Current project state](.planning/STATE.md)
|
|
228
209
|
|
|
229
|
-
|
|
210
|
+
## Current status
|
|
230
211
|
|
|
231
|
-
|
|
212
|
+
The v1.0 milestone remains in progress. The repository generates and statically validates the complete role/runtime matrix, but authoritative client execution is not complete for every runtime and primitive. Runtime guides state the current profile outcome explicitly rather than treating package generation as proof of support.
|