Document agent instruction model and hierarchy in project arc42 architecture

[dieterbaier]

Goal

Ensure that the three-tier agent instruction hierarchy introduced in PR #29 is documented in the toolkit's own architecture documentation (arc42), making the mental model and design rationale explicit, discoverable, and verifiable by both AI agents and human reviewers.

Rationale

The toolkit's core mission is to provide:

• Agent-agnostic skills that can guide any AI tool (GitHub Copilot, local agents, code generators)
• Well-structured architecture documentation that serves as the single source of truth for project workflows
• Structured SDL (Secure Development Lifecycle) practices through explicit, machine-readable architecture

PR #29 introduces a significant architectural decision: a three-tier instruction hierarchy (global → project → skill → toolkit). This design is documented in individual skill files and templates, but it should also be present in the toolkit's own arc42 architecture documentation so that:

1. The architecture is self-describing: New users and consuming projects can read the toolkit's own arc42 docs to understand how instruction hierarchies work
2. Agents can verify alignment: Agents reading the arc42 docs can validate that project-specific instructions follow the documented pattern
3. SDL workflows are explicit: The documentation makes clear how instructions relate to secure development practices and traceability
4. Future enhancements are grounded in architecture: Follow-up improvements (like diagrams, examples, and update mechanisms) reference the architectural model

First Step: Audit Existing Architecture Documentation

Before adding or restructuring architecture docs, check whether:

• src/docs/arc42/ already contains sections explaining agent instruction models or instruction precedence
• The toolkit's own AGENTS.md (if it exists) is included or referenced in the arc42 documentation
• Sections on "Skills & Extensions" or similar explain how skills, templates, and instruction contracts work
• The decision model or design rationale for the three-tier hierarchy is documented anywhere in src/docs/
• Arc42 chapters 2 (Constraints), 4 (Solution Strategy), or 8 (Concepts) might be appropriate places to add this content

If documentation exists, assess whether it clearly conveys the agent instruction hierarchy and its design rationale.

Implementation

If gaps are found, enhance the arc42 architecture documentation to include:

1. In Arc42 Chapter 4 (Solution Strategy) or Chapter 8 (Concepts):

   • A section explaining "Agent Instruction Hierarchy" or "Agent Configuration Model"
   • The three tiers: global (user's local installation) → project-specific → toolkit defaults
   • Design rationale: why this hierarchy exists and how it enables both agent agnosticism and project customization
   • Link to the three template files and their roles

2. In Arc42 Chapter 2 (Constraints) or Chapter 5 (Building Block View):

   • A structural view or decision tree showing how agents discover and apply instructions
   • Which instruction level applies in which contexts (standalone project vs. toolkit consumer vs. developer using a local agent)
   • How instruction precedence prevents conflicts and duplication

3. In a dedicated skill or section:

   • Explicit relationship between "agent instructions" and "SDL workflows"
   • How instruction hierarchy enforces security and traceability practices
   • Examples of how consuming projects define their own instruction layer without forking the toolkit

4. Visual aids (diagrams, flowcharts, or tables):

   • Directory structure showing where each instruction tier lives
   • Decision tree showing instruction precedence
   • Reference to PlantUML or ASCII diagrams (consistent with toolkit style)

5. Traceability and relations:

   • Link architectural concepts to the related issues (Add visual diagram for agent instruction hierarchy #30, Link agent instruction templates from main README for discoverability #31, Add or enhance example usage guide for agent instruction templates #32) and PR Global agent instructions added as templates #29 via metadata relations
   • Document how the instruction model relates to existing metamodel concepts (artifacts, relations, generated fragments)

Definition of Done

• Audit complete; current arc42 coverage documented in issue comments
• Arc42 sections enhanced or created to document the agent instruction hierarchy
• Design rationale (why this model) is explained alongside the "how" (how it works)
• Architecture documentation includes visual aids (diagram or flowchart)
• Architecture documentation is discoverable from the main README or AGENTS.md
• SDL and traceability benefits of the model are made explicit
• Consuming projects can read the toolkit's own arc42 docs to understand how to structure their project instructions
• Root arc42 validation and render checks pass