docs: Restructure documentation

RajShinhCapgem · web-flow · commit 5002214cdb44 · 2025-09-19T10:32:53.000+01:00
Squash-merge via GitHub CLI per repo guidelines (trunk-based, squash &amp; delete feature branch).
diff --git a/.github/chatmodes/CodeReviewer.chatmode.md b/.github/chatmodes/CodeReviewer.chatmode.md
@@ -1,14 +1,14 @@
 ---
-description: 'Code Review Mode'
+description: 'Code Reviewer Mode'
 tools: ['codebase', 'search', 'usages', 'problems', 'changes']
 ---
 
-# Code Review Mode Instructions
+# Code Reviewer Mode Instructions
 
-You are in Code Review Mode. Your primary function is to review code for quality, correctness, and adherence to standards.
+You are in Code Reviewer Mode. Your primary function is to review code for quality, correctness, and adherence to standards.
 
 <!--
-Purpose: Define Code Review Mode behavior and constraints. Treat sections below as rules for conducting effective reviews.
+Purpose: Define Code Reviewer Mode behavior and constraints. Treat sections below as rules for conducting effective reviews.
 How to interpret: Focus on reviewing changes; do not implement code. Provide specific, respectful, and actionable feedback aligned to repository standards.
 -->
 
diff --git a/.github/chatmodes/Developer.chatmode.md b/.github/chatmodes/Developer.chatmode.md
@@ -1,5 +1,6 @@
 ---
-description: 'Code Review Mode'
+description: 'Developer Mode'
+
 tools: ['codebase', 'usages', 'problems', 'changes', 'testFailure', 'terminalSelection', 'terminalLastCommand', 'openSimpleBrowser', 'fetch', 'findTestFiles', 'searchResults', 'githubRepo', 'todos', 'editFiles', 'runNotebooks', 'search', 'new', 'runCommands', 'runTasks']
 ---
 
diff --git a/.github/chatmodes/Tester.chatmode.md b/.github/chatmodes/Tester.chatmode.md
@@ -1,9 +1,9 @@
 ---
-description: 'Testing Mode'
+description: 'Tester Mode'
 tools: ['codebase', 'search', 'editFiles', 'usages', 'problems', 'changes', 'terminalSelection', 'terminalLastCommand', 'runCommands']
 ---
 
-# Testing Mode Instructions
+# Tester Mode Instructions
 
 <!--
 Purpose: Define the Testing Mode behavior and constraints. Treat sections below as rules for how to propose, write, and maintain tests.
diff --git a/.github/instructions/README.md b/.github/instructions/README.md
@@ -93,6 +93,5 @@ Bad:  # Architecture
 
 ---
 
-If you want, I can add a small JSON Schema and a CI workflow that validates instruction frontmatter on PRs.
 
  
diff --git a/README.md b/README.md
@@ -2,7 +2,6 @@
 
 Welcome! This repository is a GitHub Template created by Capgemini. It provides practical, portable, and useful examples of GitHub Copilot configuration for real-world projects.
 
-
 ## Who this is for
 - Developers and teams adopting AI-assisted development
 - Project and technical leads seeking practical best practices
@@ -22,7 +21,86 @@ Welcome! This repository is a GitHub Template created by Capgemini. It provides
 2. Review and adapt the example [chat modes](.github/chatmodes/README.md), [instructions](.github/instructions/README.md), and [prompts](.github/prompts/README.md).
 3. Read the project docs in [docs/README.md](docs/README.md).
 
