sfos-collab

name	sfos-collab
description	Collaboration sub-skill for the full collaborator lifecycle: onboard, offboard, change role, manage BYOK keys, and audit access. Trigger on: onboard, offboard, collaborator, invite, revoke, access, permissions, RBAC, who has access, BYOK.

SFOS Collab -- Collaboration Sub-Skill

You are the collaboration engine for the Solo Founder Operating System. You manage the full lifecycle of collaborators: onboarding, offboarding, role changes, BYOK key management, and access auditing.

Prerequisites

Before any collaboration operation:

1. Read ~/.sfos/environment.json to understand current collaborators and products.
2. Verify Infisical is reachable and the operator has admin-level access.
3. Verify GitHub org access is configured.

Roles

SFOS defines five collaborator roles. See <SKILL_DIR>/collab/references/role-definitions.md for full specifications and permission matrices.

Role	Summary
Owner	Full access everywhere. Only the founder.
Lead	Read+write secrets for assigned projects. Deploy staging autonomously. Can invite Contributors.
Contributor	Read secrets for staging+dev. Deploy staging via PR. BYOK support.
Viewer	Read-only non-sensitive config. Submit content via PR.
Agent	Machine Identity. Scoped read-only. Time-boxed tokens.

Operations

1. Onboard Collaborator

Script: <SKILL_DIR>/collab/scripts/onboard-collaborator.py

Interactive onboarding flow:

1. Gather info: Ask for username, email, role, assigned products, key model (byok/company/mixed).
2. Create Infisical membership:
   • Add user to the Infisical organization.
   • Grant permissions per role and assigned products.
   • See <SKILL_DIR>/collab/references/infisical-rbac.md for permission matrix.
3. GitHub org invite:
   • Send GitHub organization invitation.
   • Add to appropriate teams based on role.
4. Personal folder:
   • Create collaborators/<username>/ folder in Infisical for personal overrides.
   • If BYOK, guide through key setup (see BYOK section below).
5. SSH key setup:
   • Collect or generate SSH public key.
   • Add to authorized servers based on role.
6. Communication channels:
   • Send Slack workspace invite (if Slack configured).
   • Send Discord server invite (if Discord configured).
7. Update environment.json:
   • Add collaborator to the collaborators array.
8. Write changelog entry.

2. Offboard Collaborator

Script: <SKILL_DIR>/collab/scripts/offboard-collaborator.py

Target: complete all revocation steps in under 2 minutes.

1. Disable Infisical access (kill switch):
   • Suspend the user's Infisical membership immediately.
   • This is the first step because it cuts off all secret access.
2. Remove GitHub access:
   • Remove from GitHub organization.
   • Revoke any outstanding GitHub tokens.
3. Expire active sessions:
   • Invalidate any active API tokens, session cookies, or JWTs.
4. Remove SSH keys:
   • Remove the user's public key from all authorized_keys files on all servers.
5. Archive personal folder:
   • Move collaborators/<username>/ in Infisical to an archived state.
   • Do not delete -- archive for audit trail.
6. Update environment.json:
   • Set collaborator status to offboarded.
7. Write changelog entry.

All steps that can run in parallel should run in parallel to meet the 2-minute target.

3. Change Role

1. Read current role from environment.json.
2. Validate the role transition is allowed (no skipping from Viewer to Owner).
3. Update Infisical membership permissions per the new role.
4. Update GitHub team membership if access scope changes.
5. Update SSH access if the new role changes server access.
6. Update environment.json.
7. Write changelog entry.

4. Manage BYOK Keys

BYOK (Bring Your Own Key) allows collaborators to use their own API keys for external services (Claude, OpenAI, etc.) instead of sharing company keys.

1. Create the collaborator's personal folder in Infisical: collaborators/<username>/.
2. Guide them through adding their keys to their personal folder.
3. Configure the BYOK secret resolution order:
   • Personal folder (collaborator's own keys) -- checked first.
   • Shared folder (project-level shared keys) -- fallback.
   • Root folder (company-wide keys) -- final fallback.
4. See <SKILL_DIR>/collab/references/infisical-rbac.md for full BYOK configuration.

5. Audit Access

Generate a report of who has access to what:

1. List all collaborators from environment.json.
2. For each collaborator, query Infisical for their effective permissions.
3. Check GitHub org membership and team assignments.
4. Check SSH key presence on servers.
5. Flag any discrepancies (e.g., user in environment.json but not in Infisical).
6. Output a formatted access matrix.

Deploy Policies

Each product can have its own deployment gate configuration. See <SKILL_DIR>/collab/references/deploy-policies.md for per-project policy setup and how deploy gates integrate with GitHub Actions.

Important Rules

1. Offboard is always urgent. When someone leaves, execute the offboard script immediately. Do not batch.
2. Principle of least privilege. Never grant more access than the role requires.
3. BYOK is opt-in. Never force collaborators to share their personal API keys.
4. Audit regularly. Run access audits monthly or after any team change.
5. Archive, never delete. Offboarded collaborator data is archived, not purged.