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.10.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 lint --profile autonomous for autonomy-readiness checks
• grace status for project health, autonomy gate, and next-action guidance
• 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
• execution packets, checkpoints, and failure handoffs make long autonomous runs recoverable
• preferred stacks and named surfaces keep agents inside high-reliability project conventions

GRACE is process-first, not prompt-first:

• do more work before launch so the agent has less ambiguity during execution
• give the agent named contracts, flows, markers, and checkpoints instead of abstract exhortations
• treat autonomy as a governed execution mode that must pass an explicit readiness gate

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 lint --profile autonomous --path /path/to/project
6. Run grace status --path /path/to/project
7. 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
grace lint --profile autonomous --path /path/to/project

# Health + next action
grace status --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 status: text, json
• grace module find: table, json
• grace module show: text, json
• grace file show: text, json

GRACE 3.8 pushes more of the autonomous-execution discipline into the product surface:

• grace lint --profile autonomous acts as a cheap readiness gate before long runs
• grace status surfaces whether the project is healthy enough for execution or needs planning, verification, or refresh work first
• technology.xml should name preferred stacks, test tools, and observability surfaces so workers stay on approved, high-reliability paths
• operational-packets.xml should define assumptions, stop conditions, retry budgets, and checkpoint fields so workers can stop or replan without hidden reasoning
• semantic anchoring matters: meaningful module names, block names, contracts, and examples are better agent guidance than abstract IDs or vague prompts

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 status --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 validate:ci.
• 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 validate:cli

Run marketplace and packaging validation:

bun run validate:marketplace

Run the full CI-compatible validation stack:

bun run validate:ci
bun run release:checklist

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