jorgex-stack 1.0.14 → 1.0.16
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 +42 -0
- package/dist/cli.js +512 -195
- package/package.json +1 -1
- package/stack/modes/programmatic/AGENTS.addendum.md +12 -0
- package/stack/modes/programmatic/agent-delegation.addendum.md +8 -0
- package/stack/modes/programmatic/final-output.schema.json +43 -0
- package/stack/modes/programmatic/orchestrator.addendum.md +15 -0
- package/stack/modes/programmatic/subagent.addendum.md +12 -0
- package/stack/plugins/opencode/engram.ts +54 -27
package/README.md
CHANGED
|
@@ -24,6 +24,48 @@ For development from a clone, run the same commands through `pnpm cli <command>`
|
|
|
24
24
|
|
|
25
25
|
Every command supports `--dry-run`, `--yes`, and `--target-dir <dir>` for testing without touching the real config. Writes create automatic backups and verify idempotency; merges into user config are surgical (marked markdown sections, JSON/TOML upserts), so user-owned content is never touched.
|
|
26
26
|
|
|
27
|
+
### Modes: Human and Programmatic
|
|
28
|
+
|
|
29
|
+
`install` and `sync` accept two mutually-exclusive installation modes. The choice is global (not per runtime) and is saved in `~/.jorgex-stack/install-mode.json` on first run; subsequent `sync` calls reuse it. Re-run `install` with `--mode` to switch.
|
|
30
|
+
|
|
31
|
+
| Mode | Audience | Final assistant response | Subagents |
|
|
32
|
+
|------|----------|--------------------------|-----------|
|
|
33
|
+
| `human` (default) | interactive users, TUI | natural language, in the user's language | today's behavior (parallel where safe) |
|
|
34
|
+
| `programmatic` | external orchestrators, CI, scripts, other agents | **strict JSON**, English | serial by default, parallel opt-in |
|
|
35
|
+
|
|
36
|
+
`human` is the recommended mode for humans. `programmatic` exists for agent/script consumers and low-resource headless machines; it is not a "better" mode for humans.
|
|
37
|
+
|
|
38
|
+
Flags:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
--mode human|programmatic
|
|
42
|
+
--subagent-concurrency serial|parallel # only valid with --mode programmatic
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- Non-interactive / agent install:
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
pnpm dlx jorgex-stack install --mode programmatic --subagent-concurrency serial --yes
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
This installs into all detected runtimes. To be explicit, add `--agents opencode,claude-code,codex` or a comma-separated subset. Always pass `--mode programmatic`; without `--mode`, `--yes` and non-TTY installs default to `human`.
|
|
52
|
+
|
|
53
|
+
- `--mode human` cannot be combined with `--subagent-concurrency`.
|
|
54
|
+
- Without `--mode`, the first run asks interactively; `--yes`, non-TTY, and `--target-dir` default to `human`.
|
|
55
|
+
- `pnpm dlx jorgex-stack sync` reuses the saved mode; pass `--mode` to change and save the preference.
|
|
56
|
+
|
|
57
|
+
Programmatic mode guarantees:
|
|
58
|
+
|
|
59
|
+
- The final assistant response is **exactly one strict JSON object**, no Markdown fences or prose around it. Schema in `stack/modes/programmatic/final-output.schema.json` — required keys: `status`, `decision`, `confidence` (0..1), `summary`, `risks[]`, `next_steps[]`, `delegations[]`; `status` is `done|partial|blocked` and each `delegations[]` item uses `agent: work — paths — inputs`.
|
|
60
|
+
- English only, compact and direct.
|
|
61
|
+
- Subagents default to **serial** delegation (one at a time, no parallel). Pass `--subagent-concurrency parallel` to allow it.
|
|
62
|
+
|
|
63
|
+
Programmatic mode does **not** provide:
|
|
64
|
+
|
|
65
|
+
- An opt-out from Engram (Engram is always part of the install).
|
|
66
|
+
- Any special stdout streaming guarantee — the runtime's normal output rules apply.
|
|
67
|
+
- Telemetry, JSONL streams, or runtime token-budget enforcement.
|
|
68
|
+
|
|
27
69
|
### Update: Interactive Flow
|
|
28
70
|
|
|
29
71
|
`update` manages two sources for the end user, plus a maintainer-only one:
|