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

Core GRACE Artifacts

| Artifact | Role | | --- | --- | | docs/requirements.xml | Product intent, scope, use cases, and requirements | | docs/technology.xml | Stack, tooling, constraints, runtime, and testing choices | | docs/development-plan.xml | Modules, contracts, implementation order, phases, and flows | | docs/verification-plan.xml | Verification entries, test commands, scenarios, and required markers | | docs/knowledge-graph.xml | Module map, dependencies, public annotations, and navigation graph | | docs/operational-packets.xml | Canonical execution packet, delta, and failure handoff templates | | src/**/* and tests/**/* with GRACE markup | File-local module context, contracts, and semantic block boundaries |

Typical Workflows

Bootstrap a New Project

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

Inspect One Module Quickly

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

Review or Refresh After Code Drift

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

Debug a Failing Flow

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

Repository Layout

| Path | Purpose | | --- | --- | | skills/grace/* | Canonical skill sources | | plugins/grace/skills/grace/* | Packaged mirror used for marketplace distribution | | .claude-plugin/marketplace.json | Marketplace entry and published skill set | | plugins/grace/.claude-plugin/plugin.json | Packaged plugin manifest | | src/grace.ts | CLI entrypoint | | src/grace-lint.ts | grace lint command | | src/grace-module.ts | grace module find/show commands | | src/grace-file.ts | grace file show command | | src/query/* | Artifact loader, index, and render layer for CLI queries | | scripts/validate-marketplace.ts | Packaging and release validation |

For Maintainers

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

Development and Validation

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

License

MIT