Skip to content

Commit 85ef798

Browse files
rocketstack-mattrocketstack-matt
authored
Merge pull request finos#1809 from gkaria:docupdates
docs: add CALM Copilot Chatmode and Voice Mode documentation
2 parents 708975c + 8cf365b commit 85ef798

File tree

4 files changed

+228
-7
lines changed

4 files changed

+228
-7
lines changed

‎docs/docs/working-with-calm/copilot-chatmode.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
id: copilot-chatmode
3+
title: CALM Copilot Chatmode
4+
sidebar_position: 6
5+
---
6+
7+
# CALM Copilot Chatmode
8+
9+
CALM Copilot Chatmode provides AI-powered development assistance for CALM architecture modeling by integrating specialized knowledge and tools directly into VS Code through GitHub Copilot Chat.
10+
11+
## Overview
12+
13+
The `copilot-chatmode` command configures your development environment with comprehensive tool prompts that help GitHub Copilot understand CALM schema requirements, validation rules, and best practices. This enables you to get intelligent assistance when creating and modifying CALM architectures.
14+
15+
## Prerequisites
16+
17+
Before setting up CALM Copilot Chatmode, ensure you have:
18+
19+
- **VS Code**: Version 1.94 or later
20+
- **GitHub Copilot**: Active GitHub Copilot subscription
21+
- **GitHub Copilot Chat Extension**: Installed in VS Code
22+
- **CALM CLI**: Installed globally (`npm install -g @finos/calm-cli`)
23+
- **Git Repository**: Your project should be in a Git repository
24+
25+
## Setting Up CALM Copilot Chatmode
26+
27+
To set up AI assistance for your CALM project, run the following command in your project directory:
28+
29+
```shell
30+
calm copilot-chatmode
31+
```
32+
33+
Or specify a different directory:
34+
35+
```shell
36+
calm copilot-chatmode --directory /path/to/your/calm-project
37+
```
38+
39+
This command creates a `.github/chatmodes/CALM.chatmode.md` configuration file in your repository that provides GitHub Copilot with specialized CALM knowledge.
40+
41+
## Command Options
42+
43+
- **`-d, --directory <path>`**: Target directory (defaults to current directory)
44+
- **`-v, --verbose`**: Enable verbose logging (default: false)
45+
- **`-h, --help`**: Display help for command
46+
47+
## What Gets Configured
48+
49+
The chatmode setup provides GitHub Copilot with:
50+
51+
- **Schema-Accurate Guidance**: Complete JSON schema definitions for all CALM components ensure that suggestions follow the official CALM specification.
52+
- **Critical Validation Requirements**: Emphasis on important constraints like `oneOf` requirements for interfaces and proper relationship structures.
53+
- **Best Practice Enforcement**: Guidance on naming conventions, relationship patterns, and proper architecture structure.
54+
55+
### Specialized Tools
56+
57+
The chatmode includes separate tools for each CALM component:
58+
59+
- **Architecture Creation**: Guide for creating complete CALM architecture documents
60+
- **Node Creation**: Creating nodes with proper validation and interface definitions
61+
- **Relationship Creation**: Creating relationships with correct types and constraints
62+
- **Interface Creation**: Critical guidance for interface `oneOf` constraints
63+
- **Control Creation**: Security controls, requirements, and configurations
64+
- **Flow Creation**: Business process flows and transitions
65+
- **Pattern Creation**: Reusable architectural patterns using JSON schema
66+
- **Metadata Creation**: Metadata structure and requirements
67+
- **Documentation Creation**: Generating documentation from CALM models
68+
69+
## Using CALM Copilot Chat
70+
71+
Once configured, you can interact with GitHub Copilot Chat in VS Code:
72+
73+
1. Open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I)
74+
2. Select the **CALM** chatmode from the mode selector
75+
3. Ask questions or request assistance with your CALM architecture
76+
77+
### Example Queries
78+
79+
Here are some examples of how to use CALM Copilot Chat:
80+
81+
**Creating Components:**
82+
```
83+
Create a new node for an API gateway service with REST interfaces
84+
```
85+
86+
**Validation Help:**
87+
```
88+
Why is my interface definition failing validation?
89+
```
90+
91+
**Best Practices:**
92+
```
93+
What's the recommended way to model a database relationship?
94+
```
95+
96+
**Documentation:**
97+
```
98+
Generate documentation for my CALM architecture
99+
```
100+
101+
## Updating Chatmode Configuration
102+
103+
If you update the CALM CLI or want to refresh the chatmode configuration:
104+
105+
```shell
106+
calm copilot-chatmode --directory /path/to/your/calm-project
107+
```
108+
109+
This will update the chatmode files with the latest tool prompts and guidance.
110+
111+
## Next Steps
112+
113+
- Learn about [Voice Mode](voice-mode) for hands-free architecture modeling

‎docs/docs/working-with-calm/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,5 +14,7 @@ Explore the topics below to get hands-on experience with CALM:
1414
- [Using the CLI](using-the-cli): Understand the basic usage of the CALM CLI and how to access its commands.
1515
- [Generate](generate): Discover how to generate architectural architectures from predefined patterns.
1616
- [Validate](validate): Learn how to validate your architecture against CALM patterns to ensure compliance.
17+
- [CALM Copilot Chatmode](copilot-chatmode): Set up AI-powered development assistance for CALM architecture modeling.
18+
- [Voice Mode](voice-mode): Enable hands-free interaction with CALM Copilot Chat using voice commands.
1719

1820
Let's get started and make the most of CALM’s capabilities!

