PACER

Project Actions, Constraints & Evidence Register

AI-First Project Tracking • Deterministic • Machine-Readable

One CSV file. One row per task. Built for AI consumption with human readability as a bonus.

What is PACER?

PACER is a minimal, deterministic project tracking format optimized for AI/LLM consumption. It uses a single CSV file where each row represents a task (called a PAC). The format enforces strict rules for dependencies, status transitions, and completion gates.

Key Features

AI-First Design - Optimized for machine consumption and automation
Deterministic Rules - Clear state transitions and dependency gates
Single Source of Truth - One CSV file, no desync
Tool Agnostic - Works with any editor, Git, or automation
Version Controlled - Text-based, diffable, auditable

Quick Start

1. Create Your Register

# Copy the template
cp docs/pacer/pacer-template.csv my-project.csv

2. Add Your First Task

ID,Title,Phase,Status,BlockedBy,Assignee,StartedAt,DoneAt,DoD,Notes
PAC-001,Initialize project,Foundation,TODO,,@you,,,Create repo; CI runs green,

3. Start Working

# Natural language commands (AI-friendly)
"Start PAC-001"     # → Status=DOING, StartedAt=now
"PAC-001 done"      # → Status=DONE, DoneAt=now (if no blockers)

4. Track Dependencies

PAC-002,Add authentication,Auth & DB,TODO,PAC-001,,,,"OAuth flow; user sessions; logout",

Core Concepts

Task Lifecycle

TODO → DOING → REVIEW → DONE
  ↑       ↑        ↑
  └───────┴────────┘
    (rollback allowed)

Required Fields

Field	Type	Description
`ID`	string	Unique identifier (e.g., `PAC-001`)
`Title`	string	Human-readable summary
`Phase`	enum	Logical grouping (Foundation, Auth & DB, etc.)
`Status`	enum	Current state (TODO, DOING, REVIEW, DONE)
`DoD`	string	Definition of Done - objective criteria

Enhanced Fields (v1.1)

Field	Type	Description
`Priority`	enum	Task priority (low, medium, high, critical)
`Urgency`	enum	Task urgency (low, medium, high, urgent)
`ValidationRules`	string	Custom validation rules (comma-separated)

AI-First Fields (v1.1)

Field	Type	Description
`Context`	string	What the AI needs to know to work on this PAC
`PreviousAttempts`	string	What has been tried before (comma-separated)
`RelatedWork`	string	Links to similar PACs or relevant work
`LearningNotes`	string	What the AI learned from this work
`DependencyType`	enum	Type of dependency (hard, soft, optional)
`DependencyReason`	string	Why this dependency exists
`UnblockingStrategy`	string	How to resolve if blocked
`Instructions`	string	Step-by-step what to do
`ExpectedOutput`	string	What success looks like
`ValidationCriteria`	string	How to verify completion
`ErrorHandling`	string	What to do when things go wrong

Dependency Rule

A task can only be DONE if all its blockers are DONE.

Enhanced Dependencies (v1.1)

PACER v1.1 supports enhanced dependency types:

Hard dependencies: PAC-001 (must be DONE before this PAC can be DONE)
Soft dependencies: PAC-001:soft (preferred but not blocking)
Weighted dependencies: PAC-001:weight:3 (priority ordering)

AI-First Intelligence (v1.1)

PACER v1.1 includes AI-specific fields for enhanced agent capabilities:

Context & Memory: Context, PreviousAttempts, RelatedWork, LearningNotes
Dependency Intelligence: DependencyType, DependencyReason, UnblockingStrategy
Instruction Clarity: Instructions, ExpectedOutput, ValidationCriteria, ErrorHandling

# PAC-010 cannot be DONE until PAC-001 and PAC-005 are DONE
PAC-010,Deploy app,Release,TODO,PAC-001,PAC-005,,,,"Live on production; health checks pass",

# AI-First Example: Database Setup with Context & Instructions
PAC-001,Setup database,Foundation,TODO,,@ai,high,urgent,,,"PostgreSQL running; migrations applied",,"Database setup failed due to port conflict","Attempted 3 times with different configs","See PAC-001 for similar issue","Use Docker instead of local install","hard","Database must be running","Check if PAC-001 is actually needed","Run database migrations in order","All tables created with proper indexes","Check migration logs for errors","If migration fails, rollback and retry"

AI/LLM Integration

Machine-Readable Artifacts

File	Purpose	Format
pacer-machine.json	Complete specification	JSON
pacer-machine.yaml	Complete specification	YAML
pacer-commands.jsonl	Command patterns	JSONL
pacer.agent.api.json	API contract	JSON
pacer.agent.grammar.ebnf	Command grammar	EBNF
pacer.agent.grammar.go	Go struct definitions	Go
pacer.agent.contract.json	Behavior rules	JSON
howto-machine-readable.md	AI integration guide	Getting started

Natural Language Commands

# Status transitions
"Start PAC-021"                    # → DOING
"Review PAC-021"                   # → REVIEW  
"PAC-021 done"                     # → DONE (if no blockers)

# Dependencies
"Block PAC-055 on 060,065"         # → BlockedBy=PAC-060,PAC-065
"Unblock PAC-055 remove 065"       # → Remove PAC-065 from BlockedBy

