Skip to content

Introduction

This repository is a software engineering template built around structured documentation, technical decision tracking, and human-supervised AI workflows.

When starting a new project from this template, replace this introductory overview with your project description. State what the software does, who uses it, and the operational constraints that shape its design.

Documentation Layout

The documentation is divided into three functional areas:

  • Glossary: Canonical definitions for domain, architectural, and governance terminology. Terms defined here automatically generate tooltips and links across all pages through zensical-glossary.
  • Decision Record: Architectural, design, product, operational, and social decisions. Each record documents context, technical constraints, considered alternatives, and consequences.
  • Feature Record: Specifications for user-facing and internal features, including interaction flows, benchmarks, and implementation notes.

Workflow

Projects built with this template follow three core practices:

  1. Explicit Decisions First: Before writing subsystem code, capture architecture choices, dependency selections, and licensing in a Decision Record. When requirements change, update the corresponding record rather than letting documentation drift.
  2. Standard Requirements Language: Specifications use RFC 2119 keywords (MUST, SHOULD, MAY) to distinguish hard technical constraints from preferences.
  3. Verified Changes: Every documentation change must pass a clean build (zensical build --clean) with zero warnings. Code commits follow Conventional Commits format.

Local Documentation Preview

Run the Zensical development server to view edits with live reload:

cd documentation
zensical serve

To build static HTML assets into documentation/site/:

cd documentation
zensical build --clean