@yanauto/broco 0.0.0-stage → 1.0.0
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/CHANGELOG.md +209 -0
- package/LICENSE +202 -0
- package/README.md +188 -2
- package/README.zh-CN.md +187 -0
- package/assets/broco-board-icon-128.png +0 -0
- package/assets/broco-favicon-192.png +0 -0
- package/assets/broco-favicon-32.png +0 -0
- package/assets/broco-favicon-64.png +0 -0
- package/assets/broco-foreman-256.png +0 -0
- package/assets/broco-hero-1024.png +0 -0
- package/assets/broco-icon-512.png +0 -0
- package/assets/broco-readme-logo-dark.png +0 -0
- package/assets/broco-readme-logo-light.png +0 -0
- package/assets/broco-social-preview-1280x640.png +0 -0
- package/assets/favicon.ico +0 -0
- package/bin/broco +1077 -0
- package/bundle/board/assets/index-Bue0HpFh.css +1 -0
- package/bundle/board/assets/index-DTqMQtD9.js +16 -0
- package/bundle/board/broco-board-icon-128.png +0 -0
- package/bundle/board/broco-favicon-32.png +0 -0
- package/bundle/board/broco-favicon-64.png +0 -0
- package/bundle/board/broco-foreman-256.png +0 -0
- package/bundle/board/favicon.ico +0 -0
- package/bundle/board/fonts/instrument-sans-latin.woff2 +0 -0
- package/bundle/board/fonts/jetbrains-mono-latin.woff2 +0 -0
- package/bundle/board/index.html +18 -0
- package/lib/attachments.mjs +104 -0
- package/lib/claude-md.mjs +132 -0
- package/lib/cli-args.mjs +292 -0
- package/lib/cli-process.mjs +75 -0
- package/lib/client.mjs +198 -0
- package/lib/credential-proxy.mjs +165 -0
- package/lib/credential-source.mjs +23 -0
- package/lib/crew.mjs +947 -0
- package/lib/detect.mjs +279 -0
- package/lib/directories.mjs +32 -0
- package/lib/map.mjs +336 -0
- package/lib/model-catalog.json +864 -0
- package/lib/model-catalog.mjs +138 -0
- package/lib/model-env.mjs +11 -0
- package/lib/native.mjs +228 -0
- package/lib/paths.mjs +63 -0
- package/lib/pi-profile.mjs +29 -0
- package/lib/pi-secrets.mjs +48 -0
- package/lib/pi.mjs +232 -0
- package/lib/platform/index.mjs +13 -0
- package/lib/platform/launchd.mjs +138 -0
- package/lib/platform/linux.mjs +168 -0
- package/lib/platform/macos.mjs +29 -0
- package/lib/platform/processes.mjs +102 -0
- package/lib/problems.mjs +50 -0
- package/lib/projects.mjs +530 -0
- package/lib/quota.mjs +132 -0
- package/lib/roster-output.mjs +136 -0
- package/lib/roster.mjs +913 -0
- package/lib/runner.mjs +403 -0
- package/lib/settings-audit.mjs +104 -0
- package/lib/setup.mjs +416 -0
- package/lib/slots.mjs +177 -0
- package/lib/stats.mjs +92 -0
- package/lib/store.mjs +737 -0
- package/lib/stream-workers.mjs +464 -0
- package/lib/templates.mjs +173 -0
- package/lib/time.mjs +25 -0
- package/lib/web.mjs +260 -0
- package/lib/worker-policy.mjs +17 -0
- package/lib/worktree.mjs +269 -0
- package/package.json +50 -4
- package/scripts/package-board.mjs +53 -0
- package/skills/broco/SKILL.md +59 -0
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: broco
|
|
3
|
+
description: On-demand crew skill for any coding agent host (Claude Code, Codex, Cursor, Antigravity, OpenCode, Pi). Summon other logged-in AI CLIs via broco when your own quota is tight, you want an independent cross-vendor worktree review, you need a modality you lack (image/audio/video/PDF), or you need sharded map batch jobs. Works zero-init (L0) in any directory once global workers are allowed.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Use the installed launcher {{launcher}} for every command. This skill works across any Agent Skills host (Claude Code, Codex, Cursor, Antigravity, OpenCode, Pi).
|
|
7
|
+
|
|
8
|
+
## When to summon broco (On-Demand Crew)
|
|
9
|
+
|
|
10
|
+
Default to doing quick work yourself or using your host's built-in subagents:
|
|
11
|
+
- **Do it yourself / host subagent**: 5-minute fixes, small single-file edits, straightforward debugging, or same-vendor quick questions.
|
|
12
|
+
- **Summon `broco` on demand** when one of these applies:
|
|
13
|
+
1. **Tight quota / rate limits**: Your primary model's budget is running low — check `{{launcher}} roster --json` and hand off heavy work to a CLI with plenty of quota left.
|
|
14
|
+
2. **Cross-vendor blind review & isolated edits**: Run `{{launcher}} say NAME ... --worktree` and `{{launcher}} review NAME` (omit `--by` to auto-pick a different vendor) so another model reviews the diff with fresh eyes.
|
|
15
|
+
3. **Missing input modalities**: Need to inspect images, audio, video, or PDFs that your current host cannot read — check `capabilities.input` for `true` and pass `--attach PATH`.
|
|
16
|
+
4. **Sharded batch work (`map`)**: Fan out one brief across N files or items with FIFO concurrency, per-shard retry, and batch acceptance.
|
|
17
|
+
|
|
18
|
+
## L0 Zero-Init vs L1 Project Isolation
|
|
19
|
+
|
|
20
|
+
- **L0 zero-init (default)**: Once global workers are allowed (`{{launcher}} setup` or `{{launcher}} allow <ids> --global`), `roster`, `say`, `review`, `map`, `ls`, `show`, `wait`, `diff`, `done`, `clean`, `stats`, `status`, `retry`, and `stop` work directly in any directory. `broco` resolves `canonical(gitRoot || cwd)` internally in `~/.broco/` and inherits global allowlist, default worker, and concurrency **without** creating `.broco/` or editing `AGENTS.md` / `CLAUDE.md`.
|
|
21
|
+
- **L1 project isolation (`init`)**: Run `{{launcher}} init [--allow ...] [--default-worker ...] [--concurrency N] [--host auto|agents|claude|codex|cursor|agy|opencode|pi] [--manager-mode] [--no-agents-md]` when a repository (such as a private workspace) needs strict project-level allowlist, concurrency, or rules that override global settings. By default `init` writes lightweight on-demand crew guidance to `AGENTS.md` (or updates an existing `CLAUDE.md` when `AGENTS.md` does not exist, or when `--host claude` is passed); pass `--manager-mode` for heavy manager-only guidance. `{{launcher}} uninit` removes `.broco` and strips the marked block.
|
|
22
|
+
|
|
23
|
+
## Recursion Guard (No Nested Worker Fan-Out)
|
|
24
|
+
|
|
25
|
+
Worker sessions run with `BROCO_IN_WORKER=1`. Inside a worker session, `say`, `review`, `map`, and `retry` are **rejected by default** to prevent recursive dispatch loops. Complete your assigned task and report back to your caller instead; only pass `--allow-nested` when explicitly authorized to orchestrate sub-workers.
|
|
26
|
+
|
|
27
|
+
## Workflow
|
|
28
|
+
|
|
29
|
+
Quote names, short prompts, and option values as separate arguments. For multi-line, backtick-heavy, or `$VAR`-containing prompts, pass `--file /path/to/prompt.md` or read stdin via `-` (`{{launcher}} say NAME - --bg --json <<'EOF' ... EOF`). To work in another directory while keeping the current project's policy, pass `say --cwd DIR` on a new name (`~/` expands automatically; conflicts with `--worktree`). From outside a directory, pass `--project PATH`.
|
|
30
|
+
|
|
31
|
+
1. **Inspect health, roster & live quota**:
|
|
32
|
+
- `{{launcher}} status [--all] --json` checks runner health, uptime, web URL, active proxies, active/queued tickets, batches, and cleanable worktrees without auto-starting an offline runner.
|
|
33
|
+
- `{{launcher}} roster --json` (pass `--global` to inspect global defaults, `--refresh` only when CLI logins/models just changed; otherwise allowed CLIs share a 45s cache). Disallowed workers return only `id`/`allowed: false`; top-level `warnings` explains sign-in/install commands for allowed workers that are missing or signed out.
|
|
34
|
+
- Check `capabilities.input` (`image`, `audio`, `video`, `pdf`) and require `true` before `--attach`. Read `quota` (`avoid`, `plentiful`, `tightGroups`) and `recentProblem`: switch worker when `avoid` is true or `recentProblem` is present; raise concurrency via `{{launcher}} set concurrency N` when `plentiful` is true and you have parallel work. A model's own `record` (3+ non-blocked tasks) outranks catalog grades.
|
|
35
|
+
2. **Dispatch single tasks**:
|
|
36
|
+
- `{{launcher}} say research "the task" --worker WORKER --model MODEL --effort LEVEL --bg --json` (or `--file PATH` / stdin `-`). Prompts never appear in worker `ps` arguments.
|
|
37
|
+
- Add `--worktree` on the first `say` for isolated parallel code edits from committed `HEAD`. Attach verified media with repeated `--attach PATH`. Reuse a name to continue its native session, or pick a new name for parallel work.
|
|
38
|
+
3. **Fan out bulk / sharded work (`map`)**:
|
|
39
|
+
- `{{launcher}} map PREFIX --brief-file brief.md --inputs shard-*.jsonl --worker WORKER --model MODEL --effort LEVEL --bg --json` (supports `--brief`, `--brief-file -`, `--input`, `--inputs`, `--inputs-file PATH|-`, and `{input}`, `{index}`, `{count}`, `{name}` placeholders).
|
|
40
|
+
- Wait for all shards with `{{launcher}} wait PREFIX --json`, inspect with `{{launcher}} show PREFIX [--status error|review] [--full] --json`, retry failed/stopped shards via `{{launcher}} retry PREFIX [--worker ID] [--model ID] --bg --json`, and close ready shards with `{{launcher}} done PREFIX --result pass --why "one line"`.
|
|
41
|
+
4. **Wait, inspect, review & clean**:
|
|
42
|
+
- Wait asynchronously using your host's background shell execution (e.g. `run_in_background: true`) with `{{launcher}} wait NAME [TURN] --json`. Event-driven `/wait` wakes immediately on completion and returns `reply`, `task`, `cwd`, `worktree`, `branch`, `changedFiles`, `contextWarning`, `quota`, and `problem`.
|
|
43
|
+
- Read receipts (`queue`, `note`, `rules`, `reminders`, `contextWarning`, `sessionWarning`). If an initial turn failed before binding a native session, use `{{launcher}} retry NAME [--model ID] [--effort LEVEL] [--worker ID] --bg --json` to replay the stored prompt and snapshotted attachments cleanly.
|
|
44
|
+
- Keep context lean: `{{launcher}} ls --active --json`, `{{launcher}} show NAME --compact --json` (or `--turn N`), `{{launcher}} diff NAME [--stat] [--json]`.
|
|
45
|
+
- Cross-vendor review: `{{launcher}} review NAME [--by OTHER_WORKER] [--model MODEL] [--bg] [--json]` — omitting `--by` automatically selects an allowed worker from a different vendor. Accept writer and reviewer separately with `done`, then remove retained worktrees with `{{launcher}} clean [NAME|PREFIX] [--delete-branch] [--dry-run] --json`.
|
|
46
|
+
- Handle `problem.class`: `quota` or `region` -> switch worker and close with `--result blocked`; `policy` -> rephrase; `network` -> `{{launcher}} retry NAME`; `auth` -> ask user to sign in; `context` -> hand off with `{{launcher}} say NEW_NAME "next task..." --from OLD_NAME --worker WORKER --bg --json`. Never record infrastructure blocks as `fail`.
|
|
47
|
+
5. **Direct configuration & audit**:
|
|
48
|
+
- Settings apply immediately, log an audit entry, and print a one-command undo (all accept `--global` or `--project PATH`, plus `--json`):
|
|
49
|
+
- `{{launcher}} set concurrency <1..64|inherit>` / `{{launcher}} set default-worker <worker>`
|
|
50
|
+
- `{{launcher}} defaults <worker> [--model ID] [--effort LEVEL] [--clear]`
|
|
51
|
+
- `{{launcher}} note <worker> "concise operational note"` (or `--clear`)
|
|
52
|
+
- `{{launcher}} allow <w1,w2> [--default-worker w]` / `{{launcher}} deny <w1,w2>` (only change allowlists when aligned with the user's instructions)
|
|
53
|
+
- `{{launcher}} rules [--add "rule"] [--rm "rule"] [--clear] [--worker ID] [--override]`
|
|
54
|
+
- `{{launcher}} hide <worker> <m1,m2>` / `{{launcher}} unhide <worker> <m1,m2>`
|
|
55
|
+
- `{{launcher}} audit [--global|--all] [--limit N]` / `{{launcher}} undo [ID]`
|
|
56
|
+
|
|
57
|
+
## Task Boundaries and Results
|
|
58
|
+
|
|
59
|
+
A name is a persistent worker session, not the unit of the performance record. Its first `say` starts task 1; each task spans consecutive turns (`tasks` in `show`). Use ordinary `say NAME` or `retry NAME` for clarifications and revisions toward the same acceptance criteria. After recording an outcome for the current task, pass `--new-task --title "short title"` when starting independent work on the same session. Record outcomes with `{{launcher}} done NAME --result pass|rework|fail|blocked --why "reason"` (`--task N` amends an earlier task; explicit `--result` also closes interrupted `error`/`stopped` tickets after inspection, while bare `done` requires `review` status). Check cross-project or per-project records anytime with `{{launcher}} stats [--project PATH] --json`.
|