harness

Legal documents should be as computable as code. harness transforms legal workflows from manual processes into automated, validated systems. You define the complete workflow—from data collection to document generation—in a single file.

The Problem We Solve

Legal practice suffers from preventable inefficiencies:

• Static documents trap legal knowledge in Word files and PDFs that software cannot process
• Inconsistent data collection forces clients to answer the same questions differently across firms
• Manual review processes create bottlenecks and introduce errors
• No standardized automation means every firm reinvents document generation
• Vendor lock-in prevents you from switching service providers without rebuilding workflows

You waste time on problems that software should solve. harness provides the foundation for computable legal documents.

What Is harness?

harness defines how to write legal workflows as code. You create markdown files called templates with structured metadata that specify three things in one place:

1. What questions to ask (client questionnaires)
2. How staff reviews submissions (approval workflows)
3. What documents to generate (output templates)

These files are human-readable, version-controllable with git, and machine-processable. You write them once and run them everywhere. Any software that conforms to harness can execute your templates.

Core Components

Templates: Single-File Workflow Definitions

A template is one markdown file that defines a complete legal workflow. Think of it the way Python treats modules — the file is the unit. The file contains structured YAML metadata at the top (front matter) followed by a document body. That front matter carries both the questionnaire and the workflow, making the three components inseparable:

• Questionnaire — the client-facing question flow, defined in questionnaire: front matter
• Workflow — the staff review process, defined in workflow: front matter
• Body — the document with variable placeholders, written in Liquid markdown

You specify:

• A unique identifier for the template
• The title and description
• Whether the template applies to individuals, organizations, or both
• The complete question flow for clients
• The complete review flow for staff
• The document body with variable placeholders

This single-file approach keeps related logic together. You never lose track of which questionnaire generates which document. Everything lives in one place.

Notations: Live Workflow Instances

A notation is a live instance of a template assigned to a specific respondent. Where a template defines the what, a notation records the who and when — linking the template to a person, entity, or both, and tracking the assignment through its lifecycle.

Every notation moves through states:

• open — the respondent needs to complete the questionnaire
• review — the submission is awaiting staff review
• waiting_for_questionnaire — blocked on a dependent questionnaire completing first
• waiting_for_workflow — waiting for workflow coordination with other parties
• closed — the notation is finalized and archived

You look at the notation to see current workflow state. You look at the template to see the predefined questionnaire and workflow logic. The two are distinct: templates are static definitions; notations are live records.

Database constraints prevent duplicate active notations, ensuring only one open notation exists for a given template and respondent at a time.

Questionnaires as State Machines

harness models questionnaires as state machines—finite paths through questions with explicit transitions. This approach eliminates ambiguity about what happens next.

Questionnaire: Client-Facing Questions

The questionnaire defines your client’s journey. Each state references a question. Based on the answer, the system moves to the next state. You specify unconditional transitions with _ and conditional transitions based on answer values.

Every questionnaire must start at BEGIN and reach END. No questions fall through the cracks. No infinite loops trap users. The validation system enforces these rules.

Workflow: Staff Review Process

The workflow defines how your staff reviews client submissions. This human-in-the-loop verification ensures quality control and legal oversight. Staff workflows can approve, reject, request clarification, or route to specialized reviewers.

You maintain final authority over automated processes. The system assists; you decide.

Document Generation

Document bodies use Liquid templating to insert client data into predefined structures. You write the body once with variable placeholders. The system replaces placeholders with actual responses when generating documents.

You can:

• Insert variables: {{client_name}}
• Format dates: {{start_date | date: "%B %d, %Y"}}
• Format currency: {{amount | currency}}
• Add conditional sections: Show text only if certain conditions apply
• Create loops: Repeat sections for multiple items

The output is a professional document ready for signatures. You generate PDFs or formatted text files depending on your needs.

Benefits By Audience

For Legal Professionals

Eliminate repetitive work. You stop drafting the same documents manually. Define the template once and reuse it for every client.

Enforce quality control. Staff review is built into the workflow. No submission bypasses verification. You catch errors before they reach clients.

Maintain compliance. Validation ensures all required information is collected. Audit trails track every action. You demonstrate compliance through system-generated logs.

