From 6288fe6e477b8eedddcea0c0eba0d139d5fef2d4 Mon Sep 17 00:00:00 2001
From: ivaseeq <126263471+ivaseeq@users.noreply.github.com>
Date: Thu, 29 Oct 2026 03:33:40 +0300
Subject: [PATCH] docs: explain Qwen extension common rule supplement

---
 docs/QWEN-GUIDE.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/docs/QWEN-GUIDE.md b/docs/QWEN-GUIDE.md
index 8e9e17122..d1f481e6d 100644
--- a/docs/QWEN-GUIDE.md
+++ b/docs/QWEN-GUIDE.md
@@ -2,6 +2,57 @@
 
 ECC can install its managed command, agent, skill, rule, and MCP surfaces into the Qwen CLI home directory.
 
+## Native extension installation and common rules
+
+Qwen Code also supports installing the Claude marketplace package through its
+own extension manager:
+
+```bash
+qwen extensions install https://github.com/affaan-m/ECC:ecc
+```
+
+This is a different installation path from the managed adapter below. On Qwen
+Code 0.26.1 with the ECC v2.2.3 release, the extension loads skills and commands,
+but reports eleven rule warnings: ten files in `rules/common/` and
+`rules/README.md` have no `paths:` frontmatter.
+
+This is intentional Qwen behavior: **extension rules must be conditional**.
+User rules under `~/.qwen/rules/` may instead be baseline instructions, loaded
+from the first request. See the [Qwen rules documentation](https://qwenlm.github.io/qwen-code-docs/en/users/features/rules/).
+Do not add artificial `paths: ["**/*"]` to shared ECC rules just to silence the
+warnings; that changes when they apply and does not preserve baseline semantics.
+`rules/README.md` is installation documentation and should not become a rule.
+
+If you explicitly want ECC's common policies in every normal Qwen session
+(outside safe mode), you can
+supplement the extension with a user-owned copy of **only** its common rules:
+
+```bash
+# Inspect these policies first: they include TDD, coverage and delegation rules.
+# Stop if the destination exists; review/merge existing files instead of overwriting.
+test ! -e "$HOME/.qwen/rules/ecc/common" && \
+  test ! -L "$HOME/.qwen/rules/ecc/common" && \
+  mkdir -p "$HOME/.qwen/rules/ecc" && \
+  cp -R "$HOME/.qwen/extensions/ecc/rules/common" "$HOME/.qwen/rules/ecc/"
+```
+
+For project-only scope, use `<project>/.qwen/rules/ecc/` as the destination;
+project rules load only in trusted workspaces. Choose one scope to avoid
+duplicating the same baseline policies. Keep the `common/` subdirectory.
+
+These copies are not owned or updated by the extension manager. After
+`qwen extensions update ecc`, compare them with the extension's common rules
+and refresh deliberately, preserving any local edits. To undo this supplement,
+remove only the copied `common/` directory after checking for local changes.
+The original extension warnings remain: verify that the user/project copies
+load, rather than treating warning disappearance as proof of success.
+
+Do not run `--modules rules-core` over an active extension as a minimal repair:
+it installs the entire rules tree, including language rules already supplied by
+the extension and the README. Likewise, do not layer a full managed install
+over the extension unintentionally. Successful skill loading does not establish
+hook-runtime compatibility.
+
 ## Install
 
 From the ECC repository root: