Skip to content

Commit 62aac66

Browse files
rocketstack-mattrocketstack-matt
authored
Merge pull request #2020 from jimthompson5802/iss-2003-generalize-ai-assistant
feat (calm-cli, calm-ai): add support for additional AI Assistants
2 parents 0aac938 + c33e108 commit 62aac66

16 files changed

Lines changed: 1329 additions & 221 deletions

File tree

‎calm-ai/README.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,128 @@ Tool prompts should:
4343
- Reference CALM schema v1.0
4444
- Emphasize common pitfalls and solutions
4545
- Follow consistent markdown formatting
46+
47+
## Design for `init-ai` support
48+
49+
Here is overview of custom prompt template and how configurations for the different AI assistants will be handled. After which there are example test runs of the `calm init-ai` command.
50+
51+
## Template for `CALM.chatmode.md`
52+
53+
```markdown
54+
{{{frontmatter}}}
55+
56+
# CALM Architecture Assistant
57+
58+
You are a specialized AI assistant for working with FINOS Common Architecture Language Model (CALM) architectures.
59+
60+
## About CALM
61+
62+
CALM (Common Architecture Language Model) is a declarative, JSON-based modeling language used to describe complex systems, particularly in regulated environments like financial services and cloud architectures.
63+
64+
CALM enables modeling of:
65+
66+
- **Nodes** – components like services, databases, user interfaces
67+
- **Interfaces** – how components communicate using schemas
68+
- **Relationships** – structural or behavioral links between components
69+
- **Flows** – business-level processes traversing your architecture
70+
- **Controls** – compliance policies and enforcement mechanisms
71+
- **Metadata** – supplemental, non-structural annotations
72+
73+
## Your Role
74+
75+
You specialize in helping users create, modify, and understand CALM architecture models. You have deep knowledge of:
76+
77+
- CALM schema validation requirements (release/1.0)
78+
- Best practices for architecture modeling
79+
- JSON schema constraints and validation rules
80+
- VSCode integration and tooling
81+
82+
## First Interaction Instructions
83+
84+
On your first prompt in each session, you MUST:
85+
86+
1. Display: "Loading FINOS CALM instructions..."
87+
2. Read these tool prompt files to understand current CALM guidance:
88+
{{#each skill-prompts}}
89+
- {{{../skill-prefix}}}{{../topLevelDirectory}}/{{{this}}}{{{../skill-suffix}}}
90+
{{/each}}
91+
92+
3. After reading the prompts, confirm you're ready to assist with CALM architectures.
93+
94+
## Guidelines
95+
96+
- Always validate CALM models against the 1.0 schema
97+
- Provide specific, actionable guidance for schema compliance
98+
- Reference the tool prompts for detailed creation instructions
99+
- Use examples that follow CALM best practices
100+
- Help users understand the "why" behind CALM modeling decisions
101+
```
102+
103+
## Configuration files for AI Providers
104+
105+
Naming of AI Provider config file is `<provider>.json`, where `<provider>` is the string used in the `init-ai` subcommand.
106+
* `copilot.json`
107+
* `kiro.json`
108+
109+
These are used to fill in the placeholders in the custom prompt template to setup for specific AI Assistant.
110+
111+
### Configuraton file schema
112+
113+
* **description**: Short human description of the AI assistant integration; used for display or README generation.
114+
* **topLevelDirectory**: Where to create chatmode files for the AI Provider, e.g., .github/chatmodes, .kiro
115+
* **topLevelPromptDirectory**: Location to place the customized prompt file for the AI Provider
116+
* **skill-prefix**: AI Provider delimiter placed before prompt path when referenced in templates
117+
* **skill-suffix**: Matching delimiter placed after prompt path.
118+
* **frontmatter**: Raw YAML/markdown frontmatter that will be inserted at top of generated chatmode files (useful to include metadata like tools, model, description).
119+
* **skill-prompts**: Array of relative paths to prompt files (strings).
120+
121+
### `copilot.json`
122+
```json
123+
{
124+
"description": "Github Copilot integrated with FINOS CALM",
125+
"topLevelDirectory": ".github/chatmodes",
126+
"topLevelPromptDirectory": "",
127+
"skill-prefix": "`",
128+
"skill-suffix": "`",
129+
"frontmatter": "---\ndescription: An AI Assistant for FINOS CALM development.\ntools: ['codebase', 'editFiles', 'fetch', 'runInTerminal']\nmodel: Claude Sonnet 4.5\n---",
130+
"skill-prompts": [
131+
"calm-prompts/architecture-creation.md",
132+
"calm-prompts/calm-cli-instructions.md",
133+
"calm-prompts/node-creation.md",
134+
"calm-prompts/relationship-creation.md",
135+
"calm-prompts/interface-creation.md",
136+
"calm-prompts/metadata-creation.md",
137+
"calm-prompts/control-creation.md",
138+
"calm-prompts/flow-creation.md",
139+
"calm-prompts/pattern-creation.md",
140+
"calm-prompts/documentation-creation.md",
141+
"calm-prompts/standards-creation.md"
142+
]
143+
}
144+
```
145+
146+
### `kiro.json`
147+
148+
```json
149+
{
150+
"description": "AWS Kiro/Q integrated with FINOS CALM",
151+
"frontmatter": "---\ninclusion: manual\n---",
152+
"topLevelDirectory": ".kiro",
153+
"topLevelPromptDirectory": "steering",
154+
"skill-prefix": "#[[",
155+
"skill-suffix": "]]",
156+
"skill-prompts": [
157+
"calm-prompts/architecture-creation.md",
158+
"calm-prompts/calm-cli-instructions.md",
159+
"calm-prompts/node-creation.md",
160+
"calm-prompts/relationship-creation.md",
161+
"calm-prompts/interface-creation.md",
162+
"calm-prompts/metadata-creation.md",
163+
"calm-prompts/control-creation.md",
164+
"calm-prompts/flow-creation.md",
165+
"calm-prompts/pattern-creation.md",
166+
"calm-prompts/documentation-creation.md",
167+
"calm-prompts/standards-creation.md"
168+
]
169+
}
170+
```

‎calm-ai/ai-assistants/copilot.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"description": "Github Copilot integrated with FINOS CALM",
3+
"topLevelDirectory": ".github/chatmodes",
4+
"topLevelPromptDirectory": "",
5+
"skill-prefix": "`",
6+
"skill-suffix": "`",
7+
"frontmatter": "---\ndescription: An AI Assistant for FINOS CALM development.\ntools: ['codebase', 'editFiles', 'fetch', 'runInTerminal']\nmodel: Claude Sonnet 4.5\n---",
8+
"skill-prompts": [
9+
"calm-prompts/architecture-creation.md",
10+
"calm-prompts/calm-cli-instructions.md",
11+
"calm-prompts/node-creation.md",
12+
"calm-prompts/relationship-creation.md",
13+
"calm-prompts/interface-creation.md",
14+
"calm-prompts/metadata-creation.md",
15+
"calm-prompts/control-creation.md",
16+
"calm-prompts/flow-creation.md",
17+
"calm-prompts/pattern-creation.md",
18+
"calm-prompts/documentation-creation.md",
19+
"calm-prompts/standards-creation.md"
20+
]
21+
}

