Create DESIGN.md

docs/DESIGN.md

@@ -0,0 +1,575 @@
+Exoshell Design Document (Draft v0.1)
+
+Overview
+
+Exoshell is a local-first cognitive shell for practitioners.
+
+It is designed for engineers, operators, hackers, and technical users who want AI augmentation without surrendering understanding, agency, or operational control.
+
+Exoshell is not an autonomous coding employee.
+
+It is not designed to maximize software generation throughput at the expense of comprehension.
+
+It is not optimized for “vibe coding.”
+
+Exoshell exists to enhance skill, preserve flow-state, increase operational awareness, and keep the human firmly in control of the machine.
+
+The philosophy is simple:
+
+Manual Supra, not Waymo.
+
+The operator remains the pilot.
+
+⸻
+
+Core Principles
+
+1. The Human Keeps The Controls
+
+Exoshell augments operators. It does not automate them away.
+
+The system should prefer:
+
+* suggestion over execution
+* visibility over hidden behavior
+* review over blind action
+* composability over abstraction
+* understanding over delegation
+
+Exoshell should never create the feeling:
+
+“oh god, it’s doing something.”
+
+The user should always feel:
+
+* oriented
+* informed
+* in control
+* capable of intervention
+
+⸻
+
+2. Enhance Skill. Do Not Replace It.
+
+Exoshell is intentionally designed for practitioners who want to preserve and deepen technical understanding rather than delegate it away.
+
+The system should:
+
+* teach
+* explain
+* preserve context
+* encourage operational literacy
+* surface better tools when appropriate
+
+The system should not:
+
+* encourage dependency
+* obscure systems
+* normalize blind patch acceptance
+* encourage unreviewed giant rewrites
+
+Exoshell is anti-skill-atrophy software.
+
+⸻
+
+3. Prefer Existing UNIX Tools
+
+Exoshell respects the shell ecosystem.
+
+If awk, sed, jq, rg, fd, grep, git, make, or existing UNIX tooling is the correct solution, Exoshell should say so.
+
+Example:
+
+Signal high:
+awk is likely the correct tool here.
+Suggested:
+awk '{print $3}'
+
+Exoshell should never force AI into workflows where deterministic tooling is superior.
+
+⸻
+
+4. Preserve Flow-State
+
+Flow is sacred.
+
+Exoshell exists to preserve:
+
+* momentum
+* orientation
+* awareness
+* context
+* operational continuity
+
+The system should feel:
+
+* calm
+* responsive
+* intentional
+* instrument-like
+
+Not:
+
+* noisy
+* attention-seeking
+* chaotic
+* overbearing
+
+⸻
+
+5. Calm Software
+
+Exoshell should feel like:
+
+* a tuned workstation
+* a mech cockpit
+* a trusted operator console at 2am
+
+Not:
+
+* a startup dashboard
+* a productivity app
+* a social platform
+* a gamified assistant
+
+The UI should be:
+
+* restrained
+* high signal
+* information dense without clutter
+* aesthetically intentional
+
+⸻
+
+6. Visible Systems
+
+Exoshell should expose:
+
+* uncertainty
+* reasoning context
+* operational state
+* diffs
+* command execution
+* memory usage
+* signal quality
+
+Users should never be forced to trust hidden machinery.
+
+⸻
+
+Non-Goals
+
+Exoshell is explicitly NOT:
+
+* a “vibe coding” platform
+* a beginner-first abstraction layer
+* an autonomous software engineer
+* a manager dashboard
+* a telemetry surveillance platform
+* a cloud lock-in product
+* an AI social platform
+* an attempt to replace the shell
+* a passive screen-watching assistant
+* a hidden-memory behavioral profiling system
+
+Exoshell deliberately makes certain workflows harder:
+
+* blind autonomous rewrites
+* opaque execution
+* no-review patching
+* hidden context accumulation
+* dependency-forming abstraction
+* cloud-dependent workflows
+* automation without understanding
+
+⸻
+
+Inspirations
+
+Exoshell is directly inspired by:
+
+GNU / UNIX Philosophy
+
+* composability
+* inspectability
+* textual interfaces
+* user freedom
+* small understandable pieces
+
+Emacs
+
+* infinite hackability
+* modes
+* user ownership
+* software as living environment
+
+Vim / Neovim
+
+* speed
+* precision
+* modal interaction
+* mastery through repetition
+* config culture
+
+Arch Linux
+
+* explicit control
+* user responsibility
+* composability
+* “build your own machine”
+
+Gentoo
+
+* deep tuning
+* obsessive configurability
+* understanding through construction
+* practitioner culture
+
+tmux / htop / lazygit / fish
+
+* operational calm
+* cockpit UX
+* high information density
+* humane interaction
+
+⸻
+
+User Archetype
+
+The canonical Exoshell user is:
+
+* terminal-native
+* technically curious
+* workflow-oriented
+* skeptical of hidden automation
+* interested in improving over time
+* willing to tune their environment
+* interested in understanding systems rather than merely operating them
+
+Examples:
+
+* SREs
+* systems programmers
+* security engineers
+* infrastructure engineers
+* shell enthusiasts
+* local-first AI practitioners
+* people who think modern AI tooling is moving too fast toward opaque automation
+
+⸻
+
+Interaction Philosophy
+
+Primary Model
+
+Exoshell is shell-adjacent.
+
+The shell remains primary.
+
+Exoshell operates as:
+
+* a cognitive overlay
+* operational instrumentation
+* contextual augmentation
+
+The operator alternates fluidly between:
+
+* direct shell interaction
+* Exoshell prompting
+* command review
+* contextual follow mode
+
+The system should feel collaborative, not supervisory.
+
+⸻
+
+Core Interaction Loop
+
+human explores system
+↓
+Exoshell observes context
+↓
+Exoshell augments awareness
+↓
+human requests action or insight
+↓
+Exoshell suggests command or interpretation
+↓
+human reviews/accepts/modifies
+↓
+Exoshell interprets results
+↓
+flow continues
+
+⸻
+
+Command Semantics
+
+By default:
+
+* Exoshell suggests commands
+* the user executes them
+* execution is explicit
+* destructive actions require confirmation
+
+Actions may include:
+
+* paste suggestion
+* paste + execute
+* explain command
+* return stdout/stderr to model
+* generate patch
+* review diff
+
+⸻
+
+Signal Strength
+
+Exoshell surfaces uncertainty as “signal strength.”
+
+Examples:
+
+* signal: weak
+* signal: medium
+* signal: high
+
+Low-confidence claims should be clearly surfaced.
+
+The system should prefer:
+
+* clarification
+* scoped suggestions
+* partial certainty
+
+over hallucinated confidence.
+
+⸻
+
+Stances
+
+Stances define operational behavior.
+
+Examples:
+
+* operator
+* audit
+* drift
+* teach
+* quiet
+* cockpit
+
+Stances affect:
+
+* verbosity
+* interruption frequency
+* skepticism
+* pacing
+* explanation depth
+* operational posture
+
+Stances are NOT personalities.
+
+⸻
+
+Personalities
+
+Personalities define aesthetic and expressive behavior.
+
+Examples:
+
+* minimalist
+* mech pilot
+* magical girl
+* sleepy night operator
+* UNIX gremlin
+
+Personality affects:
+
+* wording
+* cadence
+* flavor
+* atmosphere
+
+Personality should never compromise:
+
+* operational clarity
+* structured output
+* shell composability
+
+⸻
+
+Memory Philosophy
+
+Memory is operational, not behavioral.
+
+Exoshell should remember:
+
+* repo structure
+* workflows
+* troubleshooting knowledge
+* active task context
+* useful operational discoveries
+
+Memory should NOT silently accumulate:
+
+* invasive behavioral profiling
+* emotional manipulation data
+* opaque long-term surveillance context
+
+Memory should be:
+
+* inspectable
+* scoped
+* editable
+* searchable
+* removable
+
+Memory scopes may include:
+
+* global
+* repo
+* task
+* session
+* ephemeral
+
+⸻
+
+Logging Philosophy
+
+Logs exist for:
+
+* transparency
+* operational continuity
+* searchable notes
+* runbook generation
+* learning
+* debugging
+
+Logs should be:
+
+* human-readable
+* text-based
+* compact by default
+* optionally verbose
+
+The preferred format is markdown-oriented notebook logging.
+
+Exoshell should preserve:
+
+* discoveries
+* command outcomes
+* architectural observations
+* troubleshooting notes
+
+Not raw “session replay.”
+
+⸻
+
+Local-First Philosophy
+
+Exoshell is designed local-first.
+
+Reasons:
+
+* user sovereignty
+* reliability
+* privacy
+* hackability
+* reduced lock-in
+* stronger runtime design pressure
+
+Cloud models are supported as optional backends, not architectural assumptions.
+
+Designing for weaker local models encourages:
+
+* better orchestration
+* better context handling
+* better uncertainty semantics
+* better UX
+
+⸻
+
+Visual Language
+
+Exoshell should feel like:
+
+* a mech cockpit
+* a terminal workstation
+* a tactical HUD
+* an operator console
+
+The visual language should emphasize:
+
+* restrained palettes
+* monochrome foundations
+* selective highlights
+* tasteful box drawing
+* dense but readable layouts
+* calm instrumentation
+
+Not:
+
+* dashboard clutter
+* excessive animation
+* startup aesthetics
+* “AI toy” visual language
+
+⸻
+
+Technical Direction (Initial)
+
+Likely stack:
+
+* Rust
+* Ratatui
+* Crossterm
+* Tokio
+* tree-sitter
+* PTY integration
+* markdown-based logging
+* local model adapters
+* OpenAI-compatible providers
+
+The shell remains external in v1.
+
+Exoshell lives beside the shell rather than replacing it.
+
+⸻
+
+Cultural Direction
+
+Exoshell is practitioner software.
+
+It should encourage:
+
+* workflow craftsmanship
+* configuration culture
+* literacy
+* experimentation
+* user ownership
+* local-first values
+* composability
+* sharing tuned environments
+
+The project should resist:
+
+* enshittification
+* surveillance incentives
+* cloud dependence
+* manager-oriented analytics
+* skill erosion
+
+Exoshell should feel:
+
+* configurable like Emacs
+* precise like Vim
+* intentional like Arch
+* obsessively tunable like Gentoo
+
+⸻
+
+Sacred Rule
+
+Enhance skill. Do not replace it.
+
+Everything in Exoshell should reinforce this principle.