jonah-fleet 1.1.0 → 1.4.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.
Files changed (64) hide show
  1. package/CHANGELOG.md +115 -0
  2. package/README.md +49 -6
  3. package/dist/commands/contribute.d.ts +29 -0
  4. package/dist/commands/contribute.d.ts.map +1 -0
  5. package/dist/commands/daemon.d.ts +8 -0
  6. package/dist/commands/daemon.d.ts.map +1 -0
  7. package/dist/commands/init.d.ts +13 -0
  8. package/dist/commands/init.d.ts.map +1 -0
  9. package/dist/commands/monitor.d.ts +16 -0
  10. package/dist/commands/monitor.d.ts.map +1 -0
  11. package/dist/commands/run.d.ts +11 -0
  12. package/dist/commands/run.d.ts.map +1 -0
  13. package/dist/commands/status.d.ts +9 -0
  14. package/dist/commands/status.d.ts.map +1 -0
  15. package/dist/commands/sync.d.ts +7 -0
  16. package/dist/commands/sync.d.ts.map +1 -0
  17. package/dist/commands/telemetry.d.ts +14 -0
  18. package/dist/commands/telemetry.d.ts.map +1 -0
  19. package/dist/index.d.ts +2 -2
  20. package/dist/index.d.ts.map +1 -0
  21. package/dist/index.js +1986 -211
  22. package/dist/lib/daemon.d.ts +34 -0
  23. package/dist/lib/daemon.d.ts.map +1 -0
  24. package/dist/lib/dashboard.d.ts +10 -0
  25. package/dist/lib/dashboard.d.ts.map +1 -0
  26. package/dist/lib/detector.d.ts +25 -0
  27. package/dist/lib/detector.d.ts.map +1 -0
  28. package/dist/lib/diff.d.ts +10 -0
  29. package/dist/lib/diff.d.ts.map +1 -0
  30. package/dist/lib/evals.d.ts +72 -0
  31. package/dist/lib/evals.d.ts.map +1 -0
  32. package/dist/lib/fleet-query.d.ts +102 -0
  33. package/dist/lib/fleet-query.d.ts.map +1 -0
  34. package/dist/lib/global-config.d.ts +10 -0
  35. package/dist/lib/global-config.d.ts.map +1 -0
  36. package/dist/lib/installer.d.ts +27 -0
  37. package/dist/lib/installer.d.ts.map +1 -0
  38. package/dist/lib/manifest.d.ts +6 -0
  39. package/dist/lib/manifest.d.ts.map +1 -0
  40. package/dist/lib/presets.d.ts +52 -0
  41. package/dist/lib/presets.d.ts.map +1 -0
  42. package/dist/lib/runner.d.ts +40 -0
  43. package/dist/lib/runner.d.ts.map +1 -0
  44. package/dist/lib/telemetry.d.ts +90 -0
  45. package/dist/lib/telemetry.d.ts.map +1 -0
  46. package/dist/lib/worktree.d.ts +34 -0
  47. package/dist/lib/worktree.d.ts.map +1 -0
  48. package/package.json +17 -5
  49. package/schema.json +44 -1
  50. package/templates/docs/AGENTS.template.md +15 -0
  51. package/templates/prompts/ORCHESTRATION.md +107 -7
  52. package/templates/prompts/analytics-review.md +91 -0
  53. package/templates/prompts/autowork.md +15 -4
  54. package/templates/prompts/issues-housekeeping.md +2 -1
  55. package/templates/prompts/optimizer.md +46 -8
  56. package/templates/prompts/peer-review.md +35 -11
  57. package/templates/prompts/product-planning.md +18 -7
  58. package/templates/skills/diagnosing-bugs/SKILL.md +9 -0
  59. package/templates/workflows/autowork-cron.yml +19 -1
  60. package/templates/workflows/prompt-optimizer-cron.yml +22 -0
  61. package/templates/workflows/trigger-autowork-manual.yml +169 -0
  62. package/templates/workflows/trigger-autowork-on-bug.yml +5 -5
  63. package/templates/workflows/trigger-autowork-on-merge.yml +3 -3
  64. package/templates/workflows/trigger-review-routine.yml +107 -11