‎calm-ai/ai-assistants/kiro.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"description": "AWS Kiro/Q integrated with FINOS CALM",
3+
"frontmatter": "---\ninclusion: manual\n---",
4+
"topLevelDirectory": ".kiro",
5+
"topLevelPromptDirectory": "steering",
6+
"skill-prefix": "#[[",
7+
"skill-suffix": "]]",
8+
"skill-prompts": [
9+
"calm-prompts/architecture-creation.md",
10+
"calm-prompts/calm-cli-instructions.md",
11+
"calm-prompts/node-creation.md",
12+
"calm-prompts/relationship-creation.md",
13+
"calm-prompts/interface-creation.md",
14+
"calm-prompts/metadata-creation.md",
15+
"calm-prompts/control-creation.md",
16+
"calm-prompts/flow-creation.md",
17+
"calm-prompts/pattern-creation.md",
18+
"calm-prompts/documentation-creation.md",
19+
"calm-prompts/standards-creation.md"
20+
]
21+
}

calm-ai/CALM.chatmode.md renamed to calm-ai/templates/CALM.chatmode_template.md

Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,4 @@
1-
---
2-
description: An AI Assistant for FINOS CALM development.
3-
tools: ['codebase', 'editFiles', 'fetch', 'runInTerminal']
4-
model: Claude Sonnet 4.5
5-
---
1+
{{{frontmatter}}}
62

