convez.ai
SkillDevOps & InfraestruturaAvançado
docxology

Template para Pesquisa Computacional Reproduzível

docxology/template

Scaffold production-grade para pesquisa reproduzível com pipelines, proveniência criptográfica e suporte a agentes IA

Ver no GitHub
BomPluginScore · de 0 a 100

Scaffold de produção para pesquisa computacional com pipelines DAG de 10 estágios, cobertura de testes ≥90%, proveniência criptográfica (SHA-256 + watermarking esteganográfico em PDF) e workspace multi-projeto. Pronto para agentes de IA com documentação AGENTS.md/SKILL.md integrada.

Instalação

$npx convez-ai docxology/template

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
24
Forks
1
Acompanhando
0
Saúde
85%
Último commit
há 1 dia
Versão
v5.0.0
Issues abertas
2
Contribuidores
3

Casos de uso

  • Configurar pipelines de pesquisa computacional com rastreabilidade criptográfica
  • Colaborar com agentes IA em projetos de pesquisa com documentação estruturada
  • Garantir reprodutibilidade e integridade de artefatos científicos via steganografia

Veredito

Ferramenta robusta e bem documentada para pesquisadores que precisam de pipelines production-grade com garantias de proveniência. Exige expertise em Python e DevOps, mas oferece valor inegável em reprodutibilidade científica e automação com agentes IA.

README

A tradução para o português deste README ainda está na fila.

🔬 Research Project Template

Production-grade scaffold for reproducible computational research Pipelines · Manuscripts · Cryptographic Provenance · AI-Agent Collaboration

CI Python 3.10+ uv Ruff License: Apache 2.0 Version DOI

📄 Published: A template/ approach to Reproducible Generative Research: Architecture and Ergonomics from Configuration through Publication — DOI: 10.5281/zenodo.19139090

🧭 Choose path · 🤖 Agents · ⚡ Quick Start · 📐 Architecture · 🔄 Pipeline · 🔒 Provenance · 📚 Docs · 🔧 CI/CD


Table of contents

SectionAudience
About this documentEveryone — scope of this README vs root README.md
Choose your pathHumans — goal-based deep links
Agent & automation entry pointCursor, Claude Code, Codex, CI bots — read order, skills, commands
Quick StartFirst clone → first pipeline run
ArchitectureTwo-layer layout, directories, lifecycle
Active projectsExemplars and rotating roster
PipelineStage DAG, scripts, flags
AI collaborationAGENTS.md / SKILL.md conventions
Security & provenanceSteganography, hashing, secure_run.sh
Testing standardsNo-mocks policy, coverage floors
Documentation hubFull docs/ map with deep links
CI/CDWorkflows, jobs, local parity, branch protection
Issue & PR templatesContributing on GitHub
Troubleshootinggh CLI, common fixes

About this document

This file lives under .github/ but serves as the primary GitHub-rendered entry point for the repository: badges, architecture diagrams, pipeline reference, documentation map, and CI inventory — optimized for browsing on github.com and for agents that land here first.

DocumentUse
This fileHuman + agent overview on GitHub (you are here)
AGENTS.mdCI job ids, display names, thresholds, local parity commands
workflows/README.md · workflows/AGENTS.mdStep-level CI detail
ISSUE_TEMPLATE/README.mdIssue template inventory
../README.mdClone-first quickstart and honest positioning
../AGENTS.mdFull system manual (pipeline semantics, modules, troubleshooting index)
../CLAUDE.mdCopy-paste command cheat sheet
.cursorrulesCursor agent constraints (architecture, CI scope)

Ground truth (do not hard-code rotating names or counts): docs/_generated/active_projects.md · docs/_generated/canonical_facts.md · STATUS.md · docs/documentation-index.md

Skills manifest: .cursor/skill_manifest.json — regenerate after editing any **/SKILL.md with uv run python -m infrastructure.skills write (human index: docs/_generated/skills_index.md).


Choose your path

Pick the entry that matches your goal — each link is stable for deep navigation from issues, PRs, and agent transcripts.

GoalStart hereThen
Clone and runQuick Startdocs/RUN_GUIDE.md · docs/guides/getting-started.md
Add a research projectdocs/guides/new-project-setup.mdStart from the closest public exemplar; authoritative roster: docs/_generated/active_projects.md. Common starting points: template_active_inference, template_autoresearch_project, template_code_project, template_prose_project, template_sia, or template_template
Debug a failed pipeline stagedocs/prompts/pipeline-debugging/SKILL.mddocs/operational/troubleshooting/
Write or fix testsdocs/rules/testing_standards.mddocs/prompts/test-creation/SKILL.md
Manuscript / PDF / citationsdocs/guides/manuscript-semantics.mddocs/prompts/manuscript-cross-references/SKILL.md
Contribute / open a PRCI/CD · Issue & PR templatesdocs/development/contributing.md
Mirror CI locallySimulate CI locallydocs/maintenance/ci-local.md · scripts/ci_local.sh
Cloud / headless deploydocs/CLOUD_DEPLOY.mdinfrastructure/docker/
Full system reference../AGENTS.mddocs/documentation-index.md

Agent & automation entry point

Structured routing for coding agents, review bots, and CI automation. Read in this order unless the user task is narrowly scoped.

1 — Read order

PriorityFileWhen
1.cursorrulesCursor — architecture, thin orchestrator, no-mocks, CI scope
2CLAUDE.mdExact shell commands, CI mirror, common patterns
3AGENTS.mdPipeline stages, validation, configuration, troubleshooting index
4Directory AGENTS.mdAPI surfaces for the tree you are editing (infrastructure/, projects/<name>/, docs/, …)
5.github/AGENTS.mdGitHub Actions job names, branch protection, local CI parity

