selfware

SKILL.md

# Selfware Protocol

    A file is an app. Everything is a file.
    
    Selfware defines a unified file protocol for the Agent era: within the same distributable unit (a single file or a .self package), data, logic, and views MAY be bundled together; through distributed, decentralized Agent collaboration and self-contained human–machine interaction, it forms collaboration relationships between human↔Agent and Agent↔Agent; returning files to users so they never become obsolete and can evolve indefinitely.

Version: 0.1.0 (Draft)

License (Optional): MIT — you MAY modify, redistribute, and create derivatives.

    Edition note (Non‑Normative): selfware.md and selfware.en.md are the v0.1.0 Draft bilingual editions of the Selfware protocol. We aim to keep them in sync; if you find a mismatch, please open an issue or PR.

Unless marked as “Non‑Normative”, this document uses RFC-style terms:

    MUST / MUST NOT
    SHOULD / SHOULD NOT
    MAY

## 1. Canonical Data Authority

Selfware does not require that a “protocol/app” must be authored as a single file. Instead, it requires that every Selfware instance explicitly declares and strictly follows its Canonical Data Source.

For a Selfware instance, the source of truth (Canonical Data) MUST come from exactly one of these two sources:

    Local Canonical Data: within the instance’s content/ scope (the default write scope).
    Remote Canonical Data: a remote data source explicitly declared in manifest.md (e.g., an http(s)/git pointer), with sync/cache/merge policy defined by the runtime (and still subject to No Silent Apply + rollback requirements).

Constraints (MUST):

    Kernel, Views, Assets, Skills, etc. are runtime implementations and MAY be replaced or regenerated by an Agent.
    Views MUST NOT become a source of truth (i.e., MUST NOT hardcode Canonical Data into view files as the only source).
    Any action that changes Canonical Data MUST land within content/ (or an equivalent canonical landing scope declared by the manifest) and be rollbackable; remote changes MUST NOT be silently applied without user confirmation.

Compared to traditional software: traditional software usually separates “data” and “logic/view”, where logic and view are controlled by a small number of vendors via closed clients/services, creating a de‑facto monopoly over files and ecosystems. Selfware removes this monopoly by allowing data + logic + views to optionally live in the same file (or the same distributable package) and by enabling decentralized running and distribution. The protocol itself is optionally MIT‑licensed: you can modify, redistribute, and create derivatives. This is a unified file protocol for the Agent era.

## 2. Canonical Data

In this demo, Canonical Data is:

    content/selfware_demo.md (text/Markdown; read/edit/save from the front-end)

Notes:

    content/ is the instance’s canonical data scope / default write scope. Collaboration, saving, merging, etc. default to writing here.
    An instance MAY declare Remote Canonical Data in manifest.md as a fetch/sync source for its Canonical Data.

Remote Canonical Data (examples; examples only; not defaults):

    Remote Canonical: https://floatboat.ai/selfware.md
    Remote Canonical: git:https://github.com/floatboatai/selfware.md

Implementation constraints (MUST):

    If Remote Canonical Data is enabled, the runtime MUST declare its policy (read-only / sync / merge) and MUST follow 6.3 No Silent Apply (disclose logic + summary/diff + rollback point + user confirmation).

Selfware allows Canonical Data to be any type (non‑exhaustive):

    Text / Markdown
    JSON / YAML
    Binary (images, audio, video)
    Database files (SQLite, etc.)
    Code and project files
    Office documents (docx, etc.)

An implementation MUST define the read/write shape of Canonical Data (text, byte stream, or a named resource set).

## 3. View as Function

Any view MUST be treated as a function:

    View = f(Data, Intent, Rules)

Where:

    Data comes from Canonical Data
    Rules are defined by this file (or extensions allowed by this file)
    Views MUST NOT become a source of truth (i.e., MUST NOT hardcode Canonical Data into view files as the only source)

## 4. Runtime API

The Kernel MUST bind to loopback only (localhost/127.0.0.1/::1) unless the user explicitly configures a wider boundary.

This demo’s API:

    GET /api/content -> { "content": "<content/selfware_demo.md>" }
    POST /api/save with { "content": "<content/selfware_demo.md>" } -> { "status": "success" }
    GET /api/self -> { "path": "...", "sha256": "...", "content": "<content/selfware_demo.md>" }
    GET /api/manifest -> { "content": "<manifest.md>" }
    GET /api/capabilities -> runtime capability declaration (see 4.1)
    GET /api/check_update?url=... -> check whether a remote protocol source has updates (see 6)