# Assignments & Notes
"Assign PAC-040 to @alex"          # → Assignee=@alex
"Note PAC-021: tests passing"      # → Append to Notes
"DoD PAC-021: server returns 200"  # → Update DoD

Documentation

Human-Readable Docs

Document	Purpose	Best For
Quickstart	1-page setup guide	Getting started
Specification	Authoritative rules	Implementation
Field Manual	Daily operations	Day-to-day use
FAQ	Patterns & troubleshooting	Common questions
Rationale	Design decisions	Understanding why

Machine-Readable Docs

Document	Purpose	Best For
Machine Spec (JSON)	Complete AI specification	AI agents
Machine Spec (YAML)	Complete AI specification	AI agents
Command Patterns	Natural language → actions	Command parsing
API Contract	Method signatures	API implementation
Grammar (EBNF)	Command grammar	Parser generation
Grammar (Go)	Go struct definitions	Go implementation
How-to Guide	AI integration guide	Getting started

Usage Examples

Basic Workflow

# 1. Create task
PAC-001,Setup database,Foundation,TODO,,@dev,,,PostgreSQL running; migrations applied,

# 2. Start work  
# Command: "Start PAC-001"
PAC-001,Setup database,Foundation,DOING,,@dev,2025-01-27T10:00:00Z,,PostgreSQL running; migrations applied,

# 3. Complete work
# Command: "PAC-001 done" 
PAC-001,Setup database,Foundation,DONE,,@dev,2025-01-27T10:00:00Z,2025-01-27T11:30:00Z,PostgreSQL running; migrations applied,

Dependency Management

# PAC-002 depends on PAC-001
PAC-001,Setup database,Foundation,DONE,,@dev,2025-01-27T10:00:00Z,2025-01-27T11:30:00Z,PostgreSQL running; migrations applied,
PAC-002,Add user auth,Auth & DB,TODO,PAC-001,,,,"OAuth flow; user sessions; logout",

AI Agent Integration

# Example AI agent workflow
def process_command(command: str, register: str) -> str:
    if command.startswith("Start "):
        pac_id = extract_pac_id(command)
        return transition_to_doing(pac_id, register)
    elif command.startswith("done "):
        pac_id = extract_pac_id(command)
        return complete_pac(pac_id, register)
    # ... more command patterns

Advanced Features

Custom Phases

# Add your own phases
PAC-100,Research phase,Research,TODO,,,,"Literature review; prototype built",

Batch Operations

# Start multiple tasks
"Start PAC-010, PAC-011, PAC-012"

# Complete multiple tasks  
"Done PAC-030..PAC-033"

Emergency Overrides

# Document exceptions in Notes
PAC-999,Hotfix security issue,Security,TODO,,,,"Override dependency order due to incident",

Validation & Quality

Schema Validation

# Convert CSV to JSON and validate
csv-to-json pacer.csv | jq . | validate-json docs/pacer/machine/pacer.schema.json

Common Checks

All required fields present
IDs are unique and immutable
Status transitions are valid
Dependencies exist and are acyclic
DoD is objective and testable

Getting Started

Read: Quickstart Guide
Learn: Field Manual
Understand: Specification
Validate: JSON Schema
Test: Command Patterns
Integrate: Agent Contract

For AI Agents

Load: Machine Specification
Parse: Command Grammar
Implement: API Contract

Benefits

For AI/LLM Systems

Deterministic Processing - Clear rules, no ambiguity
Natural Language Commands - Easy to parse and execute
Structured Data - Machine-readable format with validation
Atomic Operations - Safe concurrent access
Extensible Schema - Preserve unknown fields

For Devs

Single Source of Truth - No scattered information
Clear Dependencies - Visual blocking relationships
Objective Completion - DoD eliminates "done" ambiguity
Version Control Friendly - Text-based, diffable
Tool Agnostic - Works with any editor or system

Contributing

Documentation

Keep human docs in docs/pacer/
Keep machine specs in docs/pacer/machine/
Update this README when adding features

Format Changes

Follow Specification for normative rules
Use Profiles for customizations
Document deviations explicitly

License

PACER format and documentation are open source. Use freely in your projects.

Built for AI • Simple for Humans • Deterministic by Design

Get Started • Read the Spec • Machine Docs

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
docs/pacer		docs/pacer
.gitignore		.gitignore
README.md		README.md

deadcoast/PACER

Folders and files

Latest commit

History

Repository files navigation

PACER

Project Actions, Constraints & Evidence Register

What is PACER?

Key Features

Quick Start

1. Create Your Register

2. Add Your First Task

3. Start Working

4. Track Dependencies

Core Concepts

Task Lifecycle

Required Fields

Enhanced Fields (v1.1)

AI-First Fields (v1.1)

Dependency Rule

Enhanced Dependencies (v1.1)

AI-First Intelligence (v1.1)

AI/LLM Integration

Machine-Readable Artifacts

Natural Language Commands

Documentation

Human-Readable Docs

Machine-Readable Docs

Usage Examples

Basic Workflow

Dependency Management

AI Agent Integration

Advanced Features

Custom Phases

Batch Operations

Emergency Overrides

Validation & Quality

Schema Validation

Common Checks

Getting Started

For AI Agents

Benefits

For AI/LLM Systems

For Devs

Contributing

Documentation

Format Changes

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages