GARSGitHubGitHubJavier Rodríguez Hernáez

The folder is the system

GARS is a folder of plain files: the rules an agent works under, the helpers that compute, and one directory per project that keeps its own record.

The rules below are GARS's own, at the commit the project's record names, except the plan gate, marked, which is shown at a later one; the project's files are this site's committed copy of epigenome-a, whose pipelines really ran on 3 September 2026: a deterministic driver ran it, with no model and no agent in the loop, on nf-core's own test data, at GARS v0.10.0 (commit d2d2745, six commits after the v0.10.0 tag). It shows the process, not a finding.

The file lines below are copied from GARS at a pinned commit or from the project's committed record, never typed, and a test regenerates this page's data and fails on any difference.

Architecture

Context layers

Context is layered, so an agent loads only what the current task needs:

Layer 0AGENTS.mdCLAUDE.mdOrientation. The one your agent loads is always loaded. Workspace map and entry rules.
Layer 1CONTEXT.mdRouting. Stage map, how stages connect, where reference material lives.
Layer 2<stage>/CONTEXT.mdThe stage contract. Loaded per task.
Layer 3_references/_templates/_system/a project's _config/Domain knowledge, stamps, runtime and settings. Loaded selectively.

CreditGARS's analysis first ran on ClawBio's open bioinformatics skills; its own nf-core wrappers in _system/wrappers/ are modelled on their behaviour. Issues GARS found along the way were reported upstream, and ClawBio fixed them, keeping only a rerun guard the report itself called defensible: ClawBio#333 · ClawBio#365.

Layer 4stage outputsWorking artifacts.

CreditGARS's premise, carried through every layer of the system, follows the Interpretable Context Methodology by Jake Van Clief and David McDermott (arXiv:2603.16021).

Stage flow
  1. 00_initialize_projectregister raw data
  2. human gatefill in the design
  3. 01_prepare_samplesheetsvalidate + emit
  4. 02_bioinformaticsroute to sub-stages
    • rnaseq: nfcore wrapper → DE
    • atacseq
    • chipseq
    • cutandrun
    • methylseq
    • scrnaseq: nfcore wrapper → QC/cluster
    • spatialvi (Visium, downstream)
  5. 03_custom_analysis

Who writes each project folder

Each project directory is owned by exactly one stage, and the numeric prefix encodes the owner — NN_* is written by stage NN_* and by no other:

projects/<title>/
CONTEXT.mdHISTORY.md_config/
  • 00_data/stage 00raw symlinks, files.csv, samples.csv
  • 01_samplesheets/stage 01workflow-ready samplesheet + design table
  • 02_bioinformatics/stage 02per-assay sub-stage outputs
  • 03_custom_analysis/stage 03

Source on GitHubthe README's Architecture at GARS d6963f7, on GitHub ↗

