Instruction file imported from alejobasi/SBV26 (.github/instructions/onex.instructions.md). Copyright stays with the author.

ONEX — Cross-cutting rules for all agents

These rules apply to every ONEX agent and Copilot interaction in this workspace. They are loaded automatically by VS Code and take precedence over per-agent instructions when applicable.

1. Commit message prefix — MANDATORY

All commits produced by any ONEX agent must start with ONEX_. This is mandatory for framework traceability. A commit message that does not start with ONEX_ is considered invalid and must be corrected before pushing.

ONEX_feat(SCOPE): description
ONEX_fix(SCOPE): description
ONEX_docs(SCOPE): description
ONEX_refactor(SCOPE): description

2. Code provenance marker — MANDATORY for every new file

Whenever you create a brand-new source file (any file that did not exist before), you MUST add a provenance comment as the first line of the file (after any mandatory language preamble like package, shebang, or XML declaration).

Replace <agent-name> with the active agent (e.g. onex.implement, onex.migrate.execute, onex-fix.hotfix).

• Only for brand-new files — never for existing files you edit or transform in place.
• If unsure whether a file is new, run git status — untracked = new = marker required.
• This is non-negotiable — ONEX tracking depends on it.

3. Protected folder: .github/

Before creating, modifying or deleting any file inside the .github/ folder (including agents/, prompts/, instructions/, workflows/, ISSUE_TEMPLATE/, PULL_REQUEST_TEMPLATE, copilot-instructions.md, or any other subfolder/file), you MUST stop and ask the user for explicit confirmation:

⚠️ This action will modify the .github/ folder:
   [describe the specific file/change]

Are you sure you want to modify the .github/ folder? (yes/no)

Never assume implicit permission — even if the task description mentions it.

4. Consult project memory before acting — lazy loading via INDEX

• ALWAYS read .onex/memory/INDEX.md first (if it exists). This is an ultra-light manifest (~500 bytes) that summarises every memory file, the active context (current feature, resume point, branch, last agent), and recent journal keywords.
• Only load a full memory file when needed:
  • Load constitution.md — when you need framework, testing, naming, or quality conventions (typically at the start of workflows that generate or validate code).
  • Load progress.md — when you need the Task Implementation Log to find a resume point (typically /onex.implement). Check the INDEX "Active Context → Resume point" first; if it already contains what you need, skip the full read.
  • Load journal.md — only when entering a debug loop and the INDEX "Recent Journal Keywords" section contains a keyword matching the current error/symptom. If no keyword matches, do not load the file.
  • Load decisions.md / tech-stack.md — only when the agent explicitly requires architecture decisions or full dependency information.
• After writing to any memory file, update the corresponding row in INDEX.md (size, last-updated, summary) and, if applicable, the Active Context section.

5. Update progress tracking after each completed task

After completing each task, update .onex/memory/progress.md with:

• Task ID, title, status, start date, and completion date.
• If the table does not exist, create it under the feature heading.
• Mark the next task as 🔄 In Progress so session resumption works correctly.

Then immediately update .onex/memory/INDEX.md:

• Set Resume point to the next pending task (or — (all tasks completed)).
• Set Last agent to the current agent name.
• Update the progress.md row in the Memory Manifest (size, last-updated).

The task is not finished until both progress.md and INDEX.md have been written.

6. Non-code artefact footer

All non-code artefacts generated by ONEX (PR bodies, Jira descriptions/comments, Confluence pages, hotfix reports, documentation exports) must include this footer:

Generated with ONEX `/<agent-name>`
Workflow: `<workflow>`
Source branch: `<branch>`
Revision: `<head-sha>`
Date: `<YYYY-MM-DD>`

7. Persist reusable fixes in journal

If a task required a repeated debug loop (3+ attempts on the same error, or 2 consecutive failing runs with the same root cause), update .onex/memory/journal.md with: exact symptom, root cause, validated solution, commands/tests used, reusable keywords, and affected files. Do not add trivial fixes or duplicates.