docs: add community contribution workflow

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: "Bug Report"
+about: "Report a technical error in code snippets, explanations, or commands."
+title: "[Bug]: "
+labels: ["status:needs-review", "type:bug"]
+assignees: ""
+---
+
+## 🐛 Affected File or Section
+
+What is the file or section where you found the problem?
+
+<!-- e.g., ARCHITECTURE_AND_BEST_PRACTICES/01-SOLID-Principles/README.md — Section: "What is SOLID?" -->
+
+## 🔍 Observed Behavior
+
+What is happening that seems wrong or confusing?
+
+<!-- e.g., The code example shows `const x = 5` but the explanation references a variable `count` that was never declared. -->
+
+## ✅ Expected Correction
+
+What should be there instead, or what needs to be clarified?
+
+<!-- e.g., Rename `x` to `count` to match the explanation that follows. -->
+
+## 📝 Additional Context
+
+Anything else that helps clarify the issue?
+
+<!-- e.g., This error appears in the Java section too. Links to related files if relevant. -->

.github/ISSUE_TEMPLATE/documentation_problem.md

@@ -0,0 +1,29 @@
+---
+name: "Documentation Problem"
+about: "Report outdated information, factual errors, or confusing wording."
+title: "[Docs]: "
+labels: ["status:needs-review", "type:documentation"]
+assignees: ""
+---
+
+## 📍 Location
+
+Which file or section needs attention?
+
+<!-- e.g., GIT/02-GitHub-Collaboration/README.md — Section: "Merging vs Rebasing" -->
+
+## ⚠️ What Is Wrong
+
+Describe the error, outdated content, or unclear wording.
+
+<!-- e.g., The explanation says to always rebase but doesn't mention when merging is preferable. A reader could walk away thinking rebasing is always better. -->
+
+## 💡 Suggested Fix
+
+How should this be corrected or clarified?
+
+<!-- e.g., Add a note about when merging is the better choice — specifically when preserving the full history of a feature branch matters. -->
+
+## 🔗 Related Context
+
+Links to related sections or external references, if any.

.github/ISSUE_TEMPLATE/general_feedback.md

@@ -0,0 +1,25 @@
+---
+name: "General Feedback"
+about: "Ask a question, share a perspective, or propose an improvement."
+title: "[Feedback]: "
+labels: ["status:needs-review", "type:feedback"]
+assignees: ""
+---
+
+## 💬 Your Feedback
+
+What is on your mind?
+
+<!-- Share a question, a perspective, or an idea for how something could be explained better. There are no wrong formats here. -->
+
+## 🎯 Relevant Section (optional)
+
+Is your feedback tied to a specific file or topic?
+
+<!-- e.g., ARCHITECTURE_AND_BEST_PRACTICES/02-Clean-Hexagonal — or just "General structure" if it applies broadly. -->
+
+## 🌱 What Made You Think About This
+
+Optional: what triggered this thought?
+
+<!-- e.g., Working through the Hexagonal Architecture section and wondering how it connects to domain events. -->

.github/ISSUE_TEMPLATE/topic_suggestion.md