‎docs/docs/working-with-calm/using-the-cli.md‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,15 @@ Options:
2828
-h, --help display help for command
2929

3030
Commands:
31-
generate [options] Generate an architecture from a CALM pattern file.
32-
validate [options] Validate that an architecture conforms to a given CALM pattern.
33-
server [options] Start a HTTP server to proxy CLI commands. (experimental)
34-
template [options] Generate files from a CALM model using a Handlebars template bundle
35-
docify [options] Generate a documentation website off your CALM model
36-
help [command] display help for command
37-
```
31+
generate [options] Generate an architecture from a CALM pattern file.
32+
validate [options] Validate that an architecture conforms to a given CALM pattern.
33+
copilot-chatmode [options] Augment a git repository with a CALM VSCode chatmode for AI assistance.
34+
server [options] Start a HTTP server to proxy CLI commands. (experimental)
35+
template [options] Generate files from a CALM model using a Handlebars template bundle
36+
docify [options] Generate a documentation website off your CALM model
37+
help [command] display help for command
38+
```
39+
40+
## AI-Powered Development
41+
42+
CALM CLI includes AI-powered development assistance through the `copilot-chatmode` command. This feature integrates with VS Code and GitHub Copilot to provide intelligent help with architecture modeling. Learn more in the [CALM Copilot Chatmode](copilot-chatmode) section.

‎docs/docs/working-with-calm/voice-mode.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
id: voice-mode
3+
title: Voice Mode
4+
sidebar_position: 7
5+
---
6+
7+
# Voice Mode with CALM Copilot Chat
8+
9+
Voice Mode enables hands-free interaction with CALM Copilot Chat, allowing you to speak architecture queries and receive spoken responses directly in the chat interface.
10+
11+
## Getting Started
12+
13+
### Prerequisites
14+
15+
- **VS Code**: Version 1.94 or later
16+
- **CALM Copilot Chatmode**: Configured in your repository (see [CALM Copilot Chatmode](copilot-chatmode))
17+
- **GitHub Copilot Chat**: Active subscription and extension installed
18+
- **Microphone**: A working microphone
19+
20+
### Setup
21+
22+
1. **Install the VS Code Speech Extension**
23+
- Open VS Code Extensions (Ctrl+Shift+X or Cmd+Shift+X)
24+
- Search for "VS Code Speech"
25+
- Click **Install** on the Microsoft-published extension
26+
27+
2. **Grant Microphone Permissions**
28+
- First use will prompt for microphone access - click **Allow**
29+
- If prompted on macOS, grant permissions to both "Visual Studio Code" and "Code Helper", then restart VS Code
30+
- On Windows, ensure VS Code is enabled in Settings → Privacy → Microphone
31+
32+
3. **Configure VS Code Settings**
33+
- Open VS Code Settings (Ctrl+, or Cmd+,)
34+
- Search for `accessibility.voice` and add these settings:
35+
36+
```json
37+
{
38+
"accessibility.voice.autoSynthesize": "on",
39+
"accessibility.voice.ignoreCodeBlocks": true,
40+
"accessibility.voice.speechTimeout": 1200,
41+
"accessibility.voice.keywordActivation": "chatInView"
42+
}
43+
```
44+
45+
## Using Voice Mode
46+
47+
### Starting a Voice Query
48+
49+
1. Open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I)
50+
2. Select the **CALM** chatmode
51+
3. Click the microphone icon in the chat input field or press Ctrl+I (Windows/Linux) / Cmd+I (macOS)
52+
4. Speak your query clearly
53+
5. The response will appear as you finish speaking (auto-submit after ~1.2 seconds of silence)
54+
6. Your response will be read aloud automatically
55+
56+
### Quick Voice Activation
57+
58+
Say **"Hey Code"** to activate voice input without clicking anything (requires `keywordActivation` setting enabled above).
59+
60+
### Example Queries
61+
62+
Speak naturally and clearly. Here are examples of how you can use CALM Chatmode via voice:
63+
64+
**Building Your Architecture:**
65+
66+
- "Create a microservices architecture with a web frontend, API gateway, and PostgreSQL database"
67+
- "Add a node for the authentication service with HTTPS interfaces"
68+
- "Create a connects-to relationship from the API gateway to the backend services"
69+
- "Define that the services are deployed in Kubernetes"
70+
71+
**Defining Controls and Compliance:**
72+
73+
- "Add PCI-DSS compliance controls to the payment processor service"
74+
- "Define encryption-in-transit controls for all API connections"
75+
- "What security controls should apply to our database?"
76+
77+
**Modeling Business Processes:**
78+
79+
- "Create a flow for the customer onboarding process"
80+
- "Model the trade execution flow from order placement to settlement"
81+
- "Show the data journey through our system"
82+
83+
**Validation and Best Practices:**
84+
85+
- "Is my architecture valid?"
86+
- "What patterns apply to this microservices design?"
87+
- "What interfaces should the authentication service expose?"
88+
- "Why is my relationship definition failing validation?"
89+
90+
**Documentation and Visualization:**
91+
92+
- "Generate documentation for my architecture"
93+
- "Create a visual diagram of the system"
94+
- "Document all the interfaces and their protocols"
95+
96+
### Listening to Responses
97+
98+
Responses will be read aloud automatically (if `autoSynthesize` is enabled). You can also:
99+
100+
- **Stop playback**: Press **ESC** or click the speaker icon
101+
- **Manual read-aloud**: Click the speaker icon next to any response to hear it read aloud again

0 commit comments

Comments
 (0)