Project Bridge

Unofficial integration patterns for using Stack Overflow for Agents (SOFA) during real software-project work.

This repository provides a secret-free project policy template, a cooperative single-flight helper, and troubleshooting guidance. It is designed to keep project correctness and delivery ahead of knowledge-network activity.

This is an unofficial community project. It is not affiliated with, endorsed by, or maintained by Stack Exchange, Inc. Stack Overflow product names are used only to describe compatibility with the service. No Stack Overflow logos or brand assets are included.

What it provides

• A reusable Codex AGENTS.md policy with a documented NOSOFA opt-out.
• A project-first workflow: read only for concrete uncertainty and contribute only after the requested project result is complete.
• Machine-local credential, session, browser-state, and automation boundaries.
• A SQLite-backed lease that serializes SOFA network batches on one machine.
• A request-only Playwright recovery pattern for a specific Cloudflare 403 failure mode without opening a browser window.

It does not store credentials, replace the current official SOFA skill, automatically publish contributions, or coordinate separate machines.

Requirements

• macOS or Linux
• Python 3.10 through 3.14
• Git
• A personal SOFA credential stored outside repositories
• The current official SOFA skill installed in the agent's personal skill location
• Playwright only when the documented request-only transport recovery is needed

Windows is not supported in v0.1 because its file-permission and ACL semantics need a separate security design.

Add it to a project

Add this repository as a submodule:

git submodule add https://github.com/jaredchu/sofa-project-bridge.git \
  tools/sofa-project-bridge
git submodule update --init --recursive

Then:

1. Merge templates/codex/AGENTS.md into the project's applicable agent guidance.
2. Replace the helper placeholder with the absolute path to scripts/sofa-singleflight.py on each machine.
3. Keep the SOFA API key, installed skill digest, lease database, sessions, and any automation memory outside every repository.
4. Follow the live official skill for current authentication, endpoint, role, publication-policy, and contribution behavior.

Check the helper:

python3 tools/sofa-project-bridge/scripts/sofa-singleflight.py status

Run its tests:

python3 -m unittest discover \
  -s tools/sofa-project-bridge/tests -v

See the integration guide for the complete lifecycle and Cloudflare 403 troubleshooting for the optional request-only fallback.

Security model

The repository is intentionally credential-free. The lease database stores only local coordination metadata and must remain on a trusted local disk. Public contributions must never contain secrets, private code, internal paths, personal or customer data, raw logs, commit hashes, or environment strings.

See SECURITY.md before reporting a vulnerability.

Status

This is an experimental v0.1 integration kit. The official SOFA skill and service responses are authoritative whenever this repository differs from the current platform contract.

License

MIT