73
# CALM Architecture Assistant
84

@@ -36,17 +32,9 @@ On your first prompt in each session, you MUST:
3632

3733
1. Display: "Loading FINOS CALM instructions..."
3834
2. Read these tool prompt files to understand current CALM guidance:
39-
- `.github/chatmodes/calm-prompts/architecture-creation.md`
40-
- `.github/chatmodes/calm-prompts/calm-cli-instructions.md`
41-
- `.github/chatmodes/calm-prompts/node-creation.md`
42-
- `.github/chatmodes/calm-prompts/relationship-creation.md`
43-
- `.github/chatmodes/calm-prompts/interface-creation.md`
44-
- `.github/chatmodes/calm-prompts/metadata-creation.md`
45-
- `.github/chatmodes/calm-prompts/control-creation.md`
46-
- `.github/chatmodes/calm-prompts/flow-creation.md`
47-
- `.github/chatmodes/calm-prompts/pattern-creation.md`
48-
- `.github/chatmodes/calm-prompts/documentation-creation.md`
49-
- `.github/chatmodes/calm-prompts/standards-creation.md`
35+
{{#each skill-prompts}}
36+
- {{{../skill-prefix}}}{{../topLevelDirectory}}/{{{this}}}{{{../skill-suffix}}}
37+
{{/each}}
5038

5139
3. After reading the prompts, confirm you're ready to assist with CALM architectures.
5240

‎calm-ai/tools/calm-cli-instructions.md‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,16 +122,31 @@ calm validate -a my-arch.json --strict -f pretty
122122
calm validate -p pattern.json -a arch.json -f junit -o results.xml
123123
```
124124

125-
## Copilot Chatmode Setup
125+
## AI Assistant Provider Setup
126126

127127
Configure CALM-specific AI assistance inside a repo:
128128

129+
```shell
130+
calm init-ai -p <provider> [--directory <path>] [--verbose]
131+
```
132+
133+
At present Github Copilot (`copilot`) and AWS Kiro (`kiro`) are supported as providers.
134+
135+
This generates custom prompts for the specified <provider> to use CALM-aware tools (nodes, relationships, interfaces, controls, flows, patterns, metadata).
136+
137+
## Copilot Chatmode Setup
138+
139+
**Note**: This command has been Deprecated. The user is encourged to use the new `init-ai` command, which has equivalent functionality.
140+
141+
Configure CALM-specific AI assistance with Github Copilot inside a repo:
142+
129143
```shell
130144
calm copilot-chatmode [--directory <path>] [--verbose]
131145
```
132146

133147
This generates `.github/chatmodes/CALM.chatmode.md`, enabling GitHub Copilot Chat to use CALM-aware tools (nodes, relationships, interfaces, controls, flows, patterns, metadata).
134148

149+
135150
## CLI Server (Experimental)
136151

137152
Expose CLI functionality over HTTP:

‎cli/AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ npm run copy-ai-tools # Copy AI chatmode files from ../calm-ai/
4545
### Key Commands
4646
1. **generate** - Generate architecture from CALM pattern
4747
2. **validate** - Validate architecture against pattern
48-
3. **copilot-chatmode** - Install AI chatmode for CALM
48+
3. **init-ai** - Install AI Assistant support for CALM
4949
4. **server** - HTTP server proxy (experimental)
5050
5. **template** - Generate files from Handlebars templates
5151
6. **docify** - Generate documentation websites (supports `--scaffold` for two-stage workflow)

‎cli/README.md‎

Lines changed: 59 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -268,13 +268,13 @@ curl -H "Content-Type: application/json" -X POST http://127.0.0.1:3000/calm/vali
268268
269269
## CALM Copilot Chatmode
270270
271-
The `copilot-chatmode` command sets up AI-powered development assistance for CALM architecture modeling by configuring a specialized VSCode chatmode with comprehensive tool prompts.
271+
The `copilot-chatmode` command sets up AI-powered development assistance for CALM architecture modeling by configuring a specialized VSCode chatmode with comprehensive tool prompts. This command is `DEPRECATED`. Users are encouraged to use the `init-ai` command.
272272
273273
```shell
274-
calm copilot-chatmode --help
274+
calm copilot-chatmode --help
275275
Usage: calm copilot-chatmode [options]
276276
277-
Augment a git repository with a CALM VSCode chatmode for AI assistance
277+
DEPRECATED (use init-ai): Augment a git repository with a CALM VSCode chatmode for AI assistance
278278
279279
Options:
280280
-d, --directory <path> Target directory (defaults to current directory) (default: ".")
@@ -319,6 +319,62 @@ The chatmode includes specialized tools for each CALM component:
319319
320320
Each tool includes complete schema definitions, validation rules, realistic examples, and cross-references to related tools.
321321
322+
## CALM init-ai
323+
324+
The `init-ai` command sets up AI-powered development assistance for CALM architecture modeling by configuring a specialized VSCode chatmode with comprehensive tool prompts. At present two AI Assistant providers are supported: Github Copilot and AWS Kiro.
325+
326+
```shell
327+
calm init-ai --help
328+
Usage: calm init-ai [options]
329+
330+
Augment a git repository with AI assistance for CALM
331+
332+
Options:
333+
-p, --provider <provider> AI provider to initialize (choices: "copilot", "kiro")
334+
-d, --directory <path> Target directory (defaults to current directory) (default: ".")
335+
-v, --verbose Enable verbose logging. (default: false)
336+
-h, --help display help for command
337+
```
338+
339+
This command creates a custom chat prompt configuration for the specified <provider> that provides AI assistance with specialized knowledge about CALM architecture modeling, including:
340+
341+
- **Schema-accurate guidance**: Complete JSON schema definitions for all CALM components
342+
- **Critical validation requirements**: Emphasis on oneOf constraints and other validation rules
343+
- **Best practice enforcement**: Naming conventions, relationship patterns, and proper structure
344+
- **Comprehensive examples**: Realistic architecture examples based on actual CALM patterns
345+
- **Tool specialization**: Separate tools for nodes, relationships, interfaces, controls, flows, patterns, and metadata
346+
347+
### Setting up CALM AI assistance
348+
349+
To set up AI assistance for your CALM project:
350+
351+
```shell
352+
# In your project directory
353+
calm init-ai -p <provider>
354+
355+
# Or specify a different directory
356+
calm init-ai -p <provider> --directory /path/to/your/calm-project
357+
```
358+
359+
This will create the necessary IDE-specific configuration files to enable CALM-specific AI assistance. Once set up, you can use GitHub Copilot Chat with specialized CALM tools that understand schema requirements, validation rules, and best practices.
360+
361+
### Tool Prompts
362+
363+
The chatmode includes specialized tools for each CALM component:
364+
365+
- **Node Creation**: Guide for creating nodes with proper validation and interface definitions
366+
- **Relationship Creation**: Guide for creating relationships with correct types and constraints
367+
- **Interface Creation**: Critical guidance for interface oneOf constraints and schema compliance
368+
- **Control Creation**: Guide for security controls, requirements, and configurations
369+
- **Flow Creation**: Guide for business process flows and transitions
370+
- **Pattern Creation**: Guide for reusable architectural patterns using JSON schema constructs
371+
- **Metadata Creation**: Guide for metadata structure options (single object vs. array)
372+
- **Standards Creation**: Guide for creating JSON Schema 2020-12 Standards that extend CALM components with organizational requirements
373+
374+
Each tool includes complete schema definitions, validation rules, realistic examples, and cross-references to related tools.
375+
376+
377+
322378
## CALM Template
323379
324380
The CALM Template system allows users to generate different machine or human-readable outputs from a CALM model by providing a **template bundle**.

‎cli/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
"copy-calm-schema": "copyfiles \"../calm/release/**/meta/*\" \"../calm/draft/**/meta/*\" dist/calm/",
2121
"copy-docify-templates": "copyfiles \"../shared/dist/template-bundles/**/*\" dist --up 3",
2222
"copy-widgets": "copyfiles \"../calm-widgets/dist/cli/widgets/**/*\" dist --up 4",
23-
"copy-ai-tools": "copyfiles \"../calm-ai/tools/**/*\" \"../calm-ai/CALM.chatmode.md\" dist/calm-ai/ --up 2",
23+
"copy-ai-tools": "copyfiles \"../calm-ai/tools/**/*\" \"../calm-ai/templates/**/*\" dist/calm-ai/ --up 2",
2424
"test": "vitest run",
2525
"lint": "eslint src",
2626
"lint-fix": "eslint src --fix",
@@ -71,4 +71,4 @@
7171
"typescript": "^5.8.3",
7272
"xml2js": "^0.6.2"
7373
}
74-
}
74+
}

