Add visual diagram for agent instruction hierarchy

[dieterbaier]

Goal

Create a clear, visual representation (diagram or flowchart) that illustrates the three-tier agent instruction hierarchy introduced in PR #29, making the mental model intuitive and accessible to new users and consuming projects.

Rationale

PR #29 establishes an important conceptual model:

1. Global agent instructions (user's local installation: ~/.vibe/AGENTS.md)
2. Project-specific instructions (consuming project's AGENTS.md)
3. GitHub Copilot instructions (consuming project's .github/copilot-instructions.md)
4. Toolkit instructions (toolkit repository as fallback source of truth)

The priority and flow (which level overrides which) is well explained in text, but a visual diagram could make this much clearer and faster to understand, especially for:

• New users encountering the toolkit for the first time
• Teams deciding how to structure their own project instructions
• Documentation or onboarding materials

First Step: Check Existing Diagrams

Before creating a new diagram, check whether:

• Any existing diagrams or flowcharts in the repository already illustrate instruction precedence or agent behavior
• Any documentation (architecture docs, ADRs, READMEs) already contains visual examples of instruction hierarchy
• The toolkit's own architecture documentation (src/docs/, if it exists) shows how agents should process instructions

If diagrams exist, assess whether they clearly communicate the new three-tier model.

Implementation

If no suitable diagram exists or the existing ones need updating, create:

1. A flowchart or decision tree showing:

   • The priority/execution order of instructions (global → project → skill → toolkit)
   • Which instructions override which
   • When agents should fall back to toolkit defaults
   • Examples of what happens at each level

2. Optionally, a supporting diagram showing:

   • Directory structure of instructions across local and project environments
   • Visual mapping of which instructions apply to which tools (GitHub Copilot, Vibe, Codex, etc.)

3. Integration point:

   • Add the diagram to the appropriate arc42 documentation of the project
   • Add the diagram to AGENTS.md and/or the main README (if possible, reuse the diagram from the arc42 documenation instead of duplicating it)
   • Link to it from templates/agents/README.md (if created per the other improvement issue)

Format Suggestion

• Recommended: PlantUML flowchart or UML diagram (consistent with toolkit style for AsciiDoc)
• Alternative: Mermaid diagram, ASCII art, or SVG

Definition of Done

• Audit complete; existing diagrams (if any) documented in issue comments
• Visual diagram created or updated
• Diagram is placed in accessible documentation (AGENTS.md, main README, or templates guide)
• Diagram is tested for clarity with at least one peer review