SPEC.md — Exoskeleton MVP

Purpose

Exoskeleton is a repo-local agentic harness for making any software repository inspectable, controllable, searchable, replayable, and safely automatable.

The MVP goal is:

xoskel

from inside any existing repository, resulting in that repository being bootstrapped as an Exoskeleton-aware project.

The first version must not try to be a full autonomous coding agent. It should create the substrate that allows coding agents, local models, repo analysis tools, and future reactive components to operate through an explicit, inspectable harness.

The MVP should establish:

A canonical repo-first project structure.
A deterministic project bootstrap process.
An inspectable context bundle model.
A lightweight journal and event stream.
A searchable index over repo and Exoskeleton artefacts.
Runtime memory as a rebuildable acceleration layer, not a source of truth.
A model-provider abstraction, initially stubbed.
A capability/policy system that constrains future tools and agents.
A command-line UX suitable for repeated local use.

⸻

Core Principle

The repo is the canonical source of truth.

Anything important enough to survive, replay, audit, migrate, or reason about must be represented in the repository as files, commits, refs, notes, journals, manifests, or generated-but-rebuildable artefacts.

Runtime stores such as Turso are permitted, but only as runtime memory, working state, cache, queue, or acceleration layer. They must be rebuildable from repo state.

Search indexes such as Tantivy are permitted, but only as rebuildable derived indexes over repo state and runtime material.

The .git directory is not incidental. It is a major substrate for Exoskeleton:

object database
refs
branches
commits
trees
index
reflog
hooks
notes
worktrees
sparse checkout
diffs
snapshots
provenance
rollback
promotion

Exoskeleton should use Git where Git is the right primitive, rather than hiding important system state in opaque databases.

⸻

MVP Scope

3.1 In Scope

The MVP must provide:

xoskel CLI entrypoint, published as the xoskel npm package.
Repo detection and bootstrap.
.xoskel/ project directory.
AGENTS.md generation or augmentation.
HUMANS.md operator-guide generation or preservation.
xoskel.toml project manifest.
HEAD.md current project cursor/semaphore.
journal/ append-only markdown event log.
context/ bundle format for curated context.
policy/ capability policy files.
index/ derived search index location.
Runtime memory adapter interface.
Search adapter interface.
Model provider interface.
Execution provider interface.
Basic repo scan.
Basic context pack generation.
Basic journal event writing.
Basic local search command.
Dry-run mode.
Idempotent re-runs.
Human-readable output.

3.2 Out of Scope for MVP

The MVP must not attempt to deliver:

full autonomous coding
unrestricted shell execution
complex workflow orchestration
multi-agent recursive loops
embedded Lemonade packaging
full SPINE implementation
full Turso persistence
full Tantivy Rust-native implementation
remote control plane
MCP server/client implementation
WASM or Podman sandbox execution
enterprise identity / RBAC
automatic code modification without explicit user action

These should be designed for, but not required in the first drop.

⸻

User Experience

4.1 Primary Command

From any repository:

xoskel

Expected behaviour:

Detect whether the current directory is a Git repository.
Detect whether Exoskeleton is already installed.
If not installed, create .xoskel/ and related files.
Scan the repository structure.
Generate an initial project profile.
Generate a default context bundle.
Generate a default policy.
Generate or update AGENTS.md, and generate HUMANS.md when it is absent.
Write a journal entry recording the bootstrap.
Print next steps.

Example output:

Exoskeleton bootstrap complete. Created: .xoskel/xoskel.toml .xoskel/HEAD.md .xoskel/context/default.context.md .xoskel/policy/default.policy.toml .xoskel/journal/2026-07-06.bootstrap.md AGENTS.md HUMANS.md Indexed: 184 files 37 source files 9 config files 4 documentation files Next: xoskel status xoskel context show xoskel search "authentication"

4.2 Core Commands

The MVP CLI should support:

xoskel init xoskel status xoskel scan xoskel context build xoskel context show xoskel journal add xoskel search xoskel policy show xoskel doctor

