Architecture

Sherpa combines agent-readable Markdown with a small Python core and a separate standard-library distribution CLI.

System view

Repository map

SKILL.md                    Agent instructions and master router
commands/                   Registered command manifest and command definitions
core/commands/              Command routing
core/configuration/         Configuration manager
core/ideas/                 Idea evaluation engine
workflows/                  Operation procedures
rules/                      Shared behavioral and safety constraints
templates/                  Reusable project artifacts and config examples
src/                        Verification and configuration utilities
adapters/, .claude/,         Host integration assets
.opencode/, .kilo/
distribution/                Installers, CLI, release manifest metadata
tests/, scripts/             Regression checks and evaluation tools
docs/                        This VitePress site and existing source docs

Command execution

State ownership

Project state belongs to the hackathon repository in .sherpa/. The skill's installation directory is reusable and does not hold project state. The distribution CLI explicitly avoids project .sherpa/ data.

Routing and extension points

The master behavior is in SKILL.md; canonical operation entries are in commands/manifest.json. scripts/build-distributions.py generates client-specific skill and command files from those sources. core/commands/router.py implements routing. Workflows, rules, and templates are Markdown extension points. Codex receives skills without a native slash-command claim.

Configuration and errors

Configuration handling lives in core/configuration/manager.py and src/config_manager.py. Release installation checks archive checksums, archive paths, and required skill structure. The CLI has diagnostics and scopes file operations to recognized managed locations. For exact behavior and error recovery, see installer source notes, troubleshooting, and security guidance.