| name | repo-understanding-repository-architecture |
| description | Six-layer governance hierarchy (Vision → Principles → Conventions → Development → Agents → Workflows). Use when understanding repository structure, tracing rules to foundational values, explaining architectural decisions, or navigating layer relationships. |
Repository Architecture - Six-Layer Hierarchy
This Skill provides guidance on the six-layer architecture governing the open-sharia-enterprise repository. Each layer builds on the foundation above, creating complete traceability from vision to workflows.
Purpose
Use this Skill when:
- Understanding repository governance structure
- Tracing rules back to foundational values
- Explaining architectural decisions
- Navigating layer relationships
- Creating new conventions or practices
- Understanding where Skills fit in the architecture
The Six Layers
Layer 0: Vision WHY WE EXIST (foundational purpose)
Layer 1: Principles WHY - Values (governs L2, L3)
Layer 2: Conventions WHAT - Doc Rules (governs L3, L4)
Layer 3: Development HOW - Practices (governs L4)
Layer 4: AI Agents WHO - Executors (atomic tasks)
Layer 5: Workflows WHEN - Orchestrate (multi-step processes)
Key relationships:
- Vision inspires Principles
- Principles govern Conventions and Development
- Conventions govern Development and Agents
- Development governs Agents
- Workflows orchestrate Agents
Quick Layer Reference
| Layer | Location | Purpose | Changes? | Answers? |
|---|
| 0 | repo-governance/vision/ | WHY we exist | Extremely rare | Why does project exist? |
| 1 | repo-governance/principles/ | WHY we value approaches | Rarely | Why value this approach? |
| 2 | repo-governance/conventions/ | WHAT documentation rules | Occasionally | What documentation rules? |
| 3 | repo-governance/development/ | HOW we develop software | More frequently | How develop software? |
| 4 | .claude/agents/ | WHO enforces rules | Often | Who enforces rules? |
| 5 | repo-governance/workflows/ | WHEN run agents in what order | As needed | When run which agents? |
Layer 0: Vision (WHY WE EXIST)
Purpose: Foundational purpose - WHY the project exists and WHAT change we seek.
Location: repo-governance/vision/
Key Document: Vision - Open Sharia Enterprise
Core Vision:
- Democratize Shariah-compliant enterprise
- Make Islamic finance accessible to everyone
- Open-source halal solutions anyone can use
Characteristics:
- Immutable foundational purpose
- Changes extremely rarely
- All other layers serve this vision
Layer 1: Principles (WHY - Values)
Purpose: Foundational values that govern all conventions and development practices.
Location: repo-governance/principles/
Key Document: Core Principles Index
Principles (abbreviated):
- Deliberate Problem-Solving
- Root Cause Orientation
- Simplicity Over Complexity
- Accessibility First
- Documentation First
- No Time Estimates
- Progressive Disclosure
- Automation Over Manual
- Explicit Over Implicit
- Immutability Over Mutability
- Pure Functions Over Side Effects
- Reproducibility First
Requirements:
- Each principle MUST include "Vision Supported" section
- Stable, rarely change
- Govern both L2 (Conventions) and L3 (Development)
Example Traceability:
Vision: "Accessible to everyone"
↓ inspires
Principle: Accessibility First
↓ governs
Convention: Color Accessibility Convention
Development: AI Agents Convention — agent colors use accessible palette
Layer 2: Conventions (WHAT - Documentation Rules)
Purpose: Documentation standards implementing core principles. Defines WHAT rules for writing, organizing, formatting documentation.
Location: repo-governance/conventions/
Key Document: Conventions Index
Scope:
- docs/ directory (all markdown)
- crud-fs-ts-nextjs (Next.js), crud-fs-ts-nextjs (Next.js)
- plans/ directory
- README files
Example Conventions:
- File Naming Convention
- Linking Convention
- Color Accessibility Convention
- Content Quality Principles
- Diátaxis Framework
Requirements:
- Each convention MUST include "Principles Implemented/Respected" section
- Implemented by AI agents (Layer 4)
- Changes more frequently than principles
Layer 3: Development (HOW - Software Practices)
Purpose: Software practices implementing core principles. Defines HOW we develop, test, deploy software.
Location: repo-governance/development/
Key Document: Development Index
Scope:
- Source code (JS, TS, future: Java, Kotlin, Python)
- Next.js 16 web applications (crud-fs-ts-nextjs, crud-fs-ts-nextjs)
- Build systems and tooling
- AI agents (.claude/agents/ primary, .opencode/agents/ auto-generated secondary)
- Git workflows
Example Practices:
- Trunk Based Development
- Code Quality Convention (git hooks)
- AI Agents Convention
- Maker-Checker-Fixer Pattern
- Implementation Workflow
Requirements:
- Each practice MUST include BOTH "Principles Implemented/Respected" AND "Conventions Implemented/Respected" sections
- Implemented by AI agents and automation
- Changes more frequently than conventions
Layer 4: AI Agents (WHO - Executors)
Purpose: Automated implementers enforcing conventions and development practices.
Location: .claude/agents/ (primary; .opencode/agents/ is auto-generated secondary)
Key Document: Agents Index
Agent Families:
- Makers (Blue) - Create/update content
- Checkers (Green) - Validate quality
- Fixers (Purple/Yellow) - Apply validated fixes
- Navigation - Manage structure
- Operations - Deploy and manage
Characteristics:
- Each agent enforces specific conventions/practices
- Atomic - one clear responsibility
- Frontmatter: name, description, tools, model, color
Example Traceability:
Convention: Color Accessibility
↓ implemented by
Agent: docs-checker (validates colors)
Agent: docs-fixer (applies corrections)
Layer 5: Workflows (WHEN - Multi-Step Processes)
Purpose: Orchestrated multi-step processes composing AI agents.
Location: repo-governance/workflows/
Key Document: Workflows Index
Workflow Families:
- Maker-Checker-Fixer (content quality)
- Check-Fix (iterative validation)
- Plan-Execute-Validate (planning)
Characteristics:
- Define sequences (sequential/parallel/conditional)
- Manage state between steps
- Include human approval checkpoints
- Clear termination criteria
Example:
Maker-Checker-Fixer Workflow:
1. Maker creates → draft
2. Checker validates → audit report
3. User reviews → approve/reject
4. Fixer applies fixes → corrected
5. Terminate: all findings resolved
Complete Traceability Example
Color Accessibility (Vision → Agents)
L0 - Vision: Democratize Islamic enterprise → accessible to everyone
L1 - Principle: Accessibility First
- Vision supported: Accessible tools enable global participation
- Key value: Universal access from start
L2 - Convention: Color Accessibility Convention
- Implements: Accessibility First
- Rule: Verified color-blind friendly palette
- WCAG AA compliance required
L3 - Development: AI Agents Convention
- Respects: Color Accessibility Convention
- Practice: Agent colors use accessible palette
- Implementation: Frontmatter
color field limited
L4 - Agents:
- docs-checker - Validates diagram colors
- docs-fixer - Applies color corrections
- agent-maker - Validates agent frontmatter colors
L5 - Workflow: Maker-Checker-Fixer
- Orchestrates: maker → checker → fixer
- Ensures: All diagrams use accessible colors
Where Skills Fit in the Architecture
IMPORTANT: Skills are delivery infrastructure, NOT a governance layer.
Skills sit alongside CLAUDE.md, AGENTS.md and direct references as delivery mechanisms, operating in two distinct modes:
Inline Skills (Knowledge Delivery)
Default behavior - Progressive knowledge injection:
Knowledge Flow (Inline):
L2: Conventions ──┬── CLAUDE.md/AGENTS.md (startup) ──> Claude/OpenCode
├── Skills inline (on-demand) ────> Current conversation
└── Direct refs (explicit) ───────> L4: Agents
L3: Development ──┬── CLAUDE.md/AGENTS.md (startup) ──> Claude/OpenCode
├── Skills inline (on-demand) ────> Current conversation
└── Direct refs (explicit) ───────> L4: Agents
Characteristics:
- Progressive disclosure (name/description → full content on-demand)
- Inject convention/development knowledge into current conversation
- Enable knowledge composition (multiple skills work together)
- Serve agents but don't govern them
Fork Skills (Task Delegation)
Delegation behavior with context: fork:
Delegation Flow (Fork):
Skills (context: fork) ──delegates to──> Isolated Agent Context
──returns──> Summarized Results
──to──> Main Conversation
Characteristics:
- Spawn isolated subagent contexts for focused work
- Delegate specialized tasks (research, analysis, exploration)
- Act as lightweight orchestrators
- Return results to main conversation
- Still service relationship (not governance)
Key insight: Skills SERVE agents through two modes:
- Inline skills - Deliver knowledge from L2/L3 to current conversation
- Fork skills - Delegate tasks to agents in isolated contexts
- Neither mode governs agents (service relationship, not governance)
Governance test:
- Conventions → Agents: Yes (agents MUST follow conventions)
- Development → Agents: Yes (agents MUST follow practices)
- Skills (inline) → Agents: No (inject knowledge, serve agents)
- Skills (fork) → Agents: No (delegate tasks, serve agents)
Best Practices
When Creating New Conventions
- Check principles first - Which principle does this implement?
- Add traceability section - "Principles Implemented/Respected"
- Document in Conventions Index - Add to README.md
- Consider agent impact - Which agents need to enforce this?
When Creating New Development Practices
- Check both principles AND conventions - What do you implement/respect?
- Add both traceability sections - Principles AND Conventions
- Document in Development Index - Add to README.md
- Consider automation - Git hooks? AI agents?
When Creating New Agents
- Identify governing layers - Which conventions/practices does this enforce?
- Define atomic responsibility - One clear purpose
- Choose tools carefully - Match to task (Read-only, Write, Edit, Bash)
- Document in Agents Index - Add to README.md
When Creating Workflows
- Identify agent sequence - What agents needed, in what order?
- Define termination criteria - When does workflow complete?
- Add approval checkpoints - Where does user review?
- Document state management - How does state flow between steps?
Common Misconceptions
Misconception 1: "Skills are Layer 4.5"
❌ Wrong: Skills are not a layer between Development and Agents.
✅ Correct: Skills are delivery infrastructure (like AGENTS.md), not governance layer.
Misconception 2: "Agents can ignore conventions if skilled"
❌ Wrong: Skills provide knowledge but don't override governance.
✅ Correct: Agents MUST follow conventions. Skills help agents understand conventions better.
Misconception 3: "Workflows replace agents"
❌ Wrong: Workflows don't replace agents, they orchestrate them.
✅ Correct: Workflows compose multiple agents into multi-step processes.
Misconception 4: "Principles can conflict"
❌ Wrong: Principles sometimes contradict each other.
✅ Correct: Principles complement each other. Apparent conflicts require nuanced application, not choosing one over another.
References
Related Skills
maker-checker-fixer-pattern - Understanding the three-stage quality workflow (fits in L3 Development)color-accessibility-diagrams - Example of L2 Convention implemented through Skills deliverytrunk-based-development (Phase 2) - Example of L3 Development practice
Note: This Skill provides architectural overview. The authoritative Repository Architecture document contains complete traceability examples, detailed layer characteristics, and usage guidance.
