0
# Copilot Chatmode Command
1

2
> **NOTE**: This is a CLI-only command. @finos/calm-cli does not export functions for programmatic use.
3

4
The `copilot-chatmode` command sets up AI-powered development assistance for CALM architecture modeling by configuring a specialized VSCode chatmode with comprehensive tool prompts, schema definitions, and validation guidance for GitHub Copilot integration.
5

6
## Capabilities
7

8
### Copilot Chatmode Command
9

10
Augment a git repository with CALM VSCode chatmode for AI assistance.
11

12
```typescript { .api }
13
/**
14
 * Augment a git repository with a CALM VSCode chatmode for AI assistance
15
 * @command calm copilot-chatmode [options]
16
 */
17
interface CopilotChatmodeCommandOptions {
18
  /** Target directory
19
   * CLI flags: -d, --directory <path>
20
   * Default: "."
21
   */
22
  directory?: string;
23

24
  /** Enable verbose logging
25
   * CLI flags: -v, --verbose
26
   * Default: false
27
   */
28
  verbose?: boolean;
29
}
30
```
31

32
**Usage Examples:**
33

34
```bash
35
# Setup in current directory
36
calm copilot-chatmode
37

38
# Setup in specific directory
39
calm copilot-chatmode -d /path/to/calm-project
40

41
# Setup with verbose logging
42
calm copilot-chatmode -d . -v
43
```
44

45
## Setup Process
46

47
The command performs the following steps:
48

49
1. **Directory Validation**
50
   - Verifies target directory exists
51
   - Checks for git repository (warns if not found)
52

53
2. **Resource Validation**
54
   - Validates bundled AI tool resources are present
55
   - Checks file integrity and content
56

57
3. **Directory Creation**
58
   - Creates `.github/chatmodes/` directory structure
59
   - Follows GitHub Copilot conventions
60

61
4. **Chatmode Configuration**
62
   - Copies CALM chatmode configuration
63
   - Validates configuration content quality
64

65
5. **Tool Prompt Creation**
66
   - Creates specialized tool prompt files for each CALM component
67
   - Validates tool file content
68

69
## Created Files
70

71
### Chatmode Configuration
72

73
**File:** `.github/chatmodes/CALM.chatmode.md`
74

75
Main chatmode configuration providing GitHub Copilot with specialized CALM knowledge including:
76
- Complete JSON schema definitions for all CALM components
77
- Critical validation requirements (oneOf constraints, etc.)
78
- Best practice enforcement (naming conventions, relationship patterns)
79
- Comprehensive examples based on actual CALM patterns
80

81
### Tool Prompt Files
82

83
**Directory:** `.github/chatmodes/calm-prompts/`
84

85
Specialized tool prompts for each CALM component:
86

87
1. **architecture-creation.md** - Guide for creating complete CALM architectures
88
2. **node-creation.md** - Guide for creating nodes with validation and interfaces
89
3. **relationship-creation.md** - Guide for creating relationships with correct types
90
4. **interface-creation.md** - Critical guidance for interface oneOf constraints
91
5. **metadata-creation.md** - Guide for metadata structure options
92
6. **control-creation.md** - Guide for security controls and requirements
93
7. **flow-creation.md** - Guide for business process flows and transitions
94
8. **pattern-creation.md** - Guide for reusable patterns using JSON schema
95
9. **documentation-creation.md** - Guide for CALM documentation generation
96

97
Each tool includes:
98
- Complete schema definitions
99
- Validation rules and constraints
100
- Realistic examples
101
- Cross-references to related tools
102

103
## File Structure
104

105
After running the command:
106

107
```
108
.github/
109
└── chatmodes/
110
    ├── CALM.chatmode.md               # Main chatmode configuration
111
    └── calm-prompts/
112
        ├── architecture-creation.md
113
        ├── node-creation.md
114
        ├── relationship-creation.md
115
        ├── interface-creation.md
116
        ├── metadata-creation.md
117
        ├── control-creation.md
118
        ├── flow-creation.md
119
        ├── pattern-creation.md
120
        └── documentation-creation.md
121
```
122

