Skip to content
Back to search

grace-marketplace

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/osovv--grace-marketplace/badge.svg)](/listings/osovv--grace-marketplace)

HTML

<a href="/listings/osovv--grace-marketplace"><img src="/api/listings/osovv--grace-marketplace/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install **skills** first. The CLI is optional but recommended once skills are installed.

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/

CLI

Requires `bun` on `PATH`. GRACE skills invoke the installed stable `grace` binary directly; they do not default to `bunx`, `npx`, or a prerelease dist-tag.

# Install the current stable release from npm `latest`
bun add -g @osovv/grace-cli
grace --version
grace lint --path /path/to/grace4-project

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 56 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "grace-marketplace",
  4. "strict": false,
  5. "owner": {
  6. "name": "osovv",
  7. "url": "https://github.com/osovv"
  8. },
  9. "metadata": {
  10. "description": "GRACE (Graph-RAG Anchored Code Engineering) - a methodology by Vladimir Ivanov for contract-first AI engineering with semantic markup, knowledge graphs, and log-driven verification",
  11. "version": "4.2.1"
  12. },
  13. "plugins": [
  14. {
  15. "name": "grace",
  16. "source": "./plugins/grace",
  17. "description": "Complete GRACE methodology: semantic markup, knowledge graphs, module contracts, testing, and log-driven verification for AI-driven engineering",
  18. "version": "4.2.1",
  19. "author": {
  20. "name": "osovv",
  21. "url": "https://github.com/osovv"
  22. },
  23. "license": "MIT",
  24. "keywords": [
  25. "grace",
  26. "semantic-markup",
  27. "knowledge-graph",
  28. "contracts",
  29. "ai-code-generation",
  30. "log-driven-development",
  31. "verification",
  32. "llm-friendly"
  33. ],
  34. "category": "methodology",
  35. "strict": true,
  36. "agents": [],
  37. "skills": [
  38. "./skills/grace/grace-init",
  39. "./skills/grace/grace-spec",
  40. "./skills/grace/grace-plan",
  41. "./skills/grace/grace-execute",
  42. "./skills/grace/grace-refactor",
  43. "./skills/grace/grace-setup-subagents",
  44. "./skills/grace/grace-fix",
  45. "./skills/grace/grace-refresh",
  46. "./skills/grace/grace-status",
  47. "./skills/grace/grace-ask",
  48. "./skills/grace/grace-cli",
  49. "./skills/grace/grace-explainer",
  50. "./skills/grace/grace-verification",
  51. "./skills/grace/grace-reviewer",
  52. "./skills/grace/grace-migrate"
  53. ]
  54. }
  55. ]
  56. }
