From 108f22cf959c232d33cbffe6254d4a88d19cf0ae Mon Sep 17 00:00:00 2001 From: Cian Hughes Date: Tue, 30 Jun 2026 16:22:51 +0100 Subject: [PATCH] Added agent contracts to allow for more automation of work in repo --- .agents/rules/00-master-import.md | 11 +++++++++++ .agents/rules/01-guardrails.md | 17 +++++++++++++++++ .agents/rules/02-project-context.md | 17 +++++++++++++++++ .agents/rules/03-python-validation.md | 17 +++++++++++++++++ .agents/rules/04-logging.md | 13 +++++++++++++ .cursor/rules/00-master-import.mdc | 1 + .cursor/rules/01-guardrails.mdc | 1 + .cursor/rules/02-project-context.mdc | 1 + .cursor/rules/03-python-validation.mdc | 1 + .cursor/rules/04-logging.mdc | 1 + .gitignore | 1 + AGENTS.md | 22 ++++++++++++++++++++++ 12 files changed, 103 insertions(+) create mode 100644 .agents/rules/00-master-import.md create mode 100644 .agents/rules/01-guardrails.md create mode 100644 .agents/rules/02-project-context.md create mode 100644 .agents/rules/03-python-validation.md create mode 100644 .agents/rules/04-logging.md create mode 120000 .cursor/rules/00-master-import.mdc create mode 120000 .cursor/rules/01-guardrails.mdc create mode 120000 .cursor/rules/02-project-context.mdc create mode 120000 .cursor/rules/03-python-validation.mdc create mode 120000 .cursor/rules/04-logging.mdc create mode 100644 AGENTS.md diff --git a/.agents/rules/00-master-import.md b/.agents/rules/00-master-import.md new file mode 100644 index 0000000..8d2d687 --- /dev/null +++ b/.agents/rules/00-master-import.md @@ -0,0 +1,11 @@ +--- +description: "Imports the Master AGENTS.md context." +alwaysApply: true +--- + +# AGENTS.md Integration + +- You are working in the I-Form Invenio project. +- ALWAYS prioritize the instructions defined in `AGENTS.md` in the project root. +- If a conflict arises between this local rule and `AGENTS.md`, `AGENTS.md` is + the source of truth. diff --git a/.agents/rules/01-guardrails.md b/.agents/rules/01-guardrails.md new file mode 100644 index 0000000..e71907b --- /dev/null +++ b/.agents/rules/01-guardrails.md @@ -0,0 +1,17 @@ +--- +description: "Strict behavioral guardrails for safety and iteration limits." +alwaysApply: true +--- + +# Agent Iteration & Safety Guardrails + +- **Strict Iteration Limit:** You are permitted a maximum of 3 tool calls to + solve a problem. If tests/linters fail after 3 attempts, you MUST stop + execution, summarize the failure, and wait for human input. Do NOT attempt a + 4th fix. +- **No Blind Retries:** If a tool call fails, do NOT immediately retry with the + exact same arguments. Change your approach or ask the user. +- **Destructive Action Halt:** NEVER run `rm -rf`, `git reset --hard`, or drop + database tables without explicit user confirmation. +- **No Git Operations:** Do not use `git` to sync or commit changes unless + explicitly told to. The human is the final QC step. diff --git a/.agents/rules/02-project-context.md b/.agents/rules/02-project-context.md new file mode 100644 index 0000000..c8fb9ca --- /dev/null +++ b/.agents/rules/02-project-context.md @@ -0,0 +1,17 @@ +--- +description: "Core context for the I-Form Invenio RDM repository. Use this when reasoning about architecture, deployment, or advanced manufacturing requirements." +alwaysApply: false +--- + +# I-Form Invenio Repository Context + +- **Goal:** Set up a reliable, customized Invenio instance for the Irish + "I-Form" research institution (advanced manufacturing / Powder Bed Fusion). +- **Scale:** The system must handle extreme volumes of data and remain highly + reconfigurable. +- **Tooling:** `uv` is used for environment/dependency management. +- **Containers:** All changes must be completely OCI compatible. We use podman + locally, but deployment could be Docker or podman. +- **Upstream References:** The packages `invenio-config-iform` and + `invenio-theme-iform` were forked from `invenio-config-tugraz` and + `invenio-theme-tugraz`. diff --git a/.agents/rules/03-python-validation.md b/.agents/rules/03-python-validation.md new file mode 100644 index 0000000..c4ac27f --- /dev/null +++ b/.agents/rules/03-python-validation.md @@ -0,0 +1,17 @@ +--- +description: "Strict LSP and syntax validation rules." +globs: ["**/*.py"] +alwaysApply: false +--- + +# Python Validation & Editing Rules + +- **Mandatory Planning:** Before modifying any files, you must outline the files + you intend to touch. +- **LSP Checking:** After editing or removing boilerplate, you MUST query the + LSP server (e.g., ruff) to check for broken references, undefined variables, + or unused imports. +- **Zero Warnings:** The file is not considered "clean" until the LSP returns + zero warnings for the section you modified. +- **Revert on Failure:** If your cleanup causes cascading errors in other files, + revert your change and ask the user how they want to proceed. diff --git a/.agents/rules/04-logging.md b/.agents/rules/04-logging.md new file mode 100644 index 0000000..d794a37 --- /dev/null +++ b/.agents/rules/04-logging.md @@ -0,0 +1,13 @@ +--- +description: "Workflow for documenting agent actions and handoffs." +alwaysApply: false +--- + +# Agent Logging & Handoff Protocol + +When you complete a major task, fail a task, or require a human handoff, you +must update the following files in the `gemini/` directory: - +**`gemini/history.md`**: Update this living log with your past executions, +discoveries, bug fixes, and system status. - **`gemini/handoff.md`**: If passing +control back to a human or another agent, update this with active problems, +proposed solutions, and immediate next steps. diff --git a/.cursor/rules/00-master-import.mdc b/.cursor/rules/00-master-import.mdc new file mode 120000 index 0000000..3197d7b --- /dev/null +++ b/.cursor/rules/00-master-import.mdc @@ -0,0 +1 @@ +/home/cianh/Storage/Programming/Work_Projects/iform-invenio/.agents/rules/00-master-import.md \ No newline at end of file diff --git a/.cursor/rules/01-guardrails.mdc b/.cursor/rules/01-guardrails.mdc new file mode 120000 index 0000000..3845adc --- /dev/null +++ b/.cursor/rules/01-guardrails.mdc @@ -0,0 +1 @@ +/home/cianh/Storage/Programming/Work_Projects/iform-invenio/.agents/rules/01-guardrails.md \ No newline at end of file diff --git a/.cursor/rules/02-project-context.mdc b/.cursor/rules/02-project-context.mdc new file mode 120000 index 0000000..39d81d2 --- /dev/null +++ b/.cursor/rules/02-project-context.mdc @@ -0,0 +1 @@ +/home/cianh/Storage/Programming/Work_Projects/iform-invenio/.agents/rules/02-project-context.md \ No newline at end of file diff --git a/.cursor/rules/03-python-validation.mdc b/.cursor/rules/03-python-validation.mdc new file mode 120000 index 0000000..fc92902 --- /dev/null +++ b/.cursor/rules/03-python-validation.mdc @@ -0,0 +1 @@ +/home/cianh/Storage/Programming/Work_Projects/iform-invenio/.agents/rules/03-python-validation.md \ No newline at end of file diff --git a/.cursor/rules/04-logging.mdc b/.cursor/rules/04-logging.mdc new file mode 120000 index 0000000..bfdc509 --- /dev/null +++ b/.cursor/rules/04-logging.mdc @@ -0,0 +1 @@ +/home/cianh/Storage/Programming/Work_Projects/iform-invenio/.agents/rules/04-logging.md \ No newline at end of file diff --git a/.gitignore b/.gitignore index 4c0de8c..d606c63 100644 --- a/.gitignore +++ b/.gitignore @@ -47,3 +47,4 @@ versions secrets.env .env +agents diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c6cb419 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,22 @@ +# I-Form Invenio Repository - AGENTS.md + +## Project Identity + +- **Goal:** Manage a customized Invenio RDM instance for I-Form research. +- **Scale:** High-volume data, extreme reconfigurability. +- **Tech Stack:** Invenio RDM, Python, OCI-compliant (Docker/Podman). + +## Core Principles + +1. **Human-in-the-Loop:** Do not perform git commits or destructive database + actions without explicit human approval. +2. **Deterministic Tooling:** Always prefer `uv` for environment management. +3. **Safety First:** If a tool/command fails, stop and report. Do not blindly + retry. +4. **Tool Integrity:** Use `sequential-thinking` for planning and `LSP` + (ruff/typescript) for validation. + +## Records + +- All agent logs must be synced to `agents/history.md`. +- All handoffs must be documented in `agents/handoff.md`.