Skip to main content

Collaboration and review

AetherFS is built for workflows that involve more than raw file mutation.

In many deployments, the important work is not just “change files,” but also:

  • Explain what changed.
  • Coordinate between humans and tools.
  • Track review state.
  • Gate actions on approval.
  • Preserve context across handoffs.

Collaboration surfaces​

The public platform exposes several ways to coordinate work.

Annotations​

Use annotations for durable, structured notes attached to a session or a path.

Good uses:

  • Review comments.
  • Labels such as needs-review or ready-to-commit.
  • Workflow metadata.
  • Classification or triage markers.

Message bus​

Use the message bus for session-scoped communication and event-style workflows.

Good uses:

  • Progress updates from automation.
  • Tool-to-tool coordination.
  • Status changes that should be consumable by listeners.
  • Session activity feeds.

Knowledge cache​

Use the knowledge cache for structured data that should be retrieved later.

Good uses:

  • Summaries generated by analysis tools.
  • Extracted facts about a codebase or dataset.
  • Per-session indexes.
  • Cached workflow context.

Approvals​

Use approvals when a workflow must pause until a reviewer or policy actor decides whether the next step may proceed.

Good uses:

  • Promotion to a durable state.
  • Sensitive changes.
  • High-impact automated modifications.
  • Human signoff requirements.

A strong review flow usually looks like this:

  1. Create or fork a session for proposed work.
  2. Make changes.
  3. Publish a concise summary through annotations, bus events, or both.
  4. Attach any evidence or supporting metadata needed for review.
  5. Request approval if required.
  6. Persist, export, or merge only after the review condition is satisfied.

Choosing the right surface​

Use this rule of thumb:

  • Use annotations when the information should remain attached to the session or file as durable metadata.
  • Use the message bus when the information is event-oriented or should be consumed by live listeners.
  • Use the knowledge cache when the data is structured tool output that another workflow step will retrieve later.
  • Use approvals when the information should control whether another action may happen.

Multi-actor patterns​

Human plus automation​

Automation performs inspection or proposes edits. A human reviews annotations, bus messages, or a mounted filesystem view, then approves or rejects the next step.

Agent fan-out​

A controller creates one session per attempt or per task slice, then aggregates outputs through annotations, cache entries, or session metadata.

Review branch model​

One session stays stable as the baseline. Forked sessions hold proposed changes. Reviewers compare or inspect the forks before selecting what to persist.

Collaboration design guidance​

When building on AetherFS:

  • Keep the filesystem for actual content.
  • Keep workflow state in annotations, approvals, messages, or knowledge entries.
  • Use explicit state transitions instead of hidden conventions.
  • Treat review metadata as first-class data, not just logs.

That separation makes integrations easier to automate, audit, and evolve.