grace-marketplace

GRACE Marketplace and CLI

GRACE means Graph-RAG Anchored Code Engineering: a contract-first AI engineering methodology built around semantic markup, .grace XML artifacts, knowledge-graph navigation, assertions, scopes, and log-driven verification.

This repository ships the GRACE skills plus the optional grace CLI. It is a packaging and distribution repository, not an end-user application.

Current packaged version: 4.2.1

What This Repository Ships

• Canonical GRACE skills in skills/grace/*
• Packaged Claude marketplace mirror in plugins/grace/skills/grace/*
• Marketplace metadata in .claude-plugin/marketplace.json
• Packaged plugin manifest in plugins/grace/.claude-plugin/plugin.json
• OpenPackage metadata in openpackage.yml
• Optional Bun-powered CLI package @osovv/grace-cli

GRACE 4 Model

GRACE 4 uses .grace as the durable project model:

GRACE 4 does not dual-validate legacy GRACE 3 project docs as current state. Existing GRACE 3 projects use $grace-migrate; the CLI validates the generated .grace result but does not convert legacy docs itself.

Verification commands run from the project root by default. A V-M-* entry may declare one contained project-relative <Cwd>packages/example</Cwd> while keeping <TestFiles><File>...</File></TestFiles> paths project-root-relative. Absolute paths, .. escapes, and symlink escapes fail closed.

TypeScript/JavaScript semantic analysis is bundled and compiler-backed. Governed Python and Dart files require their respective runtimes on PATH; Python export analysis is exact when a static __all__ is present (including Unicode identifiers) and otherwise emits heuristic confidence. A missing runtime fails closed with actionable analysis.runtime-missing; an installed adapter that fails emits analysis.adapter-failed. Neither failure state is presented as exact MODULE_MAP parity.

Languages without a registered adapter — including Go, Rust, Java, shell, C/C++, C#, and PowerShell — are governed structurally: markup validity, contract completeness, and MODULE_MAP shape are enforced, while export parity is not analyzed. MODULE_MAP for these languages is taken on trust. Governance is opt-in per file; sources without GRACE markers are never flagged.

Markers are recognized behind the //, #, --, ; and block-comment * prefixes, so a language whose comments use none of those — XML-comment dialects such as .xaml or .csproj — cannot carry them.

Install

Install skills first. The CLI is optional but recommended once skills are installed.

OpenPackage

opkg install gh@osovv/grace-marketplace
opkg install gh@osovv/grace-marketplace -g
opkg install gh@osovv/grace-marketplace --platforms claude-code

Claude Code Marketplace

/plugin marketplace add osovv/grace-marketplace
/plugin install grace@grace-marketplace

Agent Skills-Compatible Install

git clone https://github.com/osovv/grace-marketplace
cp -r grace-marketplace/skills/grace/grace-* /path/to/your/agent/skills/

CLI

Requires bun on PATH. GRACE skills invoke the installed stable grace binary directly; they do not default to bunx, npx, or a prerelease dist-tag.

# Install the current stable release from npm `latest`
bun add -g @osovv/grace-cli
grace --version
grace lint --path /path/to/grace4-project

GRACE 4 Quick Start

For a new GRACE 4 project:

1. Run $grace-init to create .grace.
2. Fill .grace/context artifacts with your agent.
3. Run $grace-spec for a change.
4. Run $grace-plan after spec approval.
5. Before observed writes begin, run the active-baseline preflight: grace lint --path /path/to/project --assertions current.
6. Run grace lint --path /path/to/project --change C-ID --assertions baseline before execution; add --run-commands when the baseline declares MustPassCommand.
7. Run grace status --path /path/to/project --json.
8. Run $grace-execute and choose sequential or parallel-safe mode. Parallel-safe mode additionally requires grace lint --path /path/to/project --parallel-preflight.
9. Before apply/archive, run grace lint --path /path/to/project --change C-ID --assertions final; add --run-commands when the target declares MustPassCommand.

Existing GRACE 3 projects should run $grace-migrate and review the migration report before writing .grace artifacts.

Migration cleanup is separately gated: successful current lint, fresh status proving GRACE 4 with no integrity errors, git/worktree inspection, exact cleanup paths, and explicit cleanup confirmation are mandatory. Dirty or non-git cleanup requires an additional acknowledgement naming that risk; any cleanup failure stops without automatic destructive retry.

Skills Overview

CLI Overview

MustPassCommand entries are leaf project evidence such as tests, typecheck, build, format, or package checks. Do not nest grace lint, grace status, or another GRACE lifecycle command inside plan assertions; selected target/final lint is the external orchestration gate.

Each <Command> may declare an optional budgetSeconds attribute — <Command budgetSeconds="1800">bun run gate:e2e</Command> — which becomes that command's timeout under --run-commands in preference to the global --command-timeout. The grammar matches --command-timeout: a non-negative whole number of seconds, where 0 disables the timeout for that command and omitting the attribute keeps the global default. Lint also reports assertion.command-subsumed as a warning when two commands in the same assertion section share a command head and one's path arguments are a component-wise prefix of the other's, so a gate that re-runs bun test src/grace4 under bun test src is visible rather than merely slow.

Output modes:

• grace lint: text, json
• grace status: text, json
• grace module find: table, json
• grace module show: text, json
• grace verification find: table, json
• grace verification show: text, json
• grace file show: text, json

Lint, status, and projection-backed navigation fail closed: invalid options, invalid grammar, malformed active assertions/scopes, duplicate ownership, missing routed files, or ambiguous targets produce structured results or a nonzero error envelope. JSON command failures emit one stable { "schemaVersion": "1.0.0", "ok": false, "error": { ... } } envelope on stdout; text failures emit one concise actionable line without a stack trace.

Lint Configuration

An optional .grace-lint.json file at the project root (next to .grace) controls how grace lint and the query commands collect code files, and how long command-run evidence is kept:

{
  "ignoredDirs": ["generated", "fixtures-output"],
  "runLogRetention": 25
}

• ignoredDirs lists directory names to prune from file collection, on top of the built-in set below. Names match at any depth; globs and paths are not supported.
• runLogRetention is how many non-passing --run-commands run directories survive pruning, default 10. The newest passing run of every change is protected and never pruned, so evidence an archived change cites stays on disk. --keepRuns N overrides the key for a single run; 0 keeps no non-passing runs at all, which removes the current run as soon as it fails or runs without a --change to bind it to.
• The file must be a JSON object with supported keys only. Broken JSON, a non-object shape, an unknown key, a non-array ignoredDirs, or a runLogRetention that is not a non-negative integer is a config.* lint error, and query commands refuse to run until the file is fixed.