coordination-bridge

Files (14)

• SKILL.md
• __init__.py · scripts/_generated/
• features_models.py · scripts/_generated/
• features_operations.py · scripts/_generated/
• check_coordinator.py · scripts/
• coordination_bridge.py · scripts/
• generate_bindings.py · scripts/
• github_issues.py · scripts/
• routing_fallback.py · scripts/
• test_code_search_capability.py · scripts/tests/
• test_coordination_bridge.py · scripts/tests/
• test_feature_registry_helpers.py · scripts/tests/
• test_generated_bindings.py · scripts/tests/
• test_github_issues.py · scripts/tests/

SKILL.md (first lines)

# Coordination Bridge Infrastructure Skill

Non-user-invocable infrastructure skill that provides HTTP fallback for the coordinator when MCP transport is unavailable.

## Scripts

### `<skill-base-dir>/scripts/coordination_bridge.py`

Detects coordinator availability and provides HTTP-based fallback operations.

**Usage**:
```bash
python3 "<skill-base-dir>/scripts/coordination_bridge.py" <command> [args]
```

**Commands**:
| Command | Arguments | Description |
|---------|-----------|-------------|
| `detect` | | Check coordinator availability, output JSON status |
| `try_handoff_read` | `[--agent-name NAME] [--limit N]` | Read latest handoff (HTTP fallback) |
| `try_handoff_write` | `--summary TEXT [--completed JSON] [--next-steps JSON]` | Write handoff document |
| `try_recall` | `[--tags TAG,...] [--limit N]` | Recall memories by tags |
| `try_remember` | `--event-type TYPE --summary TEXT [--tags TAG,...]` | Store a memory |

**Stdout** (detect): JSON with `COORDINATOR_AVAILABLE`, transport, capabilities
**Exit codes**: 0 = success, 1 = coordinator unavailable or error

## Feature registry helpers

Five helpers cover every operation in the feature-registry contract
(`openspec/contracts/agent-coordinator/openapi/features.yaml`). Each resolves
its method and path from the generated `OPERATIONS` table, needs
`CAN_FEATURE_REGISTRY` (probed with `GET /features/active`), and returns the
bridge's uniform envelope: `ok` (contract-typed body in `data`), `skipped`
(`coordinator_unavailable`, `capability_unavailable`, `coordinator_unreachable`,
`unauthorized`, `forbidden`), or `error`. None of them raise.

| Helper | operationId | `data` on `ok` |
|--------|-------------|----------------|
| `try_register_feature(*, feature_id, resource_claims, title=None, agent_id=None, branch_name=None, merge_priority=5, metadata=None)` | `registerFeature` | `FeatureRegisterResult` |
| `try_deregister_feature(*, feature_id, status="completed")` | `deregisterFeature` | `FeatureDeregisterResult` |
| `try_get_feature(*, feature_id)` | `getFeature` | `FeatureDetail` |
| `try_list_active_features()` | `listActiveFeatures` | `ActiveFeaturesEnvelope` |
| `try_analyze_feature_conflicts(*, candidate_feature_id, candidate_claims)` | `analyzeFeatureConflicts` | `ConflictReport` |

All also accept `http_url=None, api_key=None`. `try_get_feature` URL-encodes the
id into the path; an unknown id (404) comes back as a non-`ok` envelope.

## Contract-generated bindings

`scripts/_generated/` is generated by `scripts/generate_bindings.py` from
`openspec/contracts/` only (never from the running app's `app.openapi()`):

- `features_models.py` — `TypedDict` models from pinned
  `datamodel-code-generator==0.83.0`. They use Python 3.11+ typing, so the bridge
  imports them **only under `if TYPE_CHECKING:`**.
- `features_operations.py` — `OPERATIONS`: `operationId` →
  `Operation(method, path, path_params, requires_api_key, request_model, response_model)`.
  Imported at runtime, so it is **standard-library only and valid on Python 3.9**:
  skills run the bridge with bare `python3`, no venv.

Do not edit `_generated/` by hand. The generator is a source-repository tool
(it needs `openspec/contracts/` and the skills venv from
`cd skills && uv sync --all-extras`). After changing a contract, regenerate from
the repo root:

```bash
skills/.venv/bin/python skills/coordination-bridge/scripts/generate_bindings.py          # write  (source-contribution-only)
skills/.venv/bin/python skills/coordination-bridge/scripts/generate_bindings.py --check  # CI gate (source-contribution-only)
```

`--check` writes nothing and exits non-zero naming each stale file and the
regeneration command. Output is deterministic (no timestamps or absolute
paths). To bind another contract, add a `(contract path, module prefix)` row to
`CONTRACTS` in the generator. Re-running the skills installer refreshes the
runtime copies under `.claude/skills/` and `.agents/skills/` with `_generated/`.

## Issue backend (issue #429)

`try_issue_*` defaults to the coordinator HTTP API. Coordinator writes currently
return success with a generated UUID and then vanish from every subsequent read,
so the durable interim store is GitHub Issues in this repository.

Opt in:

```
COORDINATION_ISSUES_BACKEND=github
GITHUB_TOKEN=...                  # or GH_TOKEN / GITHUB_PAT
COORDINATION_GITHUB_REPO=owner/repo   # optional; GITHUB_REPOSITORY is also read
```

`COORDINATION_ISSUES_BACKEND=github` is required in GitHub Actions (where
`GITHUB_TOKEN` and `GITHUB_REPOSITORY` are always set) so CI does not silently
retarget onto live Issues. A failed GitHub write is a non-2xx that the bridge
surfaces; it never reports `success: true` for a discarded record.

`depends_on` is stored in the issue body (metadata comment + task list). Callers
(`seed_tasks_from_md.py`, the status renderer) are unchanged.

## Work-Queue Truth / Projection Contract

The queue helpers this skill exposes (`try_get_work` → `/work/claim`,
`try_complete_work`, and the submit path) are a **distribution/claim mechanism
only**. They are NOT a source of execution truth.

**Contract**: `openspec/changes/<change-id>/loop-state.json` (schema:
`LoopState` in `skills/autopilot/scripts/autopilot.py`) is the **authoritative
execution state** — the source of truth for a run's current phase, iteration,
and package status. The coordinator work queue is a **derived projection** whose
entries are always re-derivable from loop-state. Truth flows loop-state → queue,
**never** queue → loop-state. A `try_get_work` / `/work/claim` result is a work
item to execute; it is never the record of what phase a run is in. No skill may
read authoritative phase/loop-state from the work queue.

This is the same asymmetry `coordinator-task-status-renderer` applies to the
`tasks.md` checkboxes (truth) vs. the rendered coordinator status block
(informational projection).

See the full contract — idempotent submission keyed by

From jankneumann/agentic-coding-tools, MIT.

More from jankneumann/agentic-coding-tools