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.11.0

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

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

Why GRACE

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

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.

Install Skills

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

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/

Install CLI

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

Quick Start

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

Skills Overview

| Skill | Purpose | | --- | --- | | grace-init | Bootstrap the GRACE docs, templates, and agent guidance | | grace-plan | Design modules, phases, flows, dependencies, and contracts | | grace-verification | Build and maintain verification-plan.xml, tests, traces, and log evidence | | grace-execute | Execute the plan sequentially with scoped review and commits | | grace-multiagent-execute | Execute parallel-safe waves with controller-managed synchronization | | grace-refactor | Rename, move, split, merge, and extract modules without shared-artifact drift | | grace-fix | Debug issues from graph, contracts, tests, traces, and semantic blocks | | grace-refresh | Refresh graph and verification artifacts against the real codebase | | grace-reviewer | Review semantic integrity, graph consistency, and verification quality | | grace-status | Report overall project health and suggest the next safe action | | grace-ask | Answer architecture and implementation questions from project artifacts | | grace-cli | Use the optional grace binary as a fast lint and artifact-query layer for GRACE projects | | grace-explainer | Explain the GRACE methodology itself | | grace-setup-subagents | Scaffold shell-specific GRACE worker and reviewer presets |

CLI Overview

| Command | What It Does | | --- | --- | | grace lint --path <root> | Validate current GRACE artifacts, semantic markup, unique XML tags, and export/map drift | | grace lint --profile autonomous --path <root> | Enforce autonomy readiness for execution packets, verification coverage, observable evidence, and operational-packet presence | | grace status --path <root> | Report artifact health, codebase metrics, integrity snapshot, autonomy gate, recent changes, and the next safe action | | grace module find <query> --path <root> | Search by module ID, name, path, purpose, annotations, dependency IDs, verification IDs, and LINKS | | grace module show <id-or-path> --path <root> | Show the shared/public module record from plan, graph, steps, and linked files | | grace module show <id> --with verification --path <root> | Include verification excerpt when a V-M-* entry exists | | grace file show <path> --path <root> | Show file-local MODULE_CONTRACT, MODULE_MAP, and CHANGE_SUMMARY | | grace file show <path> --contracts --blocks --path <root> | Include scoped contracts and semantic block navigation |

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

Agentic Reliability

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

Public Shared Docs vs File-Local Markup

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

Grep-First Navigation

GRACE is designed to be easy to navigate through exact-text search.

Prefer this order when narrowing scope:

1. Search shared/public artifacts for module and verification IDs: docs/knowledge-graph.xml, docs/development-plan.xml, docs/verification-plan.xml
2. Search file-local anchors for implementation context: MODULE_CONTRACT, MODULE_MAP, START_CONTRACT:, START_BLOCK_, START_CHANGE_SUMMARY, LINKS:
3. Read full files only after the target module, file, or block is narrowed

Common anchors:

• M- for module IDs
• V-M- for verification IDs
• CrossLink for graph edges
• START_MODULE_CONTRACT
• START_MODULE_MAP
• START_CONTRACT:
• START_BLOCK_
• START_CHANGE_SUMMARY
• LINKS:

Copy-paste grep recipes:

# find module records in shared docs
grep -R -n -E '\bM-[A-Z0-9]+(-[A-Z0-9]+)*\b' docs/development-plan.xml docs/knowledge-graph.xml

# find verification entries in shared docs
grep -R -n -E '\bV-M-[A-Z0-9]+(-[A-Z0-9]+)*\b' docs/verification-plan.xml docs/knowledge-graph.xml

# find graph links from file-local markup into shared docs
grep -R -n 'LINKS:' src tests

# find file-lev