agent-rally-point

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->

# Agent Rally Point

Build-loop ships a native embedded `agent-rally-point` capability while the
standalone repo matures. Treat it as a mini-plugin inside build-loop: keep the
substrate logic, docs, tests, and thin build-loop adapters grouped so spin-out
is mechanical later.

## Native Surface

| Purpose | Path |
|---|---|
| Substrate package | `${CLAUDE_PLUGIN_ROOT}/scripts/rally_point/` |
| Host-neutral CLI | `${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py` |
| Slash command | `${CLAUDE_PLUGIN_ROOT}/commands/rally-point.md` |
| Hook adapters | `${CLAUDE_PLUGIN_ROOT}/hooks/session-start-rally-point.sh`, `${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit-rally-point.sh` |
| Build-loop adapters | `${CLAUDE_PLUGIN_ROOT}/scripts/coordination_status.py`, `${CLAUDE_PLUGIN_ROOT}/scripts/coordination_rally.py`, `${CLAUDE_PLUGIN_ROOT}/scripts/coordination_bootstrap.py` |
| Boundary manifest | `${CLAUDE_PLUGIN_ROOT}/scripts/rally_point/plugin_boundary.json` |

## Required Orchestrator Contract

At the Phase 1 preamble, before the first Rally Point write, the orchestrator
must generate or resume the durable run identity:

```python
from scripts.rally_point.build_loop_id import generate_or_resume

execution = generate_or_resume(
    workdir=Path.cwd(),
    tool="<tool-id>",
    session_id="<session-id>",
)
```

`session_id` is the ephemeral host session. `run_id` is caller-chosen legacy
provenance. `build_loop_id` is the durable human-visible run identity and is
surfaced on Rally Point records as top-level `build_loop_id` and
`build_loop_run_label`.

## Operating Rules

- Resolve the channel through `scripts/rally_point/discovery_bridge.py` or
  `scripts/agent_rally.py where`; do not hardcode legacy channel roots.
- Write cross-session events through `scripts/rally_point/post.py::post()`;
  do not append directly to `changes.jsonl`.
- Correct a wrong fact by appending a retraction (`agent_rally.py retract`),
  never by editing the log. See "Retracting a wrong fact" below.
- Keep `build_loop_id` separate from `producer_metadata`.
- Keep substrate files independent from build-loop memory/orchestration
  internals. If a build-loop-specific integration is needed, put it in a thin
  adapter named in `plugin_boundary.json`.
- Use stable tool ids: `claude_code`, `codex`, `cursor`, `gemini`, or another
  lowercase id agreed by the adapter.
- When the work produces a handoff or retrospective **document**, post its
  **absolute** path (`rally say handoff ... --evidence "file:/abs/path"`) and
  state that same path in the terminal reply. A receiver runs in a different
  working directory, so a relative path resolves to nothing or to the wrong
  file, and a retrospective written to the memory store is unreachable from the
  repo unless its path is said out loud. Post first, then go on writing; the
  post needs no reading and nothing should delay it. The common failure is not
  a thin handoff, it is a thorough one nobody located.

## Commands

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py status --workdir "$PWD" --session-id "$SESSION_ID" --json
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py heartbeat --workdir "$PWD" --session-id "$SESSION_ID" --task-ref "$TASK_REF" --progress "still working" --json
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py ack-inbox --workdir "$PWD" --session-id "$SESSION_ID" --tool "$TOOL_ID" --json
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py boundary --repo "${CLAUDE_PLUGIN_ROOT}" --check --json
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/rally_point/boundary.py --repo "${CLAUDE_PLUGIN_ROOT}" --check --json
```

Use `/agent-rally-point status` for the same sensor from Claude Code.
Status/watch envelopes include `inbox_latest_messages`, a compact doorbell
preview for the newest unread direct/broadcast inbox records. Counts are
session-ack aware; read `inbox/<tool>.jsonl` or `inbox/all.jsonl` before acting
on a full message, then run `ack-inbox` after handling it. Ack cursors live
under `inbox/.acks/` and never rewrite the append-only inbox payloads.

## Retracting a wrong fact

The ledger is append-only, so a posted fact is never edited or deleted. Withdraw
one by appending a **retraction** that names its `event_id` — the `[fact_...]`
id shown in `rally room`:

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py retract \
  --workdir "$PWD" --session-id "$SESSION_ID" --tool "$TOOL_ID" \
  --fact fact_f4c9_18c99988bcb40648 \
  --reason "wrong sha — read from a stale worktree" \
  --superseded-by fact_a1b2_0f3e4d5c6b7a8901   # optional: the corrected fact
```

From then on every build-loop read path drops the withdrawn fact and keeps the
retraction, so peers see the correction instead of the bad claim. `--superseded-by`
is optional: use it when a corrected fact replaces the retracted one, omit it when
the fact was simply wrong.

Guardrails: an unknown `--fact` id exits 1 rather than posting a retraction that
neutralizes nothing (`--force` overrides, for a fact in a store build-loop cannot
read back); a second retraction of the same fact exits 1 as `retract-noop`; and
retracting a retraction is refused, because that would erase the correction trail
— post a new corrective fact instead.

Limits worth knowing before you rely on it:

- **Resolution is build-loop-side.** `rally room` is the Rust binary and does not
  yet honor retractions, so a retracted fact still appears there (as does the
  retraction next to it). Native `rally retract` is filed against the
  `agent-rally-point` repo.
- **A fact a peer already read cannot be un-read.** A retraction arriving in a
  later poll surfaces as its own record; it cannot reach back into context a peer
  already consumed.
- **Pre-`fact.v1` records carry no `event_id`** and therefore cannot be targeted.

## Task Heartbeat — still on the claimed task

Presence is process liveness: it tells peers this session can still write to

From tyroneross/build-loop, Apache-2.0.

More from tyroneross/build-loop