-
Notifications
You must be signed in to change notification settings - Fork 0
Architecture
Weave Skills is a filesystem-native operational system for long-running engineering workflows.
The architecture intentionally prioritizes:
- filesystem authority
- implementation grounding
- bounded semantics
- deterministic-safe runtime behavior
- and dense operational capabilities
inside real engineering repositories.
This document is the authoritative source for the following architectural invariants:
-- filesystem authority -- layer separation -- runtime authority -- bounded semantics -- symbolic semantics -- dense operational capabilities -- implementation grounding -- anti-ontology positioning -- anti-graph positioning
Operational documents SHOULD reference these invariants rather than re-explaining them.
The system intentionally converged toward:
small
dense
operational
filesystem-native
implementation-grounded
contextually bounded
rather than:
large
fragmented
graph-centric
ontology-driven
platform-oriented
The filesystem remains authoritative.
Repository structure preserves:
- locality
- implementation context
- operational relationships
- workflow continuity
Skills operate as lightweight operational capabilities on top of real filesystem structures.
The repository intentionally avoids repository-wide semantic ownership.
The architecture intentionally separates responsibilities across layers.
| Layer | Responsibility |
|---|---|
| Filesystem | authoritative structure |
| Runtime | invariants |
| Serializer | canonical structure |
| Skills | operational capabilities |
| Agents | inference |
This separation stabilizes:
- operational reasoning
- contextual continuity
- deterministic behavior
- bounded semantics
The runtime preserves invariants.
Agents perform inference.
The runtime is responsible for:
- normalization
- validation
- canonical serialization
- deterministic-safe editing
- semantic consistency
Skills and agents MUST NOT:
- mutate runtime semantics
- own repository structure
- replace serializer authority
- or preserve invariants independently
Semantic participation is intentionally bounded.
Recommended semantic root:
.context/notes
Only files inside semantic scope:
-- participate in symbolic semantics -- support semantic navigation -- participate in contextual reasoning
Files outside semantic scope remain filesystem-native operational artifacts.
Core invariant:
semantic scope != filesystem scope
This preserves bounded contextual reasoning while preventing repository semanticization.
Wikilinks operate as:
bounded symbolic contextual references
They are NOT:
- ontology relationships
- graph-authoritative edges
- repository-global semantic ownership structures
The graph MAY emerge naturally from symbolic references.
The graph MUST remain secondary to:
- filesystem authority
- implementation grounding
- runtime determinism
- operational locality
Skills are:
portable operational capabilities
A skill modifies:
-- contextual reasoning -- operational heuristics -- workflow continuity -- implementation-grounded reasoning
inside a workspace.
A skill represents:
a distinct operational capability mode
NOT:
- a capability fragment
- a taxonomy unit
- a philosophy fragment
- or a conceptual decomposition
The architecture intentionally favors:
few dense operational overlays
rather than:
many fragmented conceptual overlays
This minimizes:
- overlap
- capability fragmentation
- activation ambiguity
- prompt inflation
- token waste
while improving:
-- trigger stability -- contextual continuity -- reasoning coherence -- operational survivability
Contextual reasoning remains implementation-grounded.
Operational reasoning stays tied to:
- source code
- runtime behavior
- implementation details
- repository locality
- operational workflows
This preserves:
- contextual realism
- debugging continuity
- implementation traceability
- operational recovery
across long-running engineering workflows.
Recommended shared skill surface:
.agents/skills
Optional namespaced layout:
.agents/skills/weave-skills
This convention intentionally remains:
- lightweight
- portable
- adapter-friendly
- filesystem-native
The repository does NOT define .agents as a formal standard.
Adapters and interoperability patterns are documented in Adapters.
The architecture prioritizes:
long-running operational continuity
inside real engineering repositories.
The system favors:
- workflow continuity
- contextual recovery
- unresolved operational state preservation
- implementation traceability
- deterministic-safe reasoning
across multi-session engineering workflows.