Contributor Guide

Getting Started

Thank you for your interest in contributing to ContextSubstrate (ctx). This project aims to bring reproducibility and auditability to AI agent workflows. As a contributor, you help build the substrate that makes AI execution contestable and debuggable.

Prerequisites

To contribute to this project, you will need:

• Go: Version 1.22 or later.
• Git: For version control.
• A local environment: Linux, macOS, or Windows (WSL recommended for Windows).

Development Environment Setup

1. Fork and Clone

   git clone https://github.com/scalefirstai/ContextSubstrate.git
   cd ContextSubstrate
   

2. Install Dependencies The project uses Go modules. Fetch dependencies using:

   go mod download
   

3. Build the CLI To verify your setup, build the ctx binary locally:

   go build -o ctx ./cmd/ctx
   ./ctx --version
   

Project Structure

ContextSubstrate is organized into a CLI entry point and several internal packages that handle the core logic of the substrate.

• cmd/ctx/: Contains the Cobra command definitions and CLI entry point.
• internal/store/: The storage abstraction. Handles the .ctx directory structure, blob storage (content-addressed), and hash resolution.
• internal/pack/: Core logic for creating, loading, and manifesting Context Packs. It handles the conversion of execution logs into immutable manifests.
• internal/diff/: Logic for comparing two packs. This is where drift detection (Prompt, Tool, Param, and Output drift) is implemented.
• internal/replay/: Functionality to re-execute agent steps and verify fidelity.
• internal/sharing/: Logic for forking, listing, and finalizing packs.

Testing Guidelines

We rely on a mix of unit tests for logic and end-to-end integration tests for the CLI workflow.

Running Tests

Run the entire test suite:

go test ./...

Run tests with verbose output to see execution logs:

go test -v ./...

Integration Tests

The integration_test.go file in the root directory contains a full end-to-end workflow test. It exercises:

1. ctx init
2. ctx pack
3. ctx show
4. ctx replay
5. ctx diff
6. ctx verify
7. ctx fork
8. ctx log

When adding new features, ensure that the integration test is updated to reflect the new capabilities.

Adding Unit Tests

If you are modifying logic in internal/diff or internal/pack, add corresponding _test.go files within those directories. Focus on edge cases for hash resolution and manifest serialization.

Contribution Workflow

1. Identify an Issue: Check the GitHub Issues tracker or open a new one to discuss a feature.
2. Create a Branch: Use descriptive names like feat/add-json-exporter or fix/hash-collision-logic.
3. Commit Messages: Follow a clear, imperative style (e.g., feat: implement tool drift comparison).
4. Submit a PR: Ensure your code passes go fmt and all tests.
5. Code Review: A maintainer will review your changes. Be prepared to iterate on feedback.

Standards & Style

• Error Handling: Use wrapped errors (fmt.Errorf("context: %w", err)) to provide trace-like context for CLI users.
• Consistency: Use the internal/store abstractions for all filesystem operations to ensure the .ctx store remains valid.
• Documentation: All public-facing structs and functions should have comments. If you add a new command, ensure you update the Long description in cmd/ctx/commands.go.
• Formatting: Always run go fmt ./... before committing.