Cortex Project Definition Files

This documentation explains the purpose and structure of project definition files in Cortex projects.

Overview

Every Cortex project includes a project definition file, which serves a similar role to go.mod in Golang projects. This file defines the project identity and its dependencies.

File Location

The project definition file is located in the .cortex directory at the root of the project and is named project.ctx.

File Structure

The project definition file has a straightforward structure:

project [project-identifier]

require {
  [dependency-identifier] [version] [checksum]
  [dependency-identifier] [version] [checksum]
  ...
}

Example from NDA Project

Here's the project.ctx file from the NDA example:

project cortex.law/examples/nda

require {
  cortex.law/templates/legal-base 1.0.0 #d285563c25c5152b1ae80fc64de64ff2775fa733
  cortex.law/compliance/nda-rules 2.1.0 #3ddc9fc93c1d8ce560a3961e55547e5c78bd0f3e
}

Let's break down each part:

Project Identifier

project cortex.law/examples/nda

This line declares the project's unique identifier, which typically follows a domain-style naming convention:

• cortex.law - The domain or organization
• examples - A category or group
• nda - The specific project name

Dependencies Section

require {
  cortex.law/templates/legal-base 1.0.0 #d285563c25c5152b1ae80fc64de64ff2775fa733
  cortex.law/compliance/nda-rules 2.1.0 #3ddc9fc93c1d8ce560a3961e55547e5c78bd0f3e
}

The require block lists all dependencies with:

• Dependency identifier: Similar format to the project identifier
• Version number: Semantic versioning (e.g., 1.0.0, 2.1.0)
• Checksum: SHA hash starting with # to verify integrity

Dependency Management

Cortex uses this file to:

1. Identify the project: The unique identifier distinguishes this project from others
2. Track dependencies: Lists other Cortex packages this project needs
3. Pin versions: Ensures consistent behavior by specifying exact versions
4. Verify integrity: Checksums validate that dependencies haven't been altered

Types of Dependencies

A Cortex project might depend on various types of packages:

1. Templates: Base templates that provide structure and common elements
2. Rules: Compliance or validation rules for specific document types
3. Libraries: Reusable components for specific domains
4. Utilities: Helper functions or shared code

Version Management

Cortex follows semantic versioning principles:

• Major version (1.x.x): Indicates breaking changes
• Minor version (x.1.x): Adds features in a backward-compatible manner
• Patch version (x.x.1): Backward-compatible bug fixes

Working with Project Definition Files

Creating a New Project

When creating a new Cortex project:

1. Create the .cortex directory
2. Create a project.ctx file with your project identifier
3. Add any dependencies your project needs

Adding Dependencies

To add a dependency to an existing project:

1. Identify the dependency's identifier and version
2. Add it to the require block in your project.ctx file
3. The system will calculate and add the appropriate checksum

Updating Dependencies

To update a dependency:

1. Change the version number to the desired version
2. The system will update the checksum accordingly

Best Practices

1. Meaningful Identifiers: Choose descriptive, hierarchical project identifiers
2. Version Control: Keep your project definition file in version control
3. Dependency Documentation: Document why each dependency is needed
4. Version Pinning: Always pin to specific versions to ensure reproducibility
5. Regular Updates: Periodically check for and apply dependency updates

Relationship to Other Files

The project definition file works in conjunction with:

• Template files (.md): The actual document templates
• Test files (_test.yml): Validation rules for templates
• Variable files (variables.json): Data used to populate templates

Together, these files form a complete Cortex project ecosystem.