Agentic AI (Claude Code & Codex)

This guide shows how to control MDFactory with agentic coding assistants while keeping outputs grounded in the checked-in code, commands, and docs.

What to keep in context

When you start an agent session for this repo, include these files first:

These files define project scope, command expectations, docs workflow, and agent behavior constraints.

Session bootstrap

mdfactory --help
mdfactory config path

mdfactory config show
mdfactory sync init check

Prompt templates

Use these as starting points. Both are intentionally strict about reading repo instructions first.

You are editing mdfactory in-repo.
1) Read AGENTS.md, docs/AGENTS.md, and SKILLS.md first.
2) Inspect mdfactory/cli.py and the relevant modules before proposing changes.
3) Use only commands implemented in the current codebase.
4) Show a short plan, then execute edits, then run the shortest relevant validation.
5) For docs changes, keep examples aligned with real CLI flags and command groups.

Work in this repository as a code+docs agent.
- Start by reading AGENTS.md, docs/AGENTS.md, and SKILLS.md.
- Ground all recommendations in current source files, not assumptions.
- For mdfactory usage guidance, verify command names in mdfactory/cli.py.
- Prefer small, verifiable edits with explicit file paths.
- After edits, run focused checks and summarize what changed.

High-value automation patterns

Build campaign orchestration

mdfactory check-csv input.csv
mdfactory prepare-build input.csv output_systems
mdfactory build output_systems/<hash>/<hash>.yaml output_systems/<hash>

Ask the agent to:

• validate CSV assumptions against the current schema docs
• detect likely bilayer buildability issues early
• generate a run checklist from produced hash directories

Analysis orchestration

mdfactory analysis run output_systems/input.yaml --analysis all --skip-existing
mdfactory analysis info output_systems/input.yaml --output analysis_status.csv
mdfactory analysis artifacts run output_systems/input.yaml --artifact all --skip-existing

Ask the agent to:

• select analyses by system type and runtime budget
• produce a rerun list from failed or missing outputs
• summarize completed vs pending status from the generated CSV/report

Sync/database orchestration

mdfactory sync init systems
mdfactory sync init analysis
mdfactory sync init artifacts
mdfactory sync push systems --source output_systems
mdfactory sync pull analysis --overview

Ask the agent to:

• verify init order and backend assumptions (sqlite/csv/foundry)
• run non-destructive pull/overview checks before any clear operation
• keep a command log for reproducibility

Safety controls for agent runs

Troubleshooting AI-assisted runs

Next steps