reflector

Reflective synchronization systems for recursive AI-assisted software engineering.

What is reflector?

reflector is an open-source research repository and recursive engineering platform for studying how AI-assisted software systems can stay aligned, auditable, and governable as they iterate. The repository combines:

• a research manuscript in paper/
• a synchronization-oriented CLI in reflector/
• deterministic publication workflows in scripts/ and .github/workflows/
• specification contracts in specs/
• a GitHub Pages publication surface in docs/

If you want the short version: reflector treats recursive development as a systems problem, not just a prompting problem.

Why it exists

Recursive AI workflows can move faster than humans can inspect them. reflector exists to make those workflows easier to reason about by introducing bounded execution, explicit checkpoints, inspectable metadata, and publication-grade traceability.

Core concepts

Concept	Meaning in reflector
Recursive Drift	Failure modes that emerge when recursive optimization loops move away from human intent.
Reflective Auditing	Continuous validation of state, artifacts, and workflow contracts against declared invariants.
Synchronization Checkpoints	Explicit handoff boundaries where human review or deterministic validation can gate progress.
Human Governance	The repository treats human oversight as a first-class systems constraint, not an afterthought.
Mixed-Initiative Systems	Humans, automation, and AI agents collaborate through bounded, reviewable execution layers.

How reflector works

semantic content and metadata
            ↓
specifications and synchronization contracts
            ↓
audits, validation, and milestone checkpoints
            ↓
publication orchestration and deployment
            ↓
repeatable artifacts for research, review, and release

The repository architecture is intentionally layered:

• Content — manuscript sections and semantic paper structure in paper/sections/
• Metadata — canonical publication and repository metadata in paper/macros/ and metadata/
• Style — renderer-facing presentation assets in paper/styles/
• Orchestration — build, audit, and deployment logic in scripts/, reflector/, and .github/workflows/

Quick start

See docs/getting-started.md for the complete zero-to-working-environment walkthrough.

Recommended local workflow

reflector's canonical developer workflow uses task with uv:

task setup
task doctor
task test
task examples

Direct Python fallback

If you do not use task or uv, you can still install the repository directly:

python -m pip install -e '.[dev,huggingface]'
reflector --version
reflector huggingface --check-sdk

Build the paper

./scripts/build-paper.sh paper

To publish a locally built PDF into docs/:

./scripts/build-paper.sh paper --publish

Build the visual magazine artifact

task magazine:doctor
task magazine:build
task magazine:build:print

See magazine/README.md for the full workflow and output paths.

Repository map

Need	Start here
Getting started	docs/getting-started.md
Canonical onboarding	00-README.md
Repository architecture	docs/architecture-overview.md
Publication architecture	docs/publication-architecture.md
Workflow overview	docs/workflows.md
Toolchain requirements	docs/toolchain.md
Paper overview	paper/README.md
Magazine overview	magazine/README.md
Beacon compatibility	docs/beacon-compatibility.md
Pages activation and rollback	docs/pages-deployment.md
Publication specs	specs/publication/
Audit archive index	audits/README.md
Research notes	docs/research/
Roadmap	ROADMAP.md

Research paper and publication links

• Canonical publication hub: https://reflector.egohygiene.io/
• Canonical PDF route: https://reflector.egohygiene.io/reflector.pdf
• Technical GitHub Pages fallback: https://egohygiene.github.io/reflector/
• Paper reader: https://reflector.egohygiene.io/paper/
• Magazine reader: https://reflector.egohygiene.io/magazine/
• Print edition: https://reflector.egohygiene.io/magazine/print/
• Downloads and integrity evidence: https://reflector.egohygiene.io/downloads/
• DOI (canonical version DOI): https://doi.org/10.5281/zenodo.20477044
• DOI (Zenodo concept DOI): https://doi.org/10.5281/zenodo.20477045
• Citation metadata: CITATION.cff
• CodeMeta metadata: codemeta.json
• Publication metadata: publication.json
• Paper source and section status: paper/README.md
• arXiv-oriented publication spec: specs/publication/arxiv-publication.spec.md

Citation

Use the version DOI when citing a specific archived release:

10.5281/zenodo.20477044

CITATION.cff is the canonical machine-readable citation source for GitHub and downstream tooling.

Publication

• Release metadata and DOI synchronization contract: release-manifest.json
• Release workflow and DOI lifecycle: docs/release-process.md
• Publication infrastructure details: docs/publication-infrastructure.md
• Committed audit archive index: audits/README.md

Hugging Face readiness

reflector is not publishing to Hugging Face yet, but it is now structured to make that step straightforward later:

• canonical repository metadata already includes a Hugging Face integration surface in metadata/repository.yaml
• the CLI exposes reflector huggingface for scaffold inspection
• recommended publication and mirroring strategy is documented in docs/huggingface.md
• a future-facing card scaffold is available in README_HF.md

Contributing and project governance

• Contribution guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Support guide: SUPPORT.md
• Citation guidance: CITATION.cff

Long-term vision

reflector aims to become a durable reference architecture for recursive engineering systems: publication-aware, specification-driven, synchronization-first, and legible to both humans and automation. The near-term roadmap is to complete the manuscript, harden the audit and release paths, and prepare clean distribution surfaces for arXiv, GitHub Pages, and future Hugging Face publication.

Repository lifecycle

Reflector serves two roles simultaneously:

• the published Reflector research project (the manuscript, magazine, and publication artifacts)
• the production reference implementation of the Reflector publication platform

The intended lifecycle is:

Reflector (reference implementation)
    ↓
Template Extraction
    ↓
Reusable Publication Platform
    ↓
Future Publications

Once template extraction is complete, future improvements to the generalized publication infrastructure should occur within the extracted template or its eventual standalone repository. Reflector will remain the canonical reference implementation demonstrating the platform in a real publication.

See audits/reference-implementation-readiness.md and ROADMAP.md for the current development status.

Publication Platform Template

Reflector now includes an extracted reusable publication platform in template/. The template packages the generalized paper, metadata, CI, and Pages infrastructure so it can be copied into a new repository as a bootstrap for a research publication.

Reflector remains the reference implementation for this platform. Future reuse should start from template/, while Reflector continues to demonstrate the full system in a live publication repository.