Skip to content
Public template

About

Reproducible research publishing template for Python research projects: a declared pipeline, canonical exemplars, and multi-format outputs.

Topics

Resources

Contributing

Security policy

Accessibility

Stars

24 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

3,432 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

πŸš€ Research Project Template

Release line: 5.2.0. See the release notes and acceptance/publication boundary. This coordinated minor preparation preserves exemplar own versions and historical tags. Final publication outputs, measured coverage and the complete exact-source acceptance handoff must precede the matching tag and release. Candidate metadata does not establish acceptance or publication.

Build Coverage Tests Documentation DOI

πŸ“„ Publication reference: A template/ approach to Reproducible Generative Research: Architecture and Ergonomics from Configuration through Publication β€” declared DOI: 10.5281/zenodo.19139090. This reference does not establish availability of the prepared 5.2.0 release.

Template Repository - Click "Use this template" to create a research project with this structure

graph TB
    subgraph "Two-Layer Architecture (Infrastructure β†’ Project)"
        INFRA["Infrastructure<br/>infrastructure/"] --> |"provides tools"| PROJECT["Project Code<br/>projects/&lt;qualified-name&gt;/src/"]
        PROJECT --> |"imported by"| SCRIPTS["Scripts<br/>projects/&lt;qualified-name&gt;/scripts/"]
        SCRIPTS --> |"generate"| WORKING["Working outputs<br/>projects/&lt;qualified-name&gt;/output/"]
        WORKING --> |"copy stage"| OUTPUTS["Final deliverables<br/>output/&lt;qualified-name&gt;/"]
        TESTS["Tests<br/>tests/ and per-project tests/"] --> |"validate"| PROJECT
        MANUSCRIPT["Manuscript<br/>projects/&lt;qualified-name&gt;/manuscript/"] --> |"references"| WORKING
    end

    subgraph "Core Pipeline (--mode core)"
        direction LR
        P_SETUP["Setup<br/>stage_00_setup.py"] --> P_TESTS["Tests<br/>stage_01_test.py"]
        P_TESTS --> P_ANALYSIS["Analysis<br/>stage_02_analysis.py"]
        P_ANALYSIS --> P_RENDER["Render<br/>stage_03_render.py"]
        P_RENDER --> P_VALIDATE["Validate<br/>stage_04_validate.py"]
        P_VALIDATE --> P_COPY["Copy<br/>stage_05_copy.py"]
    end

    SCRIPTS -.-> |"orchestrated by"| P_ANALYSIS
    P_COPY -.-> |"publishes"| OUTPUTS

    classDef core fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#0f172a
    classDef pipeline fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#0f172a
    classDef output fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#0f172a
    class INFRA,PROJECT,SCRIPTS,TESTS,MANUSCRIPT core
    class P_SETUP,P_TESTS,P_ANALYSIS,P_RENDER,P_VALIDATE,P_COPY pipeline
    class WORKING,OUTPUTS output
Loading

Quickstart

Just cloned the repo? Do this:

  1. git clone https://github.com/docxology/template && cd template
  2. uv sync --locked (installs the declared root environment; independent project runtimes retain their own locks)
  3. ./run.sh (interactive menu) or ./run.sh --pipeline --project templates/template_code_project --mode core (non-interactive, no LLM)
  4. PDFs land in output/templates/<project>/pdf/. Logs in output/templates/<project>/logs/.
  5. Run ./run.sh --help for all flags. The always-present roster is generated from PUBLIC_PROJECT_NAMES in infrastructure/project/public_scope.py and published in docs/_generated/active_projects.md.

Prepare the selected project's declared runtime and system rendering tools before dispatch; use the startup and setup guide and prepared-dispatch guide. Ordinary run.sh dispatch uses an already prepared Root interpreter; it never installs uv or syncs dependencies as a fallback.

Repurposing for your research? See docs/repurposing-architectures.md β€” maps every reusable architecture (DAG pipeline, two-layer separation, evidence registry, multi-format rendering, MCP server, publishing stack) to its module and adoption path.

For deeper guidance see docs/guides/getting-started.md and docs/RUN_GUIDE.md.

Thin-orchestrator gates: after locked preparation, use .venv/bin/python scripts/audit/check_template_drift.py --strict, .venv/bin/python scripts/gates/module_line_count_check.py, and .venv/bin/python -m infrastructure.core.health β€” details in docs/architecture/thin-orchestrator-summary.md.

Fast local test loop: after locked preparation, run the high-signal subset (.venv/bin/python -m pytest tests/infra_tests/git_hook_smoke tests/infra_tests/core/test_pytest_orchestration.py tests/infra_tests/core/test_pipeline.py -q) β€” see docs/operational/config/performance-optimization.md. Required CI Gate owns ordinary PR admission; complete Root/native acceptance is a separate release requirement, not the local edit loop.

Assistants and editors: start with AGENTS.md for the repository contract and .agents/AGENTS.md for shared catalogs, workflows and local memory. CLAUDE.md remains a command cheat sheet. For routable agent workflows, start at docs/prompts/SKILL.md and the generated skill index docs/_generated/skills_index.md.

Contributors and CI: GitHub Actions, Dependabot, and PR/issue templates live under .github/GITHUB.md (agent entry point, doc map, CI inventory) and .github/AGENTS.md (job names, thresholds, troubleshooting).

For ordinary CI's shared exact-Source preparation DATA and independent project feedback, see Fast functional CI. Preparation reuse does not supply hosted test results, complete Root/native acceptance, or release authorization.

Local hooks: After uv sync, run pre-commit install and pre-commit install --hook-type pre-push to mirror Ruff, mypy, Bandit, and smoke tests locally (see .pre-commit-config.yaml).

Strict Mermaid/PDF checks: Use Node 24 and the exact npm version declared by packageManager in package.json, then run npm ci at the repository root. The Python documentation and rendering gates automatically resolve the pinned node_modules/.bin/mmdc; add that directory to PATH only when invoking mmdc directly. The existing Chrome resolver supplies the browser executable.

