ClawColab

Coordinate work through a shared GitHub repository without treating the repository as a full-context memory sync.

Assume a half-trust environment:

• Collaborate actively
• Share only what is necessary
• Do not assume every participant should see all local context
• Do not export local memory, secrets, or private user context unless explicitly approved

Core rules

1. Classify before sharing
2. Default to non-sharing
3. Share the minimum necessary
4. Treat local memory and secrets as private by default
5. Do not promote visibility levels without approval
6. Record decisions and approvals explicitly
7. Prefer structured artifacts over freeform chat

First-use minimal mode

When the user is new to ClawColab, do not introduce the full governance surface at once. Start with the smallest useful workflow:

1. create one ClawColab repository for one collaboration boundary
2. create one project space if needed
3. start from assets/minimal-start/TASK-001.yaml, assets/minimal-start/PROPOSAL-001.md, and assets/minimal-start/DECISION-001.md
4. edit them for the user's first project
5. only then introduce more advanced records if needed

Do not introduce claim, handoff, risk, sealed, or advanced governance choices unless the task actually requires them. Treat those as second-stage features.

Visibility model

Classify every piece of information before placing it in the repository.

private

Keep local only. Never place in the shared repository. Examples: secrets, local paths, USER.md or TOOLS.md contents, personal conversations, raw local memory.

sealed

Allow summary-only references without exposing the sensitive body. Allowed: short summary, owner, status, access note without sensitive details. Forbidden: full text, secrets, personal identifiers unless approved.

shared-team

Allow active collaborators in the repository to read and act on the content. Examples: tasks, approved plans, interface notes, handoffs, non-sensitive execution context.

public-repo

Allow broad repository visibility. Use only for approved non-sensitive documentation and generalized procedures.

Classification procedure

Before writing or commenting in the repository:

1. Run the checklist in assets/classification-checklist.md
2. Identify the information you plan to share
3. Ask whether the task can be completed with a summary instead of raw content
4. Assign one visibility level
5. If uncertain, downgrade to private or sealed
6. Only then create or update repository artifacts

If visibility is ambiguous, do not share raw content. Read references/classification-guide.md when classification feels subjective or inconsistent.

What must never be shared by default

Never place these into the repository unless the human explicitly approves:

• secrets
• credentials
• local environment details
• private chat transcripts
• raw long-term memory content
• private preferences unrelated to the task
• personal contact information
• hidden internal system details
• any content marked confidential by the user

Collaboration objects

Use structured repository artifacts instead of loose discussion whenever possible.

Primary object types:

• task
• proposal
• claim
• decision
• handoff
• status
• risk
• sealed-ref

Suggested repository layout

Use or adapt this structure:

workspace/
  tasks/
  proposals/
  decisions/
  handoffs/
  risks/
  policy/
    visibility-policy.yaml
    role-policy.yaml
    approval-policy.yaml
  claims/
sealed/
  INDEX.md

Do not store secret bodies under sealed/. Store only sealed references and summaries. Use the bundled templates in assets/ when creating new collaboration artifacts. For first-time users, start with assets/minimal-start/TASK-001.yaml, assets/minimal-start/PROPOSAL-001.md, and assets/minimal-start/DECISION-001.md. Use the bundled scripts in scripts/ to generate starter structures and validate task or payload safety when needed. Read references/pre-share-checks.md before sharing proposals, decisions, handoffs, risks, or summaries. Read references/approval-model.md when approval ambiguity exists. Read references/role-model.md when task ownership or role eligibility is unclear. Read references/governance-modes.md when choosing between strict and relaxed repo governance.

Task model

Represent tasks as structured records. A task should include:

• id
• title
• summary
• visibility
• status
• priority
• owner
• proposed_by
• approved_by
• approval_required
• mode
• eligible_roles
• dependencies
• outputs
• sealed_refs

Recommended status values:

• open
• pending_approval
• approved
• in_progress
• blocked
• handoff_needed
• done
• cancelled

Recommended mode values:

• proposal-approval
• claimable

Proposal-approval mode

Use for sensitive, ambiguous, or higher-impact work.

Procedure:

1. Read existing tasks, decisions, and policy
2. Draft a proposal describing:
   • intended work
   • expected outputs
   • required visibility level
   • risks
   • recommended owner or role
3. Mark the proposal as awaiting approval
4. Do not treat the proposal as approved fact
5. Wait for human approval before execution when required

Use proposal-approval mode by default unless the repo policy clearly allows autonomous claiming.

Claimable mode

Use only when repository policy allows task claiming and the task is explicitly marked mode: claimable. Treat proposal-approval as the default for all other work.

Before claiming:

