Merge pull request #87 from tarun-etikala/feat/markdownlint

feat: add markdownlint linting to CI

Author: kami619

.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.github/workflows/ruff.yml renamed to .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
 > ```