A system for research and development projects. This template provides a test-driven structure with automated PDF generation, professional documentation, and validated build pipelines.

🧭 Positioning (honest framing)

This is primarily Daniel Ari Friedman's research operating system, made public and Apache 2.0-licensed so other researchers can fork it if helpful. It is not a one-size-fits-all template β€” it is opinionated, Python+pytest+LaTeX-flavored, and tuned to the kind of work Daniel does (Active Inference, computational biology, cognitive security). Honest framing ages better than wishful adoption metrics.

If your workflow looks similar (TDD-on-research-code, Markdown→PDF, multi-project monorepo, optional local-LLM draft assistance, deterministic + watermarked outputs, Zenodo DOI publishing), the template will probably save you time. If it doesn't look similar, a lighter alternative (Quarto, MyST, Cookiecutter-data-science) may serve you better. See MAINTAINERS.md for ownership and STATUS.md for per-subsystem freshness so you can judge what's actively maintained vs dormant.

Long-horizon viability guides β€” toolchain migration, regression testing, archival redundancy, local CI, and the design for a future executable-bundle stage β€” live in docs/maintenance/.

🎯 What This Template Provides

This is a GitHub Template Repository that gives you:

  • βœ… Multi-project support - Run multiple projects in one repository
  • βœ… Project structure with clear separation of concerns
  • βœ… Test-driven development setup with coverage requirements
  • βœ… Automated PDF generation from markdown sources
  • βœ… Opt-in accessible presentation composition with transactional Beamer/Reveal pairs, projection-scale typography, semantic splitting, and fail-closed density diagnostics
  • βœ… Thin orchestrator pattern for maintainable code
  • βœ… Methods orchestration linking pipeline contracts, methods prose, artifacts, and evidence
  • βœ… Executable methods contracts with DAG, script, artifact, and verification validation
  • βœ… Bounded parallel quick testing with isolated project processes and serial oracles
  • βœ… Public exemplar capability inventory covering structure and declared skip reasons
  • βœ… Ready-to-use utilities for any research project
  • βœ… Professional documentation structure (full inventory: docs/documentation-index.md)
  • βœ… Advanced quality analysis and document metrics
  • βœ… Reproducibility tools for scientific workflows
  • βœ… Integrity verification and validation
  • βœ… Publishing tools for academic dissemination
  • βœ… Scientific development best practices
  • βœ… Reporting with error aggregation and performance metrics
  • βœ… Local Ollama workflow documented in infrastructure/llm/README.md and docs/operational/troubleshooting/llm-review.md

πŸ—ΊοΈ Choose Your Path

Pick the entry point that matches your goal:

🧭 Documentation Hub

πŸ“š Documentation Index | πŸ“– Documentation Guide | πŸ” Quick Reference

The template ships with a large documentation corpus under docs/. The hierarchical map (with mermaid diagram) lives in docs/AGENTS.md; the curated long-lived documentation map lives in docs/documentation-index.md. Generated rosters and measured facts remain authoritative for their own scopes; do not rely on a hard-coded file count, which drifts. Top-level layout:

  • docs/core/ β€” essential reading: how-to-use, architecture, workflow
  • docs/guides/ β€” progressive walkthroughs by skill level (1–12)
  • docs/operational/ β€” build, configuration, troubleshooting, performance
  • docs/reference/ β€” FAQ, cheatsheet, common workflows, API reference
  • docs/architecture/ β€” two-layer architecture, thin orchestrator, decision tree
  • docs/usage/ β€” examples, showcase, markdown writing guide
  • docs/modules/ β€” module-by-module guides
  • docs/development/ β€” contributing, testing, roadmap

πŸ€– Agentic operation and SKILLS

Agents should load the smallest applicable workflow before editing. The routing surface is first-class and available via two skill discovery channels:

Hermes / agentskills.io project-local skills

Every canonical exemplar under projects/templates/ now ships its own .agents/skills/<name>/SKILL.md with YAML frontmatter discoverable by Hermes and agentskills.io runtimes. Each skill captures when to use, quick reference (pytest / analysis / render commands), pitfalls, and cross-refs for that template. Load the skill by its name (e.g. template-code-project, template-active-inference) when working inside that exemplar.

