GRACE — Graph-RAG Anchored Code Engineering

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.

The Problem GRACE Solves

LLMs lose context between sessions. Without structure:

• They don't know what modules exist or how they connect

• They generate code that duplicates or contradicts existing code

• They can't trace bugs through the codebase

• They drift from the original architecture over time

GRACE provides three interlocking systems that fix this:

Knowledge Graph (docs/knowledge-graph.xml) maps modules, dependencies, exports 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

Five Core Principles

1. Never Write Code Without a Contract

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.

2. Semantic Markup Is Not Comments

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.

3. Knowledge Graph Is Always Current

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.

4. Top-Down Synthesis

Code generation follows a strict pipeline:

Requirements -> Technology -> Development Plan -> Module Contracts -> Code

Never jump to code. If requirements are unclear — stop and clarify.

5. Governed Autonomy (PCAM)

• Purpose: defined by the contract (WHAT to build)

• Constraints: defined by the development plan (BOUNDARIES)

• Autonomy: you choose HOW to implement

• Metrics: the contract's outputs tell you if you're done

You have freedom in HOW, not in WHAT. If a contract seems wrong — propose a change, don't silently deviate.

How the Elements Connect

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, contracts) | docs/knowledge-graph.xml — MAP of everything (modules, dependencies, exports) | src/**/* — CODE with GRACE markup (contracts, blocks, maps)

Each layer feeds the next. The knowledge graph is both an output of planning and an input for code generation.

Development Workflow

• $grace-init — create docs/ structure and AGENTS.md

• Fill in requirements.xml with use cases

• Fill in technology.xml with stack decisions

• $grace-plan — architect modules, generate development plan and knowledge graph

• $grace-generate module-name — generate one module with full markup

• $grace-execute — generate all modules sequentially with review and commits

• $grace-setup-subagents — scaffold shell-specific GRACE worker/reviewer presets

• $grace-multiagent-execute — generate parallel-safe modules in controller-managed waves

• $grace-verification — design AI-friendly tests, traces, and observability

• $grace-refresh — sync knowledge graph after manual changes

• $grace-fix error-description — debug via semantic navigation

• $grace-status — health report

Detailed References

For 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, logging

• references/knowledge-graph.md — Graph structure, module types, CrossLinks, maintenance

• references/contract-driven-dev.md — MODULE_CONTRACT, function contracts, PCAM

• references/unique-tag-convention.md — Unique ID-based XML tags, why they work, full naming table