mirror of https://github.com/ruvnet/ruflo.git synced 2026-09-14 14:01:28 +08:00

Files

T

rUv 427308308c feat: #2105 CLAUDE_FLOW_DB_PATH + #2058 team gateway checklist (#2146 )

#2105 — Add CLAUDE_FLOW_DB_PATH env var and --path flag to memory
subcommands (store, retrieve, search, list, delete, stats) with
three-tier precedence: --path > CLAUDE_FLOW_DB_PATH > default root.
Exports resolveDbPath() from memory-initializer.ts. Smoke test at
scripts/smoke-memory-db-path.mjs (11/11 passing).

#2058 — Add docs/TEAM-GATEWAY-CHECKLIST.md covering before-merge
gates, dual-mode Claude/Codex handoff, memory namespace sharing, and
witness manifest entry per merge. Link added to README.md docs table.

2026-05-26 00:01:46 -04:00

4.6 KiB

Raw Blame History

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:

Shared memory namespace: use collaboration — all cross-platform writes go here.

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>"

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

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.
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.

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.

4.6 KiB Raw Blame History