Skill Template When to load
template-active-inference template_active_inference Use this template when several independent research tracks must compose into one manuscript whose claims stay consistent where the tracks overlap β€” here: a closed-form analytical oracle, a pymdp simulation harness, a Lean formalization boundary, and shared GNN/ontology notation.
template-advanced-literature-review template_advanced_literature_review Use this template when one review question needs distinct retrieval phases, phase-specific filters, and explicit cross-phase provenance.
template-autoresearch-project template_autoresearch_project Use this template when you need a bounded, offline AutoResearch loop: deterministic ML candidate evaluation over a fixed local dataset, with evidence-linked claims, machine-readable ledgers, artifact-integrity manifests, and deferred human-review gates.
template-autopoiesis template_autopoiesis Use this template when you need to generate runnable project trees deterministically: a child project with analysis.py, primitives/, tests/, and manuscript/, selected by a seed and explicit grammar filters.
template-code-project template_code_project Use this template for code-driven computational research: algorithms in src/, numerical experiments with deterministic seeds, automated publication-quality figures, and a manuscript that reports the computed results.
template-data-descriptor template_data_descriptor Use this template when the contribution is a published dataset or data paper: a schema contract, file inventory, data dictionary, provenance chain, license boundary, quality checks, and machine-readable descriptor must all stay consistent before publication.
template-eda-notebook template_eda_notebook Use this template for exploratory data analysis on tabular data: load a dataset, surface missingness, compute descriptive statistics and per-group means, rank features by correlation, and produce a few diagnostic figures.
template-experiment-tree template_experiment_tree Use template_experiment_tree when the deliverable is a research log that stays honest over months: you want planned, preregistered, and answered experiments in one durable tree, negative results registered (not buried), and a manuscript that regenerates from the tree instead of drifting from it.
template-formal template_formal Use this template when the research subject is the type architecture itself: illegal-state-unrepresentable design, session-typed protocols, affine/linear resource-handle discipline, or a decentralized (no-shared-global-state) multiagent simulation that needs its own local storage and local networking per agent.
template-literature-meta-analysis template_literature_meta_analysis Use it whenever the research object is a body of literature about a topic and you want every reported number to trace to committed, regenerable artifacts.
template-madlib template_madlib Use this template when you need configuration-driven manuscript generation with auditable token provenance, conditional section structure, explicit/default field visibility, failure-boundary reporting, and a reviewer-visible authoring contract: lexicon categories, section titles, narrative moves, method steps, design principles, pipeline phases, evaluation criteria, QA probes, failure modes, authoring obligations, visualization controls, audit rules, and slots are declared in YAML; src/ deterministically expands those declarations; and the manuscript receives large-grain {{TOKEN}} bodies only after the source code has generated the supporting artifacts.
template-newspaper template_newspaper Use this template when you need data-driven, large-format print layout: multi-page broadsheets/tabloids with precise column geometry, typography-first constraints, and strict content/engine separation (YAML editions in content/, pure-Python ReportLab engine in src/).
template-pools-rules-tools template_pools_rules_tools Use this project when you need to: - Demonstrate how a research project integrates multiple resource directories (fonds, tools, rules) in a single pipeline - Validate that your fonds, tools, and rule infrastructure modules are correctly wired and discoverable - Onboard new teams to the three-resource architecture with a concrete, runnable example - Test cross-cutting concern integration where fonds supply data, rules govern validation, and tools execute transforms - Extend the architecture by adding new resource types; copy this project as a starting point for integration testing This template is ideal for platform teams, CI engineers, and infrastructure maintainers who need a self-validating meta-project that exercises all three resource layers without coupling to a specific domain science.
template-prose-project template_prose_project Use this template for manuscript-focused editorial pipelines: readability gates (Flesch-Kincaid bands), structural checking, citation/BibTeX validation, and prose-quality review workflows where the document itself is the artifact under test.
template-autoscientists template_autoscientists Use this template when you need to isolate and measure agent-coordination mechanisms: coordinated teams vs single-thread baselines under matched budgets, deterministic ablation studies, and honest per-mechanism effect reporting (including nulls).
template-gold-refinement template_gold_refinement Use this template for analogical manuscript composition research: projects that map a scientific domain onto a refinement pipeline and generate the manuscript through deterministic mega-madlib token injection.
template-methods-paper template_methods_paper Use this template when the paper you are writing describes a methodology rather than reports results: a procedure, protocol, or specification language, where the contribution is the controlled vocabulary and its guarantees (dimensional safety, staged validation, deterministic compilation) rather than a numeric outcome.
template-redacted-report template_redacted_report Use this template when a report needs formal redaction before release: classification ceilings, source-control markings, redaction decisions, authority review, reviewer approvals, source-safe hash ledgers, residual-risk checks, mosaic-risk checks, and a public audit packet must be validated before any sanitized narrative is published.
template-registered-report template_registered_report Use this template when the core method is a registered report or preregistered replication: hypotheses, outcomes, exclusion rules, analysis plan, power or sensitivity rationale, deviation ledger, and confirmatory-versus-exploratory claim boundaries must be locked before results are interpreted.
template-search-project template_search_project Use this template for literature-review and evidence-synthesis pipelines: multi-backend search (arXiv, Crossref, local corpora, optional Paperclip), deduplication, BibTeX generation, and LLM-assisted per-paper and corpus-level synthesis.
template-sia template_sia Use this template when you need a self-improvement-agent evaluation harness: Meta β†’ Target β†’ Feedback generation loops, public/private task splits to detect overfitting, deterministic fixture replay for testability, and fail-closed loop validation.
template-storybook template_storybook Use this template when you need full-page illustrated PDF storytelling: picture-book pages, symbolic scenes, character-generation methods, page-level orchestrators, and deterministic raster art assembled into a print-ready PDF.
template-template template_template Use this template when your research subject is the repository itself β€” programmatic introspection of architecture, pipeline DAGs, module inventories, and security layers, rendered as a manuscript whose every metric is computed live (autopoietic: the paper regenerates itself from the code it describes).
template-textbook template_textbook Use this template for book-length manuscripts: units β†’ chapters β†’ labs β†’ question banks declared in a single config.yaml, with auto-numbering, deterministic figure/diagram generation, and structural-contract tests that keep hundreds of pages from drifting.
template-pitch-deck template_pitch_deck Use this template when you need a pitch, grant report, or recurring stakeholder update treated as a build artifact β€” bound to live repository facts, validated for unresolved tokens and pitch-deck clichΓ©, and regenerable byte-for-byte from source rather than hand-maintained in a proprietary slide tool.

Generated infrastructure skills