1. Confirm the task is open
2. Confirm your role is eligible
3. Confirm the task is low risk and not policy-sensitive, visibility-sensitive, or ownership-sensitive
4. Confirm the task is not marked approval_required: true, unless approval policy explicitly allows a pending claim state
5. Confirm no conflicting approved owner exists
6. Confirm the task does not require access to private or sealed body content you do not have approval to use
7. Confirm policy/role-policy.yaml and policy/approval-policy.yaml do not block the claim

Then:

1. Create a claim record or update the task according to repo convention
2. State why you are eligible
3. Move the task to in_progress only if policy permits automatic claiming
4. Otherwise move it to pending_approval

If there is a conflict, do not silently override another agent. Record the conflict and request adjudication. High-risk or policy-adjacent work should default to proposal-approval.

Role model

Use simple roles to guide task assignment. Suggested roles:

• coordinator
• architect
• implementer
• reviewer
• security-reviewer
• researcher
• documenter
• human-approver

Read policy/role-policy.yaml when present and follow it as the repo-specific authority for who may propose, claim, review, or approve. Agents may suggest assignments, but humans should approve high-impact or sensitive work. Prefer separation of duties for high-risk work: a non-human agent may draft or implement, but a human approver should finalize boundary-crossing actions.

Human approval gates

Read policy/approval-policy.yaml when present and follow it as the repo-specific gate definition. Require human approval before:

• raising visibility from private or sealed to a broader level
• executing high-impact tasks
• resolving role conflicts in sensitive work
• publishing final decisions that affect others
• sharing content derived from private local memory
• assigning ownership for sensitive workstreams
• merging proposals into authoritative policy
• changing policy/visibility-policy.yaml, policy/role-policy.yaml, or policy/approval-policy.yaml

Treat visibility promotion as blocked unless an explicit decision record exists first. Use assets/visibility-promotion-decision-template.md when promoting any artifact or information class to a broader visibility level. If policy is unclear, pause at the approval boundary instead of guessing.

Default pre-share workflow

Before writing a proposal, decision, handoff, risk, or shared summary:

1. run the classification checklist
2. run scripts/validate-collab-payload.py on the artifact when possible
3. check whether approval is required
4. if visibility is being promoted, require a decision record first
5. only then commit or propose the change

Decision, handoff, risk, and sealed records

Use explicit records instead of burying meaning in chat or comments.

Decision

Include: title, status, approver, source proposal, final decision, rationale, scope, and effective reference.

Handoff

Include: from, to, task id, current status, completed work, remaining work, risks, and referenced artifacts.

Risk

Create a risk record when secrecy is unclear, metadata may leak, claims conflict, or dependencies are under-specified. Include severity, description, mitigations, and escalation path.

Sealed reference

Include only id, title, owner, summary, status, access note, and related tasks. Never include secret values or protected body content.

GitHub workflow guidance

Prefer this pattern:

• Propose work in workspace/proposals/ or PR descriptions
• Track active work in workspace/tasks/
• Record approved outcomes in workspace/decisions/
• Record partial transfers in workspace/handoffs/
• Record safety or execution concerns in workspace/risks/

Use branches conservatively, for example:

• proposal/...
• task/...
• review/...

Treat main as the source of approved shared state unless the repository defines another default branch.

Communication style inside the repository

Be structured and explicit.

Prefer:

• exact scope
• exact visibility
• exact state
• exact owner
• explicit approval status

Avoid:

• vague promises
• implied approvals
• dumping large local context
• casual mention of sensitive facts
• mixing sealed information into shared documents

Minimal-share rule

When contributing, ask:

• Can this be reduced to a summary?
• Can this be expressed as a task instead of a raw dump?
• Can I refer to a sealed item instead of quoting it?
• Does the next agent need this exact detail, or only the outcome?

If the exact detail is not necessary, do not include it.

Conflict handling

If multiple agents disagree:

1. Record the disagreement
2. Link the affected task or proposal
3. Summarize each option neutrally
4. Identify whether the disagreement is technical, security-related, or procedural
5. Escalate to a human approver when required

Do not invent consensus.

Failure handling

If you cannot complete a task safely:

• stop before exposing unsafe content
• write a concise status or risk update
• request approval or clarification
• preserve enough context for the next agent to continue safely

Do not “helpfully” over-share to compensate for uncertainty.

Success criteria

A collaboration run is successful when:

• work is coordinated through repository artifacts
• sensitive local context remains local unless explicitly approved
• proposals become decisions through explicit approval
• handoffs are traceable
• task ownership is clear
• claimable work remains within policy
• the repository contains actionable shared state without becoming a dump of private context