Copilot Chatmode Command

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

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.

Capabilities

Copilot Chatmode Command

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

/**
 * Augment a git repository with a CALM VSCode chatmode for AI assistance
 * @command calm copilot-chatmode [options]
 */
interface CopilotChatmodeCommandOptions {
  /** Target directory
   * CLI flags: -d, --directory <path>
   * Default: "."
   */
  directory?: string;

  /** Enable verbose logging
   * CLI flags: -v, --verbose
   * Default: false
   */
  verbose?: boolean;
}

Usage Examples:

# Setup in current directory
calm copilot-chatmode

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

# Setup with verbose logging
calm copilot-chatmode -d . -v

Setup Process

The command performs the following steps:

1. Directory Validation

   • Verifies target directory exists
   • Checks for git repository (warns if not found)

2. Resource Validation

   • Validates bundled AI tool resources are present
   • Checks file integrity and content

3. Directory Creation

   • Creates .github/chatmodes/ directory structure
   • Follows GitHub Copilot conventions

4. Chatmode Configuration

   • Copies CALM chatmode configuration
   • Validates configuration content quality

5. Tool Prompt Creation

   • Creates specialized tool prompt files for each CALM component
   • Validates tool file content

Created Files

Chatmode Configuration

File: .github/chatmodes/CALM.chatmode.md

Main chatmode configuration providing GitHub Copilot with specialized CALM knowledge including:

• Complete JSON schema definitions for all CALM components
• Critical validation requirements (oneOf constraints, etc.)
• Best practice enforcement (naming conventions, relationship patterns)
• Comprehensive examples based on actual CALM patterns

Tool Prompt Files

Directory: .github/chatmodes/calm-prompts/

Specialized tool prompts for each CALM component:

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

Each tool includes:

• Complete schema definitions
• Validation rules and constraints
• Realistic examples
• Cross-references to related tools

File Structure

After running the command:

.github/
└── chatmodes/
    ├── CALM.chatmode.md               # Main chatmode configuration
    └── calm-prompts/
        ├── architecture-creation.md
        ├── node-creation.md
        ├── relationship-creation.md
        ├── interface-creation.md
        ├── metadata-creation.md
        ├── control-creation.md
        ├── flow-creation.md
        ├── pattern-creation.md
        └── documentation-creation.md

Using the Chatmode

Activation

Once set up:

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

Example Interactions

Creating a Node:

User: Create a database node with PostgreSQL interface
AI: [Uses node-creation.md tool prompt to generate correct CALM node structure]

Validating Schema:

User: Validate this architecture against CALM schema
AI: [Uses architecture validation guidance to check structure]

Creating Relationships:

User: Add a relationship from api-service to database
AI: [Uses relationship-creation.md tool prompt for correct relationship structure]

Resource Validation

The command validates bundled resources before setup:

Bundled Resources

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.

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.

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.

Required Files

• CALM.chatmode.md (main configuration)
• tools/architecture-creation.md
• tools/node-creation.md
• tools/relationship-creation.md
• tools/interface-creation.md
• tools/metadata-creation.md
• tools/control-creation.md
• tools/flow-creation.md
• tools/pattern-creation.md
• tools/documentation-creation.md

Validation Checks

• File Existence: All required files must be present in bundled package
• Content Quality:
  • CALM.chatmode.md must have at least 500 characters
  • Tool files must have at least 100 characters each
• Markdown Format: Files must contain markdown headers
• CALM References: Configuration must reference CALM

Error Handling

Setup Errors

Target Directory Does Not Exist:

❌ Failed to setup AI tools: Target path is not a directory

Solution: Verify directory path is correct and exists.

Not a Git Repository:

⚠️  Warning: No .git directory found. This may not be a git repository.

Note: This is a warning; setup continues but GitHub integration may not work.

Missing Bundled Resources:

❌ Missing bundled file: tools/node-creation.md

Solution: Reinstall @finos/calm-cli package.

Corrupted Bundled Files:

⚠️  Bundled file appears empty: CALM.chatmode.md

Solution: Reinstall @finos/calm-cli package.

Directory Creation Failed:

❌ Failed to setup AI tools: EACCES: permission denied

Solution: Verify write permissions for target directory.

Partial Setup Failures

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

⚠️  Tool prompts summary: 7 succeeded, 2 failed
   Failed files: flow-creation.md, pattern-creation.md
⚠️  Some tool prompts failed - AI functionality may be limited

If more than half fail, setup aborts:

❌ More than half of tool prompts failed - AI functionality will be severely limited
Tool prompt setup failed: 6/9 files failed

Requirements

GitHub Copilot

The chatmode requires:

• VSCode with GitHub Copilot extension
• Active GitHub Copilot subscription
• Repository opened in VSCode

Git Repository

While the command warns if .git is not found, it's not strictly required. However, for full GitHub integration:

• Initialize git repository: git init
• Commit chatmode files: git add .github && git commit -m "Add CALM chatmode"

Configuration

Chatmode File Location

The command follows GitHub Copilot conventions:

• Standard location: .github/chatmodes/
• Chatmode file: CALM.chatmode.md
• Tool prompts: calm-prompts/*.md

Custom Tool Prompts

After setup, you can customize tool prompts:

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

Example Customization:

<!-- node-creation.md -->

# Custom Project Requirements

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

[...original content...]

Integration with VSCode

Chatmode Discovery

VSCode with GitHub Copilot automatically discovers chatmodes in:

• .github/chatmodes/ directory
• Files matching *.chatmode.md pattern

Tool Prompt Access

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

Context Awareness

The chatmode provides Copilot with:

• CALM schema knowledge
• Validation requirements
• Best practices
• Common patterns
• Error prevention guidance

Use Cases

Architecture Modeling

Create CALM architectures with AI assistance:

# Setup chatmode
calm copilot-chatmode

# Open VSCode and use Copilot Chat
# "Create a microservices architecture with API gateway"
# Copilot uses CALM chatmode to generate correct structure

Validation Assistance

Get validation help from AI:

# VSCode Copilot Chat
# "Why is my CALM architecture failing validation?"
# Copilot uses schema knowledge to diagnose issues

Pattern Application

Apply CALM patterns with guidance:

# VSCode Copilot Chat
# "Apply API gateway pattern to my architecture"
# Copilot uses pattern-creation.md for correct pattern structure

Learning CALM

Learn CALM schema through interactive AI assistance:

# VSCode Copilot Chat
# "Explain CALM interface structure and oneOf constraints"
# Copilot uses interface-creation.md for detailed explanation

Best Practices

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

Team Collaboration

Shared Chatmode

Commit chatmode configuration for team use:

# Setup chatmode
calm copilot-chatmode

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

# Team members pull and use immediately
git pull
# Open VSCode - chatmode available

Customization Management

Track team-specific customizations:

# Customize tool prompts
vi .github/chatmodes/calm-prompts/node-creation.md

# Commit customizations
git add .github/chatmodes/calm-prompts/
git commit -m "Add team-specific CALM node requirements"
git push

Troubleshooting

Chatmode Not Visible in VSCode

Possible Causes:

1. GitHub Copilot extension not installed
2. VSCode not restarted after setup
3. Repository not opened as workspace
4. Files in wrong location

Solutions:

• Install GitHub Copilot extension
• Restart VSCode
• Open repository root as workspace folder
• Verify .github/chatmodes/CALM.chatmode.md exists

Copilot Not Using CALM Context

Possible Causes:

1. Chatmode not selected
2. Tool prompts missing or corrupted
3. Copilot using different chatmode

Solutions:

• Explicitly select CALM chatmode in Copilot Chat
• Verify all tool prompt files exist
• Rerun calm copilot-chatmode to repair

Permission Errors

❌ Failed to setup AI tools: EACCES: permission denied

Solutions:

• Check directory write permissions
• Run with appropriate user permissions
• Verify target directory is not read-only

Advanced Usage

Multiple Projects

Set up chatmode for multiple CALM projects:

# Project 1
calm copilot-chatmode -d ~/projects/calm-project-1

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

# Each project gets independent chatmode configuration

Automated Setup

Include in project initialization scripts:

#!/bin/bash
# init-calm-project.sh

# Initialize git repository
git init

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

# Setup AI assistance
calm copilot-chatmode

# Commit initial setup
git add .
git commit -m "Initial CALM project setup with AI assistance"

CI/CD Integration

Verify chatmode configuration in CI:

# .github/workflows/validate-chatmode.yml
name: Validate CALM Chatmode
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Verify chatmode files exist
        run: |
          test -f .github/chatmodes/CALM.chatmode.md
          test -d .github/chatmodes/calm-prompts
          ls .github/chatmodes/calm-prompts/*.md

Future Enhancements

The chatmode setup may be enhanced in future versions:

• Custom tool prompt templates
• Project-specific schema extensions
• Team coding standard integration
• Multi-language support
• Interactive setup wizard

Support

Getting Help

If setup fails:

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

Chatmode Issues

For issues with chatmode functionality:

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