Write boundary (MUST):

    POST /api/save MUST only write within content/ (canonical data scope)
    The runtime MUST NOT write selfware.md unless the user has explicit intent and confirmation

### 4.1 Capability Declaration

The runtime MUST declare its capabilities so users and other Agents can understand boundaries and interaction.

The declaration MUST include at least:

    write_scope: where writes are allowed (in this demo: content/)
    confirmation_required: actions that require user confirmation (e.g., pack, pull/merge, apply update, publish, send context)
    endpoints: available endpoints and their purpose (content R/W, update checks, packaging, etc.)
    modules: optional module status (e.g., whether git/discovery/self‑analysis is supported/enabled)

The declaration MUST be exposed via at least one carrier:

    Machine-readable (e.g., GET /api/capabilities)
    Human-readable (e.g., printed on startup, or a UI panel)

Interaction constraints (MUST):

    If the runtime/Agent discovers “a capability is supported but not enabled / missing config / has multiple strategy branches” (e.g., enabling remote collaboration, enabling Discovery, performing publish, recording runs), it MUST ask the user and obtain explicit confirmation before performing any action that produces writes or outbound communication.
    Any writes/applications triggered by such prompting MUST still satisfy: write scope (content/) and Change Record requirements.

## 5. Discovery

Example Discovery endpoint (example only; not a default):

    https://floatboat.ai/discovery/
    https://github.com/awesome-selfware/awesome-selfware (a GitHub index repo for discovering Selfware/Skills/Practices ecosystem entries)

Goal: with user permission, carry “intent + partial context” to discover better solutions (not just search).

A Discovery request SHOULD include:

    Intent: the current goal (e.g., update, recommend, fix_overflow, export_cards)
    Partial Context: the smallest directly relevant info set, e.g.:
        goal
        state / progress
        logs (optional; MUST be trimmable and redactable)

Permissions (MUST):

    Any Discovery request that includes context MUST be sent only with explicit user consent.
    By default, it SHOULD send only the minimal necessary context; higher-granularity context MUST require additional authorization.

Discovery responses MAY return (non‑exhaustive):

    a better Selfware (a complete solution file/template)
    one or more Skills (reusable workflows)
    code snippets / patch suggestions
    other artifacts consumable by Agents (rule fragments, view templates, configs, etc.)

Discovery trigger points (runtime SHOULD; but MUST support explicit user trigger):

    On Start
    On Explicit Update Intent
    On Missing Capability
    On Error Recovery
    On User Request

## 6. Official Protocol Source & Updates

### 6.1 Protocol Source

This file MAY declare an “official protocol source” (for update checks only; does not override local authority):

    Protocol Source: https://floatboat.ai/selfware.md
    Protocol Source (GitHub): https://github.com/floatboatai/selfware

### 6.2 Update Check

If update checking is enabled, the runtime MUST check at one of:

    On Start (every run), or
    On User Request

Checks SHOULD use ETag/Last‑Modified or content hashes. This demo provides /api/check_update and a diff summary.

### 6.3 No Silent Apply

If an update is detected, the runtime MUST:

    Explain the update logic (where it’s fetched from, how it’s compared, how it’s applied, how to roll back)
    Provide an update summary (at least title + summary; provide changelog/diff if available)
    Ask for user confirmation (Accept/Reject/Defer)
    Apply only after Accept; Reject MUST keep the current version runnable

## 7. Local Versioning (Git)

Selfware local files SHOULD use Git for versioning (local repo is sufficient; remote optional):

    Before applying any update (official source, Discovery, or collaboration backend), the runtime SHOULD create a rollback point (prefer Git commit/tag; otherwise backups).
    Any “auto pull/merge remote” behavior MUST follow 6.3 (No Silent Apply).

## 8. Collaboration (Git / Custom)

Beyond local versioning, Selfware MAY configure a collaboration backend for multi‑person sync. The backend does not change the definition of selfware.md as protocol authority. Writes land in content/.

### 8.1 Git Collaboration

An instance (especially content/) MAY collaborate via Git (remote optional, e.g. GitHub):

    Collaboration: git
    Remote: <git remote url>
    Ref: <branch|tag|commit> (optional; default main/master is implementation-defined)

If Git collaboration is enabled, the runtime MUST:

    Check whether remote has updates on On Start or On User Request (implementation MAY choose one, but MUST support explicit user trigger).
    If updates exist, follow 6.3 No Silent Apply before pulling/merging.
    Create a rollback point before merge (prefer Git commit/tag; otherwise backups).
    If conflicts occur, stop automatic apply and ask the user for a resolution strategy (manual/assisted/abort).