The bare command:

xoskel

should behave as:

xoskel init

when the repo is not yet bootstrapped, and as:

xoskel status

when it already is.

⸻

Generated Repository Structure

The bootstrap should create:

. ├── AGENTS.md ├── HUMANS.md └── .xoskel/ ├── xoskel.toml ├── HEAD.md ├── README.md ├── context/ │ ├── default.context.md │ ├── repo-profile.context.md │ └── prompt-contract.context.md ├── journal/ │ └── YYYY-MM-DD.bootstrap.md ├── policy/ │ ├── default.policy.toml │ └── capabilities.toml ├── manifests/ │ ├── repo.manifest.json │ ├── files.manifest.json │ └── tools.manifest.json ├── runtime/ │ └── README.md ├── index/ │ └── README.md ├── hooks/ │ └── README.md └── schemas/ ├── xoskel.schema.json ├── context.schema.json ├── journal.schema.json └── policy.schema.json

The .xoskel/runtime/ and .xoskel/index/ directories should be placeholders in MVP. Runtime state and indexes may be ignored by Git by default, but their rebuild rules must be documented.

Recommended .gitignore additions:

.xoskel/runtime/* !.xoskel/runtime/README.md .xoskel/index/* !.xoskel/index/README.md

⸻

Canonical Files

6.1 .xoskel/xoskel.toml

The project manifest.

Example:

schema_version = "0.1" project_name = "example-project" xoskel_version = "0.1.0" created_at = "2026-07-06T00:00:00Z" [canonical] source_of_truth = "repo" runtime_memory = "rebuildable" search_index = "rebuildable" [git] required = true use_notes = false use_hooks = false use_worktrees = false [context] default_bundle = ".xoskel/context/default.context.md" preserve_user_intent = true preserve_prompt_contract = true lossless_first = true [journal] enabled = true mode = "append-only-markdown" path = ".xoskel/journal" [search] provider = "local-simple" index_path = ".xoskel/index" future_provider = "tantivy" [memory] provider = "none" future_provider = "turso" role = "runtime-working-memory" [model] provider = "none" future_provider = "lemonade" [execution] provider = "none" future_providers = ["podman", "wasm-wasi"] [policy] default_policy = ".xoskel/policy/default.policy.toml" capabilities = ".xoskel/policy/capabilities.toml"

6.2 .xoskel/HEAD.md

The current project cursor and semaphore.

Purpose:

show current repo state from the harness perspective
provide a stable place for agents to understand current intent
support future workflow cursors
avoid hidden orchestration state

Example:

Exoskeleton HEAD

Current Mode

bootstrap

Current Intent

This repository has been initialised as an Exoskeleton project.

Current Cursor

No active workflow.

Intended Git Branch

main

Last Known Repo Scan

Files scanned: 184
Source files: 37
Config files: 9
Documentation files: 4

Active Context Bundle

.xoskel/context/default.context.md

Notes For Agents

Use AGENTS.md first. Use .xoskel/context/default.context.md as the initial curated context. Do not assume runtime memory is canonical. Do not modify files without showing a diff or writing a journal entry.

Intended Git Branch is the human-declared branch on which the current work is expected to continue. It is recorded at initialization and may be changed only by an explicit operator action. xoskel must never switch branches automatically; a future diagnostic may report a mismatch with the checked-out branch.

6.3 AGENTS.md

If no AGENTS.md exists, create one.

If one already exists, append a clearly delimited Exoskeleton section.

Minimum generated content:

AGENTS.md

Exoskeleton Harness Rules

This repository is Exoskeleton-aware. Canonical project state lives in the repository. Runtime memory, local indexes, caches, and model outputs are derived or temporary unless explicitly committed. Agents should:

Read this file before making changes.
Read .xoskel/HEAD.md for current project intent and cursor.
Use .xoskel/context/default.context.md as the starting context bundle.
Preserve user intent and prompt contracts exactly.
Prefer deterministic analysis before model-based inference.
Produce inspectable diffs before modifying source files.
Write or request a journal entry for meaningful actions.
Treat .xoskel/runtime/ and .xoskel/index/ as rebuildable.
Never treat Turso, Tantivy, local model memory, or temporary tool state as canonical source of truth.
Follow .xoskel/policy/default.policy.toml.

6.3.1 HUMANS.md

HUMANS.md is the concise operator guide for people who develop or operate a repository with Exoskeleton. It is complementary to, not a replacement for, README.md and AGENTS.md:

README.md explains the project to users and contributors.
AGENTS.md is the binding operating contract for agents.
HUMANS.md explains how a human operator uses the Exoskeleton harness and remains the authority for goals, priorities, and consequential decisions.

xoskel init creates a readable starter guide only if the file is absent. It must preserve existing user-authored content and must not silently convert a repository to a prescribed process. The starter guide points operators to the current cursor, policy, context, journal, status, and doctor commands, and states that agents require human authorization where repository policy says so.

6.4 .xoskel/context/default.context.md

The default context bundle.

This should be human-readable and machine-parseable enough for MVP.

Example:

schema_version: 0.1 kind: xoskel.context name: default created_at: 2026-07-06T00:00:00Z source: repo-scan

Default Exoskeleton Context

Prompt Contract

Preserve the user’s immediate intent. Do not conflate repo facts, inferred goals, and generated suggestions. When uncertain, distinguish evidence from inference.

Repo Summary

Generated from initial scan.

Important Files

package.json
README.md
AGENTS.md

Project Structure

Generated tree summary here.

Detected Technologies

Generated technology guesses here.

Agent Instructions

Use this context as a starting bundle only. Request narrower context when the task is specific. Do not assume this file contains the whole repository.

Provenance

Generated by xoskel init.

6.5 .xoskel/policy/default.policy.toml

The default policy should deny active execution by default.

Example:

schema_version = "0.1" name = "default" [defaults] network = "deny" shell = "deny" write_files = "ask" delete_files = "ask" modify_git = "ask" read_repo = "allow" read_xoskel = "allow" write_journal = "allow" write_runtime = "allow" write_index = "allow" [models] local = "allow" remote = "ask" [tools] repo_scan = "allow" context_build = "allow" search = "allow" journal = "allow" shell = "deny" package_install = "ask" test_run = "ask" format_run = "ask" [secrets] read_env = "deny" read_dotenv = "deny" redact_known_patterns = true

6.6 .xoskel/policy/capabilities.toml

This describes capability names before full enforcement exists.

schema_version = "0.1" [capabilities.read_repo] description = "Read files inside the repository." [capabilities.write_repo] description = "Modify files inside the repository." [capabilities.write_journal] description = "Append an Exoskeleton journal entry." [capabilities.search_repo] description = "Search the repo through the local search adapter." [capabilities.runtime_memory] description = "Read or write rebuildable runtime memory." [capabilities.model_inference] description = "Call a configured model provider." [capabilities.execution] description = "Run commands through an execution provider." [capabilities.network] description = "Access network resources."

⸻

Architecture

The MVP should be structured around interfaces, even where implementations are basic.

CLI ├── Bootstrapper ├── RepoScanner ├── ContextBuilder ├── JournalWriter ├── PolicyLoader ├── SearchProvider ├── MemoryProvider ├── ModelProvider └── ExecutionProvider

7.1 Bootstrapper

Responsible for:

detecting Git repo
detecting existing Exoskeleton install
creating .xoskel/
writing canonical files
updating AGENTS.md
running first scan
building first context
writing bootstrap journal entry

It must be idempotent.

Re-running xoskel init should not overwrite user edits unless explicitly requested.

7.2 RepoScanner

Responsible for building:

.xoskel/manifests/repo.manifest.json .xoskel/manifests/files.manifest.json

It should collect:

repo root
current branch
current commit hash, if available
dirty state
file list
file extensions
detected package managers
detected languages
detected frameworks, where obvious
important files
ignored directories
binary files skipped

The scanner should exclude by default:

.git/ node_modules/ dist/ build/ coverage/ target/ vendor/ .venv/ pycache/ .xoskel/runtime/ .xoskel/index/

7.3 ContextBuilder

Responsible for generating context bundles from repo manifests.

The MVP should support only:

xoskel context build xoskel context show

The context builder should produce:

.xoskel/context/default.context.md .xoskel/context/repo-profile.context.md .xoskel/context/prompt-contract.context.md

The context model should carry forward the Context Representation Compiler direction:

intent sovereignty
stable fragment identity
lossless-first representation
raw preservation for instructions and contracts
provenance
deterministic-first transformation
safe fallback to readable text

MVP context does not need compression. It needs structure.

7.4 JournalWriter

Responsible for append-only markdown event logs.

Journal entries should be plain files so they are easy to review, diff, commit, search, and replay.

Example file:

.xoskel/journal/2026-07-06T231500Z.bootstrap.md

Example content:

schema_version: 0.1 kind: xoskel.journal event: bootstrap created_at: 2026-07-06T23:15:00Z actor: xoskel-cli

Bootstrap

Exoskeleton was initialised in this repository.

Actions

Created .xoskel/
Created project manifest
Created default policy
Created default context bundle
Updated AGENTS.md

Repo State

Branch: main
Commit: abc123
Dirty: true

The journal is also the MVP form of passive event recording. Later, SPINE can make journaling a passive subscriber to typed events rather than an explicit workflow step.

7.5 PolicyLoader

Responsible for loading policy files and exposing decisions to the CLI.

MVP only needs read/display and simple internal checks.

xoskel policy show

Future enforcement should happen through capability mediation.

7.6 SearchProvider

MVP provider:

local-simple

This can be implemented with a simple JSON or SQLite-like file index at first.

Future provider:

tantivy

Important principle:

Tantivy is a rebuildable embedded search index over repo and runtime material. It is not canonical.

MVP commands:

xoskel scan xoskel search "query"

Search should include:

source files
markdown files
config files
.xoskel/context
.xoskel/journal
.xoskel/policy
.xoskel/manifests

Search should exclude:

.git
dependencies
build artefacts
binary files
runtime memory
generated index files

7.7 MemoryProvider

MVP provider:

none

Future provider:

turso

The interface should exist from the beginning, but the MVP does not need to persist runtime memory.

Turso’s role is runtime memory service:

working state
run state
temporary agent memory
queues
caches
task state
reflection state
derived relational views

Turso must not become the canonical project database.

Anything important must be serialisable back to repo artefacts.

7.8 ModelProvider

MVP provider:

none

Future providers:

Lemonade
Ollama
OpenAI-compatible endpoint
OpenRouter-compatible endpoint
enterprise control-plane proxy

The interface should distinguish:

local model provider
remote model provider
facilitator model
coding model
summarisation/compression model
embedding model

The important architectural split is:

Lemonade = candidate local model-serving substrate Ornith-style facilitator = scaffold/reflection/adaptation intelligence Coding agent = separate role Exoskeleton = harness, policy, orchestration, context, audit, mediation

The MVP should not embed Lemonade yet, but it should make the provider slot obvious.

7.9 ExecutionProvider

MVP provider:

none

Future providers:

rootless Podman
WASM/WASI
direct shell only when explicitly enabled

Execution must be denied by default.

Future execution rules:

no raw shell by default
workspace-only mounts
network disabled by default
secrets brokered
overlay/diff before commit
audit before repo mutation

⸻

Relationship To Larger Exoskeleton Architecture

The MVP should deliberately leave space for the established larger components.

8.1 FastContext

FastContext is responsible for selecting what matters.

MVP representation:

context bundles
repo manifests
prompt contract
future narrow context packs

8.2 Graphify

Graphify is responsible for explaining relationships.

MVP representation:

repo manifest
file graph placeholder
future dependency graph
future semantic graph
future RDF/LPG projection

8.3 CRC

The Context Representation Compiler is responsible for translating selected context into the most appropriate representation for the task, model, and risk level.

MVP representation:

structured markdown context
provenance
prompt contract preservation
no compression yet

8.4 Dagger

Dagger is responsible for workflow orchestration.

MVP representation:

command structure
journalled operations
future workflow manifest compatibility

8.5 Ponytail

Ponytail is responsible for reusable parsers, codecs, and adapters.

MVP representation:

scanner abstraction
parser interface placeholders
file classification

8.6 SPINE

SPINE is the future secure private signal bus.

MVP representation:

journal as explicit event log
event schema
future passive journaling subscriber

SPINE should eventually support:

typed subscriptions
schema-bound payloads
dynamic URL-based addressing
service locator pattern
secure-by-default delivery
fire-and-forget
acknowledge / negative acknowledge
optimistic delivery
retry
debounce
notify-then-fetch
payload-size controls
timeout controls
duplication and conflation policies

8.7 Git Substrate

The MVP should begin using Git facts immediately.

Minimum:

detect repo root
detect branch
detect commit hash
detect dirty state
avoid overwriting user changes

Future:

git notes for Exoskeleton metadata
worktrees for isolated agent attempts
branches for candidate changes
hooks for passive scanning
reflog-aware rollback
sparse checkout for bounded context
object database for provenance

⸻

Package Design

9.1 Package Name

Primary executable:

xoskel

Package:

{ "name": "xoskel", "bin": { "xoskel": "./dist/cli.js" } }

If the npm name is unavailable, use a scoped package while preserving the command name:

{ "name": "@xoskel/cli", "bin": { "xoskel": "./dist/cli.js" } }

Then users can run:

npx @xoskel/cli

or, if aliases are published later:

xoskel

9.2 Language

The MVP CLI can be TypeScript-first for fast delivery.

Rust can be introduced for high-performance deterministic components later:

Tantivy search provider
high-performance scanning
CRC transforms
policy engine
SPINE core
sandbox runners

9.3 Suggested Internal Structure

src/ cli.ts commands/ init.ts status.ts scan.ts context.ts journal.ts search.ts policy.ts doctor.ts core/ bootstrapper.ts repo-scanner.ts context-builder.ts journal-writer.ts policy-loader.ts project.ts git.ts fs-safe.ts providers/ search/ search-provider.ts local-simple-search-provider.ts memory/ memory-provider.ts none-memory-provider.ts model/ model-provider.ts none-model-provider.ts execution/ execution-provider.ts none-execution-provider.ts schemas/ xoskel.schema.json context.schema.json journal.schema.json policy.schema.json templates/ AGENTS.md HUMANS.md HEAD.md xoskel.toml default.context.md default.policy.toml capabilities.toml

⸻

CLI Command Behaviour

10.1 xoskel init

Options:

xoskel init xoskel init --dry-run xoskel init --force xoskel init --yes

Rules:

Must require Git repo unless --no-git is later added.
Must not overwrite existing files unless --force.
Must preserve existing AGENTS.md.
Must append delimited Exoskeleton block if AGENTS.md exists.
Must write journal entry.
Must run scan unless --no-scan is later added.

10.2 xoskel status

Shows:

Exoskeleton installed or not
manifest path
active context bundle
journal count
current branch
current commit
dirty state
policy summary
search index state

10.3 xoskel scan

Regenerates manifests.

Options:

xoskel scan xoskel scan --json xoskel scan --write

Default should write manifests and journal the scan.

10.4 xoskel context build

Regenerates context bundles.

Options:

xoskel context build xoskel context build --name default xoskel context build --dry-run

10.5 xoskel context show

Prints current active context bundle.

Options:

xoskel context show xoskel context show --name default

10.6 xoskel journal add

Adds a manual journal note.

Example:

xoskel journal add "Reviewed auth flow and identified policy issue"

Should create a timestamped markdown journal entry.

10.7 xoskel search

Example:

xoskel search "auth policy"

MVP can be simple lexical search.

Output should show:

matching file
line number where possible
snippet
whether match is source, context, policy, journal, or manifest

10.8 xoskel policy show

Prints effective policy.

10.9 xoskel doctor

Checks:

is Git installed?
is current directory a Git repo?
is .xoskel/ valid?
are required files present?
is AGENTS.md present?
are runtime/index folders correctly treated as rebuildable?
are manifests readable?
are schemas present?

⸻

Idempotency Rules

The bootstrap process must be safe to run repeatedly.

Rules:

Existing files are not overwritten unless generated and unchanged, or --force is passed.
Generated sections in AGENTS.md are bounded by markers.
Journal entries are append-only.
Manifests may be regenerated.
Search indexes may be rebuilt.
Runtime memory may be cleared and rebuilt.
User-authored context files must not be silently replaced.
The CLI should report what it changed.

Suggested generated block markers:

...

⸻

Safety Defaults

The MVP should be conservative.

Default stance:

read repo: allowed
write .xoskel: allowed during init
write source files: not performed by MVP
delete files: never
run shell commands: never, except Git read commands
install packages in target repo: never
network access: never required after package execution
read secrets: never
remote model calls: not in MVP
local model calls: not in MVP

The project should be designed so that later agents operate through Exoskeleton policy rather than around it.

⸻

Data Model

13.1 Project Manifest

Represents project-level Exoskeleton configuration.

Key identity:

schema_version project_name xoskel_version created_at

13.2 Repo Manifest

Represents current observed repo state.

Should include:

{ "schema_version": "0.1", "kind": "xoskel.repo_manifest", "generated_at": "2026-07-06T00:00:00Z", "git": { "root": "/path/to/repo", "branch": "main", "commit": "abc123", "dirty": true }, "counts": { "files": 184, "source": 37, "config": 9, "docs": 4 }, "detected": { "languages": ["typescript"], "package_managers": ["npm"], "frameworks": [] } }

13.3 File Manifest

Represents known files.

Should include:

{ "path": "src/index.ts", "kind": "source", "extension": ".ts", "size_bytes": 1234, "hash": "sha256...", "included_in_context": false }

13.4 Context Bundle

Represents curated context.

Required fields:

schema_version kind name created_at source prompt_contract repo_summary important_files detected_technologies provenance

13.5 Journal Entry

Represents an event.

Required fields:

schema_version kind event created_at actor summary actions repo_state

⸻

Git Integration

The MVP should use Git read operations only.

Required:

git rev-parse --show-toplevel git rev-parse --abbrev-ref HEAD git rev-parse HEAD git status --porcelain

The CLI must handle:

no Git installed
not a Git repo
unborn branch
detached HEAD
dirty worktree
nested execution from subdirectory

The CLI should always resolve the repo root and write .xoskel/ at the root.

⸻

Search MVP

The first search implementation can be simple.

Acceptable MVP implementation:

scan text files
tokenize lines
write JSON index
search by case-insensitive substring
return ranked-ish results by simple score

Do not overbuild this.

But the provider boundary should be named in a way that allows Tantivy to replace it.

Interface shape:

interface SearchProvider { name: string; buildIndex(input: SearchIndexInput): Promise; search(query: string, options?: SearchOptions): Promise<SearchResult[]>; }

Future Tantivy provider should be able to index:

source files
markdown
manifests
journal
context bundles
selected runtime snapshots

⸻

Runtime Memory MVP

The first memory implementation should be:

none-memory-provider

Interface shape:

interface MemoryProvider { name: string; available(): Promise; get(key: string): Promise<unknown | null>; set(key: string, value: unknown): Promise; delete(key: string): Promise; clear(): Promise; }

The interface exists to avoid hard-coding future Turso usage.

The README must explain:

Runtime memory is not canonical. It accelerates active runs and can be rebuilt from repo state.

⸻

Model Provider MVP

The first model implementation should be:

none-model-provider

Interface shape:

interface ModelProvider { name: string; available(): Promise; complete(request: ModelRequest): Promise; }

The MVP should not call models.

But the architecture should make future Lemonade integration straightforward:

Exoskeleton CLI / runtime -> ModelProvider -> LemonadeProvider -> managed local lemond subprocess -> OpenAI-compatible local API

⸻

Execution Provider MVP

The first execution implementation should be:

none-execution-provider

Interface shape:

interface ExecutionProvider { name: string; available(): Promise; execute(request: ExecutionRequest): Promise; }

The MVP should not run arbitrary commands.

Git read commands should be isolated in the Git adapter, not exposed as general execution.

⸻

Development Milestones

Milestone 1 — CLI Skeleton

Deliver:

npm package
executable xoskel
command router
help output
version output
basic error handling

Acceptance:

xoskel --help xoskel --version

work locally.

Milestone 2 — Repo Detection

Deliver:

Git root detection
branch detection
commit detection
dirty state detection
repo-root-relative path handling

Acceptance:

xoskel status

correctly reports repo state.

Milestone 3 — Bootstrap

Deliver:

.xoskel/ structure
manifest generation
default policy
default context
HEAD.md
AGENTS.md creation/update
HUMANS.md creation when absent, with existing content preserved
bootstrap journal entry

Acceptance:

xoskel init

creates the expected files and is safe to rerun.

Milestone 4 — Scan

Deliver:

repo scanner
file classifier
manifests
ignore rules

Acceptance:

xoskel scan

writes repo and file manifests.

Milestone 5 — Context

Deliver:

default context builder
repo profile context
prompt contract context
context show command

Acceptance:

xoskel context build xoskel context show

produce readable, useful context.

Milestone 6 — Journal

Deliver:

journal writer
bootstrap entries
manual journal command
scan/context journal entries

Acceptance:

xoskel journal add "Test note"

creates a timestamped markdown entry.

Milestone 7 — Search

Deliver:

simple local text index
search command
index rebuild on scan
search over source, context, journal, policy, manifests

Acceptance:

xoskel search "example"

returns useful file/snippet matches.

Milestone 8 — Doctor

Deliver:

health checks
missing file detection
manifest validation
policy validation

Acceptance:

xoskel doctor

identifies whether the repo is Exoskeleton-ready.

⸻

Acceptance Criteria For MVP

The MVP is complete when:

The package can be installed or run through npx.
Running xoskel inside a Git repo bootstraps Exoskeleton.
Running it again is safe and idempotent.
The generated files are human-readable.
The repo has an AGENTS.md that tells agents how to behave.
The repo has a HUMANS.md that guides human operators and preserves an existing human-authored guide.
.xoskel/HEAD.md records current harness state and the intended Git branch, without automatic branch switching.
.xoskel/context/default.context.md gives a useful starting context bundle.
.xoskel/journal/ records bootstrap and later events.
.xoskel/policy/ defines conservative defaults.
.xoskel/manifests/ records repo structure.
xoskel search can search repo and Exoskeleton artefacts.
xoskel doctor can validate the installation.
Runtime memory is explicitly non-canonical.
Search index is explicitly rebuildable.
The architecture has clear seams for Turso, Tantivy, Lemonade, SPINE, Podman, WASM, MCP, FastContext, Graphify, CRC, Dagger, and Ponytail.

20.1 Current Development Direction: Lightweight Operating Model

The next development work adopts a small set of operating-model conventions that improve handoff and safety without turning xoskel into a project-management system.

Generate a conservative HUMANS.md starter guide and preserve existing human-authored guides.
Make the intended Git branch explicit in .xoskel/HEAD.md; it is a visible coordination marker, not permission for an agent to change Git state.
Keep process records and project understanding distinct. The existing .xoskel/journal/ is an append-only operational trail. Durable project knowledge belongs in normal, reviewable repository material such as README.md, SPEC.md, docs/, and user-owned documents.
Keep generated context, runtime state, and search indexes derived and rebuildable. They must not become a hidden canonical knowledge store.
Treat package validation as an artifact contract: local development and CI should run the same relevant test/build checks and inspect the package that would be published, not merely whether source files compile.

These conventions do not add root .journal/ or .knowledge/ directories to target repositories, and they do not prescribe a sprint methodology.

20.2 Future Consideration: Optional Operating Profiles

The following ideas are deliberately outside current MVP development. They are valid only as explicit, opt-in profiles after the bootstrap substrate and its idempotency guarantees are stable.

A human-operated planning profile may scaffold sprint, huddle, retrospective, strategy, and backlog templates. Agents may maintain records within the approved process but must not self-authorize priorities, architectural decisions, or process transitions.
A durable knowledge-workspace profile may scaffold a clearly separate .knowledge/ area for reviewed specifications, research, and generated evidence. Its contents must have provenance and remain ordinary repository files; ephemeral memory, runtime databases, and search indexes remain non-canonical.
Containerized local/CI rendering parity may be useful for repositories whose product includes generated artifacts. It is not a mandatory Podman, Docker, Dagger, or GitHub Actions requirement for the generic xoskel CLI.

Future profiles must be additive, documented, explicitly selected by a human, and removable without making a repository's durable state opaque.

⸻

Non-Negotiable Design Constraints

Repo-first.
Git-aware.
Human-readable by default.
Deterministic before cognitive.
Inspectable before autonomous.
Policy before execution.
Journal before hidden state.
Context must preserve intent.
Runtime memory must be rebuildable.
Search index must be rebuildable.
No unrestricted shell.
No network dependency for bootstrap.
No silent overwrites.
No opaque agent state.
No conflation of user prompt, repo facts, inferred goals, and generated recommendations.

⸻

Future Backlog After MVP

After MVP, the next layer should add:

Tantivy-backed search provider.
Turso-backed runtime memory provider.
Lemonade local model provider.
SPINE event bus integration.
Passive journal subscriber.
Git notes integration.
Git worktree-based agent attempts.
Overlay-before-commit workflow.
Rootless Podman execution provider.
WASM/WASI deterministic plugin runner.
MCP adapter.
Context narrowing commands.
FastContext selector.
Graphify repo relationship model.
CRC representation compiler.
Dagger workflow runner.
Ponytail parser/codec library.
Ornith-style facilitator agent.
Prompt-contract validation.
Replay and audit commands.
Optional human-operated journal and planning profile.
Optional durable knowledge-workspace profile with provenance rules.

⸻

Suggested First Implementation Priority

Build the first version in this order:

CLI package and command router
Git repo detection
Safe file writer and template system
Bootstrap structure
AGENTS.md update
Repo scan manifests
Context generation
Journal writer
Simple search
Doctor command
HUMANS.md starter guide and intended-branch HEAD contract

This produces a useful MVP without prematurely building the harder runtime, model, search, orchestration, or sandbox layers.

The result should feel like:

xoskel

turns an ordinary repo into a governed, inspectable, context-aware repo that future agents can work inside safely.

FilesExpand file tree

SPEC.md

Latest commit

History

SPEC.md

File metadata and controls

Exoskeleton HEAD

Current Mode

Current Intent

Current Cursor

Intended Git Branch

Last Known Repo Scan

Active Context Bundle

Notes For Agents

AGENTS.md

Exoskeleton Harness Rules

schema_version: 0.1 kind: xoskel.context name: default created_at: 2026-07-06T00:00:00Z source: repo-scan

Default Exoskeleton Context

Prompt Contract

Repo Summary

Important Files

Project Structure

Detected Technologies

Agent Instructions

Provenance

schema_version: 0.1 kind: xoskel.journal event: bootstrap created_at: 2026-07-06T23:15:00Z actor: xoskel-cli

Bootstrap

Actions

Repo State