Skip to content

PRINCIPLES

Introduction

These principles are Renderflow's enduring decision rules.

Conformance

This document is authored in conformance with:

  • .github/specs/architecture/document.spec.md
  • .github/specs/architecture/identity/principles.spec.md

Purpose & Scope

This document defines how Renderflow should make architectural, engineering, and design trade-offs.

It does not prescribe implementation details or temporary preferences.

Definitions

  • Principle: a rule for making consistent decisions.
  • Trade-off: a choice where optimizing one quality changes another.
  • Deterministic behavior: behavior that remains materially consistent for the same declared inputs.

Renderflow Principles

1. Declare intent before executing work

Configurations, transform definitions, and plans should describe what the system is trying to accomplish before execution begins.

2. Keep planning visible

Users should be able to inspect paths, targets, trade-offs, and execution shape without running the full workflow.

3. Separate planning from execution

The system should reason about what to do independently from how a renderer, transform, or plugin performs the work.

4. Prefer deterministic defaults

The same inputs should produce materially equivalent outputs and diagnostics unless a user has explicitly asked for non-deterministic behavior.

5. Reuse shared work once discovered

When multiple outputs depend on a common intermediate, Renderflow should prefer a single shared path over duplicated effort.

6. Extend through contracts, not exceptions

New capabilities should enter through explicit registries, transform contracts, and stable abstractions rather than core-specific branching.

7. Preserve human authority

Automation, including AI-assisted transformation, must remain reviewable, optional, and subordinate to declared user intent.

8. Optimize for portability over local cleverness

A workflow that can be moved, validated, and reproduced is more valuable than a shortcut tied to one contributor's environment.

Requirements, Constraints & Guidelines

Requirements

  • Principles must guide decisions across code, docs, workflows, and AI usage.
  • Principles must stay implementation-independent while remaining actionable.
  • Trade-offs among cost, quality, speed, and extensibility must be explainable through these principles.

Constraints

  • Framework choices must not replace principles.
  • Temporary optimizations must not become durable rules.
  • Principles must not duplicate the roadmap or manifesto.

Guidelines

  • Prefer concise rules with wide applicability.
  • Prefer positive guidance over prohibitions where practical.
  • Prefer principles that explain existing architecture and future evolution.

Authoring Contract

Purpose

Own Renderflow's decision heuristics.

Responsibilities

This document owns:

  • cross-cutting design and engineering rules,
  • trade-off guidance,
  • the decision language used by downstream documents.

Non-Responsibilities

This document does not own:

  • the project's purpose or vision,
  • specific system boundaries,
  • release sequencing,
  • implementation algorithms.

Inputs

  • PURPOSE.md
  • VISION.md
  • MANIFESTO.md

Outputs

  • PILLARS.md
  • METHODOLOGY.md
  • FOUNDATIONS.md
  • SYSTEM.md
  • ARCHITECTURE.md
  • DESIGN.md
  • AI_CONSTITUTION.md

AI Generation Rules

AI systems should produce principles that remain stable even if modules, languages, or toolchains change.

Validation

Every major architectural decision should be explainable by one or more of these principles.

Acceptance Criteria

  • Principles are explicit and actionable.
  • They remain implementation-independent.
  • They guide trade-offs relevant to Renderflow.
  • They can be applied across architecture, engineering, and experience design.

AI Authoring Strategy

AI systems should:

  1. derive the decision rules required by purpose, vision, and manifesto,
  2. express them as reusable heuristics,
  3. avoid tying them to current source structure,
  4. ensure downstream documents can reference them directly.

Rationale & Context

Renderflow already makes non-trivial trade-offs: graph planning versus linear simplicity, shared DAG execution versus repeated independent work, and optional AI integration versus deterministic defaults. Principles ensure those trade-offs remain coherent as the system evolves.

Dependencies & External Integrations

Upstream Dependencies

  • PURPOSE.md
  • VISION.md
  • MANIFESTO.md

Downstream Dependencies

  • PILLARS.md
  • METHODOLOGY.md
  • FOUNDATIONS.md
  • SYSTEM.md
  • ARCHITECTURE.md
  • DESIGN.md
  • AI_CONSTITUTION.md

Examples & Edge Cases

Example

If a new capability could be added either as a hard-coded special case or as a registry-backed transform, the principle "extend through contracts, not exceptions" favors the latter.

Edge Case

An optimization that increases speed but hides plan visibility may be rejected when it conflicts with "keep planning visible."

Validation Criteria

This document is valid when independent contributors reach similar trade-off conclusions by applying the same principles.

  • .github/specs/architecture/document.spec.md
  • .github/specs/architecture/identity/principles.spec.md