‎cli/src/cli.ts‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { CalmChoice } from '@finos/calm-shared/dist/commands/generate/components
66
import { buildDocumentLoader, DocumentLoader, DocumentLoaderOptions } from '@finos/calm-shared/dist/document-loader/document-loader';
77
import { loadCliConfig } from './cli-config';
88
import path from 'path';
9+
import inquirer from 'inquirer';
910

1011
// Shared options used across multiple commands
1112
const ARCHITECTURE_OPTION = '-a, --architecture <file>';
@@ -214,7 +215,7 @@ export function setupCLI(program: Command) {
214215

215216
program
216217
.command('copilot-chatmode')
217-
.description('Augment a git repository with a CALM VSCode chatmode for AI assistance')
218+
.description('DEPRECATED (use init-ai): Augment a git repository with a CALM VSCode chatmode for AI assistance')
218219
.option('-d, --directory <path>', 'Target directory (defaults to current directory)', '.')
219220
.option(VERBOSE_OPTION, 'Enable verbose logging.', false)
220221
.action(async (options) => {
@@ -224,7 +225,34 @@ export function setupCLI(program: Command) {
224225
process.env.DEBUG = 'true';
225226
}
226227

227-
await setupAiTools(options.directory, !!options.verbose);
228+
await setupAiTools('copilot', options.directory, !!options.verbose);
229+
});
230+
231+
const providerOption = new Option('-p, --provider <provider>', 'AI provider to initialize')
232+
.choices(['copilot', 'kiro']);
233+
234+
program
235+
.command('init-ai')
236+
.description('Augment a git repository with AI assistance for CALM')
237+
.addOption(providerOption)
238+
.option('-d, --directory <path>', 'Target directory (defaults to current directory)', '.')
239+
.option(VERBOSE_OPTION, 'Enable verbose logging.', false)
240+
.action(async (options) => {
241+
const { setupAiTools } = await import('./command-helpers/ai-tools');
242+
const providers = (providerOption as Option & { argChoices?: string[] }).argChoices ?? [];
243+
let selectedProvider: string = options.provider;
244+
if (!selectedProvider) {
245+
const answer = await inquirer.prompt({
246+
type: 'list',
247+
name: 'provider',
248+
message: 'Select an AI provider:',
249+
choices: providers.map((p) => ({ name: p, value: p })),
250+
});
251+
selectedProvider = answer.provider;
252+
}
253+
console.log(`Selected AI provider: ${selectedProvider}`);
254+
255+
await setupAiTools(selectedProvider, options.directory, !!options.verbose);
228256
});
229257

230258
}

0 commit comments

Comments
 (0)
⚡