What happens if prerequisites are missing?

Grace-plan must be run to register the module contract and knowledge-graph entry before grace-generate can produce code.

Can I use grace-generate for any language?

Yes, but you must adapt the file header and comment markers to the target language (e.g., # for Python, // for Go/TypeScript).

How does the tool keep the knowledge graph in sync?

It reads module entries and dependencies from the knowledge-graph.xml, and after generation, it updates cross-links and annotations for key methods.

grace-generate

npx machina-cli add skill osovv/grace-marketplace/grace-generate --openclaw

Files (1)

SKILL.md

2.2 KB

Generate code for the module specified by the user.

Prerequisites

docs/development-plan.xml must contain this module's contract
docs/knowledge-graph.xml must have this module registered
If either is missing, tell the user to run $grace-plan first

Process

Step 1: Load Context

Read from the knowledge graph:

The target module's entry in knowledge-graph.xml
All modules it depends on (follow CrossLinks)
The contracts of those dependency modules (read their MODULE_CONTRACT headers)

Step 2: Generate with GRACE Markup

Generate the code file following this exact structure:

// FILE: path
// VERSION: 1.0.0
// START_MODULE_CONTRACT
//   PURPOSE: from development-plan.xml
//   SCOPE: from development-plan.xml
//   DEPENDS: list
//   LINKS: knowledge graph references
// END_MODULE_CONTRACT
//
// START_MODULE_MAP
//   list all exports with one-line descriptions
// END_MODULE_MAP

// START_CHANGE_SUMMARY
//   LAST_CHANGE: [v1.0.0 — Initial generation from development plan]
// END_CHANGE_SUMMARY

imports

// START_CONTRACT: ComponentOrFunction
//   PURPOSE: ...
//   INPUTS: ...
//   OUTPUTS: ...
// END_CONTRACT: ComponentOrFunction

code with START_BLOCK / END_BLOCK markers every ~500 tokens

Adapt comment syntax to the project language (e.g., # for Python, // for Go/TypeScript/Java).

Step 3: Update Knowledge Graph

After generation, update knowledge-graph.xml:

Add/verify the module entry with correct FILE path
Add CrossLinks to all imported modules
Add annotations for key methods

Step 4: Verify

Run type checking or linting as appropriate for the project. Report results.

Granularity Rules

Blocks should be ~500 tokens (matching LLM sliding window)
Every block name must be unique within the file
Block names should describe WHAT the block does, not HOW
- Good: VALIDATE_USER_PERMISSIONS, FETCH_AND_CACHE_DATA
- Bad: LOGIC_1, HELPER, MAIN_BLOCK

Source

git clone https://github.com/osovv/grace-marketplace/blob/main/codex-skills/grace-generate/SKILL.mdView on GitHub

Overview

Grace-generate creates the implementation code for a GRACE module once it has been planned and contracted. It reads contracts and dependencies from development-plan.xml and the knowledge graph, then outputs a structured file containing MODULE_CONTRACT, MODULE_MAP, semantic blocks, and knowledge-graph updates. This ensures a traceable, standardized, and ready-to-build module scaffold.

How This Skill Works

The tool loads the target module entry and all dependencies from the knowledge graph, along with their contracts. It then generates a code file following the exact structure: header with version, START_MODULE_CONTRACT, START_MODULE_MAP, START_CHANGE_SUMMARY, imports, and START_CONTRACT blocks, wrapped in unique BLOCK sections (~500 tokens each) and with language-appropriate comment syntax. After generation, it updates knowledge-graph.xml with new cross-links and annotated methods, followed by a lint/type-check verification.

When to Use It

You have a contracted module in development-plan.xml and need a complete implementation file with MODULE_CONTRACT and MODULE_MAP.
Dependencies for the target module are registered in the knowledge graph and you want automated code generation reflecting those contracts.
You are updating a module contract and need to regenerate the implementation to align exports and semantic blocks.
Working in a multi-language GRACE project and requiring language-specific comment syntax (e.g., # for Python, // for Go/TypeScript).
You want end-to-end automation that also updates the knowledge graph and runs verification after generation.

Quick Start

Step 1: Ensure development-plan.xml contains the active contract and the module is registered in the knowledge graph.
Step 2: Run grace-plan if needed to refresh contracts and cross-links, then execute grace-generate.
Step 3: Review the generated file for MODULE_CONTRACT, MODULE_MAP, semantic blocks, and perform post-generation verification.

Best Practices

Before running, confirm development-plan.xml contains the current contract for the target module.
Verify knowledge-graph.xml includes the module and all its dependency links.
Ensure MODULE_CONTRACT and MODULE_MAP entries are complete and exports are clearly described.
Adapt the comment syntax to the project language and maintain unique block names for each section.
Run type checking and linting after generation and review knowledge-graph updates for accuracy.

Example Use Cases

Generate implementation for a contracted AUTH module, including MODULE_CONTRACT header and MODULE_MAP exports.
Regenerate a module after contract updates to reflect new dependencies and interfaces.
Create code for a data-connector module that adds new cross-links in the knowledge graph.
Generate a module within a polyglot project, adjusting comments to Python or TypeScript as required.
Produce a module with a detailed change summary and versioned header to support traceability.

Frequently Asked Questions

Add this skill to your agents