gars/GARS's own files at commit d2d2745, on GitHub ↗

  • CLAUDE.mdThe agent's orientation file (Claude Code's entry point): read the stage map, then the contract for the step at hand, and carry it out literally. GARS today also runs under Codex, which reads AGENTS.md: a file beside this one that points the agent here, added after this older snapshot.
    ## Agent entry pointBefore responding to any request: read `CONTEXT.md` for the stage map, then read the `CONTEXT.md`of the stage the request maps to. Execute that contract literally.- Its **Scope Boundaries** are binding. Do not read, search, or act outside them, however helpful  the deviation would seem.- Its **Response Format** templates are the only messages to send. Add no observations,  suggestions, or offers of work. One exception: a direct user question may be answered from  the workspace's own files, read-only, before restating the current wait point — the bounded  voice rule in `_references/contract_standard.md`.- If a step appears to need deviation, stop and ask. Never act first and report afterwards.
    lines 13 to 24 at GARS d2d2745, on GitHub ↗
  • 02_bioinformatics/
    • CONTEXT.mdThe router for stage 02: it hands each step to that step's own contract and runs no analysis itself.
      ## PurposeRun the standardized processing workflow for one assay by executing its sub-stages in the orderdeclared in `_references/assay_stage_skill_map.md`. This stage is a router: it resolves whichsub-stages apply, checks that each one's predecessor has completed, and hands control to thatsub-stage's own contract. It runs no analysis itself.
      lines 3 to 7 at GARS d2d2745, on GitHub ↗
    • chipseq_bulk/01_nfcore-chipseq-wrapper/
      • CONTEXT.mdWhat the agent may not do at this step: compose a pipeline command, edit the files the wrapper generates, or interpret the biology.
        ## Scope BoundariesThis sub-stage performs the steps in Process and nothing else.- Never compose a `nextflow` command, and never write or edit `submit.sh` or `params.yaml` —  `prepare` generates both, and the audited parameter surface is `_config/chipseq_bulk.yaml`.  If a parameter seems missing, that is a config or wrapper change to report, not a flag to  add.- Never edit the wrapper's code. If it errors, report the error verbatim and stop.- Never substitute a hand-written pipeline. If the wrapper cannot run, report and stop.- Never modify the samplesheet, the design table, `00_data/`, or anything under  `01_samplesheets/`.- Never run the pipeline in the foreground, and never poll for it in a loop. Submit, write  STATUS, and return.- Never resubmit a job whose STATUS is `SUBMITTED` or `RUNNING`.- Never delete or move a populated `run/` directory; `check` refuses it for a reason.  Surface the refusal.- Do not interpret the biology. Report counts, paths and QC locations only.- If you believe a step should deviate, stop and ask. Do not act first and report afterwards.
        lines 22 to 39 at GARS d2d2745, on GitHub ↗
  • 03_custom_analysis/
    • CONTEXT.mdThe plan gate: the contract forbids running anything before the plan is approved, and approving it before the person has said yes; the approval is bound to the plan's sha256.This project never reached this stage, so it holds no plan; the gate is shown as it stands at commit e866cce (17 September 2026), after the run.
      - Do **not** execute anything — no script, notebook, one-liner, or skill — before  `stage03_analysis.py approve` has succeeded on the plan. Drafting is free; running is gated.- Do **not** run `approve` before the user has read the plan and said yes to it. The command  records an approval that happened in dialogue; it never substitutes for one.
      lines 34 to 57 not shown
      **Approved.** `PLAN.md` carries `Status: APPROVED <date>` **and** `PLAN.md.approved` sits besideit, both written by `approve` after its gates pass: no skeleton markers, a non-empty Outputstable, every output type in the closed vocabulary, every output path relative. The record bindsthe approval to the plan's sha256 as stamped, so `verify` refuses a plan that was edited afterapproval, and refuses a `Status: APPROVED` line that `approve` did not write (decision 0042).Approval is durable — it lives in the files, not in the conversation. `PLAN.md.approved` ismachine-owned: never write, edit, copy or move it.
      lines 30 to 64 at GARS e866cce, on GitHub ↗
  • _system/wrappers/nfcore-chipseq-wrapper/
    • SKILL.mdThe wrapper this step runs: one standard-library file with three commands, check, prepare and collect, pinned to one nf-core/chipseq release.
      ---name: nfcore-chipseq-wrapperdescription: >  GARS-authored wrapper around nf-core/chipseq 2.1.0 — peaks per IP against its declared input control (MACS3), per-antibody consensus (decision 0031).metadata:  openclaw:    source: gars                    # versioned in this repo, ours to maintain (decision 0012)    pipeline: nf-core/chipseq    pipeline_version: "2.1.0"    requires:      bins: [python3, nextflow, java, git]      python: ">=3.6 (stdlib only)"    install: >      Nothing to install for the wrapper itself. Runtime needs gars-nxf on PATH at submit time and the pinned checkout at $GARS_PIPELINES/chipseq-2.1.0.---# nfcore-chipseq-wrapperOne stdlib file on `_system/wrapperlib.py` (decision 0028): `check` (preflight), `prepare`(params.yaml + submit.sh + reproducibility bundle, deterministic bytes), `collect` (contentexit gate, OUTPUTS.tsv, STATUS, history entry). The sub-stage contract at`02_bioinformatics/chipseq_bulk/01_nfcore-chipseq-wrapper/CONTEXT.md` orchestrates it; nothing here is invokeddirectly by a user. Exit codes: 0 ok / 1 failure / 2 refused / 3 usage.
      lines 1 to 23 at GARS d2d2745, on GitHub ↗

      CreditWrappers modelled on ClawBio's open bioinformatics skills.

  • projects/epigenome-a/
    • HISTORY.mdThe project's memory, append-only: GARS's stage 00 wrote the first entry and the demo's driver added one per pipeline run.
      # History: epigenome-aAppend-only. One dated entry per stage action, newest last. Every stage appends here; no stagerewrites or removes an earlier entry.Entry format:```## <ISO-8601 date> — <stage or sub-stage> — <outcome><what was done, what was written, and where any input came from>```---## 2026-09-03 — 00_initialize_project — project createdTemplate version: v0.10.0Model: tools.modalityFile integrity check: `quick`| Assay ID | Source path | Files linked ||---|---|---|| atacseq_bulk | `/work/v2/epigenome-a/seqrun/atacseq` | 8 || chipseq_bulk | `/work/v2/epigenome-a/seqrun/chipseq` | 12 |## 2026-09-03 — 01_nfcore-chipseq-wrapper — COMPLETE- ran nf-core/chipseq 2.1.0 on AWS Batch job `e6d25fcf-5d4b-4ddd-a7ba-dc9e47c44945` (created 2026-09-03T21:06:54Z)- counted: peaks (chip-a rep1) 909, peaks (chip-a rep2) 655, peaks (chip-b rep1) 794, peaks (chip-b rep2) 999, samples 3, tasks 214- surfaces under `results/v2/epigenome-a/20260903-2106/ws`## 2026-09-03 — 01_nfcore-atacseq-wrapper — COMPLETE- ran nf-core/atacseq 2.1.2 on AWS Batch job `738bd383-d085-425b-a4b4-a86506f79770` (created 2026-09-03T21:42:28Z)- counted: peaks (atac-a rep1) 820, peaks (atac-a rep2) 567, peaks (atac-b rep1) 763, peaks (atac-b rep2) 756, samples 2, tasks 187- surfaces under `results/v2/epigenome-a/20260903-2106/ws`
      the rule it follows: HISTORY.md line 3 at GARS d2d2745, on GitHub ↗
    • PROVENANCE.jsonThe receipts, written by the demo's driver and shown as the page “What GARS remembers” reads them: each count names the AWS Batch job that made it, the object it was read from and that object's ETag.
      • 909 peaks (chip-a rep1)job e6d25fcf-5d4b-4ddd-a7ba-dc9e47c44945 · chip-a_REP1_peaks.broadPeak · ETag 7be4d209f1027507ffb5513e28ba6c52
      • 655 peaks (chip-a rep2)job e6d25fcf-5d4b-4ddd-a7ba-dc9e47c44945 · chip-a_REP2_peaks.broadPeak · ETag 93f274ab0b877bdcb9ec688497bf128f
      • 794 peaks (chip-b rep1)job e6d25fcf-5d4b-4ddd-a7ba-dc9e47c44945 · chip-b_REP1_peaks.broadPeak · ETag 89efe15f1f28a535612790c83b551f78
      • 999 peaks (chip-b rep2)job e6d25fcf-5d4b-4ddd-a7ba-dc9e47c44945 · chip-b_REP2_peaks.broadPeak · ETag 140f724d3898c6d8fa7525b5075b9752
      • 3 sample groups6 samplesheet rowsjob e6d25fcf-5d4b-4ddd-a7ba-dc9e47c44945 · chipseq_bulk_samplesheet.csv · ETag 175077053b000c3125658169eb3208ed
      • 214 tasks127 of 214 recorded a runtime above a millisecondjob e6d25fcf-5d4b-4ddd-a7ba-dc9e47c44945 · execution_trace_2026-09-03_21-07-16.txt · ETag 82fda978e4d28589c06e427371e89d32

      The link serves this site's own copy of the counted file; its match with the ETag checks that copy, not that the bytes sat in cloud storage.

      the counted file chip-a_REP1_peaks.broadPeak, as this site serves it
    • _config/
      • chipseq_bulk.yamlThe two scientific decisions for this assay, the reference genome and the peak type, in one audited file; here the driver picked them from GARS's menus to match nf-core's own test profile.
        reference:  fasta: /work/v2/epigenome-a/ws/_references_data/R64-1-1/genome.fa  gtf: /work/v2/epigenome-a/ws/_references_data/R64-1-1/genes.gtf
        lines 16 to 30 not shown
        peaks:  # narrow | broad. Narrow suits transcription factors; broad suits wide histone marks. A  # scientific decision -- chosen from the menu at stage 02, never defaulted.  type: broad  # MACS effective genome size. A property of the assembly; travels with the genome choice.  macs_gsize: 12157105
        the rule it follows: CONTEXT.md lines 17 to 26 at GARS d2d2745, on GitHub ↗
    • 02_bioinformatics/chipseq_bulk/01_nfcore-chipseq-wrapper/
      • params.yamlThe pipeline's parameters, generated by the wrapper's prepare step from that audited file and never typed by hand.
        # Generated by the chipseq_bulk wrapper's prepare. Do not hand-edit: the audited# parameter surface is _config/chipseq_bulk.yaml; change that and re-run prepare.input: /work/v2/epigenome-a/ws/projects/epigenome-a/01_samplesheets/chipseq_bulk_samplesheet.csvoutdir: /work/v2/epigenome-a/ws/projects/epigenome-a/02_bioinformatics/chipseq_bulk/01_nfcore-chipseq-wrapper/run/resultsfasta: /work/v2/epigenome-a/ws/_references_data/R64-1-1/genome.fagtf: /work/v2/epigenome-a/ws/_references_data/R64-1-1/genes.gtfaligner: bwamacs_gsize: 12157105save_reference: trueskip_preseq: true
        the rule it follows: CONTEXT.md line 26 at GARS d2d2745, on GitHub ↗
      • STATUSThe step's state in one line, and the only authority on whether it finished.
        COMPLETE 2026-09-03T21:40:28
        the rule it follows: CONTEXT.md lines 52 to 54 at GARS d2d2745, on GitHub ↗
      • OUTPUTS.tsvWhat the step produced, declared by type, so the next step finds its inputs by type rather than by path.
        # type	role	pathpeaks	native	run/results/bwa/merged_library/macs3/broad_peakpeaks_consensus	native	run/results/bwa/merged_library/macs3/broad_peak/consensuscounts_peaks	native	run/results/bwa/merged_library/macs3/broad_peak/consensus/ab-a/ab-a.consensus_peaks.featureCounts.txtbigwig	native	run/results/bwa/merged_library/bigwigbam_genome	native	run/results/bwa/merged_libraryqc_multiqc	native	run/results/multiqc/broad_peak/multiqc_report.html
        the rule it follows: CONTEXT.md lines 57 to 60 at GARS d2d2745, on GitHub ↗