feat: add markdownlint linting to CI

.github/ISSUE_TEMPLATE/bug_report.md

@@ -12,6 +12,7 @@ A clear and concise description of what the bug is.
 
 **To Reproduce**
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
@@ -28,6 +29,6 @@ If applicable, add screenshots to help explain your problem.
 
 **Libs and packages (please complete the following information):**
 `uv pip list`
- 
+
 **Additional context**
 Add any other context about the problem here.

.github/workflows/ruff.yml → .github/workflows/code-quality.yml

@@ -1,4 +1,4 @@
-name: Ruff
+name: Code Quality
 
 on:
   push:
@@ -10,7 +10,7 @@ on:
 permissions: {}
 
 concurrency:
-  group: ruff-${{ github.ref }}
+  group: code-quality-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
@@ -36,3 +36,8 @@ jobs:
 
       - name: Ruff format check
         run: ruff format --check .
+
+      - name: Markdownlint
+        uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9  # v23.0.0
+        with:
+          globs: "**/*.md"

.markdownlint-cli2.yaml

@@ -0,0 +1,8 @@
+ignores:
+  - ".venv/**"
+  - "**/venv/**"
+  - "**/.venv/**"
+  - "**/node_modules/**"
+  - "**/site-packages/**"
+  - ".claude/**"
+  - "docs/superpowers/**"

.markdownlint.jsonc

@@ -0,0 +1,34 @@
+{
+    // Start with all rules enabled
+    "default": true,
+
+    // MD013: Line length — disabled; too noisy for docs-heavy repos
+    "MD013": false,
+
+    // MD033: Inline HTML — disabled; common in GitHub markdown (badges, <details>, etc.)
+    "MD033": false,
+
+    // MD036: Emphasis used instead of heading — disabled; common pattern in READMEs
+    "MD036": false,
+
+    // MD041: First line should be a top-level heading — disabled; files often start with badges or frontmatter
+    "MD041": false,
+
+    // MD060: Table column style — disabled; too noisy, newer rule not widely adopted
+    "MD060": false,
+
+    // MD024: Multiple headings with same content — allow duplicates in different sections
+    "MD024": {
+        "siblings_only": true
+    },
+
+    // MD029: Ordered list item prefix — require incrementing numbers (1. 2. 3.)
+    "MD029": {
+        "style": "ordered"
+    },
+
+    // MD046: Code block style — require fenced (```) not indented
+    "MD046": {
+        "style": "fenced"
+    }
+}

AGENTS.md

@@ -30,6 +30,7 @@ make dry-run    # preview Helm manifests
 - All agents must expose `POST /chat/completions` (JSON + SSE) and `GET /health`
 - Source code in `src/<agent_name>/` within each agent directory
 - Keep agents self-contained -- never import from another agent's `src/`
+
 ## Workflow
 
 - `cd` into the agent directory first -- Makefiles use relative paths and read `agent.yaml` at runtime

CONTRIBUTING.md

@@ -16,7 +16,9 @@ Before submitting, please read our [Code of Conduct](CODE_OF_CONDUCT.md). By par
 
 ## Linting and formatting
 
