Skip to content

TEAM-GATEWAY-CHECKLIST.md

Latest commit

 

History

History
120 lines (87 loc) · 4.61 KB

TEAM-GATEWAY-CHECKLIST.md

File metadata and controls

120 lines (87 loc) · 4.61 KB

Team Gateway Checklist

This checklist covers governance and safety gates for teams running Claude Code / Codex-style agent workflows through a shared gateway or proxy. It supersedes ad-hoc runbooks and is enforced by the before-merge CI gates listed below.

Related: #2058

1. Before-Merge Gates

Run these checks before every merge to main:

Gate Command Blocks merge if
Lint npm run lint Any lint error
Type-check npx tsc --noEmit Any TypeScript error
Unit tests npm test Fewer than 1999 passing
Smoke tests node scripts/smoke-*.mjs Any exit code != 0
Witness manifest npx ruflo@latest verify Checksum mismatch
Semver bump npm version <patch|minor|major> No version bump on API change

Every merge to main must record a new witness manifest entry. Generate it with:

npx ruflo@latest sign --message "merge: <PR title>"

2. Dual-Mode Handoff (Claude Code + Codex)

When handing work between Claude Code and OpenAI Codex workers:

  1. Shared memory namespace: use collaboration — all cross-platform writes go here.
  2. Store design decisions before switching platforms: 
    npx @claude-flow/cli@latest memory store \
  --namespace collaboration \
  --key "design-<feature>" \
  --value "<design decisions as JSON or markdown>"
  3. Kick off Codex worker after Claude Code produces the design: 
    npx claude-flow-codex dual run \
  --worker "codex:coder:Implement based on design-<feature>" \
  --namespace collaboration
  4. Validate compatibility before shipping — OpenAI-compatible and Anthropic-compatible endpoints are verified subsets. Always smoke-test streaming, tool calling / MCP, and reasoning blocks independently before putting them in an autonomous workflow.
  5. Keep provider keys separate — gateway or proxy keys must be distinct from upstream provider keys and must be rotatable / revocable without rotating the upstream secret.

3. Memory Namespace Sharing

All agents in a team workflow share state through named namespaces. Conventions:

Namespace Owner Contents
collaboration All cross-platform agents Design decisions, code paths, review findings
patterns All agents Reusable solution patterns (stored after each successful task)
tasks Coordinator Task assignments and status
security Security auditor Vulnerability findings, remediation status

Rules:

  • Never write credentials or raw API keys to any namespace — store only key names or rotation identifiers.
  • Namespaces are not access-controlled by default; treat all shared namespaces as readable by every agent in the swarm.
  • Use --ttl to expire ephemeral coordination messages (e.g., handoff signals): 
    npx @claude-flow/cli@latest memory store \
  --namespace collaboration \
  --key "handoff-signal-<run-id>" \
  --value "ready" \
  --ttl 300

4. Witness Manifest Entry Per Merge

Each merge to main must include a signed witness manifest entry so npx ruflo@latest verify can confirm the installed dist matches the audited fix footprint.

Generating a manifest entry

# Sign the current dist with a descriptive message
npx ruflo@latest sign --message "merge: <PR-number> — <one-line description>"

# Commit the updated manifest alongside code changes
git add verification.md verification.md.json
git commit -m "chore: update witness manifest for <PR-number>"

Verifying an installation

# After npm install / npx ruflo@latest
npx ruflo@latest verify
# Expected output: "Verification passed — dist matches audited footprint"

If verify reports a mismatch, do not use the installation in a shared gateway until the discrepancy is investigated and a new manifest is signed.

5. Gateway Logging and Audit Scope

Be explicit with teammates about what your gateway logs contain:

  • Logged: usage metadata (tokens, model, latency), route, HTTP status, error class.
  • Not logged by default: prompt content or completion content (check your gateway config).
  • Avoid unauthenticated shared gateway access outside local experiments.
  • Review CLAUDE_FLOW_LOG_LEVEL=debug output before sharing logs — debug level may include request bodies.

See Also