### 8.2 Custom Collaboration

Selfware MAY use a custom collaboration service:

    Collaboration: custom
    Endpoint: <service url>

Regardless of backend:

    write boundaries MUST remain (only write to content/ or an explicitly allowed subset)
    any sync/merge that changes local selfware.md MUST be preceded by user confirmation and explanation (per 6.3)

## 9. Packaging (.self container)

### 9.1 Container Format

A .self file MUST be a ZIP container (compatibility first; it must be unpackable by standard unzip tools).

Inside, it MUST include:

    self/manifest.md

self/manifest.md MUST include at least:

    Selfware-Container: zip
    Selfware-Container-Version: 1
    Protocol-Source: https://floatboat.ai/selfware.md (example; replaceable)
    Local-Protocol-Path: selfware.md
    Canonical-Data-Scope: content/

The protocol MAY evolve to new container types/versions; implementations MUST handle compatibility via Selfware-Container-Version or fail explicitly.

### 9.2 Pack Policy

Packing is writing a Selfware project directory into a .self container. Implementations MUST:

    Declare pack scope: include/exclude rules (glob or explicit paths) and define a minimal required set.
    User confirmation: before writing the .self, MUST show:
        final included file list (or tree) and total size
        exclude rules summary (and key excluded items)
        output target path (*.self)
        and allow Accept/Reject.
    Write boundaries: pack MUST NOT modify selfware.md. If self/manifest.md is generated, generate it inside the container without writing back to the repo (unless user explicitly requests).

Default excludes (SHOULD as a safety baseline; instances MAY override/extend):

    .DS_Store
    __pycache__/, *.pyc
    node_modules/, .venv/
    dist/, build/
    output/, *.log, *.tmp
    .git/ (unless user explicitly includes)

### 9.3 Pack Plan Placement

The pack protocol (format + policy) is defined by this file.

An instance’s “pack plan” SHOULD live in an instance self-description file (e.g., manifest.md, or a dedicated section inside Canonical Data) to:

    avoid locking into a repo structure
    allow different instances to declare different include/exclude/required

This demo places its pack plan in manifest.md.

### 9.4 Sharing / Distribution

To share a Selfware project, you SHOULD pack the whole directory into a ZIP and name it with a .self suffix (e.g., my_project.self).

Benefit: you share a “living document / living app”. If the receiver is a trusted collaborator and has access to the collaboration backend within your permission boundary (e.g., GitHub repo access), then when they open the Selfware they can check for updates and, after user confirmation, pull/merge to stay aligned with the latest version.

## 10. Memory (Optional)

Memory is a set of auditable context files maintained under content/, used to:

    record conversations, decisions, changes, and run traces
    support collaboration and retrospection (humans and Agents)
    provide minimal necessary context for Discovery/update decisions, with user permission

Memory MUST NOT become the protocol authority; the protocol authority is selfware.md.

### 10.1 Placement

If enabled, instances SHOULD use:

    content/memory/

Implementations MAY use a single file (e.g., content/memory.md), but a multi-file structure is better for permission splitting and minimization.

### 10.2 File Self‑Description

Each Memory file MUST include metadata at the top explaining “who I am / what I record / how to update me”.

Two allowed formats:

    YAML front matter (recommended; still Markdown):

---
selfware:
  role: memory_chat | memory_changes | memory_decisions | memory_runs | custom
  title: "..."
  purpose: "..."
  scope: "what is included / excluded"
  update_policy: "append_only | editable | generated"
  owner: "user | team | agent"
  created_at: "YYYY-MM-DDThh:mm:ssZ"
  updated_at: "YYYY-MM-DDThh:mm:ssZ"
---

    A ## Meta section (same fields; key-value lines).

### 10.3 Change Metadata

For any change to any instance file (including content/, views/, server.py, manifest.md, etc.), the implementation MUST record a Change Record to content/memory/changes.md (or an equivalent location).

Each Change Record MUST include at least:

    id (unique)
    timestamp
    actor (user / agent / service)
    intent
    paths (affected file list)
    summary (human-readable)
    rollback_hint (how to roll back: git ref / backup / manual steps)

If Git is used locally, rollback_hint SHOULD point to a concrete Git rollback point (commit/tag/ref).

### 10.4 Discovery Consent & Minimization

