// Complete GRACE methodology reference. Use when explaining GRACE to users, onboarding new projects, or when you need to understand the GRACE framework - its principles, semantic markup, knowledge graphs, contracts, testing, and unique tag conventions.
Operate the optional `grace` CLI against a GRACE project. Use when you want to lint GRACE artifacts, explain/remediate lint issues, check autonomy readiness, inspect project or module health, inspect verification entries, resolve modules from names or file paths, inspect shared/public module context, or inspect file-local/private markup through `grace lint`, `grace status`, `grace module`, `grace verification`, and `grace file show`.
Bootstrap GRACE framework structure for a new project. Use when starting a new project with GRACE methodology - creates docs/ directory, AGENTS.md, and XML templates for requirements, technology, development plan, verification plan, knowledge graph, and operational packet contracts.
Execute the full GRACE development plan step by step with controller-managed context packets, verification-plan excerpts, scoped reviews, level-based verification, and commits after validated sequential steps.
Execute a GRACE development plan in controller-managed parallel waves with selectable safety profiles, verification-plan excerpts, batched shared-artifact sync, and scoped reviews.
Create GRACE subagent presets for the current agent shell. Use when you want GRACE worker and reviewer agent files scaffolded for Claude Code, OpenCode, Codex, or another shell.
Show the current health status of a GRACE project. Use to get an overview of project artifacts, codebase metrics, knowledge graph health, verification coverage, and suggested next actions.
| name | grace-explainer |
| description | Complete GRACE methodology reference. Use when explaining GRACE to users, onboarding new projects, or when you need to understand the GRACE framework - its principles, semantic markup, knowledge graphs, contracts, testing, and unique tag conventions. |
GRACE is a methodology for AI-driven code generation that makes codebases navigable by LLMs. It solves the core problem of AI coding assistants: they generate code but can't reliably navigate, maintain, or evolve it across sessions.
LLMs lose context between sessions. Without structure:
GRACE provides four interlocking systems that fix this:
Knowledge Graph (docs/knowledge-graph.xml)
maps modules, dependencies, and public module interfaces
Module Contracts (MODULE_CONTRACT in each file)
defines WHAT each module does
Semantic Markup (START_BLOCK / END_BLOCK in code)
makes code navigable at ~500 token granularity
Verification Plan (docs/verification-plan.xml)
defines HOW correctness, traces, and logs are proven
Operational Packets (docs/operational-packets.xml)
standardizes execution packets, deltas, and failure handoff
GRACE is process-first, not prompt-first. The point is to make good execution boring: define the contract, name the surfaces, plan verification, and give the worker a bounded packet before asking it to run.
Before generating any module, create its MODULE_CONTRACT with PURPOSE, SCOPE, INPUTS, OUTPUTS. The contract is the source of truth — code implements the contract, not the other way around.
Markers like // START_BLOCK_NAME and // END_BLOCK_NAME are navigation anchors, not documentation. They serve as attention anchors for LLM context management and retrieval points for RAG systems.
docs/knowledge-graph.xml is the single map of the entire project. When you add a module — add it to the graph. When you add a dependency — add a CrossLink. The graph never drifts from reality. Shared docs should describe the module's public contract, not every private helper or implementation detail.
Code generation follows a strict pipeline:
Requirements -> Technology -> Development Plan -> Verification Plan -> Module Contracts -> Code + Tests
Never jump to code. If requirements are unclear — stop and clarify.
Testing, traces, and log markers are not cleanup work. They are part of the architectural blueprint. If another agent cannot verify or debug a module from the evidence left behind, the module is not fully done.
You have freedom in HOW, not in WHAT. If a contract seems wrong — propose a change, don't silently deviate.
GRACE assumes that agents work better when the code and artifacts carry domain meaning directly.
CustomerProfile, ArchiveDatabase, ValidateInput, and BLOCK_ASSIGN_TITLE over abstract placeholders or opaque IDsThis does not replace contracts. It makes contracts easier for agents to execute accurately.
docs/requirements.xml — WHAT the user needs (use cases, AAG notation)
|
docs/technology.xml — WHAT tools we use (runtime, language, versions)
|
docs/development-plan.xml — HOW we structure it (modules, phases, public contracts)
|
docs/verification-plan.xml — HOW we prove it works (tests, traces, log markers)
docs/operational-packets.xml — HOW agents hand work across execution, review, and fixes
|
docs/knowledge-graph.xml — MAP of module boundaries, dependencies, public interfaces, and verification refs
|
src/**/* + tests/**/* — CODE and TESTS with GRACE markup and evidence hooks
Each layer feeds the next. The knowledge graph and verification plan are both outputs of planning and inputs for execution.
Important boundary rule:
GRACE also has an optional CLI package, @osovv/grace-cli, which installs the grace binary.
Current public commands:
grace lint --path /path/to/projectgrace lint --profile autonomous --path /path/to/projectgrace lint --explain docs.missing-required-artifactgrace status --path /path/to/projectgrace status --with modules --path /path/to/projectgrace module find auth --path /path/to/projectgrace module show M-AUTH --path /path/to/project --with verification,healthgrace module health M-AUTH --path /path/to/projectgrace verification find auth --path /path/to/projectgrace verification show V-M-AUTH --path /path/to/projectgrace file show src/auth/index.ts --path /path/to/project --contracts --blocksUse the CLI for:
Public/private split:
grace module show is the shared/public view of a module from plan, graph, steps, and verificationgrace file show is the file-local/private view from MODULE_CONTRACT, MODULE_MAP, CHANGE_SUMMARY, scoped contracts, and semantic blocksgrace module find searches both planes, including LINKS from file-local markupThe CLI does not replace $grace-reviewer, $grace-refresh, or $grace-verification. It is a cheap automated guardrail before or alongside those higher-context workflows.
Typical preflight:
grace status for the current health snapshot and next actiongrace status --with modules when you also need per-module health summariesgrace lint for structural driftgrace lint --profile autonomous before long autonomous executiongrace lint --explain <code> when one issue needs built-in remediation guidance$grace-init — create docs/ structure and AGENTS.mdrequirements.xml with use casestechnology.xml with stack decisions$grace-plan — architect modules, data flows, and verification refs$grace-verification — design and maintain tests, traces, and log-driven evidence$grace-execute — generate all modules sequentially with review and commits$grace-multiagent-execute — generate parallel-safe modules in controller-managed waves$grace-refactor — rename, move, split, merge, or extract modules without drift$grace-refresh — sync graph and verification refs after manual changes$grace-fix error-description — debug via semantic navigation$grace-status — health report$grace-ask — grounded Q&A over the project artifactsFor in-depth documentation on each GRACE component, see the reference files in this skill's references/ directory:
references/semantic-markup.md — Block conventions, granularity rules, loggingreferences/knowledge-graph.md — Graph structure, module types, CrossLinks, maintenancereferences/contract-driven-dev.md — MODULE_CONTRACT, function contracts, PCAMreferences/verification-driven-dev.md — Verification plans, test design, traces, and log-driven developmentreferences/unique-tag-convention.md — Unique ID-based XML tags, why they work, full naming table