Imported from eijex/factorforge-cds (AGENTS.md). Install upstream with npx skills add eijex/factorforge-cds. Copyright stays with the author.

FactorForge Agent Operating Rules

Implementation rules for any coding agent working in this repo.

1. Repo Role

FactorForge is the public implementation repo.

• Source code: src/factorforge/
• Scripts: scripts/
• Tests: tests/
• Docs: docs/ (public user documentation)
• Configs: configs/

2. Package Name

The PyPI distribution name is factorforge-cds — install with pip install factorforge-cds. The Python import name is factorforge.

from factorforge.engines.profile import RuleBasedOptimizer
from factorforge.engines.profile.pipeline import OptimizationPipeline

3. Branch & Commit Conventions

Branch model:

• main is release-only. Tags are cut from main; whatever is on main is what ships in the next release. Do not push day-to-day work directly to main.
• develop is the work-accumulation branch. Land completed work on develop. CI (lint/test/audit) runs on both main and develop; publish/docker/release workflows are tag/main-triggered, so nothing is published from develop.
• At release time, develop is merged into main and the release is tagged on main.

Branch naming (for topic branches off develop, optional):

feat/short-description
fix/short-description
docs/short-description
chore/short-description

Commit message format:

feat: add Wolffia globosa codon table
fix: correct GC% calculation for short sequences
docs: update README installation section
chore: bump version to 3.1.1

4. Source of Truth

Before editing, read in this order:

1. Current repo code
2. public user documentation under docs/
3. VALIDATION.md and docs/validation.md — claims policy

5. Scope Guardrails

Do not change without an explicit job:

• production optimizer behavior (src/factorforge/engines/profile/)
• CodonTokenizer vocab or special token definitions
• Codon table values

Treat as read-mostly unless the active job targets them:

• experiments/ — results storage only
• models/ — checkpoints; do not commit .pt/.ckpt/.bin files (see .gitignore)

6. Claims Policy

Do not add any of the following to code comments, docstrings, or docs:

• "increases yield"
• "guarantees expression"
• "validated expression optimizer"
• "wet-lab proven"
• "validated expression optimizer"

FactorForge is an in-silico CDS design assistant. Public claims must stay limited to deterministic CDS design, sequence metrics, validation checks, and reproducible output paths unless wet-lab evidence is explicitly documented.

LLM Claim Boundary Protocol: When providing analysis or troubleshooting, strictly distinguish your (LLM) advisory hypotheses from the deterministic outputs of the FactorForge engine.

• LLM hypotheses (e.g., structural biological inferences like overlapping SPs or 4-TM limits) must be explicitly flagged as "advisory, non-authoritative interpretation".
• Deterministic outputs (e.g., CAI, GC% from FactorForge) must be treated as the source of truth for the tool's behavior. Do not conflate the LLM's biological reasoning with the tool's deterministic claims.

7. Code Style & Testing

Before submitting a PR:

ruff check .      # linting
ruff format .     # formatting
pytest tests/ -v  # all tests must pass

New features must include tests. Bug fixes should add a regression test.

8. Security

Do not open a public GitHub issue for security vulnerabilities. Report privately to: eijex.lab@gmail.com

9. Do Not Commit

• models/*.pt, models/*.ckpt, models/*.bin — use Google Drive or HuggingFace
• data/raw/, data/embeddings/ — large files, Drive only
• CLAUDE.md, .claude/ — internal workflow files, not for public repo
• .env, secrets of any kind

10. Completion Report

After completing a job, print to terminal:

=== JOB NNN COMPLETE ===
Files created/modified: [list]
Test results: [results or N/A]
Notes: [if any, otherwise none]
========================

11. Public Document Checklist

After any change, update the relevant public-facing files before pushing:

12. Public Repo Structure Checklist

For every audit, release, or repo-structure change, check the repository as a user- and paper-facing artifact:

• README.md, docs/, and web/ should describe only supported public runtime paths first.
• src/factorforge/ should contain installable, supported package code; historical engines and experiments should stay under archive/.
• archive/ is public provenance, not an active import surface.
• Claims must stay aligned with VALIDATION.md and docs/validation.md.

13. Public Surface Coverage (all releases)

Every release must pass Step 4 of docs/release-checklist-template.md before tagging. The 8 public surfaces and their required checks:

• Run or report proportional checks for CLI, API, package build metadata, and untracked-file hygiene before push.