Skip to content

Commit 0a6ef40

Browse files
xronocodeqwencoder
xronocode
and
qwencoder
committed
GRACE. (feat) Initialize GRACE framework with offline-first architecture documentation
- Add GRACE skill system (.kilocode/skills/grace-*) - Initialize knowledge graph with 30 modules (docs/knowledge-graph.xml v0.2.0) - Add requirements analysis with 16 use cases (docs/requirements.xml) - Document technology stack decisions (docs/technology.xml) - Create development plan with 8 phases (docs/development-plan.xml) - Add MODULE_CONTRACT blocks to 12 Flutter offline mode files - Add 63 semantic blocks for code navigation - Update AGENTS.md with GRACE principles and unique tag convention Offline mode modules documented: - OutboxSyncManager (batch sync with retry) - OutboxRepository (SQLite persistence) - HttpRemoteSyncClient (HTTP adapter) - OfflineStatusTracker (UI connectivity indicator) - OutboxEventLogger (analytics queuing) - GameController (child session orchestration) - SyncStateRepository (sync state persistence) - LocalProgressRepository (snapshot aggregation) - Domain interfaces (SyncManager, RemoteSyncClient, EventLogger, OutboxRepository) Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
1 parent d9816fc commit 0a6ef40

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+2642
-364
lines changed

‎.DS_Store‎

0 Bytes
Binary file not shown.

‎.kilocode/.DS_Store‎

0 Bytes
Binary file not shown.

‎.kilocode/skills/grace-add/SKILL.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: grace-add
3+
description: "Add a new module to a GRACE project with contract and knowledge graph entry. Use when you need to introduce a new module that wasn't part of the original plan — designs the contract, updates planning artifacts, generates code, and verifies integration."
4+
---
5+
6+
Add a new module to the project.
7+
8+
## Process
9+
10+
### Step 1: Understand Context
11+
Read `docs/knowledge-graph.xml` to understand:
12+
- What modules already exist
13+
- What the new module will connect to
14+
- What gap it fills
15+
16+
### Step 2: Design Contract
17+
Propose a MODULE_CONTRACT for the new module:
18+
- PURPOSE
19+
- SCOPE
20+
- DEPENDS (which existing modules)
21+
- Key functions/components it will expose
22+
23+
**Present to user and wait for approval.**
24+
25+
### Step 3: Update Planning Artifacts
26+
After approval:
27+
1. Add the module to `docs/development-plan.xml` using unique ID-based tag: M-xxx NAME="..." TYPE="..." LAYER="N" ORDER="N". Use export-name for interface entries, step-N for pipeline steps. See AGENTS.md "Documentation Artifacts" for full convention.
28+
2. Add the module to `docs/knowledge-graph.xml` with unique ID-based tag: M-xxx NAME="..." TYPE="...". Use fn-name, type-Name, class-Name for annotation entries. Add CrossLinks to dependencies.
29+
30+
### Step 4: Generate Code
31+
Follow the same generation protocol as `$grace-generate`:
32+
- Full MODULE_CONTRACT header
33+
- MODULE_MAP
34+
- CHANGE_SUMMARY
35+
- Contracts for each function/component
36+
- Semantic blocks with unique names
37+
38+
### Step 5: Verify Integration
39+
- Check that imports from existing modules resolve
40+
- Run type checking or linting as appropriate for the project language
41+
- Verify CrossLinks are bidirectionally consistent in the knowledge graph

‎.kilocode/skills/grace-add/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "GRACE Add"
3+
short_description: "Add new module with contract"
4+
brand_color: "#4A90D9"