123
## Using the Chatmode
124

125
### Activation
126

127
Once set up:
128

129
1. **Open Repository in VSCode** with GitHub Copilot installed
130
2. **Start GitHub Copilot Chat**
131
3. **Select CALM Chatmode** from available chatmodes
132
4. **Use CALM-Specific Tools** for architecture modeling assistance
133

134
### Example Interactions
135

136
**Creating a Node:**
137
```
138
User: Create a database node with PostgreSQL interface
139
AI: [Uses node-creation.md tool prompt to generate correct CALM node structure]
140
```
141

142
**Validating Schema:**
143
```
144
User: Validate this architecture against CALM schema
145
AI: [Uses architecture validation guidance to check structure]
146
```
147

148
**Creating Relationships:**
149
```
150
User: Add a relationship from api-service to database
151
AI: [Uses relationship-creation.md tool prompt for correct relationship structure]
152
```
153

154
## Resource Validation
155

156
The command validates bundled resources before setup:
157

158
### Bundled Resources
159

160
The chatmode configuration and tool prompt files are **pre-packaged with the @finos/calm-cli npm package** during installation. These resources originate from the `calm-ai` directory in the source repository and are copied into the package's `dist/calm-ai/` directory during the build process.
161

162
When you run `calm copilot-chatmode`, the command copies these bundled resources from your installed npm package to your project's `.github/chatmodes/` directory. This ensures you always have the latest chatmode configuration that matches your installed version of the CLI.
163

164
**Note:** If you need to update the chatmode files after a CLI upgrade, simply run `calm copilot-chatmode` again to replace them with the updated versions.
165

166
### Required Files
167

168
- CALM.chatmode.md (main configuration)
169
- tools/architecture-creation.md
170
- tools/node-creation.md
171
- tools/relationship-creation.md
172
- tools/interface-creation.md
173
- tools/metadata-creation.md
174
- tools/control-creation.md
175
- tools/flow-creation.md
176
- tools/pattern-creation.md
177
- tools/documentation-creation.md
178

179
### Validation Checks
180

181
- **File Existence:** All required files must be present in bundled package
182
- **Content Quality:**
183
  - CALM.chatmode.md must have at least 500 characters
184
  - Tool files must have at least 100 characters each
185
- **Markdown Format:** Files must contain markdown headers
186
- **CALM References:** Configuration must reference CALM
187

188
## Error Handling
189

190
### Setup Errors
191

192
**Target Directory Does Not Exist:**
193
```
194
❌ Failed to setup AI tools: Target path is not a directory
195
```
196
**Solution:** Verify directory path is correct and exists.
197

198
**Not a Git Repository:**
199
```
200
⚠️  Warning: No .git directory found. This may not be a git repository.
201
```
202
**Note:** This is a warning; setup continues but GitHub integration may not work.
203

204
**Missing Bundled Resources:**
205
```
206
❌ Missing bundled file: tools/node-creation.md
207
```
208
**Solution:** Reinstall @finos/calm-cli package.
209

210
**Corrupted Bundled Files:**
211
```
212
⚠️  Bundled file appears empty: CALM.chatmode.md
213
```
214
**Solution:** Reinstall @finos/calm-cli package.
215

216
**Directory Creation Failed:**
217
```
218
❌ Failed to setup AI tools: EACCES: permission denied
219
```
220
**Solution:** Verify write permissions for target directory.
221

222
### Partial Setup Failures
223

224
If some tool prompts fail but more than half succeed, setup continues with a warning:
225

226
```
227
⚠️  Tool prompts summary: 7 succeeded, 2 failed
228
   Failed files: flow-creation.md, pattern-creation.md
229
⚠️  Some tool prompts failed - AI functionality may be limited
230
```
231

232
If more than half fail, setup aborts:
233

234
```
235
❌ More than half of tool prompts failed - AI functionality will be severely limited
236
Tool prompt setup failed: 6/9 files failed
237
```
238

