by osovv
GRACE (Graph-RAG Anchored Code Engineering): open Agent Skills for contract-driven AI code generation with semantic markup, knowledge graphs, and support for Claude Code, Codex CLI, and Kilo Code.
# Add to your Claude Code skills
git clone https://github.com/osovv/grace-marketplaceGuides for using ai agents skills like grace-marketplace.
No comments yet. Be the first to share your thoughts!
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
skills/grace/*plugins/grace/skills/grace/*.claude-plugin/marketplace.jsonplugins/grace/.claude-plugin/plugin.jsonopenpackage.yml@osovv/grace-cliThe published CLI currently gives you:
grace lint for integrity checksgrace lint --profile autonomous for autonomy-readiness checksgrace status for project health, autonomy gate, and next-action guidancegrace module find for module resolution across shared docs and file-local markupgrace module show for shared/public module contextgrace file show for file-local/private implementation contextGRACE is designed for AI-assisted engineering where agents need stable navigation, explicit contracts, and reusable verification evidence.
Core ideas:
GRACE is process-first, not prompt-first:
This makes it easier to:
GRACE was designed by Vladimir Ivanov (@turboplanner).
Install skills first.
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:
$grace-initdocs/requirements.xml and docs/technology.xml together with your agent$grace-plan$grace-verificationgrace lint --profile autonomous --path /path/to/projectgrace status --path /path/to/project$grace-execute or $grace-multiagent-executeFor 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
| 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 |
| 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, jsongrace status: text, jsongrace module find: table, jsongrace module show: text, jsongrace file show: text, jsonGRACE 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 runsgrace status surfaces whether the project is healthy enough for execution or needs planning, verification, or refresh work firsttechnology.xml should name preferred stacks, test tools, and observability surfaces so workers stay on approved, high-reliability pathsoperational-packets.xml should define assumptions, stop conditions, retry budgets, and checkpoint fields so workers can stop or replan without hidden reasoningGRACE works best when shared docs stay public and stable, while private detail stays close to code.
Use shared XML artifacts for:
Use file-local markup for:
MODULE_CONTRACTMODULE_MAPCHANGE_SUMMARYRule of thumb:
grace module show is the shared/public truthgrace file show is the file-local/private truthGRACE is designed to be easy to navigate through exact-text search.
Prefer this order when narrowing scope:
docs/knowledge-graph.xml, docs/development-plan.xml, docs/verification-plan.xmlMODULE_CONTRACT, MODULE_MAP, START_CONTRACT:, START_BLOCK_, START_CHANGE_SUMMARY, LINKS:Common anchors:
M- for module IDsV-M- for verification IDsCrossLink for graph edgesSTART_MODULE_CONTRACTSTART_MODULE_MAPSTART_CONTRACT:START_BLOCK_START_CHANGE_SUMMARYLINKS: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