COSS.toml: Standardizing Project Metadata for AI

The coss.toml file is a standardized metadata format that helps AI tools understand your project structure, build processes, and conventions without guesswork. By placing this file in your project root, you enable more accurate AI assistance and automation.

Why COSS.toml?

Modern AI tools often struggle to understand project conventions, leading to:

• Inefficient “detective work” to find source code, tests, and build scripts
• Incorrect assumptions about project structure
• Failed automation due to misunderstood toolchains
• Wasted computational resources

The coss.toml file solves this by providing a clear, standardized way to describe your project.

Getting Started

Quick Installation:

curl -fsSL https://raw.githubusercontent.com/contriboss/coss_spec/master/install.sh | sh

Or follow these steps:

1. Install the latest template using the command above
2. Place it in your project root alongside your README and package files
3. Fill in your project details using the sections below as a guide

Manual Download: Download specific versions from our specification repository

Key Sections Explained

Basic Information

name = "your-project-name"
version = "0.1.0" 
description = "A concise description of your project."
licenses = ["MIT", "Apache-2.0"]
ai_contributions = true  # Indicates if AI helped with development

Build & Development

build = "npm run build"
test = "npm test"
lint = "eslint src/"
format = "prettier --write src/"

Dependencies & Environment

[dependency_locks]
javascript = "package-lock.json"
python = "poetry.lock"
rust = "Cargo.lock"

[environments]
node = "18.x"
python = "3.11"

Project Structure

languages = ["TypeScript", "Python"]
project_type = "library"  # or "application", "tool", etc.
maturity = "stable"       # "experimental", "beta", "stable"

Documentation & Support

repository = "https://github.com/your-org/your-project"
documentation = "https://github.com/your-org/your-project/wiki"
issue_tracker = "https://github.com/your-org/your-project/issues"

Complete Template

The full template includes 19 comprehensive sections covering:

• Basic project information (name, version, licenses)
• Repository and issue tracking links
• Languages, frameworks, and platforms used
• Dependency management and lock files
• Build, test, and quality commands
• Maintainer and governance information
• Security scanning and compliance tools
• Documentation standards and coverage
• Contribution automation settings
• Internationalization support

Benefits for AI Tools

With a properly filled coss.toml, AI can:

• Instantly understand your project structure
• Run the correct build and test commands
• Identify the right linting and formatting tools
• Understand dependency management approach
• Respect your coding standards and conventions
• Provide more accurate suggestions and automation

Questions?

If you have questions about implementing coss.toml in your project:

• Join our community discussions
• Contact us directly
• Read the full COSS standard

Help us improve this standard by sharing your experience and feedback!