ftown-bridge 0.11.2 → 0.13.0

package/skills/{ftown-orchestrator/SKILL.md → ftown/references/orchestrator.md}

@@ -1,20 +1,10 @@
----
-name: ftown-orchestrator
-description: >-
-  Spawn and coordinate worker ftown agent sessions on this machine. Activates when
-  the session env has FTOWN_ORCHESTRATOR=1, the first input contains an [ftown]
-  orchestrator briefing, or the user asks to orchestrate, coordinate, or spawn
-  worker agent sessions. Teaches spawning and coordinating sibling ftown agent
-  sessions via ~/.ftown/ftown-sessions CLI.
----
-
 # ftown orchestrator playbook
 
 You are running inside an ftown session (your id is in `$FTOWN_SESSION_ID`) and
 can coordinate worker agent sessions on this machine using the
 `~/.ftown/ftown-sessions` CLI.
 
-See the **ftown-sessions** skill for the full CLI reference.
+See `references/sessions.md` for the full session CLI reference.
 
 ## Spawning workers
 
@@ -92,6 +82,25 @@ prefer mail, which arrives at the next turn boundary.
 
 Clean up workers you no longer need to keep the session list tidy.
 
+## Recurring work
+
+For unattended recurring work, create a scheduled loop instead of keeping an
+orchestrator alive to poll or sleep. See `references/loops.md` for the full loop
+workflow:
+
+```bash
+~/.ftown/ftown-sessions loop create \
+  --name repo-watch \
+  --every 30m \
+  --shell codex \
+  --workdir /path/to/repo \
+  --task "Inspect recent changes, run the focused checks, and report issues"
+```
+
+Loop runs show as normal ftown sessions grouped under their loop in the
+dashboard. Use `~/.ftown/ftown-sessions loop runs <loop-id>` to inspect run
+sessions from the CLI.
+
 ## Practical guidance
 
 - **Parallelize** independent tasks: spawn multiple workers before waiting for any.
@@ -104,5 +113,5 @@ Clean up workers you no longer need to keep the session list tidy.
 ## If the CLI is missing
 
 Start or restart **ftown-bridge** on this machine. It installs
-`~/.ftown/ftown-sessions` and updates this skill under
-`~/.ftown/skills/ftown-orchestrator/` (linked into ~/.agents/skills and ~/.claude/skills).
+`~/.ftown/ftown-sessions` and updates the unified skill under
+`~/.ftown/skills/ftown/` (linked into ~/.agents/skills and ~/.claude/skills).

package/skills/{ftown-sessions/SKILL.md → ftown/references/sessions.md}

@@ -1,12 +1,3 @@
----
-name: ftown-sessions
-description: >-
-  Observe and control other ftown CLI agent sessions on the same machine. Use the
-  ftown-sessions CLI (~/.ftown/ftown-sessions) to list, create, read, and drive
-  sibling sessions while running inside a ftown-managed Claude Code or Cursor Agent
-  session.
----
-
 # ftown cross-session CLI
 
 **Prefer the CLI** — installed to `~/.ftown/ftown-sessions` whenever `ftown-bridge` is running. It reads `~/.ftown/bridge.json` automatically.
@@ -15,7 +6,8 @@ description: >-
 ~/.ftown/ftown-sessions --help
 ```
 
-Skill copy (same binary via wrapper): `scripts/ftown-sessions` in this skill directory.
+Unified skill wrapper: `scripts/ftown` in this skill directory delegates to the
+top-level `~/.ftown/ftown` dispatcher.
 
 **Trust model:** anyone who can read `bridge.json` can control **every** ftown session on that bridge.
 
@@ -60,6 +52,12 @@ Skill copy (same binary via wrapper): `scripts/ftown-sessions` in this skill dir
 ~/.ftown/ftown-sessions revive <session-id>
 ```
 
+## Scheduled loops
+
+Loop runs are normal sessions tagged with `loopId`. For loop creation,
+schedule syntax, manual runs, pause/resume, and run history, read
+`references/loops.md`.
+
 ## Messaging (mail)
 
 `tell` posts to the target session's **inbox**. Mail is delivered into the
@@ -135,11 +133,11 @@ name/id and parent name/id, and how to mail the parent via
 `ftown-harness mail send --parent`. The creator's `--prompt` follows after a `Task:` line.
 
 An agent session created with `--orchestrator` additionally gets `FTOWN_ORCHESTRATOR=1`
-in its environment and a compact pointer briefing directing it to the **ftown-orchestrator**
-skill (installed at `~/.ftown/skills/ftown-orchestrator`, linked from ~/.agents/skills and
-~/.claude/skills), which contains the full orchestrator playbook for spawning workers,
-monitoring them, and cleaning up. When both apply, the child paragraph
-comes first, then the orchestrator pointer, separated by a blank line.
+in its environment and a compact pointer briefing directing it to the unified
+**ftown** skill, whose `references/orchestrator.md` contains the full
+orchestrator playbook for spawning workers, monitoring them, and cleaning up.
+When both apply, the child paragraph comes first, then the orchestrator pointer,
+separated by a blank line.
 
 ## HTTP API (optional)
 