README.md · README · 237 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # GRACE Marketplace and CLI
  2. **GRACE** means **Graph-RAG Anchored Code Engineering**: a contract-first AI engineering methodology built around semantic markup, `.grace` XML artifacts, knowledge-graph navigation, assertions, scopes, and log-driven verification.
  3. This repository ships the GRACE skills plus the optional `grace` CLI. It is a packaging and distribution repository, not an end-user application.
  4. Current packaged version: `4.2.1`
  5. ## What This Repository Ships
  6. - Canonical GRACE skills in `skills/grace/*`
  7. - Packaged Claude marketplace mirror in `plugins/grace/skills/grace/*`
  8. - Marketplace metadata in `.claude-plugin/marketplace.json`
  9. - Packaged plugin manifest in `plugins/grace/.claude-plugin/plugin.json`
  10. - OpenPackage metadata in `openpackage.yml`
  11. - Optional Bun-powered CLI package `@osovv/grace-cli`
  12. ## GRACE 4 Model
  13. GRACE 4 uses `.grace` as the durable project model:
  14. | Area | Purpose |
  15. | --- | --- |
  16. | `.grace/context/*.xml` | Requirements, technology, principles, deployment, and UX constraints |
  17. | `.grace/graph/index.xml` + routed graph docs | Current graph projection source for `GD-*`, `M-*`, and `DF-*` anchors |
  18. | `.grace/verification/index.xml` + routed verification docs | Current verification projection source for deterministic `V-M-*` entries |
  19. | `.grace/changes/active/C-*` | Active `GraceChangeSpec`, optional design context, and `GraceChangePlan` bundles |
  20. | `.grace/changes/archive/C-*` | Applied, rejected, cancelled, or superseded change bundles |
  21. | Source/test files with GRACE markup | File-local contracts, links, and semantic block anchors |
  22. GRACE 4 does not dual-validate legacy GRACE 3 project docs as current state. Existing GRACE 3 projects use `$grace-migrate`; the CLI validates the generated `.grace` result but does not convert legacy docs itself.
  23. Verification commands run from the project root by default. A `V-M-*` entry may declare one contained project-relative `<Cwd>packages/example</Cwd>` while keeping `<TestFiles><File>...</File></TestFiles>` paths project-root-relative. Absolute paths, `..` escapes, and symlink escapes fail closed.
  24. TypeScript/JavaScript semantic analysis is bundled and compiler-backed. Governed Python and Dart files require their respective runtimes on `PATH`; Python export analysis is exact when a static `__all__` is present (including Unicode identifiers) and otherwise emits heuristic confidence. A missing runtime fails closed with actionable `analysis.runtime-missing`; an installed adapter that fails emits `analysis.adapter-failed`. Neither failure state is presented as exact `MODULE_MAP` parity.
  25. Languages without a registered adapter — including Go, Rust, Java, shell, C/C++, C#, and PowerShell — are governed structurally: markup validity, contract completeness, and `MODULE_MAP` shape are enforced, while export parity is not analyzed. `MODULE_MAP` for these languages is taken on trust. Governance is opt-in per file; sources without GRACE markers are never flagged.
  26. Markers are recognized behind the `//`, `#`, `--`, `;` and block-comment `*` prefixes, so a language whose comments use none of those — XML-comment dialects such as `.xaml` or `.csproj` — cannot carry them.
  27. ## Install
  28. Install **skills** first. The CLI is optional but recommended once skills are installed.
  29. ### OpenPackage
  30. ```bash
  31. opkg install gh@osovv/grace-marketplace
  32. opkg install gh@osovv/grace-marketplace -g
  33. opkg install gh@osovv/grace-marketplace --platforms claude-code
  34. ```
  35. ### Claude Code Marketplace
  36. ```bash
  37. /plugin marketplace add osovv/grace-marketplace
  38. /plugin install grace@grace-marketplace
  39. ```
  40. ### Agent Skills-Compatible Install
  41. ```bash
  42. git clone https://github.com/osovv/grace-marketplace
  43. cp -r grace-marketplace/skills/grace/grace-* /path/to/your/agent/skills/
  44. ```
  45. ### CLI
  46. Requires `bun` on `PATH`. GRACE skills invoke the installed stable `grace` binary directly; they do not default to `bunx`, `npx`, or a prerelease dist-tag.
  47. ```bash
  48. # Install the current stable release from npm `latest`
  49. bun add -g @osovv/grace-cli
  50. grace --version
  51. grace lint --path /path/to/grace4-project
  52. ```
  53. ## GRACE 4 Quick Start
  54. For a new GRACE 4 project:
  55. 1. Run `$grace-init` to create `.grace`.
  56. 2. Fill `.grace/context` artifacts with your agent.
  57. 3. Run `$grace-spec` for a change.
  58. 4. Run `$grace-plan` after spec approval.
  59. 5. Before observed writes begin, run the active-baseline preflight: `grace lint --path /path/to/project --assertions current`.
  60. 6. Run `grace lint --path /path/to/project --change C-ID --assertions baseline` before execution; add `--run-commands` when the baseline declares `MustPassCommand`.
  61. 7. Run `grace status --path /path/to/project --json`.
  62. 8. Run `$grace-execute` and choose sequential or parallel-safe mode. Parallel-safe mode additionally requires `grace lint --path /path/to/project --parallel-preflight`.
  63. 9. Before apply/archive, run `grace lint --path /path/to/project --change C-ID --assertions final`; add `--run-commands` when the target declares `MustPassCommand`.
  64. Existing GRACE 3 projects should run `$grace-migrate` and review the migration report before writing `.grace` artifacts.
  65. Migration cleanup is separately gated: successful current lint, fresh status proving GRACE 4 with no integrity errors, git/worktree inspection, exact cleanup paths, and explicit cleanup confirmation are mandatory. Dirty or non-git cleanup requires an additional acknowledgement naming that risk; any cleanup failure stops without automatic destructive retry.
  66. ## Skills Overview
  67. | Skill | Purpose |
  68. | --- | --- |
  69. | `grace-init` | Bootstrap the `.grace` skeleton, templates, and agent guidance |
  70. | `grace-spec` | Create an approved GRACE 4 change spec and optional design context |
  71. | `grace-plan` | Design assertions, scopes, tasks, and verification gates from an approved spec |
  72. | `grace-execute` | Execute the approved plan in sequential or parallel-safe mode |
  73. | `grace-refactor` | Rename, move, split, merge, and extract modules without artifact drift |
  74. | `grace-setup-subagents` | Scaffold GRACE worker and reviewer presets |
  75. | `grace-fix` | Debug issues from graph, contracts, tests, traces, and semantic blocks |
  76. | `grace-refresh` | Detect drift and propose reconciliation changes |
  77. | `grace-status` | Report `.grace` health and suggest the next safe action |
  78. | `grace-ask` | Answer architecture and implementation questions from `.grace` artifacts |
  79. | `grace-cli` | Use the optional `grace` binary as a fast lint and artifact-query layer |
  80. | `grace-explainer` | Explain the GRACE methodology itself |
  81. | `grace-verification` | Build and maintain `.grace/verification` entries and evidence |
  82. | `grace-reviewer` | Review semantic integrity, projections, scopes, and verification quality |
  83. | `grace-migrate` | Agent-applied GRACE 3 to GRACE 4 migration with CLI validation |
  84. ## CLI Overview
  85. | Command | What It Does |
  86. | --- | --- |
  87. | `grace lint --path <root> --assertions current` | Run the pre-implementation full-project check, including baselines of active approved changes; do not use it as post-edit target/final evidence |
  88. | `grace lint --path <root> --change C-ID --assertions target \| final --run-commands` | Execute declared `MustPassCommand` gates with compact progress on stderr, per-command timings, a default 600s per-command timeout (`--command-timeout`), and full run logs under `~/.cache/grace/run-commands/` (`--keepRuns` bounds how many non-passing runs are kept) |
  89. | `grace lint --path <root> --change C-ID --assertions baseline [--run-commands]` | Validate the immutable selected baseline before implementation; command assertions run only when explicitly enabled |
  90. | `grace lint --path <root> --change C-ID --assertions target --run-commands` | Validate selected target assertions and explicitly opt into `MustPassCommand` execution |
  91. | `grace lint --path <root> --change C-ID --assertions final [--run-commands]` | Run the final full-project gate, evaluate the selected target, and keep unrelated approved baselines active without re-evaluating the selected baseline |
  92. | `grace lint --path <root> --parallel-preflight` | Run the explicit approved-plan scope coexistence gate required for parallel-safe execution |
  93. | `grace status --path <root>` | Report durable health, stale plans, scope conflicts, and explained/unexplained observed git drift |
  94. | `grace module find <query> --path <root>` | Search graph projection modules by id, path, text, dependency, or verification id |
  95. | `grace module show <id-or-path> --path <root>` | Show graph projection context and linked file-local markup |
  96. | `grace module show <id> --with verification --path <root>` | Include matching deterministic `V-M-*` verification entries |
  97. | `grace verification find <query> --path <root>` | Search verification projection entries |
  98. | `grace verification show <id-or-module> --path <root>` | Show one verification entry and module context |
  99. | `grace file show <path> --path <root>` | Show file-local `MODULE_CONTRACT`, `MODULE_MAP`, and `CHANGE_SUMMARY` |
  100. `MustPassCommand` entries are leaf project evidence such as tests, typecheck, build, format, or package checks. Do not nest `grace lint`, `grace status`, or another GRACE lifecycle command inside plan assertions; selected target/final lint is the external orchestration gate.
  101. Each `<Command>` may declare an optional `budgetSeconds` attribute — `<Command budgetSeconds="1800">bun run gate:e2e</Command>` — which becomes that command's timeout under `--run-commands` in preference to the global `--command-timeout`. The grammar matches `--command-timeout`: a non-negative whole number of seconds, where `0` disables the timeout for that command and omitting the attribute keeps the global default. Lint also reports `assertion.command-subsumed` as a warning when two commands in the same assertion section share a command head and one's path arguments are a component-wise prefix of the other's, so a gate that re-runs `bun test src/grace4` under `bun test src` is visible rather than merely slow.
  102. Output modes:
  103. - `grace lint`: `text`, `json`
  104. - `grace status`: `text`, `json`
  105. - `grace module find`: `table`, `json`
  106. - `grace module show`: `text`, `json`
  107. - `grace verification find`: `table`, `json`
  108. - `grace verification show`: `text`, `json`
  109. - `grace file show`: `text`, `json`
  110. Lint, status, and projection-backed navigation fail closed: invalid options, invalid grammar, malformed active assertions/scopes, duplicate ownership, missing routed files, or ambiguous targets produce structured results or a nonzero error envelope. JSON command failures emit one stable `{ "schemaVersion": "1.0.0", "ok": false, "error": { ... } }` envelope on stdout; text failures emit one concise actionable line without a stack trace.
  111. ### Lint Configuration
  112. An optional `.grace-lint.json` file at the project root (next to `.grace`) controls how `grace lint` and the query commands collect code files, and how long command-run evidence is kept:
  113. ```json
  114. {
  115. "ignoredDirs": ["generated", "fixtures-output"],
  116. "runLogRetention": 25
  117. }
  118. ```
  119. - `ignoredDirs` lists directory names to prune from file collection, on top of the built-in set below. Names match at any depth; globs and paths are not supported.
  120. - `runLogRetention` is how many *non-passing* `--run-commands` run directories survive pruning, default 10. The newest passing run of every change is protected and never pruned, so evidence an archived change cites stays on disk. `--keepRuns N` overrides the key for a single run; `0` keeps no non-passing runs at all, which removes the current run as soon as it fails or runs without a `--change` to bind it to.
  121. - The file must be a JSON object with supported keys only. Broken JSON, a non-object shape, an unknown key, a non-array `ignoredDirs`, or a `runLogRetention` that is not a non-negative integer is a `config.*` lint error, and query commands refuse to run until the file is fixed.
  122. - A directory that cannot be listed (restrictive permissions, sandbox leftovers) is skipped with a `walk.unreadable-directory` warning instead of aborting the run; add its name to `ignoredDirs` to prune it silently. Explain any of these codes with `grace lint --explain <code>`.
  123. Built-in ignored directories:
  124. - VCS metadata: `.git`, `.svn`, `.hg`
  125. - JavaScript/TypeScript output and caches: `node_modules`, `dist`, `build`, `coverage`, `.next`, `.nuxt`, `.output`, `out`, `.turbo`, `.vite`, `.parcel-cache`, `.svelte-kit`, `.astro`, `storybook-static`, `.cache`, `.yarn`, `.nyc_output`, `bower_components`, `jspm_packages`, `.stryker-tmp`, `.serverless`, `.docusaurus`
  126. - Python bytecode, virtualenvs, and tool caches: `__pycache__`, `venv`, `.venv`, `.tox`, `.nox`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `.pyre`, `.pytype`, `htmlcov`, `.eggs`, `.hypothesis`, `.ipynb_checkpoints`, `__pypackages__`, `.pixi`, `cover`
  127. - Test reports and artifacts: `test-results`, `test-reports`, `playwright-report`, `blob-report`, `allure-results`, `allure-report`, `test-output`, `newman`, `cucumber-report`, `cucumber-reports`
  128. - JVM and Rust build output: `target`, `.gradle`, `.idea`
  129. - Vendored dependencies (Go modules, Ruby bundler, PHP Composer): `vendor`
  130. - Swift/Apple toolchain output and dependencies: `.build`, `Pods`, `Carthage`, `DerivedData`
  131. - .NET intermediate build output: `obj`
  132. - Dart/Flutter tooling cache: `.dart_tool`
  133. - Ruby/general scratch space: `tmp`, `.bundle`
  134. - Editor metadata: `.vscode`
  135. `bin` is deliberately not built in: .NET puts compiled output there, but Node, Rails and others keep real source in it, and `ignoredDirs` can only add to this set. A .NET project that wants it pruned adds `"ignoredDirs": ["bin"]`.
  136. ### Analysis Cache
  137. Successful per-file language analyses are cached across runs, so unchanged governed files are not re-analyzed. Entries are keyed by file content and extension plus a schema version: any file edit or analyzer logic change invalidates the entry automatically, and failed analyses are never cached, so fixing a missing runtime takes effect immediately.
  138. - Location: `$XDG_CACHE_HOME/grace-cli/analysis`, falling back to `~/.cache/grace-cli/analysis`. Override the base directory with `GRACE_CACHE_DIR`.
  139. - Disable caching with `GRACE_NO_CACHE=1`.
  140. - The cache lives outside the project: it never touches `.grace` and produces no drift noise.
  141. ## Grep-First Navigation
  142. Prefer this order when narrowing scope:
  143. 1. Search `.grace/graph/index.xml` for graph document routing.
  144. 2. Open routed graph documents for `M-*` and `DF-*` anchors.
  145. 3. Search `.grace/verification/index.xml` for verification routing.
  146. 4. Open routed verification documents for `V-M-*` entries.
  147. 5. Search `.grace/changes/active/C-*` for in-flight specs and plans.
  148. 6. Search source/test files for `LINKS:`, `START_MODULE_CONTRACT`, `START_CONTRACT:`, and `START_BLOCK_`.
  149. Common anchors:
  150. - `GD-*` graph document wrappers
  151. - `M-*` module IDs
  152. - `DF-*` data-flow IDs
  153. - `VD-*` verification document wrappers
  154. - `V-M-*` verification IDs
  155. - `C-*` change bundles
  156. - `T-*` implementation plan tasks
  157. ## Repository Layout
  158. | Path | Purpose |
  159. | --- | --- |
  160. | `skills/grace/*` | Canonical skill sources |
  161. | `plugins/grace/skills/grace/*` | Packaged mirror used for marketplace distribution |
  162. | `.claude-plugin/marketplace.json` | Marketplace entry and published skill set |
  163. | `plugins/grace/.claude-plugin/plugin.json` | Packaged plugin manifest |
  164. | `src/grace.ts` | CLI entrypoint |
  165. | `src/grace4/*` | GRACE 4 project detection, XML parsing, grammar, projections, assertions, and scopes |
  166. | `src/lint/*` | `grace lint` implementation |
  167. | `src/query/*` | Projection-backed query layer for CLI navigation |
  168. | `scripts/validate-marketplace.ts` | Packaging, version, path, and mirror validation |
  169. | `RELEASING.md` | Manual release checklist and validation commands |
  170. ## Development
  171. ```bash
  172. bun test
  173. bun run ./scripts/validate-marketplace.ts
  174. bun run validate:packed
  175. bun run validate:release
  176. ```
  177. For CLI changes, keep tests in `src/grace-lint.test.ts`, `src/grace-status.test.ts`, and `src/grace-query.test.ts` aligned with the GRACE 4 `.grace` fixture model.
  178. Stable releases use a protected-main two-stage flow. `release:bump` runs on a clean release branch that contains current `origin/main`, updates and validates the version surfaces, commits them, pushes the branch, and finds or creates the release PR without creating a tag. After its required checks pass and the PR is merged, `release:finalize X.Y.Z` runs from clean synchronized `main`, revalidates the exact stable state, creates the annotated tag, and pushes only that tag. CI independently requires the stable tag commit to equal fetched `origin/main` and gates npm `latest` publication through the reviewer-protected `stable-release` environment, whose explicit deployment policies allow only branch `main` and tags `v*`. Protected `main` requires Linux, Windows, and real-Dart checks without requiring a separate PR approval, while an active ruleset keeps `v*` tags immutable. `bun run release:checklist` verifies those controls and, after publication from the exact release tag commit, verifies `HEAD == tag`, npm/GitHub channel metadata, and that the local `npm pack` shasum matches the immutable published tarball.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.