diff --git a/README.md b/README.md index 1b8ad8a15..ef3daf538 100644 --- a/README.md +++ b/README.md @@ -4,31 +4,31 @@ A community-created collection of custom agents, instructions, skills, hooks, workflows, and plugins to supercharge your GitHub Copilot experience. > [!TIP] -> **Explore the full collection on the website โ†’** [awesome-copilot.github.com](https://awesome-copilot.github.com) +> **Explore the full collection on the website โ†’** [awesome-copilot.github.com](https://enel-gict-ptg.github.io/awesome-copilot/) > -> The website offers full-text search and filtering across hundreds of resources, plus the [Tools](https://awesome-copilot.github.com/tools) section for MCP servers and developer tooling, and the [Learning Hub](https://awesome-copilot.github.com/learning-hub) for guides and tutorials. +> The website offers full-text search and filtering across hundreds of resources, plus the [Tools](https://enel-gict-ptg.github.io/awesome-copilot//tools) section for MCP servers and developer tooling, and the [Learning Hub](https://enel-gict-ptg.github.io/awesome-copilot//learning-hub) for guides and tutorials. > -> **Using this collection in an AI agent?** A machine-readable [`llms.txt`](https://awesome-copilot.github.com/llms.txt) is available with structured listings of all agents, instructions, and skills. +> **Using this collection in an AI agent?** A machine-readable [`llms.txt`](https://enel-gict-ptg.github.io/awesome-copilot//llms.txt) is available with structured listings of all agents, instructions, and skills. ## ๐Ÿ“– Learning Hub -New to GitHub Copilot customization? The **[Learning Hub](https://awesome-copilot.github.com/learning-hub)** on the website offers curated articles, walkthroughs, and reference material โ€” covering everything from core concepts like agents, skills, and instructions to hands-on guides for hooks, agentic workflows, MCP servers, and the Copilot coding agent. +New to GitHub Copilot customization? The **[Learning Hub](https://enel-gict-ptg.github.io/awesome-copilot//learning-hub)** on the website offers curated articles, walkthroughs, and reference material โ€” covering everything from core concepts like agents, skills, and instructions to hands-on guides for hooks, agentic workflows, MCP servers, and the Copilot coding agent. ## What's in this repo | Resource | Description | Browse | |----------|-------------|--------| -| ๐Ÿค– [Agents](docs/README.agents.md) | Specialized Copilot agents that integrate with MCP servers | [All agents โ†’](https://awesome-copilot.github.com/agents) | -| ๐Ÿ“‹ [Instructions](docs/README.instructions.md) | Coding standards applied automatically by file pattern | [All instructions โ†’](https://awesome-copilot.github.com/instructions) | -| ๐ŸŽฏ [Skills](docs/README.skills.md) | Self-contained folders with instructions and bundled assets | [All skills โ†’](https://awesome-copilot.github.com/skills) | -| ๐Ÿ”Œ [Plugins](docs/README.plugins.md) | Curated bundles of agents and skills for specific workflows | [All plugins โ†’](https://awesome-copilot.github.com/plugins) | -| ๐Ÿช [Hooks](docs/README.hooks.md) | Automated actions triggered during Copilot agent sessions | [All hooks โ†’](https://awesome-copilot.github.com/hooks) | -| โšก [Agentic Workflows](docs/README.workflows.md) | AI-powered GitHub Actions automations written in markdown | [All workflows โ†’](https://awesome-copilot.github.com/workflows) | +| ๐Ÿค– [Agents](docs/README.agents.md) | Specialized Copilot agents that integrate with MCP servers | [All agents โ†’](https://enel-gict-ptg.github.io/awesome-copilot//agents) | +| ๐Ÿ“‹ [Instructions](docs/README.instructions.md) | Coding standards applied automatically by file pattern | [All instructions โ†’](https://enel-gict-ptg.github.io/awesome-copilot//instructions) | +| ๐ŸŽฏ [Skills](docs/README.skills.md) | Self-contained folders with instructions and bundled assets | [All skills โ†’](https://enel-gict-ptg.github.io/awesome-copilot//skills) | +| ๐Ÿ”Œ [Plugins](docs/README.plugins.md) | Curated bundles of agents and skills for specific workflows | [All plugins โ†’](https://enel-gict-ptg.github.io/awesome-copilot//plugins) | +| ๐Ÿช [Hooks](docs/README.hooks.md) | Automated actions triggered during Copilot agent sessions | [All hooks โ†’](https://enel-gict-ptg.github.io/awesome-copilot//hooks) | +| โšก [Agentic Workflows](docs/README.workflows.md) | AI-powered GitHub Actions automations written in markdown | [All workflows โ†’](https://enel-gict-ptg.github.io/awesome-copilot//workflows) | | ๐Ÿณ [Cookbook](cookbook/README.md) | Copy-paste-ready recipes for working with Copilot APIs | โ€” | ## ๐Ÿ› ๏ธ Tools -Looking at how to use Awesome Copilot? Check out the **[Tools section](https://awesome-copilot.github.com/tools)** of the website for MCP servers, editor integrations, and other developer tooling to get the most out of this collection. +Looking at how to use Awesome Copilot? Check out the **[Tools section](https://enel-gict-ptg.github.io/awesome-copilot//tools)** of the website for MCP servers, editor integrations, and other developer tooling to get the most out of this collection. ## Install a Plugin diff --git a/plugins/enel-gict/README.md b/plugins/enel-gict/README.md new file mode 100644 index 000000000..8fb5ee8f9 --- /dev/null +++ b/plugins/enel-gict/README.md @@ -0,0 +1,3 @@ +# Enel GICT Skills + +Concise Enel GICT skill pack for Reference Architectures (RA), Architecture Decision Records (ADR), Operating Procedures (OP), and Enel Design System guidance to align delivery and governance. diff --git a/plugins/enel-gict/skills/adr/SKILL.md b/plugins/enel-gict/skills/adr/SKILL.md new file mode 100644 index 000000000..4bf2e16d4 --- /dev/null +++ b/plugins/enel-gict/skills/adr/SKILL.md @@ -0,0 +1,275 @@ +--- +name: adr +description: 'Create, update, or review an Architecture Decision Record (ADR) or a Gap Analysis document following the format used in this repository under docs/ADR/. Use when the user asks to write an ADR, document a technology decision, evaluate tool alternatives, perform a buy-vs-make analysis, compare open-source alternatives to proprietary tools, select a vendor/platform, or record a technical decision. Covers OP35 narrative 6.0 (Buy or Make Decisional Framework), OP36 design-by-default compliance checks (Cyber Security, WCAG, GDPR/Privacy, Intellectual Property, Adoption), and the decision record template with context, decision drivers, candidates, comparative assessment, SWOT, and recommendation.' +--- + +# ADR Authoring Skill + +You are an expert enterprise architect and technology evaluator for the GICT organization. Your job is to produce a complete Architecture Decision Record (ADR) or Gap Analysis following the exact conventions used in this repository under `docs/ADR/`. + +## When to Use This Skill + +- User asks to write an ADR or document a technology decision +- User asks to evaluate tool alternatives or perform a buy-vs-make analysis +- User asks to compare open-source alternatives to proprietary tools +- User asks to select a vendor or platform +- User mentions "ADR", "gap analysis", "vendor selection", "buy vs make", "OSS alternative", or "tool comparison" +- User needs OP35/OP36 compliance checklists in a decision record + +## Prerequisites + +- This repository opened as the active workspace +- Familiarity with `docs/ADR/` folder and existing ADRs +- Access to official documentation for candidate tools/vendors (the skill will fetch these) + +## Context + +This repository maintains ADRs and gap analyses under `docs/ADR/`. These documents record technology choices, vendor evaluations, open-source versus proprietary assessments, and buy-or-make decisions. + +ADRs in this repository operate within two governing Organizational Procedures: + +- **[OP35 โ€” Digital Initiatives Activation](in the source repository documentation/OP35-Digital-Initiatives-Activation.md)**: Mandates a "Buy or Make Decisional Framework" (narrative 6.0) and requires TA&CS Delivery/T&A involvement for all technical evaluations at initiative activation. +- **[OP36 โ€” Solutions Development & Release Management](in the source repository documentation/OP36-Solutions-Development-Release-Management.md)**: Requires design-by-default compliance across Cyber Security, Digital Accessibility (WCAG), Personal Data Protection (GDPR/DPIA), Intellectual Property, Adoption, and Quality Management for all Projects and Changes. + +## Before You Start + +1. **Read existing ADRs** โ€” scan `docs/ADR/` to understand conventions and avoid duplication. +2. **Ask clarifying questions** โ€” use the ask-questions tool to gather at minimum: + - **Subject** โ€” What is the technology, tool, or architectural decision being evaluated? + - **Trigger** โ€” Is this a Buy/Make decision (OP35 ยง6.0), OSS alternative evaluation, vendor selection, or architectural choice? + - **Scope** โ€” Which business unit, application, or digital object does this affect? + - **Blocking requirements** โ€” What are the hard mandatory requirements (e.g., ISO 27001, WCAG 2.1 AA, Salesforce integration, EU data residency)? + - **Candidates** โ€” Which tools, vendors, or options should be evaluated? + - **Status** โ€” Proposed, Accepted, Superseded, or Deprecated? +3. **Research** โ€” For each candidate, gather facts from official documentation, security certifications pages, and integration documentation. Every claim should reference a source. + +## When an ADR is Mandatory (OP35/OP36 Triggers) + +| Trigger | Source | Action | +|---|---|---| +| New digital initiative requires selecting a technology or vendor | OP35 ยง6.0 narrative | ADR with Buy/Make section | +| Existing proprietary tool under cost/OSS review | OP35 ยง6.0 + OSPO | Gap Analysis ADR | +| Architecture change that impacts infrastructure, middleware, or base SW | OP36 ยง4.1 (Change constraints) | ADR documenting the change scope | +| Solution with personal data processing (DPIA trigger) | OP36 ยง4.8 | ADR must include Privacy by Design assessment | +| Solution with user interface (WCAG requirement) | OP36 ยง4.7 | ADR must include Accessibility section | +| Innovative solution with non-standard security controls | OP35 ยง6.0 + OP36 ยง4.6 | ADR must include Cyber Security Risk section | +| Any solution involving third-party code or algorithms | OP36 ยง4.13 | ADR must include IP Assessment section | +| Product/platform change that replaces end-user tools | OP36 ยง4.9 | ADR must include Adoption KPI section | + +## Document Types + +### Type A โ€” Gap Analysis (OSS vs Proprietary) + +Used when evaluating open-source alternatives to existing proprietary tools. + +**Filename pattern:** `_gap_analysis.md` + +**Mandatory sections:** +1. Executive Summary table (blocking requirements vs each candidate) +2. Per-candidate analysis (source, license, model, requirements met/gaps) +3. OP35 compliance score (WCAG, ISO 27001/SOC 2, EU data residency, relevant integrations) +4. Architecture diagram (if proposing a composed OSS stack) +5. Final verdict with blocking gaps clearly marked + +### Type B โ€” Tool/Vendor Selection ADR + +Used when selecting among commercial or mixed candidates. + +**Filename pattern:** `_tool_selection.md` or `_vendor_selection.md` + +**Mandatory sections:** +1. Context and business activities table +2. Decision Drivers (weighted table) +3. Candidates table (vendor, product, HQ, founded, website) +4. Comparative Assessment โ€” Functional Coverage (table) +5. Comparative Assessment โ€” Non-Functional & Compliance (table) +6. SWOT Analysis per candidate +7. Recommendation with rationale + +### Type C โ€” Architectural Decision Record (Classic ADR) + +Used for architectural choices (patterns, platforms, integration strategies). + +**Filename pattern:** `__adr.md` or `_architecture_decision.md` + +**Mandatory sections:** +1. Status, Date, Scope +2. Context +3. Decision Drivers +4. Decision +5. Consequences (positive, negative, risks) +6. Compliance checklist (OP36 design-by-default) +7. Alternatives considered + +## Document Template + +### Header (all types) + +```markdown +# : +**Date:** <Month YYYY> +**Status:** <Proposed | Accepted | Superseded | Deprecated> +**Scope:** <What this covers and why it was triggered> +**OP Reference:** OP35 ยง6.0 | OP36 ยง<section> +``` + +### Executive Summary (Type A) + +```markdown +## Sintesi Esecutiva / Executive Summary + +### Assessed Candidates + +| Blocking Requirement | Tool A | Tool B | Tool C | +|---|---|---|---| +| <Requirement 1> | โœ… / โŒ / โš ๏ธ | ... | ... | +| **Verdict** | โœ… Suitable / โŒ Not suitable / โš ๏ธ Conditional | ... | ... | +``` + +### Context Section + +```markdown +## Context + +<Narrative explaining the current state, what problem is being solved, and which business activities are impacted.> + +| # | Activity | Responsible Unit | +|---|---|---| +| 1 | <activity> | <unit> | +``` + +### Decision Drivers Section + +```markdown +## Decision Drivers + +| # | Driver | Weight | +|---|---|---| +| D1 | **<Driver name>** โ€” <description> | Critical / High / Medium / Low | +``` + +### Comparative Assessment + +```markdown +## Comparative Assessment + +### Functional Coverage + +| Requirement | Candidate A | Candidate B | +|---|---|---| +| **<requirement>** | โœ… <note> | โŒ <note> | + +### Non-Functional & Compliance + +| Requirement | Candidate A | Candidate B | +|---|---|---| +| **GDPR compliance** | โœ… / โš ๏ธ / โŒ | ... | +| **WCAG 2.1 AA** | โœ… / โš ๏ธ / โŒ | ... | +| **ISO 27001 or equivalent** | โœ… / โš ๏ธ / โŒ | ... | +| **EU data residency** | โœ… / โš ๏ธ / โŒ | ... | +| **Cyber Security** | โœ… / โš ๏ธ / โŒ | ... | +| **IP Assessment** | โœ… / โš ๏ธ / โŒ | ... | +``` + +### OP36 Compliance Checklist + +Every ADR **must** include this checklist before the Recommendation section: + +```markdown +## OP36 Design-by-Default Compliance + +| OP36 Requirement | Status | Notes | +|---|---|---| +| **Cyber Security by Design** (ยง4.6, PL No. 17, OP No. 2420) | โœ… / โš ๏ธ / โŒ / N/A | | +| **Digital Accessibility (WCAG 2.1 AA)** (ยง4.7, PL No. 1142) | โœ… / โš ๏ธ / โŒ / N/A | | +| **Personal Data Protection by Design** (ยง4.8, PL No. 344) | โœ… / โš ๏ธ / โŒ / N/A | DPIA triggered? | +| **Adoption by Design** (ยง4.9) | โœ… / โš ๏ธ / โŒ / N/A | KPIs defined? | +| **Quality Management** (ยง4.11, ICT OI 3703) | โœ… / โš ๏ธ / โŒ / N/A | | +| **Intellectual Property by Design** (ยง4.13) | โœ… / โš ๏ธ / โŒ / N/A | IP Assessment for 3rd-party code? | +| **Buy or Make Decisional Framework** (OP35 ยง6.0) | โœ… / โš ๏ธ / โŒ / N/A | Included in Investment Memo? | +``` + +### SWOT Analysis + +```markdown +## SWOT Analysis โ€” <Candidate Name> + +| Strengths | Weaknesses | +|---|---| +| <strength> | <weakness> | + +| Opportunities | Threats | +|---|---| +| <opportunity> | <threat> | +``` + +### Recommendation Section + +```markdown +## Recommendation + +**Decision:** <Selected option and rationale in 2โ€“4 sentences.> + +**Conditions / Open Points:** +- <Any conditions that must be met before adoption> +- <Open items requiring follow-up (e.g., security certification verification, DPIA trigger)> + +**Next Steps:** +1. <Immediate action> +2. <Follow-up action> +``` + +## Blocker Classification + +Use consistent visual markers throughout the document: + +| Symbol | Meaning | +|---|---| +| โœ… | Requirement met | +| โŒ | **BLOCKING** โ€” requirement not met; disqualifies the candidate | +| โš ๏ธ | Conditional โ€” partially met or requires mitigation | +| N/A | Not applicable to this candidate/context | + +A candidate with **any โŒ on a Critical decision driver** must be marked as **Not Suitable** in the Executive Summary verdict. + +## Mandatory Involvements (OP35 ยง6.0) + +When producing an ADR that feeds into an Investment Memo, note which units must be involved: + +- **TA&CS Delivery / T&A** โ€” always involved in technical solution evaluation +- **Cyber Security** โ€” required for innovative solutions where security controls are not standardized +- **I&TS** โ€” required for infrastructure/telecom solutions not in the Service Catalog +- **P&C Applicant Unit** โ€” required for Business Initiatives financial evaluation +- **GICT Units affected** by the initiative โ€” for qualitative/quantitative perimeter information + +## Writing Conventions + +- Language: Match the primary language of the request (Italian or English); use English for technical terms and table headers +- Source links: Always cite vendor documentation, security pages, and GitHub repositories +- Dates: Use `Month YYYY` format (e.g., `March 2026`, `Marzo 2026`) +- File naming: lowercase with underscores, descriptive slug (e.g., `survey_platform_gap_analysis.md`) +- Costs: Include annual cost when evaluating proprietary vs OSS trade-offs +- Version: Not required in ADR body; use git history for versioning + +## Gap Analysis Architecture Diagrams + +For composed OSS stacks (Type A), include an ASCII architecture diagram showing: + +``` +[Input / Source System] + โ”‚ + [Core Component] โ†โ”€โ”€โ”€โ”€ <what it does> + โ”‚ + [Storage Layer] + โ”œโ”€โ”€โ”€โ”€ [Component A] โ†’ <role> + โ”œโ”€โ”€โ”€โ”€ [Component B] โ†’ <role> + โ””โ”€โ”€โ”€โ”€ [Component C] โ†’ <role> (custom, estimated effort) + โ”‚ + [Identity / SSO] โ†’ SSO for all layers +``` + +## References + +- [OP35 โ€” Digital Initiatives Activation](in the source repository documentation/OP35-Digital-Initiatives-Activation.md) +- [OP36 โ€” Solutions Development & Release Management](in the source repository documentation/OP36-Solutions-Development-Release-Management.md) +- Existing ADRs: [docs/ADR/](in the source repository documentation/ADR/) diff --git a/plugins/enel-gict/skills/enel-design-system/SKILL.md b/plugins/enel-gict/skills/enel-design-system/SKILL.md new file mode 100644 index 000000000..09cab97cf --- /dev/null +++ b/plugins/enel-gict/skills/enel-design-system/SKILL.md @@ -0,0 +1,100 @@ +--- +name: enel-design-system +description: 'Enel Design System theme for Zensical documentation sites. Use when modifying colors, typography, layout, dark mode, or Zensical theme overrides. Covers CSS custom properties, light/dark palette configuration, tab bar styling, card components, button styles, and MkDocs Material theme integration. Triggers on requests like "change theme colors", "update dark mode", "fix styling", "adjust typography", or "modify Zensical theme".' +--- + +# ENEL Design System โ€” Zensical Theme + +## When to Use This Skill + +- User asks to modify theme colors, typography, or layout in the documentation site +- User asks to adjust dark mode or light mode appearance +- User asks to update Zensical/MkDocs theme configuration +- User mentions "Enel design system", "theme", "CSS tokens", "dark mode", or "Zensical styling" + +## Prerequisites + +- This repository opened as the active workspace +- `zensical.toml` at repository root with `[project.theme]` section +- `docs/stylesheets/extra.css` for CSS overrides + +## Reference + +- Design System Storybook: `https://eneldesignsystem-dev.enelint.global` +- Tokens extracted from: `https://www.enel.com` corporate CSS bundle + +## Scope + +- Theme config: `zensical.toml` โ€” `[project.theme]` section +- CSS overrides: `docs/stylesheets/extra.css` +- Logo image: `docs/assets/images/enel-logo.png` +- Template overrides: `overrides/` directory + +## Color Tokens + +| Token | Hex | Usage | +| -------------------- | --------- | ------------------------------ | +| `--enel-primary` | `#d3135a` | Magenta โ€” primary brand color | +| `--enel-secondary` | `#0047cc` | Ocean blue โ€” accent / links | +| `--enel-ocean` | `#0047cc` | Alias for secondary | +| `--enel-dark-ocean` | `#003eb3` | Darker ocean shade | +| `--enel-dark-green` | `#008c5a` | Dark green | +| `--enel-green` | `#55be5a` | Green | +| `--enel-light-blue` | `#41b9e6` | Light blue | +| `--enel-light-ocean` | `#0152e8` | Light ocean | +| `--enel-black` | `#0e141a` | Near-black โ€” tabs bar, footer | +| `--enel-smoke` | `#667790` | Muted text | +| `--enel-dark-snow` | `#c2cddd` | Borders, dividers | +| `--enel-snow` | `#eff2f7` | Light backgrounds | +| `--enel-white` | `#fff` | Page background | +| `--enel-magenta` | `#d3135a` | Alias for primary | +| `--enel-orange` | `#ff5a0f` | Warning accent | +| `--enel-yellow` | `#ffc82c` | Highlight, chart "not yet" | +| `--enel-cyan` | `#12caea` | Info accent | +| `--enel-red` | `#eb0a00` | Error | +| `--enel-success` | `#13ce66` | Success | + +## Chart Color Conventions + +Adoption charts use these specific colors: + +| Bucket | Color | +| ------------ | --------- | +| lastWeek | `#028C59` | +| last2Weeks | `#55BD5A` | +| lastMonth | `#0655FA` | +| more | `#40B9E6` | +| notyet | `#FFC000` | + +## Theme Architecture + +### Zensical config (`zensical.toml`) + +- Light scheme named `"enel"`, dark scheme `"slate"` +- `primary = "custom"` and `accent = "custom"` โ€” colors defined in CSS, not in config +- Logo set via `logo = "assets/images/enel-logo.png"` +- Font: `Inter` for text, `Roboto Mono` for code +- Custom overrides directory: `overrides/` + +### CSS structure (`docs/stylesheets/extra.css`) + +1. **Design tokens** โ€” `:root` block with all `--enel-*` variables +2. **Logo sizing** โ€” `.md-header__button.md-logo img` at `2rem` +3. **Light scheme** โ€” `[data-md-color-scheme="enel"]` maps tokens to `--md-*` variables +4. **Dark scheme** โ€” `[data-md-color-scheme="slate"]` overrides for dark mode +5. **Header / Tabs** โ€” Dark tabs bar (`--enel-black`), white text, `!important` on active/hover +6. **Navigation** โ€” Active link color uses `--enel-primary` +7. **Typography** โ€” Bold h1, bordered h2, dark-mode color overrides +8. **Cards** โ€” Rounded borders, magenta hover glow +9. **Buttons** โ€” Primary uses magenta +10. **Layout** โ€” Max-width 1440px, chart canvas 100%, flex wrapper for chart articles +11. **Footer** โ€” Magenta top border + +## Rules + +- Always use `--enel-*` CSS custom properties, never hardcode hex values except in the `:root` token block. +- Light scheme selectors use `[data-md-color-scheme="enel"]`, dark uses `[data-md-color-scheme="slate"]`. +- The tabs bar must keep `background-color: var(--enel-black)` with white text โ€” the built-in CSS uses `color: inherit` and `opacity`, so set `color` on `.md-tabs` and use `!important` on hover/active states. +- Card hover effect: magenta border + shadow `rgba(211, 19, 90, 0.12)`. +- The logo is a PNG file (768ร—560) displayed at `height: 2rem`. Use the built-in Zensical `logo` config โ€” do not use a custom partial override. +- Font "Roobert" is the official ENEL typeface but is proprietary. Use "Inter" as the web substitute. diff --git a/plugins/enel-gict/skills/op/SKILL.md b/plugins/enel-gict/skills/op/SKILL.md new file mode 100644 index 000000000..840c2e990 --- /dev/null +++ b/plugins/enel-gict/skills/op/SKILL.md @@ -0,0 +1,291 @@ +--- +name: op +description: 'Create, update, or review an Organizational Procedure (OP) document following the format and conventions used in this repository under docs/OP/. Use when the user asks to write an OP, update an existing OP, reformat an OP from PDF to clean markdown, review an OP for completeness, or cross-reference OP requirements into other documents. Covers the standard OP section structure (Aims, Version Management, Units in Charge, Key Concepts / Process Description, References, Organizational Process Position, Definitions and Acronyms, Annexes) and the formatting pipeline for converting PDF-to-text dumps into publication-ready markdown.' +--- + +# Organizational Procedure Authoring Skill + +You are an expert process architect for the GICT organization. Your job is to produce, update, or reformat Organizational Procedure (OP) documents following the exact conventions used in this repository under `docs/OP/`. + +## When to Use This Skill + +- User asks to write, update, or review an Organizational Procedure +- User asks to reformat an OP from PDF to clean markdown +- User asks to cross-reference OP requirements into RA or ADR documents +- User mentions "OP", "organizational procedure", "reformat OP", "PDF to markdown", or "OP35"/"OP36" + +## Prerequisites + +- This repository opened as the active workspace +- Source document (PDF text dump, Word export, or original content) if creating/reformatting +- Familiarity with `docs/OP/` folder and existing OPs + +## Context + +This repository maintains Organizational Procedures under `docs/OP/`. OPs define roles, responsibilities, and operating methods for GICT processes within the Enel Group. They are **governing documents** that Reference Architectures (RAs) and Architecture Decision Records (ADRs) must comply with. + +### Current OPs + +| Document | Version | Scope | +|----------|---------|-------| +| [OP35 โ€” Digital Initiatives Activation](in the source repository documentation/OP/OP35-Digital-Initiatives-Activation.md) | v8, 28/05/2025 | Investment activation, Buy/Make framework, initiative approval | +| [OP36 โ€” Solutions Development & Release Management](in the source repository documentation/OP/OP36-Solutions-Development-Release-Management.md) | v7, 11/12/2024 | SDRM lifecycle, design-by-default compliance, Project/Change/Corrective processes | + +### Relationship to Other Document Types + +- **RA documents** (`docs/RA/`) reference OPs for compliance: OP35 ยง6.0 governs initiative technical evaluation; OP36 ยง4.6โ€“ยง4.13 mandates seven design-by-default requirements. +- **ADR documents** (`docs/ADR/`) reference OPs for Buy/Make decisions and compliance checklists. +- When updating an OP, check whether downstream RA or ADR templates need corresponding updates. + +## Before You Start + +1. **Read existing OPs** โ€” Scan `docs/OP/` to understand the document conventions and current versions. +2. **Ask clarifying questions** โ€” Use the ask-questions tool to gather: + - **Action** โ€” Are you creating a new OP, updating an existing one, or reformatting a PDF-to-text dump? + - **Source** โ€” Is the source a PDF export, a Word document, or original content? + - **Version** โ€” What version number and date should appear? + - **Authorized by** โ€” Who authorizes this OP? + - **Scope** โ€” What GICT process does it govern? +3. **Check downstream references** โ€” If modifying OP35 or OP36, verify that the RA skill (`../.github/skills/ra/SKILL.md`) and ADR skill (`../.github/skills/adr/SKILL.md`) reference the correct section numbers. + +## OP Document Structure + +Every OP follows this standard section layout: + +```markdown +# OP <NN> โ€” <Title> + +| | | +|---|---| +| **Version** | <N> โ€” <DD/MM/YYYY> | +| **Classification** | Internal Use | +| **Perimeter** | Global | +| **Service Function** | Global Information and Communication Technology | +| **Authorized by** | <Name> โ€” <Title> | + +--- + +## 1. Document Aims and Application Area + +<Purpose of the procedure, applicability scope, and legal compliance note.> + +--- + +## 2. Document Version Management + +<Table with columns: Version | Date | Main Changes> + +--- + +## 3. Units in Charge + +<Responsible for drawing up and authorizing the document.> + +--- + +## 4. <Key Concepts or Process Description> + +<Core content. Subsections use ### headings. +For OP35: Process Description with RACI, Flowchart, Narratives. +For OP36: Key Concepts (ยง4.1โ€“ยง4.13) and Process Description (ยง5).> + +--- + +## 5โ€“N. <Additional Sections> + +<References, Organizational Process Position, Definitions and Acronyms.> + +--- + +## Annexes + +<## Annex N โ€” TITLE for each annex.> +``` + +### Heading Hierarchy + +| Level | Usage | Example | +|-------|-------|---------| +| `#` | Document title (one per file) | `# OP 36 โ€” Solutions Development & Release Management` | +| `##` | Top-level sections and Annexes | `## 4. Key Concepts`, `## Annex 1 โ€” TITLE` | +| `###` | Sub-sections | `### 4.6 Risk-Based and Cyber Security by Design Approach` | +| `####` | Sub-sub-sections | `#### 5.1.1 Project โ€” SDRM Roles` | +| `#####` | Narrative steps / process steps | `##### 6.0 Evaluation of the technical solution` | + +### Front-Matter Table + +Every OP starts with a metadata table immediately below the `#` title. Fields: + +| Field | Required | Notes | +|-------|----------|-------| +| Version | Yes | Format: `<N> โ€” <DD/MM/YYYY>` | +| Classification | Yes | Typically `Internal Use` | +| Perimeter | Yes | `Global` or specific region | +| Service Function | Yes | `Global Information and Communication Technology` | +| Authorized by | Yes | Full name and title | + +## PDF-to-Markdown Conversion Pipeline + +When converting OPs from PDF-to-text dumps, follow this pipeline: + +### Step 1 โ€” Clean the Source + +Create a cleaning script (`scripts/clean_op.py`) that: + +1. **Strips repeated PDF headers** โ€” Remove the header block that appears on every page (document title, classification, version info repeated per page). +2. **Strips page footers** โ€” Remove page numbers and footer text (e.g., `<N> of <M>`, `Pag.`). +3. **Collapses excessive blank lines** โ€” Reduce 3+ blank lines to 2. +4. **Preserves content** โ€” Do NOT remove substantive text, tables, or section headers. + +Pattern for PDF header detection: +```python +# Headers typically repeat these fields on every page: +# - Document title +# - "Organizational Procedure" or "Procedura Organizzativa" +# - Version/Classification +# - "Internal Use" / "Uso Interno" +``` + +### Step 2 โ€” Convert to Structured Markdown + +Create a formatting script (e.g., `scripts/format_opNN.py`) that: + +1. **Normalizes smart quotes** โ€” Convert `\u201c`/`\u201d` (""") to straight `"` and `\u2018`/`\u2019` ('') to straight `'` **early** in the pipeline, before pattern matching. +2. **Converts section headers** โ€” Map ALL-CAPS section titles to `##` headings with proper title case. +3. **Converts sub-section headers** โ€” Map indented or numbered sub-sections to `###`/`####` headings. +4. **Handles ANNEX headers** โ€” Account for leading whitespace: `^\s*ANNEX (\d+)`. +5. **Cleans double-spacing** โ€” PDF extraction often double-spaces words; collapse ` +` to single space **AFTER** all heading conversions to avoid breaking regex patterns. +6. **Adds horizontal rules** โ€” Insert `---` separators before `##` headers. +7. **Collapses blank lines** โ€” Reduce 3+ blank lines to 2. + +**Critical ordering**: Smart quote normalization โ†’ heading conversions โ†’ double-space cleanup โ†’ separators โ†’ blank line collapse. + +### Step 3 โ€” Verify + +After conversion, verify: +```bash +# Check all heading levels are present and properly nested +grep -n '^#' docs/OP/OP<NN>-<name>.md + +# Check no raw PDF artifacts remain +grep -n 'Internal Use\|Uso Interno\|Pag\.\|of [0-9]' docs/OP/OP<NN>-<name>.md + +# Build the site +.venv/bin/zensical build +``` + +### Known Pitfalls + +| Issue | Cause | Fix | +|-------|-------|-----| +| Smart quotes (`""`) not matching regex `"` | PDF extraction preserves Unicode quotes | Normalize `\u201c`/`\u201d` to `"` before matching | +| `ANNEX` headers not converting | Leading spaces from PDF layout | Use `^\s*ANNEX` in regex | +| Double headings (`## 1. ## 1. Title`) | Section map replaces inline occurrences | Use line-anchored regex `re.sub(r'^\s*...\s*$', ..., flags=re.MULTILINE)` | +| Sub-sub-sections (e.g., `5.1.1.`) skipped | Double-space cleanup runs before regex | Move `re.sub(r' +', ' ', text)` to AFTER heading conversions | +| Tables render as plain text | PDF extraction loses column alignment | Manually reconstruct as Markdown tables | + +## Writing Conventions + +- **Language**: Match the primary language of the source document. Use English for technical terms and table headers. +- **Tables**: Use Markdown pipe tables for RACI matrices, version management, and structured data. Always include a header row and separator. +- **RACI notation**: R = Responsible, A = Accountable, C = Consulted, I = Informed. Use single letters in tables. +- **Cross-references**: Use `ยง` prefix for internal section references (e.g., `ยง4.6`). +- **Dates**: Use `DD/MM/YYYY` format consistent with Enel corporate standards. +- **File naming**: `OP<NN>-<Kebab-Case-Title>.md` (e.g., `OP35-Digital-Initiatives-Activation.md`). + +## File Naming + +Output files must follow: `docs/OP/OP<NN>-<Kebab-Case-Title>.md` + +- `<NN>` = OP number (e.g., `35`, `36`) +- `<Kebab-Case-Title>` = hyphenated title (e.g., `Digital-Initiatives-Activation`) + +## Documentation Site Integration + +After creating or updating an OP file: + +- [ ] Add the file path to the `nav` in `zensical.toml` under the `"Organizational Procedures"` group +- [ ] Add or update the entry in `docs/index.md` under the **Organizational Procedures** section +- [ ] Verify the site builds cleanly: `.venv/bin/zensical build` +- [ ] Check heading structure renders correctly in the built HTML (`public/OP/`) + +### Nav Entry Pattern + +```toml +{ "Organizational Procedures" = [ + "OP/OP35-Digital-Initiatives-Activation.md", + "OP/OP36-Solutions-Development-Release-Management.md", + # Add new OP here, in numerical order +]} +``` + +## OP35 Quick Reference โ€” Key Sections for Downstream Documents + +These OP35 sections are most frequently referenced by RAs and ADRs: + +| Section | Content | Referenced By | +|---------|---------|---------------| +| ยง4.3 Narratives | Full process narrative with 13 steps | RA ยง21.1 compliance checklist | +| ยง4.3 / ##### 6.0 | Technical solution evaluation โ€” Buy or Make | RA ยง9, ยง21.1; ADR Buy/Make section | +| ยง4.3 / ##### 9.0 | Investment Memo preparation and approval | RA ยง18, ยง21.1 | +| ยง4.1 RACI Matrix | Roles for each narrative | RA ยง21.1 unit involvement table | + +## OP36 Quick Reference โ€” Design-by-Default Requirements + +These OP36 sections define mandatory compliance checks for all Projects and Changes: + +| Section | Requirement | Policy Reference | RA/ADR Impact | +|---------|-------------|-------------------|---------------| +| ยง4.6 | Cyber Security by Design | PL No. 17, OP No. 2420 | RA ยง10, ADR Non-Functional | +| ยง4.7 | Digital Accessibility (WCAG 2.1 AA) | PL No. 1142 | RA ยง14, ADR Non-Functional | +| ยง4.8 | Personal Data Protection by Design | PL No. 344 | RA ยง11, ADR Privacy section | +| ยง4.9 | Adoption by Design | OP36 ยง4.9 | RA ยง20, ADR Adoption KPIs | +| ยง4.11 | Quality Management | ICT OI No. 3703 | RA ยง13, ADR Quality section | +| ยง4.12 | Data Security in Non-Production | OP36 ยง4.12 | RA ยง10, ADR Non-Functional | +| ยง4.13 | Intellectual Property by Design | OP No. 2059, OP No. 1785 | RA ยง9, ADR IP Assessment | + +## OP36 Process Types Quick Reference + +OP36 ยง5 defines three SDRM process types, each with its own Roles, RACI Matrix, and Narratives: + +| Type | Section | When Used | +|------|---------|-----------| +| **Project** | ยง5.1 (ยง5.1.1โ€“ยง5.1.4) | New solution development, both Waterfall and Agile | +| **Change** | ยง5.2 (ยง5.2.1โ€“ยง5.2.3) | Modifications to existing solutions | +| **Corrective** | ยง5.3 (ยง5.3.1โ€“ยง5.3.3) | Bug fixes and urgent corrections | + +## Quality Checklist + +Before finalizing, verify: + +**Structure** +- [ ] Front-matter metadata table present with all required fields +- [ ] All standard sections present (Aims, Version Management, Units in Charge, etc.) +- [ ] Heading hierarchy is correct (`#` โ†’ `##` โ†’ `###` โ†’ `####` โ†’ `#####`) +- [ ] Horizontal rules (`---`) between top-level sections +- [ ] No duplicate headings or raw PDF artifacts + +**Tables** +- [ ] RACI matrices use proper Markdown table format +- [ ] Version Management table is complete and chronological +- [ ] All tables have header rows and separator lines + +**Content** +- [ ] Smart quotes normalized to straight quotes +- [ ] No double-spaced words (PDF artifact) +- [ ] No page headers/footers remaining +- [ ] Cross-references use `ยง` notation +- [ ] Annex headers use `## Annex N โ€” TITLE` format + +**Integration** +- [ ] File added to `zensical.toml` nav +- [ ] Entry added to `docs/index.md` +- [ ] Site builds without errors +- [ ] HTML output renders headings and tables correctly + +## References + +- [OP35 โ€” Digital Initiatives Activation](in the source repository documentation/OP/OP35-Digital-Initiatives-Activation.md) +- [OP36 โ€” Solutions Development & Release Management](in the source repository documentation/OP/OP36-Solutions-Development-Release-Management.md) +- [RA Authoring Skill](../ra/SKILL.md) โ€” References OP35/OP36 for compliance +- [ADR Authoring Skill](../adr/SKILL.md) โ€” References OP35/OP36 for compliance diff --git a/plugins/enel-gict/skills/ra/SKILL.md b/plugins/enel-gict/skills/ra/SKILL.md new file mode 100644 index 000000000..50970104c --- /dev/null +++ b/plugins/enel-gict/skills/ra/SKILL.md @@ -0,0 +1,417 @@ +--- +name: ra +description: 'Create, update, or review a Reference Architecture (RA) document following the standardized template used in this repository. Use when the user asks to write a new RA, draft an architecture document, create an RA for a technology domain, or generate an architecture blueprint. Covers all standard RA sections: summary, scope, goals, assumptions, principles, capability model, logical/physical architecture, technology choices, security, data, observability, CI/CD, risks, cost, compliance, and transition plan. Enforces OP35 ยง6.0 Buy-or-Make Decisional Framework and OP36 design-by-default compliance (Cyber Security, WCAG, GDPR/Privacy, Intellectual Property, Adoption, Quality).' +license: Apache-2.0 +metadata: + author: technologies-and-architectures + version: "2.0" +--- + +# Reference Architecture Authoring Skill + +You are an expert enterprise architect for the GICT organization. Your job is to produce a complete Reference Architecture (RA) document following the exact template and conventions used in this repository, fully aligned with the organizational procedures in the `OP/` folder. + +## When to Use This Skill + +- User asks to write a new Reference Architecture +- User asks to draft an architecture document or blueprint for a technology domain +- User asks to update or review an existing RA in the catalog +- User mentions "create RA", "reference architecture", "architecture blueprint", or naming a technology domain +- User needs OP35/OP36 compliance sections filled in an architecture document + +## Prerequisites + +- This repository opened as the active workspace +- Familiarity with `docs/RA/` folder and existing RA catalog in `docs/index.md` +- Access to official documentation for technologies being evaluated (the skill will fetch these) + +## Context + +This workspace contains a catalog of Reference Architectures under `docs/`. Each RA follows a consistent numbered format (`NNN_RA_<slug>.md`) and covers a specific technology domain. The catalog index is maintained in [docs/index.md](in the source repository documentation/index.md). + +RAs serve as standardized, opinionated blueprints for building modern cloud-native systems. They must be thorough, well-sourced, and actionable. + +### Governing Organizational Procedures + +Every RA produced in this repository must comply with two internal procedures: + +- **[OP35 โ€” Digital Initiatives Activation](../in the source repository documentation/OP35-Digital-Initiatives-Activation.md)** (v8, 28/05/2025): An RA IS the formal technical output of **narrative 6.0 โ€” Evaluation of the technical solution of the initiative**. It must cover: technical alternatives and justification, high-level architecture, technical/functional impact on existing systems, cyber security high-level information, preliminary cost estimate, internal workforce needs, partners and technologies, macro plan. The RA must also contain the output of the **Buy or Make Decisional Framework** when a new digital initiative is involved. + +- **[OP36 โ€” Solutions Development & Release Management](../in the source repository documentation/OP36-Solutions-Development-Release-Management.md)** (v7, 11/12/2024): Mandates seven **design-by-default** compliance requirements that must be addressed in every RA before it can feed a Project narrative. These are: Cyber Security by Design (ยง4.6), Digital Accessibility/WCAG (ยง4.7), Personal Data Protection/GDPR (ยง4.8), Adoption by Design (ยง4.9), Quality Management (ยง4.11), Data Security in non-production (ยง4.12), and Intellectual Property by Design (ยง4.13). + +## Before You Start + +1. **Read the catalog** โ€” Open [docs/index.md](in the source repository documentation/index.md) to understand existing RAs and avoid overlaps. +2. **Ask clarifying questions** โ€” Use the ask-questions tool to interview the user on at minimum: + - **Domain / Title** โ€” What technology domain or capability does this RA cover? + - **Key Technologies** โ€” Which specific open-source or commercial technologies should be evaluated? + - **Audience** โ€” Who are the primary consumers (developers, architects, ops, security, business)? + - **Status** โ€” Draft, Requested Approval, or Approved? + - **Cross-references** โ€” Does this RA relate to any existing RAs in the catalog? + - **OP35 trigger** โ€” Is this RA supporting a new digital initiative (requires Buy/Make section)? If so, which units are involved? + - **OP36 triggers** โ€” Does the solution process personal data (DPIA)? Does it have a user interface (WCAG)? Does it use third-party code or OSS (IP Assessment)? +3. **Research** โ€” For each technology the user names, fetch the official documentation to gather accurate descriptions, architecture patterns, and source URLs. Every architectural claim must have a source link. + +## OP35 ยง6.0 โ€” Mandatory Unit Involvements + +When the RA supports a digital initiative activation, the following units must be involved in its production: + +| Unit | When Required | +|---|---| +| **TA&CS Delivery / T&A** | Always โ€” joint technical evaluation | +| **I&TS** | When the solution includes infrastructure or telecom elements not in the GICT Service Catalog | +| **Cyber Security** | When the solution is innovative and security controls are not standardized yet | +| **Other GICT units affected** | For qualitative/quantitative information about their perimeter | +| **P&C Applicant Unit** | For Business Initiatives โ€” financial evaluation and benefits calculation | + +Record which units were involved in **Section 21** of the RA. + +## OP35 ยง6.0 โ€” Buy or Make Decision + +For every new digital initiative the RA must document the outcome of the **Buy or Make Decisional Framework**: + +1. **Existing portfolio check**: Does a product in the Delivery Unit portfolio already address the same need? โ†’ Adopt existing. +2. **Buy evaluation**: Are there market solutions (Buy/Hybrid Solution) that fit the need? โ†’ Evaluate against blocking requirements. +3. **Make evaluation**: Must the solution be developed from scratch? โ†’ Justify with technical and economic rationale. + +The result of this framework must also be included in the **Capex ICT โ€” Investment Memo Template** (EGS Document Library). Reference this in Section 21. + +## OP36 โ€” Design-by-Default Compliance Map + +Each of the seven OP36 design-by-default requirements maps to a specific RA section: + +| OP36 Requirement | Policy Reference | Primary RA Section | Checklist Item | +|---|---|---|---| +| **Cyber Security by Design** | PL No. 17, OP No. 2420 | ยง10 Security Architecture | Cyber Risk Assessment (CRA) status | +| **Digital Accessibility (WCAG 2.1 AA)** | PL No. 1142 | ยง10 Security Architecture / ยง14 NFRs | Accessibility Statement or VPAT | +| **Personal Data Protection by Design** | PL No. 344 | ยง11 Data & State | DPIA triggered? Privacy by Design tool activated? | +| **Adoption by Design** | OP36 ยง4.9 | ยง20 Transition Plan | Adoption KPIs defined, Adoption Chapter involved | +| **Quality Management** | ICT OI No. 3703 | ยง14 NFRs / ยง13 CI/CD | SW Intelligence practices, test strategy | +| **Data Security in non-production** | OP36 ยง4.12 | ยง10 Security Architecture | Non-prod data controls, masking/pseudonymization | +| **Intellectual Property by Design** | OP No. 2059, OP No. 1785 | ยง9 Technology Choices | IP Assessment / FTO for OSS and third-party code | + +## RA Document Template + +Generate the RA using **exactly** these sections in this order. Adapt content to the domain but preserve the structure. + +```markdown +# Reference Architecture: <Title> + +**Version:** <1.0> +**Status:** <Draft | Requested Approval | Approved> +**Owner:** Technologies and Architectures +**Audience:** <comma-separated roles> +**Last Updated:** <YYYY-MM-DD> +**OP35 Initiative:** <Initiative name or "Not applicable"> +**OP36 Triggers:** <List: WCAG / DPIA / IP Assessment / Adoption KPIs โ€” or "None identified"> + +--- + +## 1. Summary + +<2-4 paragraphs explaining what this RA proposes, the key architectural decisions, and how the components fit together. Use bullet points for each major component with source links in double-bracket format: [[label]](url). End with alignment notes to related RAs if applicable.> + +--- + +## 2. Scope + +**In scope** +- <bullet list of what this RA covers, with source links> + +**Out of scope** +- <bullet list of exclusions> + +--- + +## 3. Goals & Drivers + +<Table or bullet list mapping business/technical goals to technology enablers. Include source links.> + +--- + +## 4. Assumptions & Constraints + +<Bullet list of deployment assumptions (e.g., Kubernetes-first), technology constraints, standards (CloudEvents, OTel), and organizational constraints (OP35/OP36 compliance). Include source links.> + +--- + +## 5. Architecture Principles + +<Bullet list of principles: event-driven first, cloud-native, secure-by-default, separation of concerns, standards-based, etc. Include source links.> + +--- + +## 6. Capability Model + +<Table with columns: Capability | Description | Technology. Each row maps an architectural capability to the technology implementing it, with source links.> + +--- + +## 7. Logical Architecture + +<Describe the high-level flow as numbered steps (1-N). Include an ASCII or Mermaid architecture diagram showing component relationships. Reference source links for each technology interaction.> + +--- + +## 8. Physical / Deployment View (Kubernetes) + +<Describe deployment topology: namespaces, pods, sidecars, networking. Use Kubernetes-first conventions. Include source links.> + +--- + +## 9. Technology Choices (Evaluated Options) + +### 9.1 Feature Comparison + +<For each technology category, list evaluated options with descriptions, trade-offs, and source links. Use subsections per category.> + +### 9.2 Notes + +<Additional selection criteria, migration notes, deprecation warnings.> + +--- + +## 10. Security Architecture + +<Bullet list covering: service-to-service security (mTLS, capability-based), secrets management, identity/IAM integration, network policies. Include source links.> + +--- + +## 11. Data & State + +<Describe state management per component: workflow state, event stores, caches, databases. Include source links.> + +--- + +## 12. Developer Experience & Tooling + +<SDKs, CLIs, modeling tools, IDE extensions, local development patterns. Include source links.> + +--- + +## 13. CI/CD Integration + +<Helm/Kustomize, validation, testing, telemetry pipeline as code. Include source links.> + +--- + +## 14. Non-Functional Requirements (targets) + +<Scalability, resilience, observability targets per component. Include source links.> + +--- + +## 15. Observability + +<Instrumentation strategy: traces, metrics, logs across all components. Key metrics to track. Include source links.> + +--- + +## 16. Eventing & Messaging + +<Event backbone, routing, cross-stack interop patterns. Include source links.> + +--- + +## 17. Risks & Mitigations + +<Bullet list of risks with corresponding mitigations. Include source links.> + +--- + +## 18. Cost Considerations + +<Operational footprint, sizing guidance, cost optimization strategies.> + +--- + +## 19. Decision & Rationale + +<Formal decision statement and rationale explaining why this architecture was chosen over alternatives.> + +--- + +## 20. Transition Plan + +**Pilot (4-6 weeks)** +<Steps to bootstrap and validate the architecture.> + +**Bootstrap assets** +<Templates, samples, manifests to provide.> + +**Enablement** +<Workshops, runbooks, guardrails.> + +**Rollout phases** +<Phase 1-3 progressive adoption.> + +--- + +## 21. Compliance & Governance + +### 21.1 OP35 โ€” Digital Initiatives Activation Compliance + +> Complete this section when this RA supports a digital initiative (OP35 narrative 6.0 output). + +| OP35 Requirement | Status | Notes | +|---|---|---| +| **Buy or Make Decisional Framework** (OP35 ยง6.0) | โœ… / โš ๏ธ / โŒ / N/A | Decision: Buy / Make / Hybrid / Existing portfolio | +| **TA&CS Delivery/T&A involvement** (OP35 ยง6.0) | โœ… / โš ๏ธ / โŒ / N/A | Unit representative: | +| **I&TS involvement** (OP35 ยง6.0 โ€” infra/telecom) | โœ… / โš ๏ธ / โŒ / N/A | Required if solution uses infra/telecom not in Service Catalog | +| **Cyber Security involvement** (OP35 ยง6.0 โ€” innovative solutions) | โœ… / โš ๏ธ / โŒ / N/A | Required for non-standard security controls | +| **Investment Memo alignment** (OP246 via OP35 ยง9.0) | โœ… / โš ๏ธ / โŒ / N/A | IM reference: | +| **Capex ICT estimate included** (OP35 ยง6.0) | โœ… / โš ๏ธ / โŒ / N/A | See ยง18 Cost Considerations | +| **High-level architecture documented** (OP35 ยง6.0) | โœ… / โš ๏ธ / โŒ / N/A | See ยง7 Logical Architecture | +| **Technical/functional impact assessed** (OP35 ยง6.0) | โœ… / โš ๏ธ / โŒ / N/A | See ยง17 Risks | +| **Macro plan included** (OP35 ยง6.0) | โœ… / โš ๏ธ / โŒ / N/A | See ยง20 Transition Plan | + +### 21.2 OP36 โ€” Design-by-Default Compliance + +| OP36 Requirement | Policy | Status | Notes | +|---|---|---|---| +| **Cyber Security by Design** (ยง4.6) | PL No. 17, OP No. 2420 | โœ… / โš ๏ธ / โŒ / N/A | CRA status; see ยง10 | +| **Digital Accessibility โ€” WCAG 2.1 AA** (ยง4.7) | PL No. 1142 | โœ… / โš ๏ธ / โŒ / N/A | Accessibility Statement / VPAT; see ยง14 | +| **Personal Data Protection by Design โ€” GDPR** (ยง4.8) | PL No. 344 | โœ… / โš ๏ธ / โŒ / N/A | DPIA triggered? Privacy by Design tool? | +| **Adoption by Design** (ยง4.9) | OP36 ยง4.9 | โœ… / โš ๏ธ / โŒ / N/A | Adoption KPIs; Adoption Chapter involved; see ยง20 | +| **Quality Management** (ยง4.11) | ICT OI No. 3703 | โœ… / โš ๏ธ / โŒ / N/A | SW Intelligence practices; test strategy; see ยง13 | +| **Data Security โ€” non-production** (ยง4.12) | OP36 ยง4.12, PL No. 33 | โœ… / โš ๏ธ / โŒ / N/A | Data masking / pseudonymization strategy | +| **Intellectual Property by Design** (ยง4.13) | OP No. 2059, OP No. 1785 | โœ… / โš ๏ธ / โŒ / N/A | IP Assessment / FTO for OSS; see ยง9 | + +### 21.3 General Governance + +<Versioning, review processes, security controls, policy enforcement. Reference OP35/OP36 where applicable.> + +--- + +## 22. Appendix (Quick Links) + +<Bullet list of key documentation URLs for all technologies referenced.> + +--- + +## Reference Implementation Snippets + +<YAML, code, or configuration samples illustrating key integration points. Use fenced code blocks with language tags.> +``` + +## Writing Guidelines + +1. **Source everything** โ€” Every technology claim must include a `[[label]](url)` link to official documentation. Do not invent URLs; fetch and verify them. +2. **Use the existing style** โ€” Study [docs/001_RA_workflow.md](in the source repository documentation/001_RA_workflow.md) for tone, density, and formatting conventions. Match the level of detail. +3. **Cross-reference related RAs** โ€” Link to other RAs in the catalog where capabilities overlap (e.g., "See [001_RA_workflow.md](in the source repository documentation/001_RA_workflow.md) for orchestration patterns"). +4. **ASCII diagrams** โ€” Use ASCII box-and-arrow diagrams for architecture overviews (the existing RAs use this style). Mermaid is acceptable as a secondary option. +5. **Tables for comparisons** โ€” Use Markdown tables for feature comparisons, capability models, and requirements matrices. +6. **Be opinionated** โ€” RAs are not surveys. State clear decisions and rationale. Evaluated alternatives go in Section 9. +7. **OP35 ยง6.0 alignment** โ€” When the RA supports an initiative, Section 7 (Logical Architecture) and Section 18 (Cost Considerations) directly feed the Investment Memo. Section 9 (Technology Choices) contains the Buy or Make framework output. These three sections must be complete before the RA can be submitted to the DE PC&CM. +8. **OP36 design-by-default** โ€” Section 10 (Security Architecture) must address Cyber Security by Design (PL No. 17 / OP No. 2420), Digital Accessibility requirements (PL No. 1142), and data security in non-production environments (ยง4.12). Section 11 (Data & State) must address Personal Data Protection by Design (PL No. 344). Section 9 (Technology Choices) must flag any IP Assessment or FTO needs for OSS components (OP No. 2059 / OP No. 1785). Section 20 (Transition Plan) must include Adoption KPIs aligned with OP36 ยง4.9. Section 21 must contain the completed OP35 and OP36 compliance checklists. + +## File Naming + +The output file must follow: `docs/RA/NNN_RA_<slug>.md` + +- `NNN` = next sequential number (check `docs/index.md` for the latest) +- `<slug>` = lowercase, underscores, short domain descriptor + +--- + +## Documentation Site + +This repository publishes the `docs/` folder as a static documentation site via **[Zensical](https://zensical.io)** (a MkDocs-based build tool) and **GitHub Pages**. + +### Site Configuration โ€” `zensical.toml` + +The site is configured in `zensical.toml` at the repository root. Key conventions: + +| Key | Value | Notes | +|-----|-------|-------| +| `docs_dir` | `"docs"` | Source folder โ€” all RA, ADR, OP files live here | +| `site_dir` | `"public"` | Build output โ€” uploaded as GitHub Pages artifact | +| `use_directory_urls` | `false` | Keeps `.md` links valid both locally and on the site | +| `nav` | explicit entries | Every new document **must** be added to the `nav` table | + +When you create or update an RA, ADR, or OP file you **must** also update `zensical.toml` to add the new file to the appropriate `nav` group. Follow the existing pattern: + +```toml +nav = [ + { "Home" = "index.md" }, + { "Reference Architectures" = [ + "RA/001_RA_workflow.md", + "RA/001_RA_workflow_PoC-plan.md", + "RA/002_RA_serverless_microservices.md", + # ... add new entry here, in numerical order + ]}, + { "ADR" = [ + "ADR/ai_sdlc_architecture_decision.md", + # ... + ]}, + { "Organizational Procedures" = [ + "OP/OP35-Digital-Initiatives-Activation.md", + "OP/OP36-Solutions-Development-Release-Management.md", + ]}, +] +``` + +### GitHub Actions Workflow โ€” `.github/workflows/pages.yml` + +The workflow at `.github/workflows/pages.yml` builds and deploys the site automatically on every push to `main`. The pipeline: + +1. **Checks out** the repository (`actions/checkout@v5`) +2. **Installs** `uv` and Zensical (`uv venv .venv && uv pip install zensical`) +3. **Builds** the site (`zensical build`) โ€” outputs to `public/` +4. **Uploads** the `public/` folder as a Pages artifact (`actions/upload-pages-artifact@v4`) +5. **Deploys** to GitHub Pages (`actions/deploy-pages@v5`) + +Required repository settings: +- **Pages source**: GitHub Actions (not `gh-pages` branch) +- **Permissions** in the workflow: `pages: write`, `id-token: write` + +### Checklist When Adding a New RA + +After generating `docs/RA/NNN_RA_<slug>.md`: + +- [ ] Add the file path to the `nav` in `zensical.toml` (correct section, numerical order) +- [ ] Add a row to the **Reference Architecture Index** table in `docs/index.md` with the `RA/` prefix path +- [ ] Verify links use relative paths from `docs/` root (e.g., `RA/001_RA_workflow.md`), not absolute paths +- [ ] Confirm `use_directory_urls = false` is set so `.md` links resolve correctly on the published site + +After creating the RA, update `docs/index.md` to add the new entry to the Reference Architecture Index table. + +## Companion Documents + +If the user requests it, also create a PoC plan following the pattern in `docs/001_RA_workflow_PoC-plan.md`: `docs/NNN_RA_<slug>_PoC-plan.md`. + +## Quality Checklist + +Before finalizing, verify: + +**Structure** +- [ ] All 22 sections present (1-22 + Reference Implementation Snippets) +- [ ] Every technology has at least one source link +- [ ] ASCII architecture diagram in Section 7 +- [ ] Capability model table in Section 6 +- [ ] Technology comparison table in Section 9 +- [ ] Risks and mitigations in Section 17 +- [ ] Transition plan with concrete phases in Section 20 +- [ ] File named correctly and index.md updated +- [ ] Cross-references to related RAs included + +**OP35 โ€” Digital Initiatives Activation (ยง6.0)** +- [ ] Buy or Make Decisional Framework outcome documented (Section 9 or Section 21) +- [ ] TA&CS Delivery/T&A involvement noted (Section 21) +- [ ] I&TS involvement noted if infra/telecom is in scope (Section 21) +- [ ] Cyber Security involvement noted for innovative solutions (Section 21) +- [ ] High-level architecture present (Section 7) +- [ ] Preliminary cost estimate present (Section 18) +- [ ] Macro plan / deliverables present (Section 20) +- [ ] Technical/functional impact on existing systems addressed (Sections 4 and 17) +- [ ] OP35 compliance table filled in Section 21.1 + +**OP36 โ€” Design-by-Default Compliance** +- [ ] Cyber Security by Design addressed in Section 10 (PL No. 17, OP No. 2420) +- [ ] Digital Accessibility / WCAG 2.1 AA addressed in Sections 10 or 14 (PL No. 1142) +- [ ] Personal Data Protection by Design addressed in Section 11 (PL No. 344 โ€” DPIA trigger assessed) +- [ ] Adoption KPIs defined in Section 20 (OP36 ยง4.9) +- [ ] Quality Management / SW Intelligence practices noted in Section 13 (ICT OI No. 3703) +- [ ] Data security in non-production environments addressed in Section 10 (OP36 ยง4.12) +- [ ] IP Assessment / FTO need identified for any OSS or third-party code in Section 9 (OP No. 2059 / OP No. 1785) +- [ ] OP36 compliance table filled in Section 21.2 diff --git a/website/src/pages/llms.txt.ts b/website/src/pages/llms.txt.ts index 49c174a80..d2ba03f48 100644 --- a/website/src/pages/llms.txt.ts +++ b/website/src/pages/llms.txt.ts @@ -6,7 +6,7 @@ import skillsData from "../../public/data/skills.json"; // Base URL for absolute links (to raw GitHub content) const GITHUB_RAW_BASE = "https://raw.githubusercontent.com/github/awesome-copilot/main"; -const WEBSITE_BASE = "https://awesome-copilot.github.com"; +const WEBSITE_BASE = "https://enel-gict-ptg.github.io/awesome-copilot/"; const normalizeDescription = (value?: string) => (value || "No description available").replace(/\s+/g, " ").trim(); @@ -97,7 +97,7 @@ export const GET: APIRoute = async () => { content += "## Repository\n\n"; content += "- **GitHub**: https://github.com/github/awesome-copilot\n"; content += "- **License**: MIT\n"; - content += "- **Website**: https://awesome-copilot.github.com\n"; + content += "- **Website**: https://enel-gict-ptg.github.io/awesome-copilot/\n"; return new Response(content, { headers: { "Content-Type": "text/plain; charset=utf-8" },