‎.kilocode/skills/grace-ask/SKILL.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: grace-ask
3+
description: "Answer a question about a GRACE project using full project context. Use when the user has a question about the codebase, architecture, modules, or implementation — loads all GRACE artifacts, navigates the knowledge graph, and provides a grounded answer with citations."
4+
---
5+
6+
Answer a question about the current GRACE project.
7+
8+
## Process
9+
10+
### Step 1: Load Project Context
11+
Read the following files (skip any that don't exist):
12+
1. `AGENTS.md` — project principles and conventions
13+
2. `docs/knowledge-graph.xml` — module map, dependencies, exports
14+
3. `docs/requirements.xml` — use cases and requirements
15+
4. `docs/technology.xml` — stack, runtime, libraries
16+
5. `docs/development-plan.xml` — phases, modules, contracts
17+
18+
### Step 2: Identify Relevant Modules
19+
Based on the question, find the most relevant modules:
20+
1. Use the knowledge graph to locate modules related to the question
21+
2. Follow CrossLinks to find connected modules
22+
3. Read MODULE_CONTRACTs of relevant modules for detailed context
23+
24+
### Step 3: Dive Into Code If Needed
25+
If the question is about specific behavior or implementation:
26+
1. Use MODULE_MAP to locate relevant functions/blocks
27+
2. Read the specific START_BLOCK/END_BLOCK sections
28+
3. Read function CONTRACTs for intent vs implementation details
29+
30+
### Step 4: Answer
31+
Provide a clear, concise answer grounded in the actual project artifacts. Always cite which files/modules/blocks your answer is based on.
32+
33+
### Important
34+
- Never guess — if the information isn't in the project artifacts, say so
35+
- If the question reveals a gap in documentation or contracts, mention it
36+
- If the answer requires changes to the project, suggest the appropriate `$grace-*` skill

‎.kilocode/skills/grace-ask/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "GRACE Ask"
3+
short_description: "Answer questions with project context"
4+
brand_color: "#4A90D9"

‎.kilocode/skills/grace-execute/SKILL.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
name: grace-execute
3+
description: "Execute the full GRACE development plan step by step, generating code for each pending module with validation and commits. Use when the architecture is planned and you want to generate all modules sequentially with review checkpoints."
4+
---
5+
6+
Execute the development plan step by step, generating code for each pending module with validation and commits.
7+
8+
## Prerequisites
9+
- `docs/development-plan.xml` must exist with an ImplementationOrder section
10+
- `docs/knowledge-graph.xml` must exist
11+
- If either is missing, tell the user to run `$grace-plan` first
12+
13+
## Process
14+
15+
### Step 1: Load and Parse the Plan
16+
Read `docs/development-plan.xml`. Parse ImplementationOrder and build the execution queue:
17+
1. Collect all Phase-N elements where status="pending" (tags use unique names: Phase-1, Phase-2, etc.)
18+
2. Within each phase, collect step-N elements (unique tags: step-1, step-2, etc.)
19+
3. Present the execution queue to the user as a numbered list:
20+
```
21+
Execution Queue:
22+
Phase N: phase name
23+
Step order: module ID — step description
24+
Step order: module ID — step description
25+
Phase N+1: ...
26+
```
27+
4. **Wait for user approval before proceeding.** The user may exclude specific steps or reorder.
28+
29+
### Step 2: Execute Each Step
30+
For each step in the approved queue, sequentially:
31+
32+
#### 2a. Generate Code
33+
Follow the `$grace-generate` protocol for this module:
34+
- Load context from knowledge-graph.xml
35+
- Generate code with MODULE_CONTRACT + MODULE_MAP + CHANGE_SUMMARY + semantic blocks
36+
- Update knowledge-graph.xml with CrossLinks
37+
- Run type checking
38+
39+
#### 2b. Code Review
40+
After generating, review the code:
41+
- Does the generated code match the MODULE_CONTRACT from `development-plan.xml`?
42+
- Are all GRACE markup conventions followed (paired blocks, unique names, ~500 token granularity)?
43+
- Are imports correct and do they reference existing modules?
44+
- Are there any security issues or obvious bugs?
45+
46+
If **critical issues** found (missing contract fields, broken imports, security problems):
47+
1. Present the issues to the user
48+
2. Fix them before proceeding
49+
3. Re-run the review
50+
51+
If only **minor issues** (style, naming suggestions): note them and proceed.
52+
53+
#### 2c. Plan Review
54+
Verify the step against the development plan:
55+
1. Read the module's M-xxx entry in `development-plan.xml`
56+
2. Confirm all export-xxx entries are implemented
57+
3. Confirm all depends modules are imported
58+
4. Confirm the contract inputs/outputs/errors match the implementation
59+
5. Check that `docs/knowledge-graph.xml` was updated with the new module entry and CrossLinks
60+
61+
If mismatches are found — fix them before committing.
62+
63+
#### 2d. Commit
64+
After validation passes:
65+
1. Stage only the files related to this step (the generated module + updated knowledge-graph.xml)
66+
2. Create a commit with message format:
67+
```
68+
grace(MODULE_ID): short description of what was generated
69+
70+
Phase N, Step order
71+
Module: module name (module path)
72+
Contract: one-line purpose from development-plan.xml
73+
```
74+
3. Report commit hash to user
75+
76+
#### 2e. Progress Report
77+
After each step, print:
78+
```
79+
--- Step order/total complete ---
80+
Module: MODULE_ID (path)
81+
Status: DONE
82+
Review: passed / passed with N minor notes
83+
Commit: hash
84+
Remaining: count steps
85+
```
86+
87+
### Step 3: Phase Completion
88+
After all steps in a phase are done:
89+
1. Update `docs/development-plan.xml`: set the Phase-N element's status attribute to "done"
90+
2. Run `$grace-refresh` to verify knowledge graph integrity
91+
3. Commit the plan update:
92+
```
93+
grace(plan): mark Phase N "phase name" as done
94+
```
95+
4. Print phase summary
96+
97+
### Step 4: Final Summary
98+
After all phases are executed:
99+
```
100+
=== EXECUTION COMPLETE ===
101+
Phases executed: count
102+
Modules generated: count
103+
Total commits: count
104+
Knowledge graph: synced
105+
```
106+
107+
## Error Handling
108+
- If a step fails — stop execution, report the error, and ask the user how to proceed
109+
- If type checking fails — attempt to fix, if unfixable stop and report
110+
- Never skip a failing step — the dependency chain matters
111+
112+
## Important
113+
- Steps within a phase are executed **sequentially** (dependencies matter)
114+
- Always verify the previous step's outputs exist before starting the next step
115+
- The development plan is the source of truth — never deviate from the contract

‎.kilocode/skills/grace-execute/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "GRACE Execute"
3+
short_description: "Execute full development plan"
4+
brand_color: "#4A90D9"

‎.kilocode/skills/grace-explainer/SKILL.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
name: grace-explainer
3+
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, and unique tag conventions."
4+
---
5+
6+
# GRACE — Graph-RAG Anchored Code Engineering
7+
8+
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.
9+
10+
## The Problem GRACE Solves
11+
12+
LLMs lose context between sessions. Without structure:
13+
- They don't know what modules exist or how they connect
14+
- They generate code that duplicates or contradicts existing code
15+
- They can't trace bugs through the codebase
16+
- They drift from the original architecture over time
17+
18+
GRACE provides three interlocking systems that fix this:
19+
20+
```
21+
Knowledge Graph (docs/knowledge-graph.xml)
22+
maps modules, dependencies, exports
23+
Module Contracts (MODULE_CONTRACT in each file)
24+
defines WHAT each module does
25+
Semantic Markup (START_BLOCK / END_BLOCK in code)
26+
makes code navigable at ~500 token granularity
27+
```
28+
29+
## Five Core Principles
30+
31+
### 1. Never Write Code Without a Contract
32+
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.
33+
34+
### 2. Semantic Markup Is Not Comments
35+
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.
36+
37+
### 3. Knowledge Graph Is Always Current
38+
`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.
39+
40+
### 4. Top-Down Synthesis
41+
Code generation follows a strict pipeline:
42+
```
43+
Requirements -> Technology -> Development Plan -> Module Contracts -> Code
44+
```
45+
Never jump to code. If requirements are unclear — stop and clarify.
46+
47+
### 5. Governed Autonomy (PCAM)
48+
- **Purpose**: defined by the contract (WHAT to build)
49+
- **Constraints**: defined by the development plan (BOUNDARIES)
50+
- **Autonomy**: you choose HOW to implement
51+
- **Metrics**: the contract's outputs tell you if you're done
52+
53+
You have freedom in HOW, not in WHAT. If a contract seems wrong — propose a change, don't silently deviate.
54+
55+
## How the Elements Connect
56+
57+
```
58+
docs/requirements.xml — WHAT the user needs (use cases, AAG notation)
59+
|
60+
docs/technology.xml — WHAT tools we use (runtime, language, versions)
61+
|
62+
docs/development-plan.xml — HOW we structure it (modules, phases, contracts)
63+
|
64+
docs/knowledge-graph.xml — MAP of everything (modules, dependencies, exports)
65+
|
66+
src/**/* — CODE with GRACE markup (contracts, blocks, maps)
67+
```
68+
69+
Each layer feeds the next. The knowledge graph is both an output of planning and an input for code generation.
70+
71+
## Development Workflow
72+
73+
1. `$grace-init` — create docs/ structure and AGENTS.md
74+
2. Fill in `requirements.xml` with use cases
75+
3. Fill in `technology.xml` with stack decisions
76+
4. `$grace-plan` — architect modules, generate development plan and knowledge graph
77+
5. `$grace-generate module-name` — generate one module with full markup
78+
6. `$grace-execute` — generate all modules with review and commits
79+
7. `$grace-refresh` — sync knowledge graph after manual changes
80+
8. `$grace-fix error-description` — debug via semantic navigation
81+
9. `$grace-status` — health report
82+
83+
## Detailed References
84+
85+
For in-depth documentation on each GRACE component, see the reference files in this skill's `references/` directory:
86+
87+
- `references/semantic-markup.md` — Block conventions, granularity rules, logging
88+
- `references/knowledge-graph.md` — Graph structure, module types, CrossLinks, maintenance
89+
- `references/contract-driven-dev.md` — MODULE_CONTRACT, function contracts, PCAM
90+
- `references/unique-tag-convention.md` — Unique ID-based XML tags, why they work, full naming table

‎.kilocode/skills/grace-explainer/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "GRACE Explainer"
3+
short_description: "Complete GRACE methodology reference"
4+
brand_color: "#4A90D9"

0 commit comments

Comments
 (0)