corsette 0.2.1

Portable AI context product with OKF knowledge and generated adapters.

Corsette

Corsette is a portable AI context package. It stores reusable knowledge, agents, skills, and commands in canonical source files, then renders installable output for multiple agent runtimes such as OpenCode and pi.dev.

The project is designed for public distribution: generated files are disposable, private context stays local, and model choices are expressed through semantic profiles instead of concrete provider IDs.

What Corsette contains

Area	Purpose
okf/knowledge/	Portable Markdown knowledge vault using OKF-style frontmatter.
catalog/skills/	Canonical skill definitions and prebuilt skill packages.
catalog/agents/	Canonical agent definitions using semantic model_profile values.
catalog/commands/	Canonical slash-command prompts.
adapters/	Generated runtime packages for OpenCode, pi.dev, aicontext, Claude, and agents-md.
tools/	Validation, privacy scrubbing, and generation scripts.
packages/corsette/	Python CLI for local workflows and ingestion helpers.

Core capabilities

• SDD + TDD: OpenSpec-shaped behavior contracts plus Corsette's five-agent harness and mutation-testing discipline.
• AutoResearch: source capture, iteration, and finding synthesis into OKF notes.
• CodeGraph: Graphify-backed code graph artifact capture.
• Model eval: semantic model profile evaluation and local model resolution.

Install for local development

python3 -m pip install -e .

After installation, the CLI is available as corsette:

corsette --help
corsette validate
corsette scrub
corsette generate --adapter opencode
corsette generate --adapter pi-dev

You can also run the module directly without installing:

python3 -m corsette --help

Install on another machine

Clone the public repository, create an isolated Python environment, install the package, then regenerate runtime adapters from canonical sources.

git clone https://github.com/arturonaredo/corsette.git
cd corsette
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
corsette --help

Generate the runtime package you want to install into your agent runtime:

corsette generate --adapter opencode
corsette generate --adapter pi-dev

For OpenCode, copy or symlink adapters/opencode/generated/.opencode/ into the target project or user OpenCode configuration. For pi.dev, install or copy from adapters/pi-dev/generated/ according to your pi.dev setup.

Private overlays are intentionally not part of the public repository. Keep local machine-specific context in .corsette/ or okf/private/, and keep concrete model IDs in environment variables referenced by catalog/profiles/model-profiles.yaml.

Run this smoke check after installing on a new machine:

corsette validate
corsette scrub
corsette generate --adapter opencode --check
corsette generate --adapter pi-dev --check
python -m pytest packages/corsette/tests

Generate adapter output

Canonical files live in okf/ and catalog/. Runtime-specific files are generated and should not be edited by hand.

corsette generate --adapter opencode
corsette generate --adapter pi-dev

Generated output is written under:

• adapters/opencode/generated/
• adapters/pi-dev/generated/

Those directories are ignored by git and can always be regenerated.

Install generated packages

OpenCode

Generate the OpenCode adapter, then copy or symlink the generated .opencode/ content into the target project or user configuration according to your OpenCode setup.

corsette generate --adapter opencode

agents-md

Generates a single AGENTS.md at the project root that follows the AGENTS.md convention used by tools like Aider and some Cursor modes. The file lists the canonical project layout, core rules, available skills, agents, commands, and the most useful CLI entry points. Sources are the same as every other adapter — okf/, catalog/, and the routing matrix.

corsette generate --adapter agents-md

pi.dev

Generate the pi.dev adapter, then install from the generated package directory.

corsette generate --adapter pi-dev
# install from adapters/pi-dev/generated according to your pi.dev setup

The pi.dev package includes skills, prompts, agent prompt files, and an extension bridge.

CLI workflows

Corsette includes a small Python CLI for repository maintenance and ingestion helpers.

corsette okf-youtube <url> --offline-metadata metadata.json --offline-transcript transcript.vtt
corsette okf-code-graph <path> --offline-artifacts path/to/graphify-output
corsette okf-notebooklm import notes exported-note.md
corsette okf-notebooklm import dir exported-notes/
corsette okf-research "investigate a topic" --source README.md
corsette okf-research-run "investigate a topic" --source README.md --max-iterations 3
corsette okf-sdd-tdd "installable package" --scenario "package installs locally"
# writes openspec/changes/installable-package/ plus an OKF spec note
corsette okf-capture-web saved-page.html --url https://example.test/page
corsette capture-server --host 127.0.0.1 --port 8765
# then load capabilities/chrome-capture/extension/ as an unpacked Chrome extension
corsette okf-model-eval models.json
corsette okf-model-judge models.json --goal "pick a strong general model" [--live --api-url <url> --api-key <key>]
corsette okf-model-telemetry telemetry.json
corsette okf-improve
corsette okf-index
corsette okf-catalog-index
corsette okf-catalog-index --no-mobile  # exclude the TIER 3 iOS/Android mobile pack
corsette release 0.2.0                # dry-run: runs validate, scrub, generate, pytest (no build, no version bump)
corsette release 0.2.0 --apply       # also bumps pyproject.toml and runs python -m build
corsette release 0.2.0 --apply --tag  # also creates git tag v0.2.0
corsette release 0.2.0 --apply --tag --push  # also pushes the tag to origin
corsette okf-release-checklist v0.1.0
corsette install-pack mobile --output /tmp/mobile-pack  # extract the TIER 3 iOS/Android skill pack without touching the source catalog
corsette okf-doctor  # run validate + scrub + generate --check (5 adapters) + pytest; does not mutate the checkout
corsette upgrade  # post-install umbrella: report current version, scan for deprecated CLI names, write OKF report
corsette upgrade --release-metadata release.json --apply --venv .venv  # actually install the release + rewrite files in place
corsette upgrade --target-dir ~/projects  # scan a specific directory for deprecated CLI references
corsette upgrade --target-dir ~/projects --apply  # scan + rewrite files in place
corsette okf-visual-plan "review UI" --summary "Plan the review UI" --file src/review.tsx
corsette okf-visual-recap "workflow work" --summary "Summarize implemented workflow changes" --file packages/corsette/src/corsette/workflows.py
corsette okf-daily-log --scope corsette --entry "what you did" --source opencode
# appends to okf/knowledge/daily-log-corsette-YYYY-MM-DD.md

The ingestion commands write OKF-compatible notes under okf/knowledge/.

Verification

Run these before publishing or opening a pull request:

corsette validate
corsette scrub
corsette generate --adapter opencode --check
corsette generate --adapter pi-dev --check
corsette generate --adapter aicontext --check
corsette generate --adapter claude --check
corsette generate --adapter agents-md --check
python3 -m pytest packages/corsette/tests
python3 -m build

GitHub Actions runs the same validation contract on pull requests and pushes to main, including a wheel install smoke test.

Public-safety rules

This repository is intended to be public. Do not commit:

• API keys, tokens, credentials, or .env files;
• private IP addresses or internal hostnames;
• private provider names, company-specific infrastructure, or internal model IDs;
• generated adapter output;
• local private vault content under .corsette/ or okf/private/.

Use semantic model profiles such as balanced_coding, deep_reasoning, strong_general, and fast_utility in public catalog files.

Maintenance rules

• Edit canonical sources in okf/ and catalog/.
• Never hand-edit generated files under adapters/*/generated/.
• Record substantial research, decisions, and findings as OKF notes under okf/knowledge/.
• Keep repository-facing documentation in English.
• Run validation, scrub, generation checks, and tests before claiming work is complete.