Scale without proportional hiring. Automated workflows handle increased volume without proportional staff growth. You serve more clients without sacrificing quality.

For Organizations

Standardize across teams. Every office uses the same templates. You eliminate inconsistency between jurisdictions and practitioners.

Swap service providers seamlessly. harness defines the interface. Any conforming provider can execute your templates. You avoid vendor lock-in.

Track every step. Complete audit trails show who did what and when. You prove compliance and identify bottlenecks.

Own your workflows. Template definitions are text files you control. You migrate to new systems without rebuilding from scratch.

For Clients

Experience faster turnaround. Automated workflows eliminate manual handoffs. You get documents faster.

Provide information once. Structured data collection prevents redundant questions. You answer each question one time.

See transparent processes. You know exactly what information is needed and why. No surprises or hidden requirements.

For the Legal Industry

Enable interoperability. Different legal tech systems can share template definitions. You break down data silos.

Foster innovation. Open standards let anyone build conforming tools. Competition improves quality and reduces cost.

Democratize sophisticated workflows. Small firms access the same automation as large firms. You compete on legal expertise, not software budgets.

Foundation for AI assistance. Structured, validated documents let language models provide reliable assistance. You augment human expertise with machine intelligence.

Technical Architecture

File Format

harness templates use markdown files with YAML front matter. The structure is:

---
code: unique_identifier
title: Document Title
description: Purpose of this template
respondent_type: person_and_entity
questionnaire:
  BEGIN:
    _: "first_question"
  first_question:
    _: "END"
workflow:
  BEGIN:
    _: "staff_review"
  staff_review:
    _: "END"
---

# Document Body

Dear {{client_name}},

Your {{service_type}} is confirmed...

Required fields are code, title, description, respondent_type, questionnaire, and workflow. The validation system rejects files that omit required fields.

State Machine Structure

State machines define paths through questionnaires and workflows:

• BEGIN state - Entry point for every state machine
• Question states - Reference questions that exist in your database
• Transitions - Define what happens next based on answers
• END state - Terminal state when the machine completes

You use _ for unconditional transitions (always go to this next state) and answer values for conditional transitions (go to different states based on the answer).

The validation system ensures:

• BEGIN state exists
• At least one path reaches END
• No infinite loops
• No unreachable states
• All question references are valid

Variable Interpolation

Document bodies use Liquid templating syntax. Variables appear in double curly braces: {{variable_name}}. You reference:

• Client data: {{client_name}}, {{organization_name}}

• Question answers: {{service_type}}, {{start_date}}

• Conditional sections:

  {% if respondent_type == "person_and_entity" %}
  This binds both organization and individual.
  {% endif %}
  

The validation system checks that all variables reference available data sources.

Validation System

harness enforces strict validation:

YAML Validation

• Proper front matter delimiters (---)
• Valid YAML syntax
• All required fields present
• Field constraints met (title under 255 characters, respondent_type matches allowed values)

State Machine Validation

• BEGIN and END states exist in both questionnaire and workflow
• All paths are reachable
• No infinite loops
• Question references exist in database
• Conditional transitions match valid answer values

Variable Validation

• All {{variables}} in bodies correspond to available data
• Liquid syntax is properly formatted
• Filters are valid (date, currency, etc.)

When validation fails, you receive specific error messages identifying the problem. You fix the issue and revalidate.

Implementation Standards

Legal Compliance Requirements

Jurisdiction: Use Nevada law and Washoe County when possible. This provides predictable legal interpretation and venue.

End Dates: Include explicit end dates for all agreements. Nevada courts favor definite terms.

Human Review: Implement staff review (workflow) for quality control. Automated systems should augment, not replace, professional judgment.

Audit Trails: Maintain comprehensive logs of all actions. Track who answered what and when. Record all state transitions and document generations.

Technical Requirements

Liquid Templating: Use the Liquid templating engine for variable substitution. This provides proven, secure template processing.

PDF Support: Handle PDF form population and generation. Many legal documents require PDF output.

Markdown Support: Support markdown for document creation. Markdown provides clean, version-controllable source.

Cross-Platform: Ensure implementations work across operating systems and platforms.

APIs and Webhooks: Provide RESTful APIs for integration. Support webhooks for real-time notifications of notation state changes.

Quality Assurance