2 — Workflow skill router

Natural-language tasks map to one child skill under docs/prompts/. Hub: docs/prompts/SKILL.md.

Symptom or goalSkill
Pipeline stage failed / stuckpipeline-debugging
Regenerate-from-clean / determinismreproducibility-audit
Triple-check manuscript claimsmanuscript-claim-verification
[[FIG:]] / registry / cross-refsmanuscript-cross-references
New manuscript + project from briefmanuscript-creation
Full repo health auditcomprehensive-assessment
Validation CLI / markdown / PDF gatesvalidation-quality
New module or algorithmcode-development
Tests (no mocks)test-creation
End-to-end featurefeature-addition
New infrastructure/* packageinfrastructure-module
Directory docs (AGENTS.md / README.md)documentation-creation

Ambiguous intent: load the hub docs/prompts/SKILL.md and pick one child — do not improvise without it.

3 — Non-negotiable invariants

4 — Command cheat sheet (agents)

uv sync                                                          # install deps
./run.sh --pipeline --project template_code_project --core-only  # 8-stage core DAG
uv run python scripts/01_run_tests.py --project template_code_project
uv run python -m infrastructure.project.public_scope source-paths | xargs uvx ruff check
uv run python -m infrastructure.validation.cli markdown projects/templates/template_code_project/manuscript/
uv run python -m infrastructure.skills check                     # manifest freshness
pre-commit run --hook-stage pre-push --all-files                 # local CI subset

Full command matrix: CLAUDE.md · docs/reference/quick-start-cheatsheet.md


What Is This?

The Research Project Template addresses the structural root of research irreproducibility: fragmentation between code, tests, manuscripts, and provenance. Instead of patching tools together, it enforces integrity at the architectural level.

You getHow
Reproducible builds10-stage DAG pipeline from env setup → tests → PDF → hashed artifact
Real test enforcementZero-Mock policy · ≥90% project coverage · ≥60% infra coverage
Cryptographic provenanceSHA-256/512 hashing + steganographic watermarking on every PDF
Horizontal scalingN independent projects share one infrastructure layer — no coupling
AI-agent-ready codebaseAGENTS.md + README.md per directory; SKILL.md + .cursor/skill_manifest.json for routing
Interactive orchestrationrun.sh TUI menu for humans · --pipeline flag for CI

⚡ Quick Start

# 1. Create your research repo from this template
gh repo create my-research --template docxology/template --private
cd my-research

# 2. Install dependencies
uv sync

# 3. Run the interactive pipeline menu
./run.sh

# 4. Or run non-interactively against the exemplar project
./run.sh --pipeline --project template_code_project

# Outputs → output/template_code_project/

Don't have uv? → curl -Ls https://astral.sh/uv/install.sh | sh

See the full walkthrough in docs/RUN_GUIDE.md and docs/guides/getting-started.md.


📐 Architecture

The repository is organized into two strictly separated layers — shared infrastructure that never changes per-project, and self-contained project workspaces that know nothing about each other.

graph TD
    Root["/ (Repository Root)"] --> Infra["infrastructure/ (Layer 1 — Shared)"]
    Root --> Scripts["scripts/ (Pipeline Stage Scripts)"]
    Root --> Projects["projects/ (Layer 2 — Project Workspaces)"]
    Root --> Docs["docs/ (see documentation-index.md)"]
    Root --> Output["output/ (Final Deliverables)"]

    subgraph "Layer 1 · 19 importable Python packages under infrastructure/ (+ config/docker templates) · docs/modules/"
        Infra --> Core["core/ — logging, config, exceptions"]
        Infra --> Rendering["rendering/ — Pandoc + XeLaTeX"]
        Infra --> Stego["steganography/ — SHA-256 + watermarking"]
        Infra --> Valid["validation/ — PDF + Markdown integrity"]
        Infra --> LLM["llm/ — Ollama review + translation"]
        Infra --> More["+ publishing, reporting, scientific, project, documentation…"]
    end

    subgraph "Layer 2 · Active Project Workspaces"
        Projects --> AP["template_autoresearch_project/ ← AutoResearch exemplar"]
        Projects --> CP["template_code_project/ ← Code exemplar"]
        Projects --> PP["template_prose_project/ ← Prose exemplar"]
        Projects --> Dots["Rotating projects ← Auto-discovered"]
    end

Authoritative slugs: docs/_generated/active_projects.md. Archived or local-only exemplars live under projects/archive/ when present.

Directory Reference

PathPersistencePurpose
infrastructure/PermanentTop-level Python packages under infrastructure/ (plus config/documentation-only directories); live count in docs/_generated/canonical_facts.md, documented areas in docs/modules/modules-guide.md, and package details in infrastructure/AGENTS.md
projects/PermanentActive projects — discovered and executed by pipeline (docs/_generated/active_projects.md)
projects/working/TransientStaging area: scaffold here before promoting to projects/
projects/archive/PermanentCompleted/retired work — preserved, not executed
scripts/Permanent8 generic pipeline stage scripts (Stages 00–07)
output/DisposableFinal PDFs, dashboards, reports — cleaned on each run
docs/PermanentLarge documentation hub — inventory in docs/documentation-index.md (counts vary; do not rely on a single “N files” figure across READMEs)
tests/PermanentInfrastructure-level test suite (≥ 60% coverage gate)

Key invariant: All domain logic lives in projects/{name}/src/. Scripts are thin orchestrators — they import and call, never implement. See docs/architecture/thin-orchestrator-summary.md.


📁 Active Projects

template_code_project — Code Exemplar

projects/templates/template_code_project/ is the canonical example of a complete, working project. Use it as the reference when building your own.

FeatureImplementation
Gradient descent optimizationprojects/templates/template_code_project/src/optimizer.py
Scientific benchmarkinguses infrastructure.scientific
Project test suitetests/ — real operations only, coverage gated at 90%
6 publication-quality figuresgenerated in scripts/, registered via FigureManager
Full pipeline outputPDF rendered, validated, steganographically signed
Complete documentationAGENTS.md + README.md throughout

→ Details: projects/templates/template_code_project/AGENTS.md · projects/templates/template_code_project/README.md

Published exemplars — pipeline productivity, advanced provenance, and autopoiesis

The repository ships nine public template projects. Seven are independently published as their own GitHub repository + Zenodo deposit (versioned, authored by Daniel Ari Friedman); template_sia is deposited from the shared docxology/template repository, and template_textbook is published to Zenodo. Each demonstrates the pipeline end-to-end on real, citable artifacts.

The table below is auto-injected from public project config files plus optional GitHub/Zenodo API refreshes. Do not hand-edit it.

ExemplarConfig versionGitHubLatest releaseZenodo concept DOILatest version DOI
templates/template_active_inference0.3.0docxology/template_active_inferencenot checked10.5281/zenodo.2041702110.5281/zenodo.20420352
templates/template_autoresearch_project0.3.0docxology/template_autoresearch_projectnot checked10.5281/zenodo.2041701610.5281/zenodo.20420357
templates/template_autoscientists1.0.0docxology/template_autoscientistsnot checked10.5281/zenodo.2053366910.5281/zenodo.20533670
templates/template_code_project2.5.0docxology/template_code_projectnot checked10.5281/zenodo.2041713610.5281/zenodo.20420368
templates/template_newspaper1.0.0docxology/template_newspapernot checked10.5281/zenodo.2053367510.5281/zenodo.20533676
templates/template_prose_project0.4.0docxology/template_prose_projectnot checked10.5281/zenodo.2041710410.5281/zenodo.20420342
templates/template_sia0.1.0docxology/templatenot checked10.5281/zenodo.2045387910.5281/zenodo.20453880
templates/template_template1.0.6docxology/template_templatenot checked10.5281/zenodo.2041900710.5281/zenodo.20420387
templates/template_textbook0.1.0docxology/template_textbooknot checked10.5281/zenodo.2053312510.5281/zenodo.20533126

Full generated matrix: docs/_generated/publication_records.md.

Productive — every exemplar above is the output of running this repo's own pipeline (./run.sh --pipeline): tested (≥90 % project coverage), rendered to a validated PDF, then released. The artifacts are not hand-authored — they are produced by the DAG they describe.

Advanced — double-referenced provenance. Each release is cross-linked both ways: the GitHub release body cites the Zenodo DOI + PDF SHA-256, and the Zenodo record carries a related_identifiers: isSupplementTo back to the GitHub release. The DOI resolves to the archived PDF; the repo resolves to the source — neither is orphaned. Releases are versioned (concept DOI for "always-latest" + per-version DOIs).

Autopoietic — template_template. The meta-template exemplar is a self-referential research project: its manuscript is generated by programmatically introspecting this repository's own infrastructure/ (module inventory, pipeline DAG, public-exemplar roster) via src/template_template/introspection.py and injecting the live metrics into its prose. The pipeline documents itself, renders that documentation, and publishes it — a system that produces a description of its own production. Its introspection is scoped to PUBLIC_PROJECT_NAMES only (a confidentiality invariant enforced by a negative-control test), so the published artifact never embeds private/rotating project data.

Rotating projects

Beyond the permanent public exemplars, other projects rotate between projects/working/, projects/, and projects/archive/ as work progresses (meta-documentation, domain catalogues, Lean-toolchain projects, case studies). Their paths are deliberately not hard-coded here — per the repo-wide rule also stated in the root README.md and ../AGENTS.md, the single authoritative roster is docs/_generated/active_projects.md (regenerated from infrastructure.project.public_scope), with measured facts in docs/_generated/canonical_facts.md. This keeps the docs-lint "zero ghost references" gate green without per-line noqa suppressions.

Archived exemplars

Retired or sample projects are kept under projects/archive/ when present, but that roster is checkout-specific and not executed by ./run.sh until moved back into projects/.

Project Directory Layout

flowchart LR
    P[/projects/&lt;name&gt;/]
    P --> SRC[/src/&lt;name&gt;<br/>All domain logic · algorithms · analysis/]
    P --> T[/tests<br/>Real tests · no mocks · ≥ 90% coverage/]
    P --> SC[/scripts<br/>Thin orchestrators calling src/]
    P --> M[/manuscript<br/>Markdown chapters · config.yaml/]
    P --> O[/output<br/>Pipeline artifacts · generated/]
    P --> AG[AGENTS.md<br/>AI-agent context for this project]

    classDef d fill:#0f172a,stroke:#0f172a,color:#fff
    classDef f fill:#0f766e,stroke:#0f172a,color:#fff
    class P,SRC,T,SC,M,O d
    class AG f

System Architecture Overview

graph TB
    subgraph Entry["🚀 Entry Points"]
        RUNSH[./run.sh<br/>Interactive menu<br/>Full pipeline control]
        RUNALL[uv run python scripts/execute_pipeline.py --core-only<br/>Programmatic<br/>Core pipeline]
        INDIVIDUAL[Individual Scripts<br/>scripts/00-07_*.py<br/>Stage-specific execution]
    end

    subgraph Orchestration["⚙️ Orchestration Layer"]
        SETUP[Environment Setup<br/>Dependencies & validation]
        TESTING[Test Execution<br/>Coverage requirements]
        ANALYSIS[Script Discovery<br/>Project analysis execution]
        RENDERING[PDF Generation<br/>Manuscript compilation]
        VALIDATION[Quality Assurance<br/>Content validation]
        DELIVERY[Output Distribution<br/>Final deliverables]
    end

    subgraph Core["🧠 Core Systems (DAG Engine)"]
        INFRASTRUCTURE[Infrastructure Modules<br/>19 Python packages<br/>Validation, rendering, LLM, methods]
        BUSINESS_LOGIC[Business Logic<br/>Project algorithms<br/>100% test coverage]
        CONFIGURATION[Configuration System<br/>YAML + environment<br/>Runtime flexibility]
    end

    subgraph Data["📊 Data Flow"]
        SOURCE_CODE[Source Code<br/>Python modules<br/>Algorithm implementation]
        MANUSCRIPT_CONTENT[Manuscript Content<br/>Markdown sections<br/>Research writing]
        GENERATED_OUTPUTS[Generated Outputs<br/>PDFs, figures, data<br/>Research deliverables]
    end

    subgraph Quality["✅ Quality Assurance"]
        UNIT_TESTS[Unit Tests<br/>Function validation<br/>Real data, no mocks]
        INTEGRATION_TESTS[Integration Tests<br/>System validation<br/>End-to-end workflows]
        VALIDATION_CHECKS[Content Validation<br/>Quality assurance<br/>Academic standards]
    end

    RUNSH --> Orchestration
    RUNALL --> Orchestration
    INDIVIDUAL --> Orchestration

    Orchestration --> Core
    Core --> Data
    Data --> Quality

    Quality -.->|Feedback| Orchestration

    classDef entry fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef orchestration fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef core fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef data fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef quality fill:#fce4ec,stroke:#c2185b,stroke-width:2px

    class Entry entry
    class Orchestration orchestration
    class Core core
    class Data data
    class Quality quality

To add your own project, follow docs/guides/new-project-setup.md.

Project Lifecycle

stateDiagram-v2
    [*] --> InProgress: Create scaffold
    InProgress --> Active: Add src/ + tests/ + manuscript/config.yaml
    Active --> Archive: Complete / retire
    Archive --> Active: Reactivate

    InProgress : projects/working/ — not executed
    Active : projects/ — auto-discovered, pipeline-executed
    Archive : projects/archive/ — preserved, not executed

🔄 Pipeline

run.sh executes a 10-stage declarative DAG pipeline configured via pipeline.yaml. secure_run.sh appends steganographic post-processing.

flowchart TD
    subgraph Input["📥 Input Data"]
        SOURCE_CODE["Source Code<br/>projects/{name}/src/*.py<br/>Algorithm implementations"]
        ANALYSIS_SCRIPTS["Analysis Scripts<br/>projects/{name}/scripts/*.py<br/>Workflow orchestrators"]
        MANUSCRIPT_FILES["Manuscript Files<br/>projects/{name}/manuscript/*.md<br/>Research content"]
        CONFIG_FILES[Configuration<br/>config.yaml<br/>Runtime parameters]
    end

    subgraph Processing["⚙️ 10-Stage DAG Pipeline"]
        STAGE0["Stage 0 — Clean<br/>(built-in / executor)"]
        STAGE1["Stage 1 — Setup<br/>00_setup_environment.py"]
        STAGE2["Stage 2 — Infra smoke<br/>01_run_tests.py --infra-scope pipeline-smoke"]
        STAGE3["Stage 3 — Project tests<br/>01_run_tests.py --project-only"]
        STAGE4["Stage 4 — Analysis<br/>02_run_analysis.py"]
        STAGE5["Stage 5 — Render PDF<br/>03_render_pdf.py"]
        STAGE6["Stage 6 — Validate<br/>04_validate_output.py"]
        STAGE7["Stage 7 — LLM reviews<br/>06_llm_review.py --reviews-only"]
        STAGE8["Stage 8 — LLM translations<br/>06_llm_review.py --translations-only"]
        STAGE9["Stage 9 — Copy outputs<br/>05_copy_outputs.py"]
    end

    subgraph Output["📤 Generated Outputs"]
        PDF_DOCS["PDF Documents<br/>output/{name}/pdf/*.pdf<br/>Professional manuscripts"]
        FIGURES["Figures<br/>output/{name}/figures/*.png<br/>Publication-quality plots"]
        DATA_FILES["Data Files<br/>output/{name}/data/*.csv<br/>Analysis results"]
        REPORTS["Reports<br/>output/{name}/reports/*.md<br/>Validation summaries"]
    end

    SOURCE_CODE --> STAGE3
    ANALYSIS_SCRIPTS --> STAGE4
    MANUSCRIPT_FILES --> STAGE5
    CONFIG_FILES --> STAGE1

    STAGE0 --> STAGE1 
    STAGE1 --> STAGE2
    STAGE1 --> STAGE3
    STAGE3 --> STAGE4
    STAGE4 --> STAGE5
    STAGE5 --> STAGE6
    STAGE6 --> STAGE7
    STAGE6 --> STAGE8
    STAGE6 --> STAGE9

    STAGE4 --> FIGURES
    STAGE4 --> DATA_FILES
    STAGE5 --> PDF_DOCS
    STAGE6 --> REPORTS

    classDef input fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef process fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef output fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px

    class Input input
    class Processing process
    class Output output

Stage indices 0–9 are pipeline positions; they do not match scripts/NN_*.py numeric prefixes (e.g. stage 2 uses 01_run_tests.py). The table below is authoritative.

StageScriptTagsFailure mode
0 Clean Output Directoriesbuilt-in _run_clean_outputscore, cleansoft fail
1 Environment Setup00_setup_environment.pycorehard fail
2 Infrastructure Tests01_run_tests.py --infra-only --verbose --infra-scope pipeline-smokecore, testsconfigurable tolerance
3 Project Tests01_run_tests.py --project-only --verbosecore, testsconfigurable tolerance
4 Project Analysis02_run_analysis.pycorehard fail
5 PDF Rendering03_render_pdf.pycorehard fail
6 Output Validation04_validate_output.pycorewarning + report
7 LLM Scientific Review06_llm_review.py --reviews-onlyllmskipped if Ollama absent
8 LLM Translations06_llm_review.py --translations-onlyllmskipped if Ollama absent
9 Copy Outputs05_copy_outputs.pycoresoft fail
10 Executable Bundle08_executable_bundle.pybundlesoft fail
11 Archival Publication09_archive_publication.pyarchivalsoft fail

Full stage details: docs/core/workflow.md · docs/core/how-to-use.md.


AI collaboration

Every permanent directory carries README.md (human navigation) and AGENTS.md (machine-readable API tables, constraints, file inventories). infrastructure/ subpackages add SKILL.md for agent routing.

flowchart TB
    GH[".github/README.md<br/>GitHub entry · CI · doc map"]
    CL["CLAUDE.md<br/>Commands · CI mirror"]
    AG["AGENTS.md · per directory<br/>Local APIs · integration"]
    SK["SKILL.md · infrastructure + docs/prompts<br/>Workflow routing"]
    RD["README.md<br/>Quick-start"]

    GH --> CL --> AG
    AG --> SK --> RD

    classDef root fill:#0f172a,stroke:#0f172a,color:#fff
    classDef tech fill:#1e3a8a,stroke:#0f172a,color:#fff
    classDef hum fill:#0f766e,stroke:#0f172a,color:#fff
    class GH,CL root
    class AG,SK tech
    class RD hum
LayerEntry
Workflow skills (14 tasks)docs/prompts/SKILL.md · Agent router
Infrastructure skillsinfrastructure/SKILL.md · docs/_generated/skills_index.md
Editor manifest.cursor/skill_manifest.json — uv run python -m infrastructure.skills write
Contributor normsdocs/rules/ · .cursorrules
PAI integrationdocs/PAI.md
Skill eval harness (synthetic)docs/prompts/_skill-eval/AGENTS.md

🔒 Security & Provenance

Every rendered PDF is automatically processed by the steganographic pipeline via secure_run.sh:

LayerMechanismSurvives
PDF MetadataXMP + Info dictionary (author, DOI, ORCID, build timestamp)All viewers
Hash manifestSHA-256 + SHA-512 in *.hashes.jsonExternal verification
Alpha overlayLow-opacity text per page (build time + commit hash)Standard PDF operations, printing
QR codeRepository URL injected on final pageRedistribution

Full specification: docs/security/steganography.md · docs/security/hashing_and_manifests.md · docs/security/secure_execution.md.


🧪 Testing Standards

StandardRequirement
Zero-Mock policyNo MagicMock, mocker.patch, or unittest.mock anywhere
Real operationsTests use real filesystem, subprocess, and HTTP calls
Infrastructure coverage≥ 60% (live % → docs/development/coverage-gaps.md)
Project coverage≥ 90% for public exemplar src/ trees; confirm live figures in docs/_generated/canonical_facts.md
Optional service skipping@pytest.mark.requires_ollama for graceful degradation
# Mirror CI locally
uv run pytest tests/infra_tests/ --cov=infrastructure --cov-fail-under=60 -m "not requires_ollama"
uv run pytest projects/templates/template_code_project/tests/ --cov-fail-under=90 -m "not requires_ollama"
python scripts/verify_no_mocks.py

See docs/development/testing/ and docs/guides/testing-and-reproducibility.md.


📚 Documentation Hub

graph TD
    subgraph Core["📂 Core — Start Here"]
        HOW[how-to-use.md]
        WORK[workflow.md]
        ARCH[architecture.md]
    end

    subgraph Build["🏗️ Architecture"]
        TLA[two-layer-architecture.md]
        THIN[thin-orchestrator-summary.md]
        DECIDE[decision-tree.md]
    end

    subgraph Learn["📖 Guides"]
        START[getting-started.md]
        NEW[new-project-setup.md]
        TEST[testing-and-reproducibility.md]
        FIG[figures-and-analysis.md]
    end

    subgraph Enforce["📏 Rules"]
        TSTD[testing_standards.md]
        CODE[code_style.md]
        DOC[documentation_standards.md]
    end

    subgraph Operate["🔧 Operational"]
        BUILD[build/]
        CONF[config/]
        TROUBLE[troubleshooting/]
    end

    HOW -->|"Deep dive"| TLA
    HOW -->|"First run"| START
    WORK -->|"Stage details"| BUILD
    ARCH -->|"Pattern"| THIN
    START -->|"Add project"| NEW
    NEW -->|"Write tests"| TEST
    TEST -->|"Standards"| TSTD
    FIG -->|"Style"| DOC

    classDef core fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef build fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef learn fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef enforce fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef operate fill:#fce4ec,stroke:#c2185b,stroke-width:2px

    class Core core
    class Build build
    class Learn learn
    class Enforce enforce
    class Operate operate

The docs/ directory spans many files across multiple subdirectories — see docs/documentation-index.md for the authoritative live inventory (counts drift; do not hard-code a subdir or file total here). Every subdirectory has its own README.md and AGENTS.md. Start at docs/README.md.

📂 Core (docs/core/)

Essential start-here docs — read these first.

FilePurpose
how-to-use.mdStep-by-step usage guide for the full system
workflow.mdPipeline workflow: stages, flags, modes
architecture.mdTwo-Layer Architecture overview

🏗️ Architecture (docs/architecture/)

Design decisions, patterns, and migration guides.

FilePurpose
two-layer-architecture.mdDeep dive into the Layer 1 / Layer 2 separation
thin-orchestrator-summary.mdThe Thin Orchestrator pattern — why and how
testing-strategy.mdTesting architecture and Zero-Mock rationale
decision-tree.mdWhere does new code go? Decision guide
migration-from-flat.mdMigrating a flat repo to the Two-Layer model

📖 Guides (docs/guides/)

Progressive tutorials from first project to advanced automation.

FilePurpose
getting-started.mdFirst-time setup and first pipeline run
new-project-setup.mdFull checklist for adding a new project
figures-and-analysis.mdGenerating, registering, and embedding figures
testing-and-reproducibility.mdWriting real tests, coverage, markers
extending-and-automation.mdCustomizing the pipeline, adding CI stages

📏 Rules (docs/rules/)

Authoritative standards enforced across the codebase.

FilePurpose
testing_standards.mdZero-Mock policy, coverage thresholds, markers
code_style.mdRuff config, formatting, naming conventions
documentation_standards.mdAGENTS.md / README.md duality requirements
manuscript_style.mdChapter structure, figure captions, citations
api_design.mdModule API conventions, dataclass patterns
error_handling.mdException hierarchy, pipeline flow control
security.mdDependency pinning, secrets management
llm_standards.mdOllama integration, prompt templates, markers
python_logging.mdStructured logging via get_logger
type_hints_standards.mdmypy-compatible type annotation requirements
infrastructure_modules.mdModule API contracts and extension patterns
git_workflow.mdBranch strategy, commit conventions, PRs
folder_structure.mdDirectory layout invariants

🔧 Operational (docs/operational/)

Build, config, logging, and troubleshooting.

Directory / FilePurpose
build/Build system internals and stage details
config/config.yaml reference, environment variables
logging/Logging configuration, log levels, rotation
troubleshooting/Common errors, rendering issues, coverage gaps
error-handling-guide.mdPipeline error handling patterns
reporting-guide.mdExecutive reports, coverage JSON, dashboards

📦 Modules (docs/modules/)

Infrastructure subpackage documentation.

FilePurpose
modules-guide.mdOverview of infrastructure subpackages
pdf-validation.mdinfrastructure.validation — PDF integrity checking
scientific-simulation-guide.mdinfrastructure.scientific — stability, benchmarking
guides/Per-module usage guides

📝 Usage (docs/usage/)

Manuscript authoring, style, and content guides.

FilePurpose
markdown-template-guide.mdChapter structure, frontmatter, Pandoc quirks
style-guide.mdVoice, tense, academic writing conventions
manuscript-numbering-system.mdSection/figure/table numbering
visualization-guide.mdFigure accessibility standards (16pt floor, colorblind palettes)
image-management.mdFigure registration, paths, captions
examples.mdWorked example manuscript snippets
examples-showcase.mdGallery of generated figures from exemplar projects

📐 Best Practices (docs/best-practices/)

Project hygiene, version control, and multi-project management.

FilePurpose
best-practices.mdConsolidated best practices across all concerns
multi-project-management.mdManaging N projects, discovery rules, isolation
version-control.mdGit workflow, tagging, output tracking
migration-guide.mdUpgrading the template across major versions
backup-recovery.mdOutput preservation, disaster recovery

🛠️ Development (docs/development/)

Contributing, testing internals, roadmap.

FilePurpose
contributing.mdHow to contribute — branch, test, PR
testing/Test writing guide, coverage analysis, patterns
coverage-gaps.mdKnown low-coverage modules and improvement plans
roadmap.mdFeature roadmap and planned improvements
security.mdSecurity disclosure policy
code-of-conduct.mdCommunity standards

Prompts / workflow skills (docs/prompts/)

Discoverable agent skills — hub + 14 workflow directories — for template-compliant tasks. Invoke in natural language; indexed in .cursor/skill_manifest.json. Agent router: Agent & automation entry point.

Hub and index: docs/prompts/SKILL.md, docs/prompts/README.md, docs/prompts/AGENTS.md.

Skill directoryPurpose
code-development/New modules, algorithms, or utilities
comprehensive-assessment/Wide audit: tests, docs, manuscript, pipeline
documentation-creation/AGENTS.md / README.md for a directory
feature-addition/End-to-end feature work across layers
infrastructure-module/New or extended infrastructure/* packages
literature-synthesis/LLM blocks for per-paper and corpus synthesis
manuscript-claim-verification/Triple-check every manuscript claim
manuscript-creation/New manuscript + project from a research brief
manuscript-cross-references/Registry/token cross-ref audits
pipeline-debugging/DAG-stage triage when pipeline fails
refactoring/Clean-break refactors with migration
reproducibility-audit/Determinism + regenerate-from-clean
test-creation/Tests under the no-mocks policy
validation-quality/Validation CLI, gates, output checks

Regenerate manifest after skill edits: uv run python -m infrastructure.skills write.

📖 Reference (docs/reference/)

API reference, glossary, cheatsheets, and FAQ.

FilePurpose
api-reference.mdPublic API reference for infrastructure modules
api-project-modules.mdProject-level module patterns and conventions
glossary.mdDefinitions for all template-specific terms
faq.mdFrequently asked questions
quick-start-cheatsheet.mdOne-page command reference
common-workflows.mdRecipes for common research tasks
copypasta.mdCopy-paste code snippets for common patterns

🔒 Security (docs/security/)

Steganography, hashing, and secure execution.

FilePurpose
steganography.mdWatermarking layers, alpha overlay, QR injection
hashing_and_manifests.mdSHA-256/512 hash manifests and tamper detection
secure_execution.mdsecure_run.sh, steganography config, output files

🔍 Audit (docs/audit/)

Documentation review reports and filepath audits.

FilePurpose
Live doc linteruv run python scripts/lint_docs.py — mermaid + cross-link + consistency (replaces stale audit snapshots)
audit/archived/Historical audit snapshots with -YYYY-MM-DD.md suffix (point-in-time, not current state)

🚀 Top-Level Docs

FilePurpose
docs/README.mdDocumentation hub index and navigation
docs/AGENTS.mdTechnical guide for the docs/ tree
docs/documentation-index.mdFull inventory of documentation files (authoritative count)
docs/RUN_GUIDE.mdComplete run guide: modes, flags, troubleshooting
docs/CLOUD_DEPLOY.mdCloud deployment guide (AWS, GCP, Azure, Docker)
docs/PAI.mdPersonal AI Infrastructure integration guide

🔧 Maintenance (docs/maintenance/)

Long-horizon viability — toolchain migration, local CI, archival targets, regression testing.

FilePurpose
docs/maintenance/README.mdMaintenance hub index
docs/maintenance/ci-local.mdReproduce GitHub Actions with act / scripts/ci_local.sh
docs/maintenance/regression-testing.mdPinned numerical outputs for claim binding
docs/maintenance/archival-targets.mdStage 11 Zenodo / Software Heritage / IPFS
docs/maintenance/private-projects-repo.mdPrivate active/ / working/ / published/ / archive/ / other/ lifecycle
docs/maintenance/stage-10-executable-bundle.mdOpt-in executable bundle stage

📋 Repo meta (root)

FilePurpose
STATUS.mdPer-subsystem manual E2E verification ledger
MAINTAINERS.mdOwnership and contact
CHANGELOG.mdTemplate repository (Layer 1) release history
.pre-commit-config.yamlLocal Ruff, mypy, Bandit, pre-push gates

🔧 CI/CD

Workflows

WorkflowTriggerPurpose
ci.ymlpush/PR to main · weekly (Sun 00:00 UTC) · manual12 jobs (2 conditional) — see the full table below
stale.ymlDaily scheduleClose inactive issues/PRs (actions/stale)
release.ymlv*.*.* tag · manual dispatchGitHub Release with generated changelog

CI Jobs (ci.yml) — complete inventory

The repo-wide permissions: is contents: read; every job re-declares its own minimal scope. Conditional jobs are gated by the detect job's outputs — not by a job-level hashFiles() (that is invalid in a job-level if: and rejects the entire workflow at parse time).

#Job (id)needsRuns whenPurpose
1detect—alwaysEmits presence flags (setup_hook, fep_lean) for the optional jobs
2lint—alwaysruff check + ruff format + mypy (CI scope) + __all__ audit + tracked-generated-artifact guard (output/, .codegraph/, package metadata) + confidentiality guard (check_tracked_projects.py — only public template projects may be tracked)
3healthlintalwaysUnified health report (informational, non-blocking)
4verify-no-mockslintalwaysEnforces the zero-mock policy (scripts/verify_no_mocks.py)
5setup-hook-windows-smokeverify-no-mocks, detectneeds.detect.outputs.setup_hook == 'true'Windows smoke test of projects/**/scripts/setup_hook.py
6test-infraverify-no-mocksalwaysInfra suite, matrix Ubuntu × Py 3.10/3.11/3.12 + macOS × Py 3.12 (4 cells), --cov-fail-under=60 (macOS leg continue-on-error)
7test-projectverify-no-mocksalwaysPer-project suites — one parallel ubuntu job per public exemplar × {py3.10, py3.12} (9 × 2 = 18 cells); each enforces that project's own ≥90 floor via 01_run_tests.py --project <name> --project-only --include-slow
8fep-leanverify-no-mocks, detectneeds.detect.outputs.fep_lean == 'true'Lean-toolchain project build + tests (--cov-fail-under=89 rotating exception)
9validatelintalwaysManuscript/output validation (infrastructure.validation.cli)
10securitylintalwaysBandit MEDIUM+ (bandit.yaml) over infrastructure/ scripts/ projects/
11docs-lintlintalwaysMermaid render + relative-link resolution + doc-pair + consistency
12performancetest-infra, test-projectalwaysBenchmarks + coverage-history dashboard (informational)

Required status checks for branch protection on main are documented in AGENTS.md (the conditional jobs setup-hook-windows-smoke / fep-lean must NOT be required — they are skipped, not failed, when their project is absent). Reproduce every gate locally with the commands in AGENTS.md → "Local CI parity" and the root CLAUDE.md Quick Reference.

CI Job Flow

flowchart TB
    D[detect — presence flags]
    L[lint + type check]
    H[health — informational]
    VNM[verify-no-mocks]
    SH[setup-hook windows — conditional]
    TI[test-infra matrix]
    TP[test-project matrix]
    FL[fep-lean — conditional]
    VM[validate manuscripts]
    SS[security scan]
    DL[docs lint]
    PC[performance — informational]
    L --> H
    L --> VNM
    L --> VM
    L --> SS
    L --> DL
    VNM --> TI
    VNM --> TP
    VNM --> SH
    VNM --> FL
    D -. setup_hook .-> SH
    D -. fep_lean .-> FL
    TI --> PC
    TP --> PC

See workflows/AGENTS.md for step-level detail (pip-audit ignore file, bandit.yaml, 01_run_tests.py).

Quality Gates

GateToolThreshold
Code styleRuffzero violations
FormattingRuffzero diffs
Type safetymypyno errors
No mocksverify_no_mocks.pyzero mock usage
Exports auditinfrastructure.skills check-all-exportszero violations
Infra coveragepytest-cov≥ 60%
Project coveragepytest-cov≥ 90%
pip-auditblockingzero unignored vulns
SecurityBandit -c bandit.yaml MEDIUM+zero findings
Docs lintscripts/lint_docs.pyMermaid, links, consistency, and doc pairs clean
Performanceimport timer≤ 5 s

Simulate CI Locally

One command (act + fallback): scripts/ci_local.sh — see docs/maintenance/ci-local.md.

# Lint + format check (mirror CI)
uv run python -m infrastructure.project.public_scope source-paths | xargs uvx ruff check
uv run python -m infrastructure.project.public_scope source-paths | xargs uvx ruff format --check
uv run python -m infrastructure.project.public_scope source-paths | xargs uv run mypy

# Tests (skip Ollama-requiring tests)
uv run pytest tests/infra_tests/ --cov=infrastructure --cov-fail-under=60 -m "not requires_ollama"
uv sync --group rendering --group monitoring --group discopy
COVERAGE_FILE=.coverage.project uv run python scripts/01_run_tests.py --project-only --all-projects --public-projects --non-strict --include-slow

# Security (mirror CI)
IGNORE_ARGS=()
while IFS= read -r raw || [ -n "$raw" ]; do
  [[ "$raw" =~ ^[[:space:]]*# ]] && continue
  line="${raw%%#*}"; line="$(echo "$line" | xargs)"
  [ -z "$line" ] || IGNORE_ARGS+=(--ignore-vuln "$line")
done < .github/pip-audit-ignore.txt
uv run pip-audit "${IGNORE_ARGS[@]}"
uv run bandit -c bandit.yaml -r -ll infrastructure/ scripts/ projects/

# Pre-push hook bundle (fast local gate)
pre-commit run --hook-stage pre-push --all-files

Branch Protection

main is currently unprotected, so the following is illustrative. Set in Settings → Branches → main:

Required status checks:
  Lint & Type Check
  Infra Tests (ubuntu-latest, Python 3.10/3.11/3.12)
  Infra Tests (macos-latest, Python 3.12)
  # test-project expands to 18 checks: Project Tests (templates/<exemplar>, py3.10|py3.12)
  # one per public exemplar × {py3.10, py3.12}. Examples:
  Project Tests (templates/template_active_inference, py3.12)
  Project Tests (templates/template_code_project, py3.10)
  Validate Manuscripts · Security Scan · Documentation Lint · Performance Check
  # Optional informational artefact: Unified Health Report (informational)

Require PR review before merging: 1 approver
SecretRequired for
CODECOV_TOKENCoverage upload to Codecov (optional)

📋 Issue & PR Templates

Issues → New Issue

TemplateLabelsBest for
🐛 Bug Reportbug · needs-triageReproducible errors with log output and pipeline stage
✨ Feature Requestenhancement · needs-triageNew capabilities with priority and alternatives
📝 Documentationdocumentation · needs-triageIncorrect, missing, or outdated docs with file paths

💬 Questions? Use GitHub Discussions — blank issues are disabled.

PR Checklist → PULL_REQUEST_TEMPLATE.md

  • ✅ Linked issue · type-of-change label · pipeline stage(s) affected
  • ✅ Test evidence — local run confirmation with pass rates
  • ✅ Zero-Mock confirmation — no MagicMock / mocker.patch
  • ✅ Thin Orchestrator compliance — no logic in scripts

📦 Dependency Management

dependabot.yml — weekly automated PRs:

EcosystemGroupMax PRs
GitHub Actionsall minor/patch batched5
Python (uv)dev-tools (pytest, mypy, ruff…)5
Python (uv)scientific-core (numpy, scipy…)5

Current pinned GitHub Actions use the Node 24 action runtime. GitHub-hosted runners satisfy this; self-hosted runners must be Actions runner v2.327.1 or newer.


🔍 Troubleshooting

# CI status
gh run list --workflow=CI --limit=5
gh run view <run-id> --log-failed
gh run rerun <run-id> --failed

# Fix lint locally
uv run python -m infrastructure.project.public_scope source-paths | xargs uvx ruff check --fix
uv run python -m infrastructure.project.public_scope source-paths | xargs uvx ruff format

Common issues: docs/operational/troubleshooting/ · docs/reference/faq.md.


🤖 Agent entry · 📖 AGENTS.md · ⌨️ CLAUDE.md · 🚀 Run Guide · 📐 Architecture · 📋 Rules · 🔧 CI AGENTS.md · 📊 STATUS · 🐛 Issues · 💬 Discussions

Reproducibility as architecture, not afterthought.

Ver o original no GitHub

Bom para

Relacionados