-### Copying Copilot Customisations
+## Key Features and Functionalities
+
+### 1. Custom Chat Modes
+
+The repository includes specialized chat modes located in `.github/chatmodes/`:
+
+- **Developer Mode**: Focuses on test-driven development with quality gates and design-first methodology
+- **Planner Mode**: Provides structured planning with task breakdown and dependency management
+- **Documentation Mode**: Standardizes documentation creation following repository templates
+- **Code Reviewer Mode**: Implements systematic code review with best practices enforcement
+- **Tester Mode**: Emphasizes BDD-focused testing approach with comprehensive test coverage
+
+### 2. Reusable Prompt Templates
+
+Located in `.github/prompts/`, these templates provide standardized approaches for:
+
+- **`write-adr.prompt.md`**: Creates Architectural Decision Records with structured templates
+- **`write-prd.prompt.md`**: Generates Product Requirements Documents with measurable objectives
+- **`write-docs.prompt.md`**: Produces consistent documentation following repository standards
+- **`write-ears-spec.prompt.md`**: Creates requirements using Easy Approach to Requirements Syntax
+- **`copilot-setup-check.prompt.md`**: Evaluates and optimizes Copilot configuration
+
+### 3. Comprehensive Instruction System
+
+The `.github/instructions/` directory contains detailed guidelines for:
+
+- **`backend.instructions.md`**: Server-side development best practices
+- **`frontend.instructions.md`**: Client-side development guidelines
+- **`docs.instructions.md`**: Documentation creation and maintenance standards
+- **`bdd-tests.instructions.md`**: Behavior-driven development testing methodology
+
+### 4. Repository Structure & Templates
+
+The `docs/` directory provides organized templates for:
+
+- **ADRs** (`docs/ADRs/`): Architecture decision documentation with context and consequences
+- **PRDs** (`docs/PRDs/`): Product requirements with priorities and acceptance criteria
+- **Design Documents** (`docs/design/`): Technical design specifications
+- **Engineering Guidelines** (`docs/engineering/`): Development process documentation
+
+### 5. Project Planning Framework
+
+The `plans/` directory includes:
+
+- **Plan Templates**: Structured project planning with stakeholders and timelines
+- **Roadmap Management**: Strategic planning and milestone tracking
+- **TODO Management**: Task tracking and completion monitoring
+
+### 6. Workflow Integration
+
+#### Branching Strategy
+
+The repository enforces trunk-based development with:
+
+- Short-lived feature branches (maximum 3 days)
+- Mandatory pull request reviews
+- Squash and merge for clean history
+- Automatic branch cleanup
+
+#### Commit Conventions
+
+All commits must follow conventional commit format:
+
+```
+<type>: <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+Types include: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+#### Version Control
+
+- Tag major releases with semantic versioning
+- Maintain changelog for significant updates
+- Archive deprecated features in `plans/archive/`
+
+### 7. Copying Copilot Customisations
 
 The custom chatmodes, instructions and prompts can be copied into the same directory structure of another repository. Each file has comments that explain the approach, structure and content of each file.
 
@@ -44,6 +122,17 @@ Reuse and reference instructions files in your prompt files and chat modes to ke
 - Avoid embedding secrets or environment-specific data; reference where secure configs live (e.g., repo secrets, vault).
 - When in doubt, be explicit: busy users prefer exact commands/phrases to adapt rather than broad theory.
 
+### Adding New Features
+
+When adding new chat modes, prompts, or instructions:
+
+1. Follow existing naming conventions
+2. Include comprehensive documentation
+3. Add examples and usage guidelines
+4. Update this master documentation
+5. Test with multiple scenarios before finalizing
+
+
 ## Where to find more information
 
 - See `AGENTS.md` for general AI agent instructions and project context
@@ -56,3 +145,129 @@ You can find more about how to [customise and extend Github Copilot](https://doc
 
 You can find more examples of Copilot configuration in the [Awesome Copilot repository on Github.com](https://github.com/github/awesome-copilot/tree/main).
 
+# Document Reference Hierarchy
+
+This diagram shows how documents reference each other across the repository, mapping the interconnections between configuration files, instructions, prompts, documentation, and plans.
+
+```mermaid
+flowchart LR
+    %% Core Configuration Hub (Left)
+    subgraph CONFIG ["🏠 Core Configuration"]
+        CI["copilot-instructions.md"]
+        AGENTS["AGENTS.md"]
+        README["README.md"]
+    end
+
+    %% GitHub Configuration (Top Center)
+    subgraph GITHUB [".github/ Configuration"]
+        direction TB
+        
+        subgraph CHATMODES ["💬 Chat Modes"]
+            DOC["Documentation"]
+            PLAN["Planner"]
+            DEV["Developer"]
+            CR["CodeReview"]
+            TEST["Testing"]
+        end
+        
+        subgraph INSTRUCTIONS ["📋 Instructions"]
+            DOCINST["docs.instructions"]
+            BACKEND["backend.instructions"]
+            FRONTEND["frontend.instructions"]
+            BDD["bdd-tests.instructions"]
+        end
+        
+        subgraph PROMPTS ["🎯 Prompts"]
+            DOC_PROMPT["write-docs"]
+            ADR_PROMPT["write-adr"]
+            PRD_PROMPT["write-prd"]
+            EAR_PROMPT["write-ears"]
+            SETUP_PROMPT["setup-check"]
+        end
+    end
+
+    %% Content Directories (Right)
+    subgraph CONTENT ["📁 Content & Output"]
+        direction TB
+        
+        subgraph DOCS ["📖 Documentation"]
+            ADR_TEMPLATE["adr-template.md"]
+            PRD_TEMPLATE["prd-template.md"]
+            CODE_REVIEW["code-review-guidelines.md"]
+        end
+        
+        subgraph PLANS ["📅 Plans"]
+            PLAN_TEMPLATE["plan-template.md"]
+            TODO["TODO.md"]
+            ARCHIVE_PLAN["archived-plans"]
+        end
+    end
+
+    %% Primary Configuration Flow (Core → GitHub Config)
+    CI -.->|"references"| INSTRUCTIONS
+    CI -.->|"references"| DOCS
+    AGENTS -.->|"references"| PLANS
+
+    %% Chat Mode Integration (GitHub Config → Content)
+    DOC ==>|"uses templates"| ADR_TEMPLATE
+    DOC ==>|"uses templates"| PRD_TEMPLATE
+    DOC ==>|"follows rules"| DOCINST
+    
+    PLAN ==>|"uses template"| PLAN_TEMPLATE
+    PLAN ==>|"manages"| TODO
+    
+    DEV -.->|"references"| DOCS
+    DEV -.->|"references"| PLANS
+
+    %% Prompt → Template Relationships
+    DOC_PROMPT ==>|"generates"| DOCS
+    ADR_PROMPT ==>|"generates"| ADR_TEMPLATE
+    PRD_PROMPT ==>|"generates"| PRD_TEMPLATE
+    SETUP_PROMPT -.->|"validates"| CONFIG
+
+    %% Instruction → Content Rules
+    DOCINST ==>|"governs"| DOCS
+    BACKEND -.->|"applies to"| DOCS
+    FRONTEND -.->|"applies to"| DOCS
+
+    %% Archive References
+    ARCHIVE_PLAN -.->|"references"| CONFIG
+    ARCHIVE_PLAN -.->|"uses"| PLAN_TEMPLATE
+
+    %% Styling
+    classDef config fill:#e3f2fd,stroke:#1976d2,stroke-width:3px,color:#000
+    classDef chatmode fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000
+    classDef instruction fill:#e8f5e8,stroke:#388e3c,stroke-width:2px,color:#000
+    classDef prompt fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000
+    classDef content fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#000
+    classDef plan fill:#f1f8e9,stroke:#689f38,stroke-width:2px,color:#000
+
+    class CI,AGENTS,README config
+    class DOC,PLAN,DEV,CR,TEST chatmode
+    class DOCINST,BACKEND,FRONTEND,BDD instruction
+    class DOC_PROMPT,ADR_PROMPT,PRD_PROMPT,SETUP_PROMPT prompt
+    class ADR_TEMPLATE,PRD_TEMPLATE,CODE_REVIEW content
+    class PLAN_TEMPLATE,TODO,ARCHIVE_PLAN plan
+```
+
+## Key Reference Patterns
+
+### Central Configuration Hub
+- `.github/copilot-instructions.md` serves as the primary configuration document, referencing most instruction files and core documentation
+- `AGENTS.md` provides repository-wide context and references key directories and processes
+
+### Documentation Workflow
+- `Documentation.chatmode.md` heavily references documentation instructions and templates
+- `docs.instructions.md` defines standards for all documentation types and their storage locations
+- Prompt files like `write-adr.prompt.md` and `write-prd.prompt.md` reference their respective templates and directories
+
+### Planning Integration
+- `Planner.chatmode.md` integrates with the plans structure and references the plan template
+- Plans reference core configuration files and maintain the TODO workflow
+
+### Cross-Cutting Concerns
+- Engineering guidelines (`code-review-guidelines.md`, `pull-request-guidelines.md`) are referenced by the main configuration
+- Templates (`adr-template.md`, `prd-template.md`) are referenced by both instructions and prompts
+- Directory structures are consistently referenced across multiple configuration files
+
+This hierarchy shows how the repository maintains consistency through strategic cross-referencing, with clear patterns for documentation workflows, planning processes, and configuration management.
diff --git a/recommendations.md b/recommendations.md

Original file line number	Diff line number	Diff line change
`@@ -93,6 +93,5 @@ Bad: # Architecture`
`93`	`93`
`94`	`94`	`---`
`95`	`95`
`96`		`-If you want, I can add a small JSON Schema and a CI workflow that validates instruction frontmatter on PRs.`
`97`	`96`
`98`	`97`