@@ -0,0 +1,33 @@
+---
+name: "Topic Suggestion"
+about: "Propose a new topic, section, or learning level for the playbook."
+title: "[Suggestion]: "
+labels: ["status:needs-review", "type:enhancement"]
+assignees: ""
+---
+
+## 🎯 Proposed Topic
+
+What topic or area do you want to see added or expanded?
+
+<!-- e.g., A section on error handling patterns in Go, or a deep-dive into database transaction isolation levels. -->
+
+## 📊 Level
+
+Which level fits this topic best?
+
+- [ ] **Level 01** — Fundamentals and core concepts
+- [ ] **Level 02** — Intermediate patterns and practical application
+- [ ] **Level 03** — Advanced techniques and real-world integration
+
+## 💬 Rationale
+
+Why would this topic help someone learning software engineering?
+
+<!-- e.g., Error handling is one of the most undervalued skills — seeing concrete patterns early would save learners months of debugging pain. -->
+
+## 📚 Suggested Structure
+
+Do you have ideas for how this topic could be organized?
+
+<!-- e.g., 01-Error-Wrapping, 02-Retry-Patterns, 03-Circuit-Breakers -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,35 @@
+## ⚠️ Before Opening This Pull Request
+
+**This repository uses an issue-first workflow for content contributions.**
+
+Content changes — new sections, rewritten explanations, restructured topics — are not accepted as pull requests. This protects the playbook's teaching voice, progressive structure, and conceptual sequencing.
+
+### What belongs in a PR
+
+✅ **Small maintenance only:**
+- Typo corrections
+- Broken links
+- Formatting improvements
+- Minor repository maintenance
+
+### What does NOT belong in a PR
+
+❌ **Content changes require an issue first:**
+- New sections or topics
+- Rewritten explanations
+- Structural changes to existing content
+- Conceptual additions or reorderings
+
+---
+
+## PR Checklist
+
+- [ ] This PR fixes a typo, broken link, or formatting issue (no content changes)
+- [ ] I have not changed any substantive explanation or added new content
+- [ ] If unsure, I have opened an issue first and linked it below
+
+---
+
+**For content suggestions:** Please close this PR and open an issue using the appropriate template instead.
+
+👉 [Open an Issue](https://github.com/DevMPoveaCL/software-engineering-playbook/issues/new/choose)

.github/workflows/docs-quality.yml

@@ -0,0 +1,68 @@
+name: Documentation Quality
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - "**/*.md"
+      - ".github/workflows/docs-quality.yml"
+      - ".markdownlint.yaml"
+      - ".lychee.toml"
+  push:
+    branches: [main]
+    paths:
+      - "**/*.md"
+      - ".github/workflows/docs-quality.yml"
+      - ".markdownlint.yaml"
+      - ".lychee.toml"
+
+jobs:
+  quality-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # ── Markdown consistency ────────────────────────────────────────────────
+      - name: Lint Markdown
+        run: >-
+          npx --yes markdownlint-cli "**/*.md"
+          --ignore ".atl/**"
+          --ignore ".github/ISSUE_TEMPLATE/**"
+          --ignore ".github/PULL_REQUEST_TEMPLATE.md"
+
+      # ── Link integrity ──────────────────────────────────────────────────────
+      - name: Check Links
+        uses: lycheeverse/lychee-action@v1
+        with:
+          args: "--config=.lychee.toml '**/*.md' --exclude-path='.atl/**' --exclude-path='.github/ISSUE_TEMPLATE/**' --exclude-path='.github/PULL_REQUEST_TEMPLATE.md'"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # ── Repository structure — level progression ────────────────────────────
+      - name: Enforce topic level progression
+        run: |
+          MISSING_LEVELS=""
+
+          for dir in CSS DOCKER GIT HTML JAVA JS NETWORKING SQL UX_UI_ACCESSIBILITY "IONIC+ANGULAR+FIREBASE+CAPACITOR" "REACT+SPRINGBOOT" ARCHITECTURE_AND_BEST_PRACTICES; do
+            if [ ! -d "$dir" ]; then
+              continue
+            fi
+
+            for level in 01 02 03; do
+              MATCH=$(find "$dir" -maxdepth 1 -type d -name "${level}-*" | wc -l)
+              if [ "$MATCH" -eq 0 ]; then
+                MISSING_LEVELS="${MISSING_LEVELS}  ${dir}/: missing ${level}-* subdirectory\n"
+              fi
+            done
+          done
+
+          if [ -n "$MISSING_LEVELS" ]; then
+            echo "❌ Topic directory level progression violations:"
+            echo -e "$MISSING_LEVELS"
+            echo ""
+            echo "Each topic directory must contain exactly three subdirectories: 01-*, 02-*, 03-*"
+            exit 1
+          fi
+
+          echo "✅ All topic directories follow the 01/02/03 level progression."

.gitignore

@@ -0,0 +1,2 @@
+# Local AI/agent tooling artifacts
+.atl/

.lychee.toml

@@ -0,0 +1,12 @@
+# Lychee configuration for software-engineering-playbook
+# Excludes link patterns that are not verifiable in CI or are local-only.
+
+# Exclude URI patterns that are intentionally not checked in CI.
+exclude = [
+  "mailto:.*",
+  "http://localhost.*",
+  "file://.*"
+]
+
+# Allow relative markdown links like [Text](./path) — the workflow runs lychee
+# with filesystem-aware checks for repository files.

.markdownlint.yaml

@@ -0,0 +1,34 @@
+# Markdownlint configuration for software-engineering-playbook
+# Disables rules that conflict with the didactic structure of this playbook.
+#
+# MD025: Multiple top-level headings — allowed because topic READMEs may
+#        restate the topic title as an H1 alongside an H2 section overview.
+# MD041: First line heading — allowed; H1 is optional for topic introductions.
+# MD047: Single trailing newline — allowed; some files intentionally omit the
+#        final newline to keep diffs clean on appended content.
+# MD013: Line length — disabled; long code/resource links are common here.
+# MD022/MD031/MD032: Blank-line strictness is intentionally relaxed because
+#        many lessons use compact teaching blocks with headings, lists, and code.
+# MD033: Inline HTML is allowed for navigation spacing already used in the repo.
+# MD034: Bare URLs are allowed in resource sections where the URL is the lesson.
+# MD036: Emphasis-as-heading is allowed for didactic callouts.
+# MD040: Some conceptual diagrams use plain fences without a language.
+# MD060: Existing tables use compact style; this check should not rewrite history.
+# MD024: Repeated didactic subheadings like "The Rule" and "Analogy" are
+#        intentional inside repeated concept patterns.
+# MD058: Some compact intro sections place tables close to surrounding text.
+
+MD025: false
+MD041: false
+MD047: false
+MD013: false
+MD022: false
+MD031: false
+MD032: false
+MD033: false
+MD034: false
+MD036: false
+MD040: false
+MD060: false
+MD024: false
+MD058: false

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# 🤝 Contributing to the Software Engineering Playbook
+
+> **Start here if you want to suggest an improvement or report a problem.**
+
+---
+
+## Our Issue-First Philosophy
+
+This playbook is **maintainer-curated**. That is a deliberate choice.
+
+The repository's value comes from its coherent teaching voice, progressive structure, and carefully sequenced learning path — from fundamentals to advanced patterns. Every topic is placed where it is for a reason, and explanations are written to build on each other.
+
+**For this reason, content contributions (new sections, rewritten explanations, structural changes) are not accepted as pull requests.** Instead, we ask you to open an issue so we can discuss the change together before any integration work happens.
+
+This does not mean your input is unwelcome. It means we protect the learning experience for everyone — including you, when you revisit a topic later.
+
+---
+
+## Why We Use Structured Issue Templates
+
+Every issue template is designed to capture the minimum information needed to evaluate a suggestion:
+
+| Template | When to Use |
+|----------|-------------|
+| **[Bug Report](./.github/ISSUE_TEMPLATE/bug_report.md)** | Code snippets that don't work, contradictory explanations, or missing steps |
+| **[Documentation Problem](./.github/ISSUE_TEMPLATE/documentation_problem.md)** | Outdated information, factual errors, or confusing wording |
+| **[Topic Suggestion](./.github/ISSUE_TEMPLATE/topic_suggestion.md)** | A new topic or learning level you think is missing |
+| **[General Feedback](./.github/ISSUE_TEMPLATE/general_feedback.md)** | Questions, perspectives, or open-ended ideas |
+
+Using the right template ensures your feedback reaches the right context and gets the attention it deserves.
+
+---
+
+## What Is Welcome Without an Issue
+
+Not everything requires a discussion. The following are perfectly fine to submit as pull requests:
+
+- **Typo corrections**
+- **Broken links**
+- **Formatting inconsistencies** (heading levels, list styles, code block formatting)
+- **Minor repository maintenance** (missing assets, stale configuration files)
+
+If you are unsure whether something needs an issue first, open an issue anyway. We would rather discuss the idea than merge something that conflicts with the playbook's structure.
+
+---
+
+## What Happens After You Open an Issue
+
+1. A maintainer will label the issue with `status:needs-review`.
+2. The issue will be evaluated for alignment with the playbook's teaching goals and structural integrity.
+3. If approved, the maintainer will either implement the change directly or open a discussion about the best approach.
+4. You are welcome to follow along and participate in the discussion.
+
+---
+
+## The Goal
+
+A playbook that is **easy to navigate**, **consistent in voice**, and **progressive in structure** — so every learner can trust that the path is worth following.
+
+Your feedback is what keeps this repository alive. Thank you for helping us keep it that way.

README.md

@@ -138,9 +138,11 @@ These principles are not slogans. They are decision-making tools. Use them when
 
 ## 🤝 Contributions
 
-This repository is personal, but it is also open for improvement.
+This repository is **maintainer-curated** to preserve its teaching voice, progressive structure, and conceptual sequencing.
 
-If you spot an error, a broken link, an unclear explanation, or a better way to teach a concept, feel free to open an issue or pull request. The best documentation is not the one that sounds impressive; it is the one that helps someone understand faster and with less friction.
+**If you spot an error, a broken link, or have a suggestion for how to teach something better, open an issue.** Do not open a content pull request directly — we ask that you let us discuss the change first so we can keep the playbook coherent for everyone.
+
+Before contributing, read the [**Contribution Guidelines**](./CONTRIBUTING.md) to understand our issue-first workflow and what types of changes are welcome without prior discussion.
 
 ---