GRACE Marketplace and CLI

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

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: 3.7.0

• 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

The published CLI currently gives you:

• grace lint for integrity checks
• grace module find for module resolution across shared docs and file-local markup
• grace module show for shared/public module context
• grace file show for file-local/private implementation context

GRACE is designed for AI-assisted engineering where agents need stable navigation, explicit contracts, and reusable verification evidence.

Core ideas:

• shared artifacts define the public module boundary
• file-local markup defines private implementation detail
• contracts describe expected behavior before code changes spread
• verification is planned, named, and reused instead of improvised per task
• semantic blocks give agents precise read and patch targets

This makes it easier to:

• plan modules and execution order
• hand work across agents without losing context
• review for drift between code, graph, and verification
• debug failures from named blocks and planned evidence

GRACE was designed by Vladimir Ivanov (@turboplanner).

Install skills first.

• Skills are the core GRACE product surface.
• The CLI is optional, but highly recommended once the skills are installed.
• Installing only skills is a valid setup.
• Installing only the CLI is usually not useful without the GRACE skills and workflow.

Skills and CLI are complementary, but they are distributed differently.

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

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

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

The CLI is a companion to the GRACE skills, not a replacement for them.

Requires bun on PATH.

bun add -g @osovv/grace-cli
grace lint --path /path/to/grace-project

For a new GRACE project:

1. Run $grace-init
2. Design docs/requirements.xml and docs/technology.xml together with your agent
3. Run $grace-plan
4. Run $grace-verification
5. Run $grace-execute or $grace-multiagent-execute

For an existing GRACE project, the CLI is often the fastest way to orient yourself:

# Integrity gate
grace lint --path /path/to/project

# Resolve the relevant module
grace module find auth --path /path/to/project
grace module find src/provider/config-repo.ts --path /path/to/project --json

# Read shared/public context
grace module show M-AUTH --path /path/to/project
grace module show M-AUTH --path /path/to/project --with verification

# Read file-local/private context
grace file show src/auth/index.ts --path /path/to/project
grace file show src/auth/index.ts --path /path/to/project --contracts --blocks

Current output modes:

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

GRACE works best when shared docs stay public and stable, while private detail stays close to code.

Use shared XML artifacts for:

• module IDs and module boundaries
• public module contracts and public interfaces
• dependencies and execution order
• verification entries, commands, scenarios, and required markers
• project-level flows and phases

Use file-local markup for:

• MODULE_CONTRACT
• MODULE_MAP
• CHANGE_SUMMARY
• function and type contracts
• semantic block boundaries
• implementation-only helpers and orchestration details

Rule of thumb:

• grace module show is the shared/public truth
• grace file show is the file-local/private truth

$grace-init
design requirements.xml and technology.xml together with your agent
$grace-plan
$grace-verification
$grace-execute or $grace-multiagent-execute

grace module find <name-or-path>
grace module show M-XXX --with verification
grace file show <governed-file> --contracts --blocks

grace lint --path <project-root>
$grace-reviewer
$grace-refresh

grace module find <error-or-path>
grace module show M-XXX --with verification
grace file show <governed-file> --contracts --blocks
$grace-fix

• Treat skills/grace/* as the source of truth unless the task is explicitly about packaged output.
• Keep plugins/grace/skills/grace/* synchronized with the canonical skill files.
• Keep versions synchronized across README.md, package.json, openpackage.yml, .claude-plugin/marketplace.json, and plugins/grace/.claude-plugin/plugin.json.
• Validate packaging changes with bun run ./scripts/validate-marketplace.ts.
• Validate CLI changes with bun run ./src/grace.ts lint --path . --allow-missing-docs and bun test.
• Do not assume every directory under skills/grace/ is published; the actual shipped set is declared in .claude-plugin/marketplace.json.

Install dependencies:

bun install

Run the test suite:

bun test

Run the CLI against the repository itself:

bun run ./src/grace.ts lint --path . --allow-missing-docs

Run marketplace and packaging validation:

bun run ./scripts/validate-marketplace.ts

Smoke test the query layer against a real GRACE project:

bun run ./src/grace.ts module show M-AUTH --path /path/to/grace-project --with verification
bun run ./src/grace.ts file show src/auth/index.ts --path /path/to/grace-project --contracts --blocks

MIT