@@ -159,7 +157,15 @@ The CLI wraps the loopback API. Raw access if needed:
 | DELETE | `/api/sessions/:id` | Remove (tombstone-archived) |
 | GET | `/api/archive` | List removed-session tombstones |
 | POST | `/api/sessions/:id/revive` | Recreate a removed session (new id) |
+| GET | `/api/loops` | List scheduled loops |
+| POST | `/api/loops` | Create a scheduled loop on this bridge |
+| GET/PATCH/DELETE | `/api/loops/:id` | Inspect, update, or delete a loop |
+| POST | `/api/loops/:id/run-now` | Request an immediate loop run |
+| GET | `/api/loops/:id/runs` | List run sessions for a loop |
 
 ## If the CLI is missing
 
-Start or restart **ftown-bridge** on this machine. It installs `~/.ftown/ftown-sessions`, `~/.ftown/notify.sh`, and updates this skill under `~/.ftown/skills/ftown-sessions/` (linked into ~/.agents/skills and ~/.claude/skills).
+Start or restart **ftown-bridge** on this machine. It installs
+`~/.ftown/ftown-sessions`, `~/.ftown/notify.sh`, and updates the unified skill
+under `~/.ftown/skills/ftown/` (linked into ~/.agents/skills and
+~/.claude/skills).

package/skills/{ftown-workflows/SKILL.md → ftown/references/workflows.md}

@@ -1,14 +1,3 @@
----
-name: ftown-workflows
-description: >-
-  Run deterministic, scripted, resumable multi-session workflows across real
-  ftown agent sessions. Activates when the user wants to fan out ftown worker
-  sessions over a work list, run a pipeline or parallel batch across ftown
-  sessions, perform adversarial-verify (majority-vote) across sessions,
-  loop-until-dry over a dataset, or write a repeatable orchestration script
-  instead of doing it by hand.
----
-
 # ftown-workflows
 
 `ftown-workflows` is a **scripted orchestration engine** for real ftown sessions.
@@ -17,10 +6,14 @@ You write a `.mjs` script using a small API (`agent`, `parallel`, `pipeline`,
 cursor / codex), waits for each to write a result file, cleans up, and returns the
 value — all deterministically and repeatably.
 
-This complements the by-hand **ftown-orchestrator** skill (which is the ad-hoc,
-human-in-the-loop playbook). Use ftown-workflows when the work is scripted and
-repeatable; use ftown-orchestrator when you need to improvise or keep a human in
-the loop.
+This complements the by-hand orchestrator playbook in
+`references/orchestrator.md`. Use ftown-workflows when the work is scripted and
+repeatable; use orchestrator guidance when you need to improvise or keep a
+human in the loop.
+
+This is separate from **scheduled loops** managed by `~/.ftown/ftown-sessions
+loop ...`. Scheduled loops create recurring ftown sessions over time. A workflow
+loop is control flow inside one deterministic workflow run.
 
 ## Operating Contract
 
@@ -204,7 +197,7 @@ For long runs, launch in the background and tail the run dir:
 tail -f ~/.ftown/workflows/<run-id>/*.json
 ```
 
-See the runnable template at `skills/ftown-workflows/scripts/example.flow.mjs`.
+See the runnable template at `scripts/example.flow.mjs` in this skill directory.
 
 ## Script API
 
@@ -462,9 +455,9 @@ session. To resume a partial run:
 
 The run id and run directory are printed at startup.
 
-## When to use this vs ftown-orchestrator
+## When to use this vs orchestrator guidance
 
-| | ftown-orchestrator | ftown-workflows |
+| | orchestrator guidance | ftown-workflows |
 |---|---|---|
 | **style** | ad-hoc, by hand | scripted, deterministic |
 | **human in loop** | yes — you direct workers via mail | no — script drives everything |
@@ -475,5 +468,5 @@ The run id and run directory are printed at startup.
 ## If the CLI is missing
 
 Start or restart **ftown-bridge** on this machine. It installs
-`~/.ftown/ftown-workflows` and updates this skill under
-`~/.ftown/skills/ftown-workflows/` (linked into ~/.agents/skills and ~/.claude/skills).
+`~/.ftown/ftown-workflows` and updates the unified skill under
+`~/.ftown/skills/ftown/` (linked into ~/.agents/skills and ~/.claude/skills).

package/skills/ftown/scripts/ftown

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Delegates to the bridge-installed top-level ftown dispatcher.
+set -euo pipefail
+exec "${HOME}/.ftown/ftown" "$@"

package/skills/ftown-sessions/scripts/ftown-sessions

@@ -1,4 +0,0 @@
-#!/usr/bin/env bash
-# Delegates to the bridge-installed CLI (~/.ftown/ftown-sessions).
-set -euo pipefail
-exec "${HOME}/.ftown/ftown-sessions" "$@"

package/skills/ftown-workflows/scripts/ftown-workflows

@@ -1,4 +0,0 @@
-#!/usr/bin/env bash
-# Delegates to the bridge-installed CLI (~/.ftown/ftown-workflows).
-set -euo pipefail
-exec "${HOME}/.ftown/ftown-workflows" "$@"