Instruction System Reference

Quick Start (TL;DR)

Instructions are evaluated from highest to lowest priority.
Hard constraints (must/never/forbidden) are binding unless superseded by a higher-priority source.
Path-scoped instructions apply only to files inside their subtree.
When instructions conflict, precedence and specificity decide the final behavior.
If blocked, continue with the safest compliant fallback and state what happened.

1) Instruction Sources and Priority

Priority	Source	What it controls	Override behavior
1 (highest)	System instructions	Global policy, safety rules, core behavior, policy limitations.	Overrides all lower-priority sources.
2	Developer instructions	Task workflow, tool usage requirements, output formatting requirements.	Overrides user and repository-local guidance.
3	User instructions	Requested deliverable, target files, desired outcome.	Overrides repo-local conventions when no higher-level conflict exists.
4	Repository-local instructions (for example, AGENTS.md)	Code style, folder-level rules, testing notes, PR conventions.	Overrides lower conventions within its scope; cannot override higher layers.
5 (lowest)	Defaults and conventions	General style assumptions when no explicit instruction exists.	Always yields to explicit instructions.

2) Scope Rules for Path-Based Instruction Files

Instruction files like AGENTS.md apply to the entire directory tree rooted at their location.
More deeply nested instruction files have higher precedence for files in their subtree.
Only touched files must comply with applicable scoped instructions.
Direct system/developer/user instructions still take precedence over path-scoped files.

Example Scope Tree

repo/ ├── AGENTS.md # applies to everything in repo/ ├── frontend/ │ ├── AGENTS.md # overrides repo AGENTS for frontend/** │ └── src/app.js └── backend/ └── api/server.js

In this example, edits to frontend/src/app.js follow frontend/AGENTS.md first, then fall back to repo-level guidance only where non-conflicting.

3) Instruction Types and How to Interpret Them

A) Hard constraints

Terms like must, do not, never, and strictly forbidden are mandatory.

B) Conditional constraints

Rules in the form "if X, then Y" only apply when condition X is true. Document both trigger and required action.

C) Preference guidance

Terms like prefer and use judgment are advisory and should be followed unless they conflict with stronger rules.

D) Output formatting rules

Required output templates, headings, and symbols are compliance requirements and should be followed exactly.

4) Conflict Resolution Algorithm

Collect all active instructions from all sources.
Sort by precedence (system → developer → user → scoped repo files → defaults).
Apply hard constraints first.
Filter scoped instructions by touched file path.
Resolve direct conflicts by higher source priority, then by narrower scope specificity.
If ambiguity remains, choose the safest compliant interpretation and state assumptions in the response.

5) Worked Conflict Examples

Example A: User preference vs developer requirement

Input: User asks for plain text. Developer requires markdown template output.

Resolution: Use markdown template output (developer instruction has higher priority).

Example B: Nested scoped files

Input: Root AGENTS says "2-space indent"; nested AGENTS says "4-space indent".

Resolution: Files in nested subtree use 4 spaces; files outside use 2 spaces.

Example C: Preference vs hard rule

Input: "Prefer command A" and "Never run command A with flag --unsafe".

Resolution: Hard prohibition wins; use safe variant or fallback.

6) Execution Workflow

Read request and identify deliverable.
Locate applicable instruction sources and scoped files.
Build a short execution plan.
Implement edits with scope-compliant style and structure.
Run checks/tests aligned with instructions.
Prepare final response in required template.
Verify no forbidden actions or missing required steps remain.

7) Output Template Requirements

Use exact heading names when required.
Include testing/check sections when required by instruction source.
Apply any mandated status symbols, checklists, or citation style exactly.
Do not include optional sections if an instruction explicitly prohibits them.

8) Tooling and Environment Constraints

Use only approved tools and workflows permitted by active instructions.
Respect sandbox and approval policies from the runtime environment.
If a required tool is unavailable, continue with best fallback and clearly report limitations.
Never introduce prohibited workarounds (for example, installing disallowed dependencies).

9) Skill Usage Rules

If a named or clearly matching skill exists, use it for that turn.
Load only the parts of skill documentation required for the current task.
If multiple skills match, choose the minimum set needed and state sequence.
If skill files are missing or blocked, report briefly and proceed with compliant fallback.

10) Failure Handling and Fallbacks

Missing file: note missing asset and continue with best available input.
Conflicting requirements: apply precedence algorithm and explain result.
Unavailable command/tool: report constraint and run alternative checks.
Ambiguous request: choose conservative compliant interpretation and document assumptions.

11) End-of-Task Compliance Checklist

[ ] All applicable instruction sources identified and applied.
[ ] Scope and nested precedence rules validated for touched files.
[ ] Hard constraints satisfied without violation.
[ ] Required output format followed exactly.
[ ] Checks/tests executed and reported.
[ ] Fallbacks explained where limitations existed.