In addition to the project-local skills, the repo generates infrastructure-level SKILL.md files from live discovery:

  • Shared context-engineering skills: .agents/skills/ carries a pinned, provenance-checked Agent Skills collection discoverable by Codex/OpenAI and Hermes-compatible runtimes. Use uv run python -m infrastructure.skills runtime-status to audit Codex, Claude Code, and Hermes parity, or ... runtime-install to create reversible user-level links from the pinned shared store.
  • Workflow router: docs/prompts/SKILL.md (template-workflows) routes broad requests such as full audits, pipeline debugging, code changes, tests, validation, manuscript work, and release checks to exactly one child workflow.
  • Agentic-use hardening: docs/prompts/agentic-use/SKILL.md covers skill inventory, routing checks, .agents/skill_manifest.json, and generated skill-index maintenance.
  • Infrastructure module skills: infrastructure/SKILL.md is the Layer-1 hub; pair the relevant infrastructure/<module>/SKILL.md with that module's AGENTS.md before editing code.
  • Script and resource-pool skills: scripts/*/SKILL.md files and public fonds/templates/, rules/templates/, and tools/templates/ skills are included when present, without scanning private lifecycle roots.
  • Human skill index: docs/_generated/skills_index.md lists all discovered skills. Regenerate after skill changes with uv run python -m infrastructure.skills write-index; refresh the editor manifest with uv run python -m infrastructure.skills write; verify both with uv run python -m infrastructure.skills check and uv run python -m infrastructure.skills check-contracts. The same inventory is returned by the opt-in stdio MCP server's list_skills tool via uv run python -m infrastructure.mcp_server.

πŸ”€ Multi-Project Support

The repo can host multiple research projects in parallel. Each project owns its own src/, tests/, manuscript/, scripts/, and output/ directory under projects/<name>/. Layer-1 infrastructure is shared.

Permanent canonical exemplars β€” always present and tracked in git:

Exemplar When to use
template_active_inference Use this template when several independent research tracks must compose into one manuscript whose claims stay consistent where the tracks overlap β€” here: a closed-form analytical oracle, a pymdp simulation harness, a Lean formalization boundary, and shared GNN/ontology notation.
template_advanced_literature_review Use this template when one review question needs distinct retrieval phases, phase-specific filters, and explicit cross-phase provenance.
template_autoresearch_project Use this template when you need a bounded, offline AutoResearch loop: deterministic ML candidate evaluation over a fixed local dataset, with evidence-linked claims, machine-readable ledgers, artifact-integrity manifests, and deferred human-review gates.
template_autopoiesis Use this template when you need to generate runnable project trees deterministically: a child project with analysis.py, primitives/, tests/, and manuscript/, selected by a seed and explicit grammar filters.
template_code_project Use this template for code-driven computational research: algorithms in src/, numerical experiments with deterministic seeds, automated publication-quality figures, and a manuscript that reports the computed results.
template_data_descriptor Use this template when the contribution is a published dataset or data paper: a schema contract, file inventory, data dictionary, provenance chain, license boundary, quality checks, and machine-readable descriptor must all stay consistent before publication.
template_eda_notebook Use this template for exploratory data analysis on tabular data: load a dataset, surface missingness, compute descriptive statistics and per-group means, rank features by correlation, and produce a few diagnostic figures.
template_experiment_tree Use template_experiment_tree when the deliverable is a research log that stays honest over months: you want planned, preregistered, and answered experiments in one durable tree, negative results registered (not buried), and a manuscript that regenerates from the tree instead of drifting from it.
template_formal Use this template when the research subject is the type architecture itself: illegal-state-unrepresentable design, session-typed protocols, affine/linear resource-handle discipline, or a decentralized (no-shared-global-state) multiagent simulation that needs its own local storage and local networking per agent.
template_literature_meta_analysis Use it whenever the research object is a body of literature about a topic and you want every reported number to trace to committed, regenerable artifacts.
template_madlib Use this template when you need configuration-driven manuscript generation with auditable token provenance, conditional section structure, explicit/default field visibility, failure-boundary reporting, and a reviewer-visible authoring contract: lexicon categories, section titles, narrative moves, method steps, design principles, pipeline phases, evaluation criteria, QA probes, failure modes, authoring obligations, visualization controls, audit rules, and slots are declared in YAML; src/ deterministically expands those declarations; and the manuscript receives large-grain {{TOKEN}} bodies only after the source code has generated the supporting artifacts.
template_newspaper Use this template when you need data-driven, large-format print layout: multi-page broadsheets/tabloids with precise column geometry, typography-first constraints, and strict content/engine separation (YAML editions in content/, pure-Python ReportLab engine in src/).
template_pools_rules_tools Use this project when you need to: - Demonstrate how a research project integrates multiple resource directories (fonds, tools, rules) in a single pipeline - Validate that your fonds, tools, and rule infrastructure modules are correctly wired and discoverable - Onboard new teams to the three-resource architecture with a concrete, runnable example - Test cross-cutting concern integration where fonds supply data, rules govern validation, and tools execute transforms - Extend the architecture by adding new resource types; copy this project as a starting point for integration testing This template is ideal for platform teams, CI engineers, and infrastructure maintainers who need a self-validating meta-project that exercises all three resource layers without coupling to a specific domain science.
template_prose_project Use this template for manuscript-focused editorial pipelines: readability gates (Flesch-Kincaid bands), structural checking, citation/BibTeX validation, and prose-quality review workflows where the document itself is the artifact under test.
template_autoscientists Use this template when you need to isolate and measure agent-coordination mechanisms: coordinated teams vs single-thread baselines under matched budgets, deterministic ablation studies, and honest per-mechanism effect reporting (including nulls).
template_gold_refinement Use this template for analogical manuscript composition research: projects that map a scientific domain onto a refinement pipeline and generate the manuscript through deterministic mega-madlib token injection.
template_methods_paper Use this template when the paper you are writing describes a methodology rather than reports results: a procedure, protocol, or specification language, where the contribution is the controlled vocabulary and its guarantees (dimensional safety, staged validation, deterministic compilation) rather than a numeric outcome.
template_redacted_report Use this template when a report needs formal redaction before release: classification ceilings, source-control markings, redaction decisions, authority review, reviewer approvals, source-safe hash ledgers, residual-risk checks, mosaic-risk checks, and a public audit packet must be validated before any sanitized narrative is published.
template_registered_report Use this template when the core method is a registered report or preregistered replication: hypotheses, outcomes, exclusion rules, analysis plan, power or sensitivity rationale, deviation ledger, and confirmatory-versus-exploratory claim boundaries must be locked before results are interpreted.
template_search_project Use this template for literature-review and evidence-synthesis pipelines: multi-backend search (arXiv, Crossref, local corpora, optional Paperclip), deduplication, BibTeX generation, and LLM-assisted per-paper and corpus-level synthesis.
template_sia Use this template when you need a self-improvement-agent evaluation harness: Meta β†’ Target β†’ Feedback generation loops, public/private task splits to detect overfitting, deterministic fixture replay for testability, and fail-closed loop validation.
template_storybook Use this template when you need full-page illustrated PDF storytelling: picture-book pages, symbolic scenes, character-generation methods, page-level orchestrators, and deterministic raster art assembled into a print-ready PDF.
template_template Use this template when your research subject is the repository itself β€” programmatic introspection of architecture, pipeline DAGs, module inventories, and security layers, rendered as a manuscript whose every metric is computed live (autopoietic: the paper regenerates itself from the code it describes).
template_textbook Use this template for book-length manuscripts: units β†’ chapters β†’ labs β†’ question banks declared in a single config.yaml, with auto-numbering, deterministic figure/diagram generation, and structural-contract tests that keep hundreds of pages from drifting.
template_pitch_deck Use this template when you need a pitch, grant report, or recurring stakeholder update treated as a build artifact β€” bound to live repository facts, validated for unresolved tokens and pitch-deck clichΓ©, and regenerable byte-for-byte from source rather than hand-maintained in a proprietary slide tool.

Test and coverage figures are representative; confirm against docs/_generated/COUNTS.md after substantive changes.

Choosing an exemplar: every exemplar README opens with a ## When to use this template section, and the generated differentiation map in docs/_generated/exemplar_roster.md collects them into one "copy THIS when…" table (regenerate with uv run python scripts/docgen/exemplar_roster.py; sync is test-enforced).

The permanent exemplars share the same core layout and verification checklist. The code/prose exemplars also carry the 12-file project docs/ hub (agent_instructions.md, style_guide.md, syntax_guide.md, testing_philosophy.md, rendering_pipeline.md, faq.md, quickstart.md, output_conventions.md, troubleshooting.md, architecture.md, AGENTS.md, README.md). New projects copy whichever exemplar is closest in shape and adjust from there. See projects/AGENTS.md for the full comparison.

Publication metadata for every public exemplar is generated from project config and sidecars into docs/_generated/publication_records.md, and the GitHub-facing table in .github/GITHUB.md is auto-injected from that same source. To publish a project modularly, start with the Publication runbook: it covers the standalone public GitHub mirror, first real Zenodo DOI, new-version releases, optional mirrors, status blocks, and archival handoff.

Public Exemplar Outputs And Mirrors

Every canonical exemplar under projects/templates/ is tracked in this monorepo, including its project-local output/ tree. The copied release artifacts under output/templates/<name>/ are tracked as well, so a clone of docxology/template contains both the source and the latest rendered public artifacts. Public output files above 50 MB remain excluded by the generated-artifact guard; private or rotating project outputs remain blocked.

Where declared, an exemplar has a standalone docxology/template_* GitHub repository and Zenodo concept/version records. The current declaration and verification state is the generated matrix in docs/_generated/publication_records.md; unverified or n/a fields are not publication evidence. The standalone repository must exist before scripts/publish/publish_project_release.py can create a release there; the release script publishes the GitHub release asset and Zenodo deposit, but it does not create the repository itself. To regenerate any exemplar from the monorepo:

git clone https://github.com/docxology/template
cd template
uv sync --locked
./run.sh --project templates/template_code_project --pipeline --mode core

Replace template_code_project with any public exemplar name from the table above. The standalone repositories are publication mirrors; use this monorepo when you need the shared infrastructure, full render pipeline, or cross-template validation.

The canonical exemplars also ship project-local composability overlays: domain_profile.yaml declares review gates, source policy, artifact expectations, and benchmark rubric preferences; experiment_plan.yaml declares design-validation conditions, primary metric direction, expected figures/tables, baselines, and ablations. These files are declarative inputs for validation and benchmark tooling; they do not generate experiments or run autonomous agents.

πŸ”’ Confidentiality. This is a public template repo. Only the canonical exemplars above (under projects/templates/) are git-tracked/pushed β€” .gitignore ignores projects/* and negates only projects/templates/. Any other project you add under projects/ (research, client, or confidential work) stays local-only and is never committed; scripts/audit/check_tracked_all.py blocks any accidental commit in the pre-push hook and CI.

Private lifecycle projects. In Daniel's working checkout, confidential projects live outside this public repo at $TEMPLATE_PRIVATE_PROJECTS_ROOT. The simplified sidecar uses working/ and archive/; optional ongoing/ (long-lived projects with no publication target) and optional active/ hot-seat folders support explicit work and default rendering. run.sh and python -m infrastructure.orchestration auto-sync existing folders into matching typed subfolders under projects/: working/* into projects/working/*, ongoing/* into projects/ongoing/*, archive/* into projects/archive/*, and optional active/* into projects/active/*. templates/ and optional active/ links behave like native rendered entries; working/, ongoing/, and archive/ links are visible for explicit targeted work but are not default-rendered. Inspect without changing the tree: uv run python -m infrastructure.orchestration link-projects --dry-run. Override the sibling path with TEMPLATE_PRIVATE_PROJECTS_ROOT or .private_projects_root; disable auto-sync with TEMPLATE_SKIP_LINK_SYNC=1. The symlinked project keeps working outputs at projects/<subfolder>/<name>/output/ (the private target), while final deliverables still copy to output/<subfolder>/<name>/ in this template checkout.

Other entries rotate between projects/working/ and projects/archive/ as work progresses. Never hard-code their paths in long-lived docs β€” consult docs/_generated/active_projects.md (authoritative public scope, regenerated from infrastructure.project.public_scope) and docs/_generated/COUNTS.md instead.

Common commands:

./run.sh                                     # Interactive project selection
./run.sh --project templates/template_code_project --pipeline --mode core
./run.sh --all-projects --pipeline           # All discovered projects sequentially
./secure_run.sh --steganography-only --project templates/template_code_project  # Re-watermark PDFs
# Create a runnable fork with the clean-copy helper; see "Forking an exemplar" below.

Lifecycle: rendered = projects/templates/ plus optional projects/active/ (discovered, executed). The simplified private sidecar normally uses working/ and archive/ (plus optional ongoing/ for long-lived work with no publication target); render sidecar projects explicitly with a qualified name such as working/{name} or ongoing/{name}. See projects/PROJECTS_PARADIGM.md for lifecycle, slug rules, and discovery semantics.

Checkout preparation and dispatch

Use the Quickstart for the clone-to-PDF flow and the startup and setup guide for explicit locked runtime and system-tool preparation. Ordinary ./run.sh --pipeline does not install uv, reconcile dependencies, or fall back from a broken selected runtime; RUN_GUIDE owns prepared dispatch and runtime selection. For headless deployment, see docs/CLOUD_DEPLOY.md. Beginner walkthrough: docs/guides/getting-started.md. One-page command reference: docs/reference/quick-start-cheatsheet.md. Twelve-level usage guide: docs/core/how-to-use.md.

System Status

Current state is captured in docs/_generated/COUNTS.md (updated from discovery, test runs, and CI configuration).

Key elements:

  • Active projects listed via discover_projects()
  • Coverage enforced at 60% (infrastructure) and 90% (projects)
  • Tests run with real data and computations
  • Commands standardized to uv run
  • Outputs organized per project under output/{name}/

See docs/_generated/COUNTS.md and docs/development/testing/testing-guide.md for details.

πŸŽ“ Skill-Based Learning Paths

Twelve progressive levels β€” Document Creation (1–3), Figures & Automation (4–6), Test-Driven Development (7–9), System Architecture (10–12) β€” are documented end-to-end in docs/core/how-to-use.md. Per-band walkthroughs: docs/guides/getting-started.md, docs/guides/figures-and-analysis.md, docs/guides/testing-and-reproducibility.md, docs/guides/extending-and-automation.md.

πŸ—οΈ Project Structure

Two-layer architecture:

  • Layer 1 β€” infrastructure/ (generic, reusable): build, validation, rendering, LLM, publishing, etc. Plus scripts/ (entry-point orchestrators) and tests/ (infrastructure tests, β‰₯60 % coverage).
  • Layer 2 β€” projects/<name>/ (project-specific, customizable): src/ (algorithms, β‰₯90 % coverage), tests/, scripts/ (thin orchestrators), manuscript/ (markdown sections + config.yaml).
  • Output is generated under each exemplar's project-local projects/templates/<name>/output/ tree. Final deterministic evidence (publication PDFs, figures, analysis data, hydrated manuscripts, and release/validation registries) may be tracked for public exemplars; checkpoints, logs, telemetry, pipeline snapshots, and LaTeX/slide build intermediates are disposable, ignored, and regeneratable.
  • Docs live under docs/ (full hierarchy in docs/AGENTS.md); per-directory AGENTS.md files document every leaf.

System Architecture Overview

A short summary lives here; full architecture diagrams (system overview, module-dependency graph, per-stage data flow, configuration-system flow) are maintained in AGENTS.md and docs/core/architecture.md. In short:

  • Entry points: ./run.sh (interactive or --pipeline) and uv run python scripts/runner/execute_pipeline.py --project <name> [--mode core]; numbered orchestrators under scripts/pipeline/ run stage_00_setup.py through stage_13_docxplus.py (setup β†’ copy, LLM, executive report, metadata, ebook, docxplus β€” see scripts/AGENTS.md).
  • Orchestration: the pipeline runs Setup β†’ Tests β†’ Analysis β†’ Render β†’ Validate β†’ Copy, with optional LLM Review and LLM Translations stages.
  • Core systems: importable infrastructure/ packages (Layer 1; live list in docs/_generated/COUNTS.md) plus per-project projects/{name}/src/ algorithms (Layer 2); see docs/_generated/COUNTS.md for the live module list.
  • Data flow: project source + manuscript markdown + config.yaml flow through the pipeline into output/<name>/{pdf,figures,data,reports}/.
  • Quality assurance: infra β‰₯60 % and project β‰₯90 % coverage gates, no-mocks policy, deterministic seeds, real PDF/markdown validation.
  • Configuration: projects/{name}/manuscript/config.yaml plus environment overrides feed PDF metadata, LaTeX preamble, figure labels, and validation rules.

Directory Overview with Documentation Links:

Directory Purpose Documentation
infrastructure/ Generic build/validation tools (Layer 1) infrastructure/AGENTS.md
scripts/ Entry point orchestrators scripts/AGENTS.md
tests/ Infrastructure test suite tests/AGENTS.md
projects/{name}/src/ Project-specific scientific code (Layer 2) Per-project AGENTS.md
projects/{name}/tests/ Project test suite Per-project AGENTS.md
docs/ Documentation hub docs/documentation-index.md
projects/{name}/manuscript/ Research manuscript sections Per-project AGENTS.md
output/ Generated public evidence plus local build output Final evidence is tracked selectively; runtime residue is ignored

πŸ“š Explore Documentation: See docs/documentation-index.md for documentation structure

πŸ”‘ Key Architectural Principles

The repository follows a thin orchestrator pattern: business logic lives only in infrastructure/ and projects/{name}/src/; scripts coordinate, never implement. Tests prohibit mock frameworks and prefer real execution; remaining pytest.monkeypatch dependency replacements are explicitly inventoried rather than treated as proof of a mock-free suite. Coverage gates remain strict. Full narrative + benefits: docs/architecture/thin-orchestrator-summary.md, docs/core/architecture.md.

✨ Key Features

πŸ“¦ Optional export: docxplus

An opt-in stage exports a project as a conforming .docx (and .docxplus, the same bytes under a name that says so) which also carries the project's own source tree in a signed manifest. Word, LibreOffice, and Google Docs open it as an ordinary document; docxplus recovers the repository from inside it.

uv sync --extra docxplus
uv run python scripts/pipeline/stage_13_docxplus.py --project templates/template_code_project

The container format is imported from upstream (docxology/docxplus, pinned to a released tag) rather than vendored: this repository stays the rendering engine, and the specification stays the container project's business. The stage is excluded from default runs by its docxplus tag and skips cleanly when the extra is absent, so nobody who does not want it pays for it.

πŸ”’ Security & Monitoring

LLM input sanitization (infrastructure.llm.core.sanitization), security validators (infrastructure.core.security), runtime health checks (infrastructure.core.runtime.health_check), rate limiting, and HTTP security headers. Full surface and worked usage examples: docs/development/security.md.

πŸ› οΈ Installation & Setup

Installed SDK

Use an existing Python 3.14+ environment and an actual matching SDK wheel. Set SDK_PYTHON to that environment's interpreter and SDK_WHEEL to the wheel's local path; an intended version is not evidence that a download or package-index release exists.

uv pip install --python "$SDK_PYTHON" "$SDK_WHEEL"
"$(dirname "$SDK_PYTHON")/research-template" --help

The wheel contains the infrastructure SDK and its research-template entry point, not the exemplar trees or repository scripts/. The pipeline needs a real project and its declared script targets; use a checkout to author the canonical examples. Optional package extras, such as research-project-template[rendering,publishing], are distinct from checkout development groups.

Checkout author

Run uv sync --locked from the repository root to prepare .venv/ from pyproject.toml, uv.lock and .python-version. The supported CI minors are 3.14 and 3.15; the local default is 3.14. Already-prepared dispatch and explicit runtime nomination are documented in docs/RUN_GUIDE.md.

Pandoc and TeX are rendering prerequisites, not prerequisites for importing the SDK. Follow the canonical startup and setup guide for system tools, the first selected core pipeline, and optional contributor checks. It also documents scripts/shell/setup-system-deps.sh; --check observes preparation without installing. To generate a manuscript, continue with the Quickstart.

🐳 Docker Support

docker-compose up (or docker build -t research-template . && docker run -it research-template) builds a reproducible image with pandoc, TeX, Ollama LLM server support, persistent model/output volumes, and hot-reload. See Dockerfile and docker-compose.yml.

πŸ”§ Customization

Project Metadata Configuration

Two configuration paths exist: edit projects/{name}/manuscript/config.yaml (recommended) or export AUTHOR_NAME / AUTHOR_ORCID / AUTHOR_EMAIL / PROJECT_TITLE / DOI environment variables (env vars override the YAML file). The YAML schema (paper title, authors with ORCID, publication DOI, keywords, optional LLM translations block) and a worked example are documented once in CLAUDE.md and AGENTS.md; both files also list every available field. See projects/{name}/manuscript/config.yaml.example for the full template. Applied configuration drives PDF metadata, LaTeX document properties (see docs/reference/copypasta.md for preamble examples), generated file headers, and cross-reference systems.

Forking an exemplar

Use the canonical fork guide for the clean-copy helper, new project/author identity, SDK source selection and preparation of the fork's own environment. It also explains the source-bound .template-export.json manifest and the difference between checkout-local and independent exported use. Raw directory creation or copying is not an equivalent runnable-project setup.

Adding Project-Specific Scripts

Place Python scripts under projects/{name}/scripts/. They must follow the thin orchestrator pattern: import computation from projects/{name}/src/ or infrastructure/, handle only I/O / visualization / orchestration, print output paths to stdout for manifest collection, and never implement algorithms inline. Worked examples and the full pattern walkthrough live in scripts/AGENTS.md and docs/architecture/thin-orchestrator-summary.md.

Manuscript Structure

Per-project manuscript files live in projects/{name}/manuscript/: config.yaml, preamble.md, zero-padded numbered chapter files (00_abstract.md onward), optional S01_*.md supplements, and 99_references.md. Exact chapter slugs vary per project β€” the canonical exemplar is projects/templates/template_code_project/manuscript/; the numbering system and slug rules are authoritative in docs/usage/manuscript-numbering-system.md.

πŸ“Š Testing

Fast local lane first: uv run --no-sync python scripts/gates/local_gate.py format lint types runs the same commands as the Lint & Type Check job, and --changed narrows them to your working-tree files. gates, security, unit and infra cover the remaining hosted lanes; --list prints the exact argv.

TDD with strict coverage gates: infrastructure β‰₯ 60 %, projects β‰₯ 90 %. No unit-level mock frameworks β€” tests use real data, real files; HTTP boundaries use pytest-httpserver (in-process test server). The project pipeline runs a focused pipeline-smoke infrastructure contract plus the selected project's declared test profile; its default quick selection is not the whole release/native matrix. Run the full infrastructure gate explicitly with uv run python scripts/pipeline/stage_01_test.py --infra-only --infra-scope full; run a project suite with uv run python scripts/pipeline/stage_01_test.py --project-only --project <name>. Per-suite commands and coverage report flags are documented in tests/AGENTS.md and docs/development/testing/testing-guide.md; live coverage / test counts live in docs/_generated/COUNTS.md.

Output

Public exemplars retain deterministic deliverables and evidence under both projects/templates/<name>/output/ and the copied output/templates/<name>/ surface. These are retained publication evidence, not blanket-disposable trees. Runtime state (.checkpoints/, .pipeline/, logs/, telemetry, snapshots) and renderer intermediates remain local-only under the tracking policy. Preserve retained public evidence before regeneration or cleanup; do not blanket-delete either output tree. Private project outputs remain local-only. See Public Exemplar Outputs And Mirrors.

πŸ” How It Works

Two entry points β€” ./run.sh (interactive or --pipeline) and uv run python scripts/runner/execute_pipeline.py --project <name> [--mode core].

The default pipeline.yaml declares 17 named stages (indices 0–16). Default --mode core runs execute 8 stages; explicit --mode live executes 10 selected core and live stages. Opt-in tags (archival, bundle, docxplus, ebook, metadata, provenance, science) stay out of these selections unless a stage is invoked directly. YAML stage indices do not match stage_NN_*.py prefixes.

Stage Script Tags Failure mode
0 Clean Output Directories built-in _run_clean_outputs core, clean failure prevents completion
1 Environment Setup scripts/pipeline/stage_00_setup.py core hard fail
2 Infrastructure Tests scripts/pipeline/stage_01_test.py --infra-only --verbose --infra-scope pipeline-smoke core, tests required tests and coverage must pass
3 Project Tests scripts/pipeline/stage_01_test.py --project-only --verbose core, tests required nonempty tests, project-local coverage, verifier evidence, and runner success must pass
4 Project Analysis scripts/pipeline/stage_02_analysis.py core hard fail
5 Connector Search scripts/pipeline/stage_08_connector_search.py science, live absent configuration requires a fresh policy-bound skip receipt
6 Provenance Record scripts/pipeline/stage_09_provenance_record.py --stage Connector Search provenance absent configuration requires a fresh policy-bound skip receipt
7 PDF Rendering scripts/pipeline/stage_03_render.py core hard fail
8 Output Validation scripts/pipeline/stage_04_validate.py core enabled-format, enabled-PDF bookend, and artifact/provenance failures block; markdown, general output structure, and prose-quality checks remain advisory
9 LLM Manuscript Review scripts/pipeline/stage_06_llm_review.py --reviews-only llm, live fresh policy-bound skip; unavailable required live acceptance is blocked
10 LLM Translations scripts/pipeline/stage_06_llm_review.py --translations-only llm, live fresh policy-bound skip; unavailable required live acceptance is blocked
11 Copy Outputs scripts/pipeline/stage_05_copy.py core failure prevents completion
12 Ebook Generation scripts/pipeline/stage_11_ebook.py core, ebook failure prevents completion
13 docxplus Export scripts/pipeline/stage_13_docxplus.py core, docxplus failure prevents completion
14 Metadata Package scripts/pipeline/stage_12_metadata.py core, metadata failure prevents completion
15 Executable Bundle scripts/runner/bundle_executable.py bundle failure prevents completion
16 Archival Publication scripts/runner/archive_publication.py archival, live failure prevents completion

Full per-stage flowchart, failure/skip transitions, and the script-to-stage mapping for --mode core live in AGENTS.md and docs/RUN_GUIDE.md. Workflow narrative: docs/core/workflow.md. Architecture narrative: docs/core/architecture.md.

πŸ“š Documentation Index

The curated documentation map lives in docs/documentation-index.md. It is a maintained map, not an exhaustive per-file inventory; generated counts and roster facts remain source-bound. Top-level entry points:

🀝 Contributing

contribution guide | Code of conduct | Roadmap

We welcome contributions! To contribute:

  1. Ensure all tests pass with coverage requirements met - Testing Guide
  2. Follow the established project structure - Architecture
  3. Add tests for new functionality - Workflow
  4. Update documentation as needed - Documentation Guide
  5. Maintain thin orchestrator pattern - scripts use src/ methods - Pattern Guide

Recent Improvements:

  • Build system optimizations - Performance Optimization
  • Test suite enhancements
  • Simplified directory structure with markdown/ elimination

πŸ“„ License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

πŸ“š Citation

The machine-readable CITATION.cff is the single source of truth (GitHub's "Cite this repository" widget reads it). If you use this template in your research, please cite:

DOI

Use the citation metadata attached to the actual released version you consume. The concept DOI recorded here is metadata, not proof that a prepared version or its assets are available from Zenodo; verify the actual release and archival records through the publication runbook.

BibTeX:

@software{friedman_template_2026,
  author    = {Daniel Ari Friedman},
  title     = {A template/ approach to Reproducible Generative Research:
               Architecture and Ergonomics from Configuration through Publication},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.19139090},
  url       = {https://doi.org/10.5281/zenodo.19139090}
}

Plain text: Daniel Ari Friedman. (2026). A template/ approach to Reproducible Generative Research: Architecture and Ergonomics from Configuration through Publication. Zenodo. https://doi.org/10.5281/zenodo.19139090

πŸ†˜ Troubleshooting

Common issue catalog β€” failing tests, missing pandoc/xelatex, PDF quality, LLM unavailability β€” lives in docs/operational/troubleshooting/README.md and docs/reference/faq.md. Pipeline entry points and flags: docs/RUN_GUIDE.md. PDF validator: docs/modules/pdf-validation.md.

πŸ”„ Migration from Other Projects

To adapt this template: copy infrastructure/ and scripts/, mirror the projects/{name}/{src,tests,scripts,manuscript}/ layout, adopt config.yaml (see AGENTS.md), and validate by running the pipeline. Worked examples: docs/usage/examples.md, docs/best-practices/migration-guide.md.

πŸ—οΈ Architecture Benefits

Thin orchestrator pattern delivers single-source-of-truth business logic, high testability (β‰₯90 % project coverage), reusability across projects, and CI-gated quality. Full benefits + rationale: docs/core/architecture.md.


Quick Navigation by Task

Task Start here
Assistants / editors .agents/AGENTS.md, AGENTS.md, CLAUDE.md
Write documents docs/guides/getting-started.md, docs/usage/markdown-template-guide.md
Add figures docs/guides/figures-and-analysis.md, docs/usage/visualization-guide.md
Fix issues docs/operational/troubleshooting/README.md, docs/reference/faq.md
Understand architecture docs/core/architecture.md, docs/architecture/two-layer-architecture.md
Configure system docs/operational/config/configuration.md, AGENTS.md
Run pipeline docs/RUN_GUIDE.md
Contribute code docs/development/contributing.md, docs/rules/AGENTS.md
Find all docs docs/documentation-index.md
Check the backlog TO-DO.md
See what changed CHANGELOG.md

πŸŽ‰ Get Started Now

Ready to begin? Choose your path:

  1. New User? β†’ Start with Quickstart or docs/guides/getting-started.md
  2. Developer? β†’ Read docs/core/architecture.md and docs/core/workflow.md
  3. Need Help? β†’ Check docs/reference/faq.md or docs/operational/troubleshooting/README.md
  4. Explore All Docs? β†’ Browse docs/documentation-index.md

πŸ“š Documentation Hub: All documentation is organized in the docs/ directory with guides for every aspect of the template.

About

Reproducible research publishing template for Python research projects: a declared pipeline, canonical exemplars, and multi-format outputs.

Topics

Resources

Contributing

Security policy

Accessibility

Stars

24 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages