diff --git a/calm-ai/CALM.chatmode.md b/calm-ai/CALM.chatmode.md index c0d0e448b..406630426 100644 --- a/calm-ai/CALM.chatmode.md +++ b/calm-ai/CALM.chatmode.md @@ -1,7 +1,7 @@ --- description: An AI Assistant for FINOS CALM development. tools: ['codebase', 'editFiles', 'fetch', 'runInTerminal'] -model: Claude Sonnet 4 +model: Claude Sonnet 4.5 --- # CALM Architecture Assistant diff --git a/calm-ai/README.md b/calm-ai/README.md index 2340e66ca..5dad60779 100644 --- a/calm-ai/README.md +++ b/calm-ai/README.md @@ -10,14 +10,15 @@ The CALM AI tools provide specialized prompts and guidance for AI assistants to - `tools/` - Individual tool prompt files - `architecture-creation.md` - Guide for creating CALM architecture documents - - `node-creation.md` - Guide for creating nodes with proper validation - - `relationship-creation.md` - Guide for creating relationships between nodes - - `interface-creation.md` - Critical guidance for interface oneOf constraints - - `metadata-creation.md` - Guide for metadata array requirements + - `calm-cli-instructions.md` - Summary of CALM CLI commands and usage flags - `control-creation.md` - Guide for control requirements and configurations + - `documentation-creation.md` - Guide for generating documentation - `flow-creation.md` - Guide for business process flows + - `interface-creation.md` - Critical guidance for interface oneOf constraints + - `metadata-creation.md` - Guide for metadata array requirements + - `node-creation.md` - Guide for creating nodes with proper validation - `pattern-creation.md` - Guide for reusable architectural patterns - - `documentation-creation.md` - Guide for generating documentation + - `relationship-creation.md` - Guide for creating relationships between nodes ## Usage diff --git a/calm-ai/tools/calm-cli-instructions.md b/calm-ai/tools/calm-cli-instructions.md new file mode 100644 index 000000000..32c1032ab --- /dev/null +++ b/calm-ai/tools/calm-cli-instructions.md @@ -0,0 +1,133 @@ +# CALM CLI Instructions + +The CALM CLI provides command-line utilities for working with Common Architecture Language Model (CALM) files. This guide summarizes the primary commands and their usage. + +## Installation and Help + +Install globally via npm: + +```shell +npm install -g @finos/calm-cli +``` + +Run `calm` with no arguments to see the top-level help: + +```shell +calm +``` + +This displays available commands such as `generate`, `validate`, `copilot-chatmode`, `server`, `template`, and `docify`. + +## Generate Architectures from Patterns + +Create an architecture scaffold from a CALM pattern: + +```shell +calm generate -p [-o ] [--schema-directory ] [--verbose] +``` + +- `-p, --pattern`: Path or URL to the pattern file (required). +- `-o, --output`: Where to write the generated architecture (defaults to `architecture.json`). +- `-s, --schema-directory`: Location of CALM meta schemas (defaults to `../calm/release`). +- `-v, --verbose`: Enables verbose logging. + +Example: + +```shell +calm generate -p calm/pattern/api-gateway.json +``` + +## Validate Architectures + +Validate that an architecture conforms to a pattern: + +```shell +calm validate -p -a [--schema-directory ] [--strict] [--format ] [-o ] [--verbose] +``` + +- `-p, --pattern`: Path or URL to the pattern (required). +- `-a, --architecture`: Path or URL to the architecture (required). +- `--strict`: Treat warnings as failures. +- `-f, --format`: Output format (`json` or `junit`). +- `-o, --output`: Write the validation output to a file. +- `-v, --verbose`: Verbose logging. + +Warnings highlight potential issues (like placeholder values) but only errors cause a non-zero exit unless `--strict` is used. + +## Copilot Chatmode Setup + +Configure CALM-specific AI assistance inside a repo: + +```shell +calm copilot-chatmode [--directory ] [--verbose] +``` + +This generates `.github/chatmodes/CALM.chatmode.md`, enabling GitHub Copilot Chat to use CALM-aware tools (nodes, relationships, interfaces, controls, flows, patterns, metadata). + +## CLI Server (Experimental) + +Expose CLI functionality over HTTP: + +```shell +calm server --schema-directory +``` + +Endpoints (default `http://127.0.0.1:3000`): + +- `GET /health` for health checks +- `POST /calm/validate` with a CALM model payload to validate + +## Template Command + +Generate arbitrary files from CALM models using Handlebars bundles: + +```shell +calm template -a -o [--bundle | --template | --template-dir ] [--url-to-local-file-mapping ] [--clear-output-directory] [--verbose] +``` + +Useful for producing documentation, reports, or configs. Template bundles require an `index.json`, transformer implementation, and templates. + +## Docify Command + +Generate a documentation website from a CALM model: + +```shell +calm docify -a -o [--template ] [--template-dir ] [--url-to-local-file-mapping ] [--clear-output-directory] [--verbose] +``` + +Creates a browsable site that visualizes nodes, relationships, interfaces, and metadata. + +### Using `--url-to-local-file-mapping` + +`docify` resolves schema references or linked assets (flows, controls, ADRs) by default via HTTP(S). If your architecture references resources that are not yet published, provide a mapping file so Docify can replace remote URLs with local paths during generation. + +**Mapping file format (JSON object):** + +```json +{ + "https://calm.finos.org/docuflow/flow/document-upload": "flows/flow-document-upload.json", + "https://internal-policy.example.com/security/tls": "docs/policies/tls.json" +} +``` + +**Usage example:** + +```shell +calm docify \ + -a architectures/ecommerce-platform.json \ + -o docs/ecommerce \ + --url-to-local-file-mapping docs/url-map.json +``` + +During generation, each referenced URL is swapped with the corresponding local file path so Docify can inline the referenced content without network access. This is especially helpful when: + +- Referenced resources live in the same repo but are not public yet +- You need reproducible offline builds in CI +- Documentation reviewers shouldn’t depend on internal endpoints + +## Tips + +- Keep schema files accessible via `--schema-directory` for offline use. +- Use `calm generate` + `calm validate` workflow to quickly iterate on architectures. +- Leverage warnings to replace placeholder values before production. +- Combine `calm copilot-chatmode` with VS Code for CALM-aware AI assistance. diff --git a/cli/src/command-helpers/ai-tools.ts b/cli/src/command-helpers/ai-tools.ts index 63b06367b..88d6dcfb3 100644 --- a/cli/src/command-helpers/ai-tools.ts +++ b/cli/src/command-helpers/ai-tools.ts @@ -142,7 +142,8 @@ async function createToolPrompts(chatmodesDir: string, logger: Logger): Promise< 'control-creation.md', 'flow-creation.md', 'pattern-creation.md', - 'documentation-creation.md' + 'documentation-creation.md', + 'calm-cli-instructions.md' ]; let successCount = 0;