Facts

Product Introduction

1. Definition: Facts is a high-performance CLI tool and specification framework written in Rust, designed to facilitate Spec-Driven Development (SDD) and Agent-Augmented Engineering. It serves as a centralized source of truth for a project, where requirements are documented as atomic "claims" that are both human-readable (Markdown) and machine-verifiable (Shell/YAML).

2. Core Value Proposition: Facts exists to solve the "documentation-implementation gap" by providing a verifiable link between project specs and codebase reality. By utilizing a lifecycle-based tagging system (@draft, @spec, @implemented), it allows developers and AI agents (like Claude Code or GitHub Copilot) to collaborate on a living specification. This ensures that project requirements are not just passive text but active, executable tests that verify a project's state in seconds.

Main Features

1. Lifecycle Tagging & Agent Workflow: Facts employs a structured pipeline to manage project requirements. Claims start as @draft (rough ideas), transition to @spec (precise, actionable requirements), and finally move to @implemented (verified code). This workflow is specifically optimized for LLM agents, allowing them to autonomously refine ideas into technical specs and then build the code necessary to satisfy those specs.

2. Automated Verification Engine: The core of the utility is the facts check command. Each fact can be associated with a specific shell command that returns an exit code of 0 when the claim is true. This enables automated project linting where the machine verifies architectural constraints, presence of files, or specific string patterns in the code, reducing the need for manual oversight.

3. Agentic Skills Integration: The product ships with four distinct agent skills: facts-discover (codebase scanning), facts-refine (sharpening drafts), facts-implement (autonomous building), and facts-core. These skills allow AI agents to interact with the .facts file as a dynamic dashboard, enabling "vibe-coding" to transition into structured, professional-grade development.

4. Hybrid File Format: A .facts file is a syntactically valid hybrid of Markdown and YAML. This allows for deep structural organization using Markdown headings while maintaining the data density of YAML for machine parsing. Each fact is assigned a stable ID (short hash of the label), ensuring that references remain consistent even as the project evolves.

Problems Solved

1. Pain Point: Outdated Documentation and Hallucinations. Traditional project specs often fall out of sync with the code. For AI agents, this leads to "hallucinations" where the agent assumes features exist that don't, or vice-versa. Facts solves this by making the spec a verified asset that the agent must check against the current state of the repository.

2. Target Audience: This tool is built for Software Engineers using AI coding assistants, Technical Architects managing complex project requirements, and DevOps teams looking for a lightweight way to enforce project-level constraints without the overhead of heavy testing frameworks. It is particularly useful for "Agentic" workflows where autonomous agents (Claude, GPT-4o, Copilot) are responsible for feature implementation.

3. Use Cases:

• Rapid Prototyping: Quickly sketching out @draft ideas and letting an agent refine them into @spec.
• CI/CD Guardrails: Running facts check in a deployment pipeline to ensure all @implemented facts remain true before a merge.
• Agent Onboarding: Providing a new AI agent with a .facts file so it instantly understands the project's architecture, auth protocols, and data models without manual prompting.

Unique Advantages

1. Differentiation: Unlike traditional unit testing frameworks (like Jest or Pytest) which focus on low-level function logic, Facts focuses on high-level project truths. Unlike Jira or Trello, the "tickets" (facts) live inside the repository and are physically verified by the code itself. It bridges the gap between project management and version control.

2. Key Innovation: The "Command-Backed Claim" is the primary innovation. By allowing any shell command to act as the validator for a requirement, Facts turns the project specification into a suite of high-level integration tests. Its implementation in Rust ensures near-instant execution, allowing for a "read the entire spec in 30 seconds" experience even for large-scale projects.

Frequently Asked Questions (FAQ)

1. How does Facts improve AI agent coding performance? Facts provides a structured interface for AI agents. Instead of giving an agent a vague prompt, you give it a .facts file. The agent can then use the facts-implement skill to identify exactly what is missing (@spec) and verify its own work by running facts check, significantly reducing the feedback loop and error rate.

2. Is Facts compatible with existing testing frameworks? Yes. Facts is designed to sit above traditional testing frameworks. A fact's command can actually trigger a specific test suite (e.g., command: npm test --grep "auth") or check for the existence of a compiled binary. It acts as an orchestrator for project-wide verification.

3. What is the difference between a @spec and an @implemented fact? A @spec fact is a requirement that has been clearly defined with technical parameters but has not yet been built or verified in the code. An @implemented fact is a claim that currently holds true in the codebase, as verified by a passing shell command or an agent's analysis of the source files.

4. Can Facts be used in a multi-language repository? Absolutely. Because Facts is a standalone Rust binary that executes shell commands, it is language-agnostic. It works equally well for TypeScript, Python, Rust, Go, or even documentation-only projects, as long as there is a way to programmatically verify the claims.