netsky: topology and taxonomy

Topology is where authority, work, and failure live. Taxonomy is how agents compress that shape into short, durable instructions.

topology #

• S5 policy: the base prompt plus the cwd addendum.
• S4 intelligence: agent0 meta-work, session notes, and self-improvement.
• S3 control: agent0 orchestration, pipeline control, and collation.
• S3* audit: direct spot-checks of clone output before merge.
• S2 coordination: workspace isolation, merge cascades, and per-workspace cwd.
• S1 operations: clones and spawned subsystems doing concrete work.
• watchdog: agentinfinity keeping agent0 alive and repairing broken state.

That mapping is in the policy file, not a diagram in someone’s head (src/crates/netsky-prompts/prompts/base.md:20).

flowchart TB
    Owner[owner]
    A0[agent0: S3 control]
    S4[S4: notes + meta-work]
    S5[S5: prompt + addenda]
    INF[agentinfinity: watchdog]
    TICK[netsky-ticker]

    subgraph Ops[S1 operations]
        A1[agent1]
        A2[agent2]
        AN[agentN]
    end

    subgraph Coord[S2 coordination]
        WS[workspaces]
        BR[branches]
        TMUX[tmux cwd]
    end

    Owner <--> A0
    S5 --> A0
    A0 <--> S4
    A0 --> Coord
    Coord --> Ops
    A0 -. S3* audit .-> Ops
    TICK --> INF
    INF --> A0
    INF --> Owner

One machine has one root. agent0 is the root orchestrator. It interfaces with the owner and owns meta-work on the in-tree checkout (src/crates/netsky-prompts/prompts/base.md:32).

agent1..agentN are clones. They have the same capability but a distinct identity. Their work lives in fresh workspaces and dedicated branches (src/crates/netsky-prompts/prompts/base.md:33).

agentinfinity is the watchdog. It keeps agent0 alive through an external tick, handles planned restarts, handles crash recovery, and pages the owner on red signals (src/crates/netsky-prompts/prompts/base.md:34).

Each agent lives in tmux as agent<N> or agentinfinity. The launch command can bring up agent0, N clones, and the watchdog. Attach targets are named after those sessions (src/crates/netsky-prompts/prompts/base.md:36).

The authority arrow is one-way. Clones treat agent0 as user, with judgment. Agent0 outranks clones (src/crates/netsky-prompts/prompts/base.md:37).

That rule matters more than it looks. Clones-of-clones create an audit failure. A root dispatches work, a clone writes output, and agent0 harvests or rejects it. If clones spawn more clones, the chain stops being human-readable. The system gains apparent throughput and loses accountability.

Workspace isolation is the other half. Work uses workspaces/<task-name>/. Fresh clone first. Dedicated branch second. Third-party checkouts under gh-org/ stay read-only (src/crates/netsky-prompts/prompts/base.md:38).

Isolation gives S2 a physical surface. A branch can be pushed. A commit can be cherry-picked. A workspace can be deleted. A dirty tree can be ignored if it belongs to another unit. Coordination becomes a file path and a branch name.

Cross-machine topology keeps the same shape. iroh extends the envelope shape over QUIC and TLS 1.3. It treats remote traffic with the same untrusted-data posture as local inboxes (src/crates/netsky-prompts/prompts/base.md:48).

Two machines do not become one flat swarm. They become a network of constellations. Root talks to root. Each root keeps authority over its own clones.

taxonomy #

core nouns - what is running #

Source: src/crates/netsky-prompts/prompts/base.md:149.

Those words prevent a common failure. “Agent” is too broad. It can mean the root, a clone, a runtime, a model, or a process. agent0 and clone remove the ambiguity.

control verbs - how work moves #

Source: src/crates/netsky-prompts/prompts/base.md:160.

These are not synonyms for “ask.” A dispatch has a target, a workspace, a branch, a gate, and a deliverable. A critique has an adversarial role. Collation means the root keeps judgment instead of pasting summaries together.

commands - operational transitions #

Source: src/crates/netsky-prompts/prompts/base.md:168.

state - diagnosis words #

Source: src/crates/netsky-prompts/prompts/base.md:179.

The difference between stale and wedged is operational. A stale clone may need a ping. A wedged clone may need a kill. A parked clone needs neither. Precise state words save action.

tempo - how time is spent #

Source: src/crates/netsky-prompts/prompts/base.md:190.

Tempo needs names because autonomous work drifts without a clock. “Keep the pipeline full” is a policy. “Send every milestone” is a cadence. “Launch the next wave” is a coordination act.

why this shape #

The VSM is useful because it has survived fifty years of management fashions and is still concrete enough to assign failure. S1 does the work. S2 prevents collision. S3 allocates and harvests. S3* audits. S4 models the future. S5 holds identity.

That beats an “orchestrator hierarchy” because it names the missing paths. A tree of workers explains command flow. It does not explain audit, future modeling, policy, or pain signals.

One-way authority keeps the audit trail readable. Agent0 can be wrong. Clones can push back. The root still owns the final action. That gives the owner one accountable party.

Fresh workspaces make coordination inspectable. The question is not “what did the swarm do?” The question is “which branch, which commit, which gate?” That question has a shell answer.

Named states make failure cheap to report. “Stale” says liveness. “Wedged” says I/O. “Parked” says intent. “Viable” says progress. Vague adjectives create follow-up messages. The taxonomy removes them.

Named tempo keeps the system active. A wave is parallel work. A pipeline is backlog plus in-flight work. A cadence is the report rhythm. Without those words, time management turns into vibes.