239
## Requirements
240

241
### GitHub Copilot
242

243
The chatmode requires:
244
- VSCode with GitHub Copilot extension
245
- Active GitHub Copilot subscription
246
- Repository opened in VSCode
247

248
### Git Repository
249

250
While the command warns if `.git` is not found, it's not strictly required. However, for full GitHub integration:
251
- Initialize git repository: `git init`
252
- Commit chatmode files: `git add .github && git commit -m "Add CALM chatmode"`
253

254
## Configuration
255

256
### Chatmode File Location
257

258
The command follows GitHub Copilot conventions:
259
- Standard location: `.github/chatmodes/`
260
- Chatmode file: `CALM.chatmode.md`
261
- Tool prompts: `calm-prompts/*.md`
262

263
### Custom Tool Prompts
264

265
After setup, you can customize tool prompts:
266

267
1. Edit files in `.github/chatmodes/calm-prompts/`
268
2. Add project-specific examples
269
3. Include custom validation rules
270
4. Add team coding standards
271

272
**Example Customization:**
273

274
```markdown
275
<!-- node-creation.md -->
276

277
# Custom Project Requirements
278

279
For our project, all nodes must include:
280
- owner field in metadata
281
- cost-center field in metadata
282
- environment tag (dev/staging/prod)
283

284
[...original content...]
285
```
286

287
## Integration with VSCode
288

289
### Chatmode Discovery
290

291
VSCode with GitHub Copilot automatically discovers chatmodes in:
292
- `.github/chatmodes/` directory
293
- Files matching `*.chatmode.md` pattern
294

295
### Tool Prompt Access
296

297
Tool prompts are referenced by the main chatmode configuration and accessed by Copilot when relevant to user requests.
298

299
### Context Awareness
300

301
The chatmode provides Copilot with:
302
- CALM schema knowledge
303
- Validation requirements
304
- Best practices
305
- Common patterns
306
- Error prevention guidance
307

308
## Use Cases
309

310
### Architecture Modeling
311

312
Create CALM architectures with AI assistance:
313

314
```bash
315
# Setup chatmode
316
calm copilot-chatmode
317

318
# Open VSCode and use Copilot Chat
319
# "Create a microservices architecture with API gateway"
320
# Copilot uses CALM chatmode to generate correct structure
321
```
322

323
### Validation Assistance
324

325
Get validation help from AI:
326

327
```bash
328
# VSCode Copilot Chat
329
# "Why is my CALM architecture failing validation?"
330
# Copilot uses schema knowledge to diagnose issues
331
```
332

333
### Pattern Application
334

335
Apply CALM patterns with guidance:
336

337
```bash
338
# VSCode Copilot Chat
339
# "Apply API gateway pattern to my architecture"
340
# Copilot uses pattern-creation.md for correct pattern structure
341
```
342

343
### Learning CALM
344

345
Learn CALM schema through interactive AI assistance:
346

347
```bash
348
# VSCode Copilot Chat
349
# "Explain CALM interface structure and oneOf constraints"
350
# Copilot uses interface-creation.md for detailed explanation
351
```
352

353
## Best Practices
354

355
1. **Run Early:** Set up chatmode at project start for consistent guidance
356
2. **Commit Configuration:** Track chatmode files in version control
357
3. **Update Regularly:** Rerun command after @finos/calm-cli updates
358
4. **Customize for Team:** Add team-specific guidance to tool prompts
359
5. **Share Knowledge:** Commit customized prompts for team consistency
360
6. **Verify Setup:** Check created files after setup
361
7. **Test Integration:** Verify Copilot recognizes chatmode in VSCode
362

363
## Team Collaboration
364

365
### Shared Chatmode
366

367
Commit chatmode configuration for team use:
368

369
```bash
370
# Setup chatmode
371
calm copilot-chatmode
372

373
# Commit for team
374
git add .github/chatmodes
375
git commit -m "Add CALM AI assistance chatmode"
376
git push
377

378
# Team members pull and use immediately
379
git pull
380
# Open VSCode - chatmode available
381
```
382