-This project uses [ruff](https://docs.astral.sh/ruff/) for Python linting and formatting. CI runs ruff as a blocking check on all pull requests.
+This project uses [ruff](https://docs.astral.sh/ruff/) for Python linting and formatting, and [markdownlint](https://github.com/DavidAnson/markdownlint) for Markdown linting. Both run as blocking CI checks on all pull requests via the `Code Quality` workflow.
+
+### Python (ruff)
 
 Run locally before pushing:
 
@@ -29,6 +31,17 @@ ruff format .         # auto-format
 
 Configuration is in [`ruff.toml`](ruff.toml) at the repo root.
 
+### Markdown (markdownlint)
+
+Run locally before pushing:
+
+```bash
+npx markdownlint-cli2@0.22.1 "**/*.md"          # lint
+npx markdownlint-cli2@0.22.1 --fix "**/*.md"    # auto-fix
+```
+
+Configuration is in [`.markdownlint.jsonc`](.markdownlint.jsonc) (rules) and [`.markdownlint-cli2.yaml`](.markdownlint-cli2.yaml) (ignored paths) at the repo root.
+
 ## Commit message conventions
 
 We encourage [Conventional Commits](https://www.conventionalcommits.org/) so that history and release notes stay clear.
@@ -48,7 +61,7 @@ You can optionally add a scope (e.g. the agent or module name) in parentheses af
 
 ### Examples
 
-```
+```text
 feat: add health check endpoint to autogen mcp_agent
 fix: correct env var name in deployment in langgraph_react_agent
 docs: update README with OpenShift deploy steps
@@ -107,6 +120,7 @@ These are the files you need to create or update when adding tracing to your age
 This module exports `enable_tracing()` (and `wrap_func_with_mlflow_trace()` if your framework's autolog doesn't cover everything). It handles health-checking the MLflow server with retry logic, configuring the experiment, enabling the correct autolog for your framework, and gracefully degrading if the server is unreachable. MLflow imports are inside `enable_tracing()` (not at module top) so the module can be imported without MLflow installed — but if `MLFLOW_TRACKING_URI` is set and MLflow is missing, the agent will fail at startup with a clear error.
 
 See existing examples:
+
 - Full autolog (no manual wrapping needed): `agents/langgraph/react_agent/src/react_agent/tracing.py`
 - Partial autolog (tools need manual wrapping): `agents/crewai/websearch_agent/src/crewai_web_search/tracing.py`
 - No framework autolog (tools + agent entry point need manual wrapping): `agents/vanilla_python/openai_responses_agent/src/openai_responses_agent/tracing.py`

MAINTAINERS.md

@@ -4,9 +4,7 @@ A repository maintainer is a committer with the additional privilege of managing
 
 ## Current Maintainers
 
-
 | Name            | GitHub Username                       |
 |-----------------|---------------------------------------|
 | Tomasz Guzik    | [MRGuziX](https://github.com/MRGuziX) |
 | Wojciech Rębisz | [Wojciech-Rebisz](https://github.com/Wojciech-Rebisz)  |
-

README.md

@@ -1,6 +1,7 @@
 <div style="text-align: center;">
 
 ![Agentic Starter Kits](/images/ask_logo.png)
+
 # Agentic Starter Kits
 
 </div>
@@ -48,7 +49,7 @@ Agents in this repository can support two deployment modes:
 
 ## Repository Structure
 
-```
+```text
 agentic-starter-kits/
 ├── agents/
 │   ├── langgraph/
@@ -146,10 +147,10 @@ See `tests/behavioral/` for full details.
 
 ## Additional Resources
 
-- **Llama Stack Documentation**: https://llama-stack.readthedocs.io/
-- **Ollama Documentation**: https://docs.ollama.com/
-- **OpenShift Documentation**: https://docs.openshift.com/
-- **Kubernetes**: https://kubernetes.io/docs/
+- **Llama Stack Documentation**: <https://llama-stack.readthedocs.io/>
+- **Ollama Documentation**: <https://docs.ollama.com/>
+- **OpenShift Documentation**: <https://docs.openshift.com/>
+- **Kubernetes**: <https://kubernetes.io/docs/>
 
 ## Contributing
 

agents/a2a/langgraph_crewai_agent/README.md

@@ -55,7 +55,7 @@ This runs `uv sync --python 3.12` and creates or updates `.venv`.
 
 You can use placeholders for container images if you only run Python locally:
 
-```
+```ini
 API_KEY=your-key-or-not-needed
 BASE_URL=http://localhost:8321/v1
 MODEL_ID=ollama/llama3.1:8b
@@ -115,7 +115,7 @@ Default ports: **9100** (Crew), **9200** (LangGraph). Do not set `PORT` unless y
 
 ### Playground (LangGraph orchestrator)
 
-With the LangGraph server running (terminal 2), open **http://127.0.0.1:9200/** in a browser. The chat uses **A2A JSON-RPC** on **`POST /`** with **`message/send`**. The server also exposes **`POST /chat/completions`** (OpenAI-style). For local `curl`, use `http://127.0.0.1:9200`.
+With the LangGraph server running (terminal 2), open **<http://127.0.0.1:9200/>** in a browser. The chat uses **A2A JSON-RPC** on **`POST /`** with **`message/send`**. The server also exposes **`POST /chat/completions`** (OpenAI-style). For local `curl`, use `http://127.0.0.1:9200`.
 
 ---
 

agents/autogen/mcp_agent/README.md

@@ -18,7 +18,7 @@ dynamically (e.g. churn prediction, deployment), and answers user questions via
 
 - Discovers and loads tools from an MCP server at startup
 - Uses `reflect_on_tool_use=True` so the LLM reasons about tool results before responding
-- Supports both streaming (SSE) and non-streaming responses (streaming auto-adjusts when MLflow tracing is enabled; see [Tracing](#tracing) section)
+- Supports both streaming (SSE) and non-streaming responses (streaming auto-adjusts when MLflow tracing is enabled; see [Tracing](#tracing-optional) section)
 - Includes an interactive web playground with an MCP tools panel
 - Extends OpenAI streaming with `mcp.tool_usage` events and `tool_invocations` in JSON responses
 
@@ -166,6 +166,7 @@ MLFLOW_WORKSPACE="default"
 ```
 
 **Notes:**
+
 - `MLFLOW_TRACKING_URI` - URL of your MLflow server. For local development, use `http://localhost:5000`. If using MLflow on an OpenShift cluster, replace `<openshift-dashboard-url>` with your cluster's data science gateway URL.
 - `MLFLOW_TRACKING_TOKEN` - Required for OpenShift only. Your OpenShift authentication token, obtained from the OpenShift console.
 - `MLFLOW_EXPERIMENT_NAME` - A descriptive name for your experiment (e.g., "AutoGen MCP Demo")
@@ -298,9 +299,9 @@ CONTAINER_IMAGE=quay.io/your-username/autogen-mcp-agent:latest
 
   Examples:
 
-    - Quay.io: `quay.io/your-username/autogen-mcp-agent:latest`
-    - Docker Hub: `docker.io/your-username/autogen-mcp-agent:latest`
-    - GHCR: `ghcr.io/your-org/autogen-mcp-agent:latest`
+  - Quay.io: `quay.io/your-username/autogen-mcp-agent:latest`
+  - Docker Hub: `docker.io/your-username/autogen-mcp-agent:latest`
+  - GHCR: `ghcr.io/your-org/autogen-mcp-agent:latest`
 
 #### Preview manifests
 
@@ -335,6 +336,7 @@ make undeploy
 ```
 
 > **Note:** `make undeploy` removes only the agent. To also remove the MCP server:
+>
 > ```bash
 > make undeploy-mcp
 > ```

agents/autogen/mcp_agent/mcp_automl_template/AUTOML_DEPLOYMENT.md

@@ -204,4 +204,4 @@ The tool will POST to `DEPLOYMENT_URL` with `Authorization: Bearer <DEPLOYMENT_T
 - [Red Hat AI examples – Predict Customer Churn (AutoML)](https://github.com/red-hat-data-services/red-hat-ai-examples/blob/automl_sample/examples/automl/churn_prediction_tutorial.md) – full tutorial (project, S3, pipeline, leaderboard, predictor notebook, model registry, ServingRuntime, deployment, scoring).
 - [autogluon_tabular_training_pipeline](https://github.com/LukaszCmielowski/pipelines-components/tree/rhoai_automl/pipelines/training/automl/autogluon_tabular_training_pipeline) – pipeline source (branch `rhoai_automl`).
 - [KServe V1 Protocol](https://kserve.github.io/website/docs/concepts/architecture/data-plane/v1-protocol) – inference request/response format.
-- This repo’s [README](README.md) – MCP server setup, tools, Cursor/Ollama, and `.env`.
+- This repo’s [README](README.md) – MCP server setup, tools, Cursor/Ollama, and `.env`.

agents/autogen/mcp_agent/mcp_automl_template/README.md

@@ -36,7 +36,7 @@ For quick tests or custom pipelines, raw requests are fine (see the notebook). F
 
 ## Directory structure
 
-```
+```text
 mcp_automl_template/
 ├── pyproject.toml      # Project metadata and dependencies
 ├── mcp_server.py       # FastMCP server; registers example tools + tools from YAML
@@ -59,6 +59,7 @@ mcp_automl_template/
 1. **Install dependencies**
 
    With [uv](https://docs.astral.sh/uv/):
+
    ```bash
    uv pip install .
    ```

agents/crewai/websearch_agent/README.md

@@ -30,7 +30,7 @@ questions. Use with any OpenAI-compatible API.
 
 ## Local Development
 
-#### Initiating base
+### Initiating base
 
 Here you copy .env.example file into .env
 
@@ -43,7 +43,7 @@ Edit `.env` with your configuration, then:
 
 See [Local Development](../../../docs/local-development.md) for Ollama + Llama Stack setup for local model serving.
 
-#### Pointing to a remotely hosted model
+### Pointing to a remotely hosted model
 
 ```ini
 API_KEY=your-api-key-here
@@ -57,15 +57,15 @@ MODEL_ID=llama-3.1-8b-instruct
 - `BASE_URL` — should end with `/v1`
 - `MODEL_ID` — model identifier available on your endpoint
 
-#### Creating environment
+### Creating environment
 
 Now you will remove old .venv and create new. Next dependencies will be installed.
 
 ```bash
 make env
 ```
 
-#### Setup Ollama
+### Setup Ollama
 
 This will install ollama if it is not installed already. Then pull needed models for local work.
 The default model is `llama3.1:8b`. To use a different model, pass `MODEL=`:
@@ -75,7 +75,7 @@ The default model is `llama3.1:8b`. To use a different model, pass `MODEL=`:
 make ollama
 ```
 
-#### Run llama server
+### Run llama server
 
 > **Keep this terminal open** – the server needs to keep running.
 > You should see output indicating the server started on `http://localhost:8321`.
@@ -84,7 +84,7 @@ make ollama
 make llama-server
 ```
 
-#### Run the interactive web application
+### Run the interactive web application
 
 > **Keep this terminal open** – the app needs to keep running.
 > You should see output indicating the app started on `http://localhost:8000`.
@@ -94,7 +94,7 @@ cd agents/crewai/websearch_agent
 make run-app           # fails if port is already in use and print steps TO-DO
 ```
 
-#### Interactive CLI
+### Interactive CLI
 
 For terminal-based testing without a browser:
 
@@ -103,7 +103,7 @@ cd agents/crewai/websearch_agent
 make run-cli
 ```
 
-#### Tracing with a local MLflow server
+### Tracing with a local MLflow server
 
 To enable MLflow tracing, add the following to your `.env`:
 
@@ -123,7 +123,7 @@ uv run --extra tracing mlflow server --port 5000
 
 When `MLFLOW_TRACKING_URI` is set, `make run-app` and `make run-cli` will automatically install the tracing dependency.
 
-##### Configuring the LLM provider for tracing
+#### Configuring the LLM provider for tracing
 
 CrewAI can use different LLM providers. Set `LLM_PROVIDER` to match your provider so MLflow uses the correct autolog
 integration:
@@ -137,7 +137,7 @@ integration:
 | `azure`              | `mlflow.openai.autolog()`    | Azure OpenAI                |
 | `bedrock`            | `mlflow.bedrock.autolog()`   | AWS Bedrock                 |
 
-#### Tracing with an OpenShift MLflow server
+### Tracing with an OpenShift MLflow server
 
 To enable tracing and logging with MLflow on your OpenShift cluster, add the following environment variables to your
 `.env` file:
@@ -198,9 +198,9 @@ CONTAINER_IMAGE = quay.io/your-username/crewai-websearch-agent:latest
 
   Examples:
 
-    - Quay.io: `quay.io/your-username/crewai-websearch-agent:latest`
-    - Docker Hub: `docker.io/your-username/crewai-websearch-agent:latest`
-    - GHCR: `ghcr.io/your-org/crewai-websearch-agent:latest`
+  - Quay.io: `quay.io/your-username/crewai-websearch-agent:latest`
+  - Docker Hub: `docker.io/your-username/crewai-websearch-agent:latest`
+  - GHCR: `ghcr.io/your-org/crewai-websearch-agent:latest`
 
   > **Note:** OpenShift must be able to pull the container image. Make the image **public**, or configure
   an [image pull secret](https://docs.openshift.com/container-platform/latest/openshift_images/managing_images/using-image-pull-secrets.html)
@@ -315,4 +315,4 @@ curl http://localhost:8000/health
 ## Resources
 
 - [CrewAI Documentation](https://docs.crewai.com/)
-- [CrewAI Tools](https://docs.crewai.com/concepts/tools)
+- [CrewAI Tools](https://docs.crewai.com/concepts/tools)