When Discovery carries context, Memory MAY be selectively referenced, but MUST:

    be sent only with explicit user consent
    default to minimal fragments (e.g., decision/change summaries rather than full runs/logs)
    support trimming and redaction

## 11. Ecosystem (Optional)

The Ecosystem module defines how Selfware-related artifacts (skills, practices, selfware files, patches) are described, distributed, published, and consumed—without requiring a single centralized vendor.

### 11.1 Artifact Metadata (MUST be self-describing)

An artifact MUST carry metadata including at least:

    id
    title
    type (e.g., selfware / skill / practice / patch / view / template)
    version
    protocol_version_range (compatible Selfware protocol versions)
    applies_to (scope/platform/runtime)
    license
    sha256 (content hash for verifiability)
    provenance (how it was derived; may include hashes)
    distribution (one or more distribution entries: hosted URL, index pointer, git url+ref, etc.)

Optional fields (MAY):

    trust (signing/publisher/verification info; not required, but implementations SHOULD be able to use it for local trust policy)

distribution constraints (MUST):

    MUST include at least one resolvable “fetch hint” (e.g., URL or git: pointer)
    MUST be human-readable, but SHOULD follow machine-extractable prefix conventions

Recommended distribution prefixes (SHOULD):

    hosted: hosted content URL
    index: index entry URL
    git: decentralized pointer (e.g., repo#ref=...:path=...)
    sha256: explicit hash (same as metadata sha256)

sha256 rules (MUST):

    MUST be the SHA‑256 of the artifact content that is fetched and applied (lowercase hex).
    If distributed as hosted text: hash UTF‑8 bytes (no implicit rewrites).
    If distributed as zip/binary container: hash the container bytes.

### 11.2 Publish & Consume Boundaries

Publish:

    Before pushing local know‑how to any external destination (host/index/git), the runtime MUST obtain user confirmation.
    Publish MUST write a Change Record (see 10.3), including where/how it was published and rollback strategy.

Consume:

    Discovery MUST return a candidate artifact list + metadata; it MUST NOT silently apply anything.
    Runtime/Agent MUST let the user (or their delegate) choose, and then follow 6.3 No Silent Apply (logic + summary/diff + rollback point + user confirmation).

### 11.3 Ecosystem Repo Convention (SHOULD)

For decentralized ecosystem building and indexing, ecosystem repos SHOULD use top-level directories:

    selfware/
    skills/
    practices/

This convention is for “ecosystem repos” (publishing/sharing repos), not mandatory for normal .self instances.

## 12. Self‑Analysis (Optional)

Self‑Analysis is an optional module that extracts know‑how from an instance’s progress and changes, and—under user permission—closes an evolution loop with Discovery/ecosystem publishing.

This chapter defines only protocol boundaries and outputs; implementation details are runtime-specific and replaceable.

### 12.1 Inputs

Self‑Analysis MAY read (non‑exhaustive):

    Canonical Data (e.g., content/selfware_demo.md)
    Memory files (e.g., content/memory/changes.md, content/memory/decisions.md) if enabled
    manifest.md (pack plan, runtime conventions)
    runtime files (e.g., server.py, views/) for consistency/boundary scanning

Self‑Analysis MUST respect write boundaries: it MUST NOT bypass the protocol to write selfware.md; any writes MUST land within the instance’s allowed scope (in this demo: content/).

### 12.2 Outputs (MUST be file-based)

Self‑Analysis outputs MUST be materialized as files, auditable and rollbackable. Outputs MAY include:

    insights (conclusions and executable recommendations)
    drafts of practices/skills/selfware/patch artifacts (for local review before publishing)
    discovery request drafts (intent + minimal context)
    publish queues (artifact list with sha256 and distribution drafts)

Any output writes MUST be recorded as Change Records (see 10.3).

### 12.3 Consent & Loop

Self‑Analysis may trigger Discovery or publishing, but MUST:

    obtain explicit user consent before sending anything to external endpoints
    default to minimal necessary context (and allow user selection/trimming)
    apply updates only via 6.3 No Silent Apply

### 12.4 Trigger Freedom

Trigger points are implementation-defined (On Start / On User Request / On Significant Change, etc.). The protocol requires:

    MUST support explicit user trigger
    MUST record key actions and rollback points (via Change Records)

## Non‑Normative

In this repository, views/, server.py, assets/, skills/ demonstrate a minimal loop: the same Markdown projected into multiple views + saved back.

The content/ directory is demo instance data (fixtures/experiments) and is the instance’s Canonical Data write scope, but it is not the protocol authority (the protocol authority is selfware.md).