Comprehensive Validation: Validate all inputs—YAML structure, state machines, question references, variables. Catch errors before they affect users.

Clear Error Messages: When validation fails, explain what went wrong and how to fix it. Point to the specific line or field causing problems.

Thorough Testing: Test all templates end-to-end. Verify that every path through the state machine works correctly.

Performance Optimization: Optimize for fast response times. Users should not wait for validation or document generation.

Example Template

This simplified service agreement shows harness in practice:

---
code: simple_service_agreement
title: Simple Service Agreement
description: Basic service agreement for consulting services
respondent_type: person_and_entity
questionnaire:
  BEGIN:
    _: "what_is_your_name__personal_name"
  what_is_your_name__personal_name:
    _: "what_is_service_type__text"
  what_is_service_type__text:
    _: "what_is_start_date__date"
  what_is_start_date__date:
    _: "END"
workflow:
  BEGIN:
    _: "staff_review__approve_reject"
  staff_review__approve_reject:
    "Approve": "END"
    "Reject": "rejection_reason__text"
  rejection_reason__text:
    _: "END"
---

# Service Agreement

**Agreement Date**: {{agreement_date | date: "%B %d, %Y"}}

This Service Agreement ("Agreement") is entered into between:

**Client**: {{client_name}}
**Service Provider**: Your Firm Name

## Services

The Service Provider agrees to provide {{service_type}} services
beginning on {{start_date | date: "%B %d, %Y"}}.

{% if respondent_type == "person_and_entity" %}
This agreement binds both the organization and the individual signatory.
{% endif %}

## Terms

This agreement shall remain in effect until {{end_date | date: "%B %d, %Y"}}.

---

*Nothing in this document constitutes legal advice without a
valid signed retainer.*

The client completes three questions: name, service type, and start date. Staff reviews and either approves or rejects with a reason. When you assign this template to a respondent, harness creates a notation in open state. The notation moves to review when the client submits, and to closed when staff approves.

Why Open Standards Matter

Avoid Vendor Lock-In

You own your template definitions. The files are plain text that any conforming system can execute. You switch service providers without rewriting templates from scratch.

Proprietary systems trap your processes behind their interfaces. Open standards set you free.

Enable Innovation

Anyone can build tools that conform to harness. Competition drives quality improvements and cost reductions. You benefit from innovation across the entire ecosystem.

Closed systems stagnate. Open standards evolve through community contribution.

Foster Collaboration

You share template definitions with other organizations. Peer review improves quality. Best practices spread through the community.

Siloed systems prevent learning from others’ experience. Open standards create a knowledge commons.

Future-Proof Your Investment

Standards outlast any single implementation. Your templates remain executable even if specific software products disappear. Text files never become obsolete.

Proprietary formats die with their creators. Open standards persist across generations.

Getting Started

For Organizations

Evaluate your needs. Identify repetitive legal workflows that consume staff time. Look for processes where you collect similar information repeatedly.

Review the specification. Read the complete technical specification to understand requirements and capabilities. Determine if harness fits your workflow patterns.

Contact for guidance. Reach out for implementation assistance. We help you adopt standards in your practice and connect you with conforming service providers.

For Developers

Access the repository. The harness repository on GitHub contains the complete specification and validation rules.

Study validation requirements. Understand what makes a template valid. Review state machine validation, variable checking, and YAML structure requirements.

Build conforming tools. Create software that executes harness templates and manages notation lifecycle. Join the ecosystem of interoperable legal tech.

For Legal Professionals

Understand computable documents. Learn how structured workflows differ from traditional documents. See how questionnaires, review processes, and bodies combine into complete templates.

Explore example templates. Review templates for common legal workflows. Understand how your practice areas map to the harness structure.

Consider adoption. Evaluate whether standardized workflows would improve your practice. Assess time savings from automation and consistency improvements from validation.

Contact and Resources

Technical Support: support@sagebrush.services

GitHub Repository: github.com/neon-law-foundation/harness

General Inquiries: support@neonlaw.org

Legal Notice: Nothing in this document constitutes legal advice without a valid signed retainer. harness is a technical specification, not legal counsel. The Neon Law Foundation maintains these standards as an open resource for the legal industry.

The harness specification is open and freely implementable by anyone.