383
### Customization Management
384

385
Track team-specific customizations:
386

387
```bash
388
# Customize tool prompts
389
vi .github/chatmodes/calm-prompts/node-creation.md
390

391
# Commit customizations
392
git add .github/chatmodes/calm-prompts/
393
git commit -m "Add team-specific CALM node requirements"
394
git push
395
```
396

397
## Troubleshooting
398

399
### Chatmode Not Visible in VSCode
400

401
**Possible Causes:**
402
1. GitHub Copilot extension not installed
403
2. VSCode not restarted after setup
404
3. Repository not opened as workspace
405
4. Files in wrong location
406

407
**Solutions:**
408
- Install GitHub Copilot extension
409
- Restart VSCode
410
- Open repository root as workspace folder
411
- Verify `.github/chatmodes/CALM.chatmode.md` exists
412

413
### Copilot Not Using CALM Context
414

415
**Possible Causes:**
416
1. Chatmode not selected
417
2. Tool prompts missing or corrupted
418
3. Copilot using different chatmode
419

420
**Solutions:**
421
- Explicitly select CALM chatmode in Copilot Chat
422
- Verify all tool prompt files exist
423
- Rerun `calm copilot-chatmode` to repair
424

425
### Permission Errors
426

427
```
428
❌ Failed to setup AI tools: EACCES: permission denied
429
```
430

431
**Solutions:**
432
- Check directory write permissions
433
- Run with appropriate user permissions
434
- Verify target directory is not read-only
435

436
## Advanced Usage
437

438
### Multiple Projects
439

440
Set up chatmode for multiple CALM projects:
441

442
```bash
443
# Project 1
444
calm copilot-chatmode -d ~/projects/calm-project-1
445

446
# Project 2
447
calm copilot-chatmode -d ~/projects/calm-project-2
448

449
# Each project gets independent chatmode configuration
450
```
451

452
### Automated Setup
453

454
Include in project initialization scripts:
455

456
```bash
457
#!/bin/bash
458
# init-calm-project.sh
459

460
# Initialize git repository
461
git init
462

463
# Create initial architecture
464
calm generate -p pattern.json -o architecture.json
465

466
# Setup AI assistance
467
calm copilot-chatmode
468

469
# Commit initial setup
470
git add .
471
git commit -m "Initial CALM project setup with AI assistance"
472
```
473

474
### CI/CD Integration
475

476
Verify chatmode configuration in CI:
477

478
```yaml
479
# .github/workflows/validate-chatmode.yml
480
name: Validate CALM Chatmode
481
on: [push, pull_request]
482

483
jobs:
484
  validate:
485
    runs-on: ubuntu-latest
486
    steps:
487
      - uses: actions/checkout@v3
488
      - name: Verify chatmode files exist
489
        run: |
490
          test -f .github/chatmodes/CALM.chatmode.md
491
          test -d .github/chatmodes/calm-prompts
492
          ls .github/chatmodes/calm-prompts/*.md
493
```
494

495
## Future Enhancements
496

497
The chatmode setup may be enhanced in future versions:
498

499
- Custom tool prompt templates
500
- Project-specific schema extensions
501
- Team coding standard integration
502
- Multi-language support
503
- Interactive setup wizard
504

505
## Support
506

507
### Getting Help
508

509
If setup fails:
510

511
1. **Check Logs:** Run with `-v` for verbose output
512
2. **Verify Installation:** Ensure @finos/calm-cli is correctly installed
513
3. **Check Permissions:** Verify directory write permissions
514
4. **Report Issues:** File issues at https://github.com/finos/architecture-as-code/issues
515

516
### Chatmode Issues
517

518
For issues with chatmode functionality:
519

520
1. **Verify Files:** Check all files were created correctly
521
2. **Check VSCode:** Ensure GitHub Copilot extension is active
522
3. **Restart VSCode:** Sometimes required for chatmode discovery
523
4. **Review Documentation:** Check GitHub Copilot chatmode documentation
524