Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
75 commits
Select commit Hold shift + click to select a range
a2488f4
docs: ADRs for fork divergences vs upstream
gabadi Jun 14, 2026
13fb738
docs(adr-0002): settle two-case delivery; universal re-injection; Cla…
gabadi Jun 14, 2026
6e75b82
docs(adr): capture five accepted pipeline divergences + one open item
gabadi Jun 14, 2026
21ff2e0
docs(adr-0006): decide harness-enforced holdout via sparse-checkout
gabadi Jun 14, 2026
e164241
docs(adr-0009): feature files open with a structured spec header
gabadi Jun 14, 2026
8929068
docs(adr-0010,0011): split observation harness into surface + fidelity
gabadi Jun 14, 2026
dad5f9a
docs(adr-0012): per-role model/effort/advisor in swarmforge.conf
gabadi Jun 14, 2026
5f0081d
docs(adr): recapture lost role detail; lean ADR style (divergence + w…
gabadi Jun 14, 2026
1a24b8a
docs(adr-0013,0014): curator role + .agents knowledge injection (idea V)
gabadi Jun 14, 2026
1af7118
docs(adr-0015,0016): platform-feasibility stop rule + boundary-logic …
gabadi Jun 14, 2026
75c3865
docs: fork change manifest + migration recovery docs (impl playbook)
gabadi Jun 14, 2026
1fb38b7
docs(adr-0017,0018,0019,0020,0021): document section-C script-layer d…
gabadi Jun 14, 2026
181cb4b
docs(adr-0002,0003,0010,0013): extend ADRs + CONTEXT glossary
gabadi Jun 14, 2026
fbc4c27
docs: fix cross-doc inconsistencies from code review
gabadi Jun 14, 2026
a846c5b
docs: fork divergence implementation plan — 2 PRs, one per delivery b…
gabadi Jun 14, 2026
5514154
docs(adr-0001): upstream baseline anchor + squash-divergence/merge-up…
gabadi Jun 14, 2026
11e352a
docs: ADRs for fork divergences vs upstream (#28)
gabadi Jun 14, 2026
665b6eb
docs: ADRs 0003–0021, fork-change-manifest, and implementation plan
gabadi Jun 14, 2026
20844b7
feat: fork divergences — main script + skill layer (#31)
gabadi Jun 14, 2026
336f388
Add shared engineering and workflow articles
unclebob Jun 14, 2026
e654687
Prefer Babashka APS tools by default
unclebob Jun 14, 2026
8409333
Document constitution article inheritance
unclebob Jun 14, 2026
5e21205
Rename handoff command to swarm-handoff
unclebob Jun 14, 2026
1ea174a
Keep handoff logbook in swarm state
unclebob Jun 14, 2026
2b3b3ba
Trim prompt logbook guidance
unclebob Jun 14, 2026
5bdc770
Require latest quality tools from GitHub
unclebob Jun 14, 2026
2c53669
Document swarm-handoff approval prefix
unclebob Jun 14, 2026
d8afe64
Protect swarm-handoff executable
unclebob Jun 14, 2026
0f11d63
refactor(harness): simplify delivery; remove executing logbook and cl…
gabadi Jun 14, 2026
da5a813
docs(readme): fix install URL to point at fork
gabadi Jun 14, 2026
f41852f
last_changes
gabadi Jun 14, 2026
60ce375
fix(swarmforge): create STATE_DIR before writing skills sentinel
gabadi Jun 15, 2026
6e78b23
fix(install_skills): install all local skills, not just agent-retro
gabadi Jun 15, 2026
dc3712f
fix(setup-swarm): drop logbook.jsonl and tmp/ from gitignore step
gabadi Jun 15, 2026
ee97af5
feat(swarmforge): persona skill load + flat handoff delivery + setup …
gabadi Jun 15, 2026
0de094f
docs(readme): add /setup-swarm step and ./swarm stop to getting started
gabadi Jun 15, 2026
86d1e7b
docs(readme): add bootstrap ./swarm step before /setup-swarm
gabadi Jun 15, 2026
1a3263f
fix(setup-swarm): derive stack list from engineering.prompt, not hard…
gabadi Jun 15, 2026
ae1791e
fix(swarm): move persona trigger from init to handoff delivery
gabadi Jun 15, 2026
3c8d9d3
fix(swarmforge): silence zsh local-redecl noise and sparse-checkout d…
gabadi Jun 15, 2026
d1936b4
fix(swarmforge): bundle articles in persona skill + exempt specifier …
gabadi Jun 15, 2026
26234eb
fix(swarm-handoff): use /swarm-persona and add startup wait before de…
gabadi Jun 15, 2026
1f4bdd4
fix(swarm-handoff): restore C-j after C-m to complete CR+LF Enter seq…
gabadi Jun 15, 2026
e3db3fa
fix(swarmforge): pass initial message to claude at launch to exit wel…
gabadi Jun 15, 2026
153a1d1
Revert "fix(swarmforge): pass initial message to claude at launch to …
gabadi Jun 15, 2026
6712fe9
fix(swarm-handoff): use tmux Enter key instead of C-m/C-j for kitty p…
gabadi Jun 15, 2026
c9fad0c
fix(handoffs): back-routes must include role-specified diagnostic fie…
gabadi Jun 15, 2026
72070c1
chore(docs): remove migration guides, manifest, and planning artifact…
gabadi Jun 15, 2026
dff992d
merge(upstream): Babashka handoff port + daemon protocol
gabadi Jun 15, 2026
bb24a15
feat(fork): apply fork divergences on top of upstream Babashka port
gabadi Jun 15, 2026
54df8a1
Merge pull request #35 from gabadi/feat/upstream-sync
gabadi Jun 15, 2026
099cadc
Merge branch 'unclebob:main' into main
gabadi Jun 16, 2026
95443d0
enter-fix
gabadi Jun 17, 2026
a38bd87
Merge remote-tracking branch 'upstream/main' into feat/upstream-bb-mi…
gabadi Jun 17, 2026
fddf730
feat(fork): migrate ADR divergences to fork.bb, port to Babashka format
gabadi Jun 17, 2026
09502f8
fork(handoffs): remove startup awake notification
gabadi Jun 17, 2026
844fd60
Merge pull request #41 from gabadi/feat/upstream-bb-migration
gabadi Jun 17, 2026
599be8d
feat(skill): add fork-upstream-sync skill
gabadi Jun 17, 2026
b267ee9
merge(upstream): sync with upstream/main — iterm2, extra-args, tmux f…
gabadi Jun 18, 2026
2a42ec8
fix(sync): take upstream extra-args as-is; only intercept advisor=X
gabadi Jun 18, 2026
adef8c2
fix(launch): make --permission-mode auto overridable via extra-args
gabadi Jun 18, 2026
a5e4102
Merge pull request #48 from gabadi/feat/upstream-sync-2026-06-18
gabadi Jun 18, 2026
5649837
fix(handoff): state-dir from roles.tsv + implement merge_and_process …
gabadi Jun 19, 2026
36f0add
fix(swarmforge): remove extra paren in grok launch-command case
gabadi Jun 19, 2026
fe71357
fix(swarmforge): handle start subcommand in -main dispatch
gabadi Jun 19, 2026
3c6b707
fix(handoffs): idle gate for notify! and reframe git_handoff routing …
gabadi Jun 21, 2026
583f3e0
feat(skills): add mattpocock/skills selective install with allowlist …
gabadi Jun 21, 2026
1b47660
fix(swarm): apply drywall execution learnings to handoff protocol (#61)
gabadi Jun 21, 2026
2514f44
fix(fork): search all mattpocock skill subdirs, not just engineering/…
gabadi Jun 21, 2026
801b486
fix(swarm): drop initial user message for claude agents on startup
gabadi Jun 21, 2026
5a81227
docs(adr): specifier gates on frontier intent, not formal spec (#64)
gabadi Jun 21, 2026
7a809d1
fix(swarm): apply drywall execution learnings to main branch (#66)
gabadi Jun 21, 2026
b4a4823
docs(plan): rewrite tool analysis as actionable plan with current status
gabadi Jun 22, 2026
9374b7a
fix(handoffd): notify only on new inbox write, not on duplicate deliv…
gabadi Jun 23, 2026
b34cc4f
feat(setup-swarm): broaden git reset allow-rule to all forms
gabadi Jun 23, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions .agents/references/hunk-agent-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Hunk Agent Guide

How agents interact with a live Hunk session for code review.

## Pre-requisites

- Hunk must be running in a terminal (e.g. `git diff ... | hunk patch -`).
- The Hunk session daemon auto-registers on startup.

## Inspect

```bash
hunk session list
git diff upstream/main...HEAD --diff-filter=M | hunk patch -
```

## Inspect

```bash
hunk session list # find live sessions
hunk session get --repo . # confirm session repo match
hunk session review --repo . --json # file/hunk structure
hunk session review --repo . --include-patch --json # include raw diff text
hunk session context --repo . # current focus
```

## Navigate

```bash
hunk session navigate --repo . --file <path> --hunk <n> # 1-based hunk
hunk session navigate --repo . --file <path> --new-line <n>
hunk session navigate --repo . --next-comment
hunk session navigate --repo . --prev-comment
```

## Reload content

```bash
hunk session reload --repo . -- diff --exclude-untracked
hunk session reload --repo . -- show HEAD~1
```

Always pass `--` before the nested Hunk command.

## Add comments

Single note:
```bash
hunk session comment add --repo . --file <path> --new-line <n> --summary "text" [--focus]
```

Batch:
```bash
printf '%s\n' '{"comments":[{"filePath":"...","newLine":N,"summary":"..."}]}' \
| hunk session comment apply --repo . --stdin [--focus]
```

## Common fixes

- **"No active session matches repoRoot"** — pass session ID explicitly instead of `--repo .`.
- **"No active Hunk sessions"** — Hunk is not running; ask the user to open it first.
57 changes: 57 additions & 0 deletions .agents/references/hunk-user-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Hunk User Guide

Quick reference for [Hunk](https://github.com/modem-dev/hunk) — the review-first terminal diff viewer used in this fork.

## Open a diff (modified files only)

```bash
git diff upstream/main...HEAD --diff-filter=M | hunk patch -
```

`--diff-filter=M` shows only **modified** tracked files, excluding new/untracked files.

## Navigation

| Key | Action |
|-----|--------|
| `↑ / ↓` | move line by line |
| `Space` or `f` | page down |
| `b` or `Shift+Space` | page up |
| `d / u` | half page down / up |
| `[ / ]` | previous / next hunk |
| `, / .` | previous / next file |
| `{ / }` | previous / next comment |
| `← / →` | scroll code horizontally (Shift = faster) |
| `Home / End` or `g / G` | jump to top / bottom |

## View

| Key | Action |
|-----|--------|
| `1 / 2 / 0` | split / stack / auto layout |
| `s` | toggle sidebar |
| `t` | toggle theme |
| `a` | toggle AI notes |
| `z` | toggle unchanged context |
| `l / w / m` | toggle line numbers / wrap / metadata |
| `e` | open file in `$EDITOR` |

## Review

| Key | Action |
|-----|--------|
| `/` | focus file filter |
| `c` | create review note |
| `Tab` | toggle files/filter focus |
| `F10` | open menus |
| `r` | reload (watch mode) |
| `q` | quit |

## Mouse

- Wheel — scroll vertically
- Shift+Wheel — scroll horizontally

## In-app help

Press `?` or `h` inside Hunk to open the full controls help modal.
63 changes: 63 additions & 0 deletions .claude/skills/fork-upstream-sync/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
name: fork-upstream-sync
description: Sync this fork with new commits from unclebob/swarm-forge upstream. Identifies real conflicts (only files both sides modified since merge base), checks whether fork changes are superseded, migrates divergences to fork.bb, and opens a PR to gabadi/swarm-forge. Use when upstream has new commits, user says "sync upstream", "upstream has changes", or "merge upstream".
---

# Fork Upstream Sync

## Core rule: only intersecting files are real conflicts

After fetching upstream, find what each side changed since the merge base:

```bash
MERGE_BASE=$(rtk git merge-base HEAD upstream/main)
rtk git diff "$MERGE_BASE"..HEAD --name-only # our side
rtk git diff "$MERGE_BASE"..upstream/main --name-only # upstream side
```

Files only upstream changed → trivial forward merge, don't mention them.
Files only we changed → no conflict.
**Files in both lists → real conflicts. Analyze each one.**

## Classify each real conflict

For every intersecting file, answer in order:

1. **Superseded?** Read upstream's new version and grep for the intent of our change. If upstream solved it already (even differently), our change is moot — take theirs.
2. **Non-overlapping edits?** If our edit and upstream's are on different lines, take both — no decision needed.
3. **Migration needed?** If upstream rewrote/replaced the file and we have substantive logic in it, extract our logic to `fork.bb` (see below).

## Migration pattern: fork.bb

When upstream replaces a script file we've extended, move our logic into `swarmforge/scripts/fork.bb`. This file is loaded by `swarmforge.bb` via `(load-file ...)` and is 100% fork-owned — zero conflict surface on future syncs.

- Extractable: self-contained functions (settings writers, skill installers, sparse-checkout setup, prompt bundle resolvers)
- Must stay in `swarmforge.bb`: config parsing for new fields, permission-mode flags, setup guards, load-file call itself
- Keep the upstream file edits to small, stable hook call sites only

## Resolving constitution/articles conflicts

These files get edited by both sides frequently. Always:
- Take upstream's structural/wording changes
- Preserve our fork-specific rule insertions (check `rtk git diff "$MERGE_BASE"..HEAD -- <file>` to see exactly what we added)
- Never remove an upstream rule unless there's an explicit ADR for it

## Doing the merge

```bash
rtk git checkout -b feat/upstream-sync
rtk git merge upstream/main
# Files to take entirely from upstream:
rtk git checkout --theirs <file> && rtk git add <file>
# Manual resolutions: edit file, then rtk git add
rtk git commit
rtk git push origin feat/upstream-sync
gh pr create -R gabadi/swarm-forge --title "..." --body "..."
```

**Never** open a PR against `unclebob/swarm-forge`. Always target `gabadi/swarm-forge`.
`gh` CLI defaults to upstream — always pass `-R gabadi/swarm-forge`.

## After the PR

If any migrated divergences aren't yet documented, add an ADR row or manifest entry. ADR house style: divergence + why only, no rejected-options section.
Loading