package/CHANGELOG.md CHANGED
@@ -5,8 +5,123 @@ All notable changes to `jonah-fleet` will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.4.0] - 2026-09-03
9
+
10
+ ### Added
11
+ - Priority-Driven Dual Agent Execution (Local + GitHub Actions):
12
+ - Added CLI `jonah-fleet run <routine>` command to execute prompt routines locally with automatic Git worktree isolation (`.jonah-fleet/worktrees/`), protecting active working copies and uncommitted editor files.
13
+ - Added CLI `jonah-fleet daemon [start|stop|status]` background worker to continuously poll open issues and PRs for local execution.
14
+ - Added `dualExecution` configuration schema in `agents-manifest.json` and `schema.json` supporting configurable `cloudPriorities` (default: `['P0', 'P1']`) and `cloudCatchupHours` (default: `48`).
15
+ - Added PR priority label mirroring in `autowork.md` to automatically mirror `priority/PX` labels onto opened PRs.
16
+ - Added dual routing and 48-hour cloud catchup logic in `autowork.md`, `peer-review.md`, and `trigger-review-routine.yml`.
17
+ - Added Git worktree isolation manager (`src/lib/worktree.ts`) and local routine runner (`src/lib/runner.ts`).
18
+ - Design System & Telemetry Friction Guardrails in Core Routines:
19
+ - Added Design System & Viewport Density Pass to `peer-review.md` (`templates/prompts/peer-review.md` & `.github/prompts/peer-review.md`) enforcing Token Purity, WCAG AA 4.5:1 contrast ratios, single primary CTA hierarchy, and mobile viewport budget checks on UI diffs (#49).
20
+ - Added Design System & Viewport Pre-flight to `autowork.md` (`templates/prompts/autowork.md` & `.github/prompts/autowork.md`) in Pre-ready self-audit (#49).
21
+ - Added UI Friction & Nudge Fatigue Guardrail to `analytics-review.md` (`templates/prompts/analytics-review.md` & `.github/prompts/analytics-review.md`) to aggregate component-level `$rageclick` events and flag low-conversion promotional elements (500+ impressions, CTR < 2.0%) (#49).
22
+ - Documented Design System & UI Guardrails in `templates/docs/AGENTS.template.md` and `AGENTS.md` (#49).
23
+ - Custom Cron Schedules & Sync Preservation: Added `schedules` configuration support in `agents-manifest.json` and `schema.json` for routines (`autowork`, `peer-review`, `optimizer`, `issues-housekeeping`, `dependency-update-security-check`, `analytics-review`, `sync-fleet`). Enhanced `installFleet()` and `checkDrift()` to dynamically inject configured schedules, preserve existing local workflow cron triggers, and prevent false-positive drift on synchronizations (#47).
24
+ - Analytics Review Routine (`templates/prompts/analytics-review.md` & `.github/prompts/analytics-review.md`): Evaluates active and scheduled measurement trackers against product metrics, user adoption, and conversion funnels. Requires mandatory structured action directives (`RECOMMENDATION: [PIVOT | DEPRECATE | ITERATE]`) upon measurement closure to bridge outcomes directly into product planning (#28).
25
+ - Feature Pruning & Deprecation Audit in Product Planning (`templates/prompts/product-planning.md` & `.github/prompts/product-planning.md`): Audits shipped features and closed measurement tracker verdicts in Propose mode for low-ROI / high-maintenance features (<2% adoption, >50% failure rate) and drafts deprecation / simplification proposals (#28).
26
+ - Intent vs. Defect Guardrail & Telemetry Rabbit Hole Prevention in Autowork and Diagnosing Bugs (`templates/prompts/autowork.md`, `.github/prompts/autowork.md`, `templates/skills/diagnosing-bugs/SKILL.md`, `.agents/skills/diagnosing-bugs/SKILL.md`): Prevents agents from wasting cycles writing elaborate fallback telemetry or defensive error handling when low adoption stems from lack of user intent rather than software defects, routing issues to `needs-design`/`roadmap/*` (#28).
27
+ - Post-Measurement Product Bridge & Intent vs. Defect Guardrail Architecture in `ORCHESTRATION.md` (#28).
28
+ - Registered `analytics-review` in `schema.json`, `src/lib/presets.ts`, `src/lib/manifest.ts`, and `full` preset bundle (#28).
29
+
30
+ ### Performance
31
+ - GitHub Actions Quota Optimization:
32
+ - Added zero-open-PR preflight check to `trigger-review-routine.yml` scheduled sweeps to skip Node setup, Antigravity CLI installation, and agent runs when no PRs are pending review, cutting empty sweep runner time from ~4m to ~3s (#51, #52).
33
+ - Fixed `trigger-autowork-on-bug.yml` issue event trigger condition to strictly require both `bug` and priority labels (`priority/P1` or `priority/P0`), preventing arbitrary label modifications from spawning unnecessary runners (#51, #52).
34
+ - Tightened job and step timeouts across routine trigger workflows (`trigger-review-routine.yml`, `trigger-autowork-on-bug.yml`, `trigger-autowork-on-merge.yml`) to 30m–35m to prevent runaway billing on stuck runners (#51, #52).
35
+
36
+ ### Changed
37
+ - Upgraded development dependency `@types/node` from `22.20.1` to `^26.4.0` (#41).
38
+ - Upgraded development dependency `typescript` from `5.9.3` to `^7.0.2`, configured `"types": ["node"]` in `tsconfig.json`, and configured `tsc` declaration emit (#40).
39
+ - Upgraded production dependency `commander` from `12.1.0` to `^15.0.0` (#39).
40
+
41
+ ### Fixed
42
+ - Resolved Critical (GHSA-5xrq-8626-4rwp), High (GHSA-fx2h-pf6j-xcff), and Moderate security vulnerabilities in `vitest` and transitive dependencies (`vite`, `esbuild`, `vite-node`, `@vitest/mocker`) by upgrading `vitest` to `^4.1.11` and overriding `esbuild` to `^0.28.2` (#38).
43
+
44
+ ## [1.3.0](https://github.com/juliendurandeu/jonah-fleet/compare/jonah-fleet-v1.2.0...jonah-fleet-v1.3.0) (2026-08-31)
45
+
46
+
47
+ ### Features
48
+
49
+ * **cli:** add multi-repo fleet monitoring command (jonah-fleet monitor) ([#6](https://github.com/juliendurandeu/jonah-fleet/issues/6)) ([0093c0f](https://github.com/juliendurandeu/jonah-fleet/commit/0093c0f2bdeb0d48d952119b96e541be73c59a03))
50
+ * **cli:** add per-agent token breakdown to jonah-fleet status and monitor commands ([#16](https://github.com/juliendurandeu/jonah-fleet/issues/16)) ([7e51d0c](https://github.com/juliendurandeu/jonah-fleet/commit/7e51d0cb6bdf8fef127cac7f13f8320821cb4391))
51
+ * **evals:** add automated test suite for bi-directional optimization bridge and downstream sync ([#23](https://github.com/juliendurandeu/jonah-fleet/issues/23)) ([2e55227](https://github.com/juliendurandeu/jonah-fleet/commit/2e552273600c22879d81b6ad607ad912809d3dbb))
52
+ * **fleet-query:** extend fleet query engine with per-routine token and iteration aggregation ([#15](https://github.com/juliendurandeu/jonah-fleet/issues/15)) ([cabbbbc](https://github.com/juliendurandeu/jonah-fleet/commit/cabbbbcc62d8fe39ea135f56acdba0343aa11e02))
53
+ * **fleet:** initial release of jonah-fleet standalone agent suite and CLI ([1b08b3e](https://github.com/juliendurandeu/jonah-fleet/commit/1b08b3e14626cda25e76464d92782f16cfaae936))
54
+ * **optimizer:** implement token anomaly heuristics and automated PR triggers ([#10](https://github.com/juliendurandeu/jonah-fleet/issues/10)) ([#17](https://github.com/juliendurandeu/jonah-fleet/issues/17)) ([3090785](https://github.com/juliendurandeu/jonah-fleet/commit/30907857f7e24edaee1d2c2dbca61568d95f7767))
55
+ * **optimizer:** update optimizer routine with per-agent token aggregation protocol and scorecard schema ([#14](https://github.com/juliendurandeu/jonah-fleet/issues/14)) ([2e435ef](https://github.com/juliendurandeu/jonah-fleet/commit/2e435ef7492bf75dbf3c081d64375f49ea542667))
56
+ * **peer-review:** add autonomous issue synthesis for unlinked PRs ([54e9a54](https://github.com/juliendurandeu/jonah-fleet/commit/54e9a54685ee89bf124923fb6086760c3753d097))
57
+ * **peer-review:** allow self-contained PR descriptions without blocking on linked issues ([97b7034](https://github.com/juliendurandeu/jonah-fleet/commit/97b703403040fc9dbe4f6b6622000822d9925aae))
58
+ * **prompts:** add feedback loop stagnation heuristic and closed-loop verification audit ([#24](https://github.com/juliendurandeu/jonah-fleet/issues/24)) ([c3ea012](https://github.com/juliendurandeu/jonah-fleet/commit/c3ea01297017347f6b3c43e4bdd99ea2704fd60e))
59
+ * **telemetry:** design and implement centralized cross-repo telemetry and token tracking hub (closes [#5](https://github.com/juliendurandeu/jonah-fleet/issues/5)) ([#22](https://github.com/juliendurandeu/jonah-fleet/issues/22)) ([e910277](https://github.com/juliendurandeu/jonah-fleet/commit/e9102779293601e94a23401a10e669bb174cb972))
60
+ * **workflows:** support manual and comment-based (re)triggering for peer review routine ([#30](https://github.com/juliendurandeu/jonah-fleet/issues/30)) ([e8be955](https://github.com/juliendurandeu/jonah-fleet/commit/e8be955f429450fdce2d79f52a27c3ee4bb41acd)), closes [#29](https://github.com/juliendurandeu/jonah-fleet/issues/29)
61
+ * **workflows:** support triggering autowork via workflow_dispatch badge link (closes [#18](https://github.com/juliendurandeu/jonah-fleet/issues/18)) ([#20](https://github.com/juliendurandeu/jonah-fleet/issues/20)) ([a44e54e](https://github.com/juliendurandeu/jonah-fleet/commit/a44e54e647db11587ab58eb0ec01201cb7e9376f))
62
+
63
+
64
+ ### Added
65
+ - Smart Tech-Stack Auto-Detection for `jonah-fleet init` (`src/lib/detector.ts`): inspects repository files to detect languages (TypeScript, JavaScript, Python, Go, Rust), frameworks (Next.js, React, Remix, Astro, Vue, Nuxt, SvelteKit, Express, Fastify, NestJS, Koa, Hono, FastAPI, Django, Flask, Gin, Echo, Chi, Fiber, Axum, Actix Web, Rocket), package managers (npm, pnpm, yarn, bun, pip, uv, poetry, pipenv, go, cargo), linters, test runners, and auto-populates tailored build, test, and type-check commands into `AGENTS.md` (#4).
66
+ - CLI flag overrides (`--stack`, `--package-manager`, `--test-cmd`, `--build-cmd`, `--interactive`, `--no-interactive`) on `jonah-fleet init` for customized initialization.
67
+ - Inward Blocker Dependency Gating in `autowork.md` (`templates/prompts/autowork.md` and `.github/prompts/autowork.md`): automatically detects and gates issues carrying `Blocked by #N` / `Depends on #N` until prerequisite issues merge, preventing premature execution of dependent tasks.
68
+ - Standard `NOTICE` attribution file formally crediting OpenAI Symphony's architectural lineage under Apache-2.0.
69
+ - Automated Upstream Symphony Radar GitHub Actions workflow (`.github/workflows/symphony-radar.yml` and `.github/scripts/fetch-symphony-radar.js`) for periodic detection and issue reporting of specification updates in `openai/symphony`.
70
+ - Explicit Acknowledgments & Credits section in `README.md`.
71
+ - Review failure notification handler and 2-hour scheduled scan sweep watchdog in `trigger-review-routine.yml` to prevent stuck PRs and recover orphaned ready PRs.
72
+ - Orphaned ready PR watchdog in `autowork.md` (Step 3c) and Scan mode unreviewed prioritization in `peer-review.md`.
73
+ - Peer Review Resilience & Orphaned PR Recovery protocol documentation in `ORCHESTRATION.md`.
74
+ - Comprehensive bi-directional optimization bridge evaluations test suite and synthetic run log fixtures (`src/lib/evals.ts`, `tests/evals.test.ts`).
75
+ - Upstream contribution CLI test suite with mock executor and dry-run support (`tests/contribute.test.ts`).
76
+ - Downstream synchronization workflow and drift scenario test suite (`tests/sync-workflow.test.ts`).
77
+ - Dedicated `evals` CI workflow job in `.github/workflows/ci.yml` and `test:evals` npm script.
78
+ - Centralized cross-repo telemetry aggregation and token tracking hub (`jonah-fleet telemetry`).
79
+ - Routine telemetry JSON schema and parser (`RoutineTelemetrySummary`) supporting failure categories, duration, iterations, cost, and tokens.
80
+ - Global 70% weekly token budget ceiling tracking (~8.75M tokens/week) with utilization percentage, daily burn rates, and health badges (`[HEALTHY]`, `[WARNING]`, `[CRITICAL]`, `[EXCEEDED]`).
81
+ - Opt-in telemetry emission step in `autowork-cron.yml`, `trigger-review-routine.yml`, and `prompt-optimizer-cron.yml`.
82
+ - `telemetry` configuration block in `schema.json` and `agents-manifest.json`.
83
+ - Dedicated `trigger-autowork-manual.yml` workflow template for targeted on-demand Autowork runs via `workflow_dispatch` and issue badge links.
84
+ - Badge link format documentation in `templates/docs/AGENTS.template.md` and repository `AGENTS.md`.
85
+ - Default GitHub Issue Templates in `.github/ISSUE_TEMPLATE/` (`feature_request.md` and `bug_report.md`) embedding the Targeted Autowork badge link.
86
+ - `trigger-autowork-manual.yml` added to `ROUTINE_TO_WORKFLOW_MAP.autowork` for automatic installation and drift detection.
87
+ - Alias support for `issue_number` in `autowork-cron.yml` `workflow_dispatch` trigger.
88
+ - Explicit `token: ${{ secrets.GH_PAT || github.token }}` parameter in `release-please.yml` ensuring automated release PRs are authored with maintainer permissions to prevent workflow approval blocks.
89
+ - Release PR branch exclusion (`release-please--*`) in `trigger-review-routine.yml` workflow triggers, guard skip step, and `peer-review.md` prompt routines.
90
+ - Unit and drift tests in `tests/workflows-validation.test.ts` and `tests/installer.test.ts`.
91
+
92
+ ## [1.2.0] - 2026-08-30
93
+
94
+ ### Added
95
+ - Manual and comment-based (re)triggering for the Peer Review routine in `trigger-review-routine.yml`: supports `workflow_dispatch` (with optional `pr_number` for Targeted mode or blank for Scan mode), PR comment commands (`/review`, `/peer-review`, `/retrigger`, `/re-review`), and `review_requested` events with anti-loop bot guards.
96
+ - Automated release pipeline powered by Google Release Please (`.github/workflows/release-please.yml`, `release-please-config.json`, `.release-please-manifest.json`), automatically analyzing Conventional Commits on `main` to create release PRs, tag SemVer versions, and publish to npm via OIDC Trusted Publishing.
97
+ - Feedback Loop Stagnation token anomaly heuristic in `optimizer.md` and `ORCHESTRATION.md`: flags when downstream processing routines report 0 intake across >= 2 consecutive runs while upstream PRs/issues close.
98
+ - Loop Discovery Mechanical Audits remediation rule in `optimizer.md`: mandates deterministic per-issue matching tables and itemized reconciliation against upstream closed work.
99
+ - Closed-loop verification check in `issues-housekeeping.md`: audits recently closed roadmap/feature issues against tracking issues for projects operating impact or verification loops.
100
+ - Autonomous Issue Synthesis in `peer-review.md` and `ORCHESTRATION.md`: peer-review routine automatically synthesizes a tracking issue on GitHub (`gh issue create`) and links `Closes #N` (`gh pr edit`) before squash-merging unlinked contributor PRs, maintaining 100% issue auditability without human contributor friction.
101
+ - Documented required GitHub Actions workflow permissions and fork approval policies in `README.md` and post-init CLI output (`src/commands/init.ts`).
102
+ - Contributor PR lenience in `peer-review.md`: allow self-contained PR descriptions to serve as the spec for external contributions rather than blocking on missing `Closes #N` tracking issues.
103
+ - Per-agent token & cost aggregation protocol and scorecard schema in `optimizer.md` (`templates/prompts/optimizer.md` and `.github/prompts/optimizer.md`).
104
+ - Token Anomaly Heuristics in `optimizer.md`: defined concrete numerical thresholds for Token Surge (>50% week-over-week), Budget Hog (>75% fleet spend), Iteration Ceiling Exhaustion (>20% at `token_limit`), and Review Loop Burn (>= 3 bounce rounds).
105
+ - Automated preventative remediation actions and triggers in `optimizer.md` for instruction pruning, early exit/skip guards, iteration ceiling tuning, and ping-pong convergence.
106
+ - Documented fleet-wide Token Anomaly Triage & Remediation workflow in `ORCHESTRATION.md`.
107
+ - Prompt validation tests verifying token anomaly heuristics, automated remediation triggers, orchestration triage, and prompt template sync.
108
+ - Per-agent token and cost consumption breakdown in `src/lib/fleet-query.ts`, `src/lib/dashboard.ts`, `src/commands/status.ts`, and `src/commands/monitor.ts`.
109
+ - `--tokens` / `--detailed` CLI options for `jonah-fleet status` and `jonah-fleet monitor` to inspect granular per-routine token usage, iteration averages, and fleet spend share.
110
+ - Extended JSON telemetry with complete `byRoutine` metadata across repositories and fleet summaries.
111
+ - Per-routine token, cost, and iteration aggregation in `src/lib/fleet-query.ts` (`RoutineTokenSpend` and `TokenSpendInfo.byRoutine`).
112
+ - Support for extracting `iterationsUsed` and `duration` in `parseLogMetadata()`.
113
+ - Extended test coverage in `tests/fleet-query.test.ts` for per-routine token stats, fleet share calculation, and parsing edge cases.
114
+
115
+ ## [1.1.1] - 2026-08-26
116
+
117
+ ### Added
118
+ - Explicit OpenAI Symphony specification lineage documentation and conceptual mapping table.
119
+ - Architectural comparison matrix contrasting Jonah Fleet's zero-daemon GitHub-native model against persistent multi-agent runtimes (SwarmClaw).
120
+ - Synchronized template orchestration docs under `templates/prompts/ORCHESTRATION.md`.
121
+
8
122
  ## [1.1.0] - 2026-08-24
9
123
 
124
+
10
125
  ### Added
11
126
  - Multi-repository fleet monitoring command (`jonah-fleet monitor` / `jonah-fleet status --fleet`).
12
127
  - Global repository registry manager (`~/.jonah-fleet/config.json`) with `--add` and `--remove` CLI flags.
package/README.md CHANGED
@@ -13,12 +13,41 @@
13
13
 
14
14
  `jonah-fleet` packages a complete suite of autonomous software engineering agents into a standalone repository and zero-install CLI (`npx jonah-fleet`). It turns any repository into an autonomous agent-driven development environment with:
15
15
 
16
- - **Symphony-aligned Orchestration**: Single-flight locking, stale-claim recovery, and reader/writer separation.
16
+ - **Symphony-aligned Orchestration**: Built on the principles formalized by OpenAI's [Symphony spec](https://github.com/openai/symphony/blob/main/SPEC.md) — single-flight locking, dead-run claim recovery, reader/writer separation, and warm-session review loops.
17
17
  - **Autonomous Autowork**: Issue claiming, test-driven implementation (`/tdd`), automated draft PR creation, and warm-session review synchronization.
18
18
  - **Strict Peer Review**: Multi-angle subagent code reviews (`/code-review`), security scanning, and automated squash-merge.
19
19
  - **Issues Housekeeping & Dependency Security**: Weekly automated sweeps for duplicate detection, triage label assignment, and vulnerability remediation.
20
20
  - **Continuous Bi-Directional Improvement Bridge**: When local `optimizer.md` routines discover generic prompt optimizations, fixes can be submitted directly back upstream to `jonah-fleet` and distributed to all projects.
21
21
 
22
+ ---
23
+
24
+ ## 🏛️ Architecture: The Symphony Lineage
25
+
26
+ Jonah Fleet is a **GitHub-native implementation of OpenAI's [Symphony specification](https://github.com/openai/symphony/blob/main/SPEC.md)** for orchestrating autonomous coding agents against issue trackers.
27
+
28
+ Rather than requiring a persistent orchestrator daemon or complex server infrastructure, Jonah Fleet maps all Symphony primitives directly onto GitHub and ephemeral CLI agent sessions:
29
+
30
+ | Symphony Concept | Jonah Fleet Implementation |
31
+ |---|---|
32
+ | **`WORKFLOW.md`** (Repo config & prompt templates) | `AGENTS.md` (aliased as `GEMINI.md`/`CLAUDE.md`) + `.github/prompts/*.md` |
33
+ | **Orchestrator** (Poll, dispatch, reconcile) | GitHub Actions event triggers + scheduled cron routines (zero persistent daemons) |
34
+ | **Issue Tracker** | GitHub Issues with single-flight claim protocols (`🔒` claim comments) |
35
+ | **Agent Runner** | Ephemeral agent sessions (**Antigravity CLI `agy`** via Gemini 3.7 Flash) in fresh clones |
36
+ | **Reader/Writer Separation** | Autowork authors PRs; Peer Review routine is sole merge authority for product PRs |
37
+ | **Warm-Context Synchronization** | In-session polling & live fix loops between Autowork and Peer Review before merge |
38
+ | **Dead-Run Recovery** | Stale claim detection (>6h without live PR) via autowork & issues-housekeeping sweeps |
39
+
40
+ ### Architectural Comparison: Jonah Fleet vs. SwarmClaw
41
+
42
+ | Dimension | ⚓ Jonah Fleet | 🦞 SwarmClaw (`@swarmclawai/swarmclaw`) |
43
+ |---|---|---|
44
+ | **Paradigm** | **Symphony-aligned, issue-driven workflow automation** | **Self-hosted multi-agent runtime & swarm platform** |
45
+ | **Runtime Model** | Ephemeral CLI sessions (`agy`) spun up per issue/PR | Persistent daemon / Electron desktop app / server |
46
+ | **State & Coordination** | GitHub Issues, PR labels, commit status checks, and run logs | Local SQLite / Postgres, live WebSockets, durable agent memory |
47
+ | **Agent Topology** | Specialized asynchronous routines (Autowork, Peer Review, Housekeeping, Optimizer) | Interactive agent teams, live org charts, and hierarchical delegation |
48
+ | **Best For** | Production software engineering pipelines & automated multi-repo maintenance | Interactive agent chat, local tool runtimes, multi-provider desktop UI |
49
+
50
+
22
51
  ---
23
52
 
24
53
  ## 🚀 Quickstart
@@ -34,9 +63,16 @@ npx jonah-fleet init --preset standard
34
63
  Available presets:
35
64
  - **`minimal`**: `autowork` + `peer-review` + `optimizer`
36
65
  - **`standard`** (default): minimal + `issues-housekeeping` + `dependency-update-security-check`
37
- - **`full`**: standard + `product-planning`
66
+ - **`full`**: standard + `product-planning` + `analytics-review`
67
+
68
+ ### 2. Configure GitHub Actions Permissions
69
+
70
+ To ensure agent workflows can create and merge PRs and run without getting stuck awaiting approval:
71
+
72
+ 1. **Workflow permissions**: Go to **Settings** → **Actions** → **General** → **Workflow permissions**, choose **"Read and write permissions"**, and check **"Allow GitHub Actions to create and approve pull requests"**.
73
+ 2. **Fork pull request workflows**: Under **Actions** → **General** → **Fork pull request workflows**, configure the workflow approval policy (*e.g.* **"Require approval for first-time contributors"** or **"Run workflows without approval"** for private/internal repositories) to prevent automated runs from stalling awaiting manual approval.
38
74
 
39
- ### 2. Configure project context (`AGENTS.md`)
75
+ ### 3. Configure project context (`AGENTS.md`)
40
76
 
41
77
  `jonah-fleet init` generates an `AGENTS.md` file (or uses your existing one). Specify your test commands, build scripts, and architecture patterns:
42
78
 
@@ -52,7 +88,7 @@ npm run type-check
52
88
  ```
53
89
  ```
54
90
 
55
- ### 3. Check health and drift
91
+ ### 4. Check health and drift
56
92
 
57
93
  To inspect which routines and skills are active or verify alignment with latest fleet updates:
58
94
 
@@ -66,7 +102,7 @@ To synchronize with the latest fleet version:
66
102
  npx jonah-fleet sync
67
103
  ```
68
104
 
69
- ### 4. Multi-repo Fleet Monitoring
105
+ ### 5. Multi-repo Fleet Monitoring
70
106
 
71
107
  Monitor health, in-flight autowork claims, open PR review loops, and token usage across your entire fleet:
72
108
 
@@ -118,7 +154,8 @@ Each target project contains an `agents-manifest.json` at its root:
118
154
  "optimizer": true,
119
155
  "issues-housekeeping": true,
120
156
  "dependency-update-security-check": true,
121
- "product-planning": false
157
+ "product-planning": false,
158
+ "analytics-review": false
122
159
  },
123
160
  "skills": [
124
161
  "tdd",
@@ -147,6 +184,12 @@ Each target project contains an `agents-manifest.json` at its root:
147
184
 
148
185
  ---
149
186
 
187
+ ## 🙏 Acknowledgments & Credits
188
+
189
+ - **[OpenAI Symphony](https://github.com/openai/symphony)**: Jonah Fleet's orchestration architecture, single-flight claim locking, reader/writer separation, and prompt engineering protocols are inspired by OpenAI's [Symphony Specification](https://github.com/openai/symphony/blob/main/SPEC.md), licensed under [Apache-2.0](https://github.com/openai/symphony/blob/main/LICENSE). See [NOTICE](./NOTICE) for formal attribution.
190
+
191
+ ---
192
+
150
193
  ## 📄 License
151
194
 
152
195
  MIT © Julien Durand
@@ -0,0 +1,29 @@
1
+ export interface ContributeOptions {
2
+ title?: string;
3
+ body?: string;
4
+ prompt?: string;
5
+ cwd?: string;
6
+ repo?: string;
7
+ dryRun?: boolean;
8
+ executor?: (args: string[]) => Promise<string> | string;
9
+ throwOnError?: boolean;
10
+ }
11
+ export interface ContributionPayload {
12
+ repo: string;
13
+ branchName: string;
14
+ title: string;
15
+ body: string;
16
+ prompt?: string;
17
+ prCommand: string;
18
+ }
19
+ export interface ContributionResult {
20
+ success: boolean;
21
+ dryRun?: boolean;
22
+ branchName?: string;
23
+ title?: string;
24
+ prUrl?: string;
25
+ error?: string;
26
+ }
27
+ export declare function prepareContributionPayload(options?: ContributeOptions): ContributionPayload;
28
+ export declare function runContribute(options?: ContributeOptions): Promise<ContributionResult>;
29
+ //# sourceMappingURL=contribute.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"contribute.d.ts","sourceRoot":"","sources":["../../src/commands/contribute.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACxD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,iBAAsB,GAAG,mBAAmB,CAgB/F;AAED,wBAAsB,aAAa,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAwEhG"}
@@ -0,0 +1,8 @@
1
+ export interface DaemonCommandOptions {
2
+ interval?: string;
3
+ routines?: string;
4
+ model?: string;
5
+ foreground?: boolean;
6
+ }
7
+ export declare function runDaemonCommand(action?: string, options?: DaemonCommandOptions): Promise<void>;
8
+ //# sourceMappingURL=daemon.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/commands/daemon.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,wBAAsB,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgFzG"}
@@ -0,0 +1,13 @@
1
+ export interface InitOptions {
2
+ preset?: string;
3
+ force?: boolean;
4
+ cwd?: string;
5
+ stack?: string;
6
+ packageManager?: string;
7
+ testCmd?: string;
8
+ buildCmd?: string;
9
+ interactive?: boolean;
10
+ }
11
+ export declare function promptQuestion(query: string, defaultValue: string): Promise<string>;
12
+ export declare function runInit(options?: InitOptions): Promise<void>;
13
+ //# sourceMappingURL=init.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYzF;AAED,wBAAsB,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoGtE"}
@@ -0,0 +1,16 @@
1
+ import { GhExecutor } from '../lib/fleet-query.js';
2
+ export interface MonitorOptions {
3
+ repos?: string[];
4
+ json?: boolean;
5
+ watch?: boolean;
6
+ interval?: string | number;
7
+ all?: boolean;
8
+ add?: string;
9
+ remove?: string;
10
+ cwd?: string;
11
+ executor?: GhExecutor;
12
+ tokens?: boolean;
13
+ detailed?: boolean;
14
+ }
15
+ export declare function runMonitor(options?: MonitorOptions): Promise<void>;
16
+ //# sourceMappingURL=monitor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../../src/commands/monitor.ts"],"names":[],"mappings":"AAMA,OAAO,EAGL,UAAU,EAEX,MAAM,uBAAuB,CAAC;AAG/B,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAsB,UAAU,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkF5E"}
@@ -0,0 +1,11 @@
1
+ export interface RunCommandOptions {
2
+ issue?: string;
3
+ pr?: string;
4
+ model?: string;
5
+ timeout?: string;
6
+ worktree?: boolean;
7
+ keepWorktree?: boolean;
8
+ dryRun?: boolean;
9
+ }
10
+ export declare function runRoutineCommand(routine: string, options?: RunCommandOptions): Promise<void>;
11
+ //# sourceMappingURL=run.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2DvG"}
@@ -0,0 +1,9 @@
1
+ export interface StatusOptions {
2
+ cwd?: string;
3
+ fleet?: boolean;
4
+ json?: boolean;
5
+ tokens?: boolean;
6
+ detailed?: boolean;
7
+ }
8
+ export declare function runStatus(options?: StatusOptions): Promise<void>;
9
+ //# sourceMappingURL=status.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAsB,SAAS,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2I1E"}
@@ -0,0 +1,7 @@
1
+ export interface SyncOptions {
2
+ check?: boolean;
3
+ force?: boolean;
4
+ cwd?: string;
5
+ }
6
+ export declare function runSync(options?: SyncOptions): Promise<void>;
7
+ //# sourceMappingURL=sync.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CtE"}
@@ -0,0 +1,14 @@
1
+ import { GhExecutor } from '../lib/fleet-query.js';
2
+ export interface TelemetryOptions {
3
+ action?: 'emit' | 'aggregate' | 'status';
4
+ log?: string;
5
+ endpoint?: string;
6
+ repo?: string;
7
+ repos?: string[];
8
+ budget?: string | number;
9
+ json?: boolean;
10
+ cwd?: string;
11
+ executor?: GhExecutor;
12
+ }
13
+ export declare function runTelemetry(options?: TelemetryOptions): Promise<void>;
14
+ //# sourceMappingURL=telemetry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/commands/telemetry.ts"],"names":[],"mappings":"AAeA,OAAO,EAAqB,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuHhF"}
package/dist/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
-
2
- export { }
1
+ export {};
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}