@ngocsangairvds/vsaf 4.0.6 → 4.0.8

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/03-memory-cross-agent.md

@@ -0,0 +1,243 @@
+<!-- diátaxis: how-to -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Using VDS AI Memory from External Agent CLIs
+
+This guide covers how external agent runtimes — Codex, OpenCode, and Qwen — can
+read from and write to VDS AI Memory using the `vds-cli memory` subcommand.
+
+## Prerequisites
+
+The VDS AI Memory API must be running and reachable. Start the active runtime stack if needed:
+
+```bash
+cd WHO-project/vds-scripts/memory_orchestrator
+docker compose --profile dev --profile mem0 up -d
+```
+
+This starts the active memory runtime stack from `memory_orchestrator/`.
+
+> `WHO-project/vds-ai-memory/` is historical/archive-only and should not be used for current startup or runtime guidance.
+
+## Runtime Environment Resolution
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `VDS_MEMORY_API_URL` | Explicit base URL of the memory API | If unset: `http://localhost:${API_PORT:-8000}` |
+
+`vds-cli memory` loads `~/.vds/.env` automatically. Set an explicit URL only
+when the runtime is on a non-default host/port:
+
+```bash
+export VDS_MEMORY_API_URL="http://localhost:8010"
+```
+
+> **Note:** The memory API does not require an API key in its default
+> local-dev configuration. For current runtime/deployment guidance, prefer
+> `WHO-project/vds-scripts/memory_orchestrator/README.md` and the canonical spec
+> triplet under `.gpt-5.4/specs/vds-ai-memory/`.
+
+## Storing a Decision
+
+```bash
+# Store a decision scoped to a project using tags
+vds-cli memory store "decided to use Kafka for async event dispatch" \
+  --category business-logic --importance high \
+  --tags PAR,architecture,kafka
+
+# Minimal store
+vds-cli memory store "merchant-billing uses Spring Boot 3.2"
+```
+
+## Searching Memories
+
+```bash
+# Semantic search across all memories
+vds-cli memory search "kafka event dispatch" --limit 5
+
+# Filter by category
+vds-cli memory search "auth patterns" --category business-logic --limit 10
+```
+
+## Usage from Each Agent CLI
+
+All agent CLIs that can run shell commands can call `vds-cli` directly.
+Inherit `~/.vds/.env` via the shell session that launches the agent. Set
+`VDS_MEMORY_API_URL` only if you need an explicit override.
+
+### Codex
+
+```bash
+codex exec --skip-git-repo-check -m gpt-5.4 "your prompt here"
+```
+
+Within the Codex session, the agent runs shell commands:
+
+```bash
+vds-cli memory store "Codex discovered that merchant-report uses JPA auditing"
+vds-cli memory search "merchant-report auditing"
+```
+
+### OpenCode (Z.AI / GLM)
+
+```bash
+opencode run -m "zai-coding-plan/glm-5.1" "your prompt here"
+```
+
+The OpenCode agent shell-executes:
+
+```bash
+vds-cli memory store "OpenCode: PAR project checklist page is 88722450" \
+  --category business-logic --importance high
+vds-cli memory search "PAR checklist"
+```
+
+### Qwen
+
+```bash
+qwen -m qwen3-coder "your prompt here"
+```
+
+Qwen agents call:
+
+```bash
+vds-cli memory store "Qwen: insurance hexagonal boundary violations found in 3 repos"
+vds-cli memory search "hexagonal boundary violations"
+```
+
+## Project Scoping via Tags
+
+To keep memories scoped to a project, include the project key as a tag:
+
+```bash
+# Store scoped to project PAR
+vds-cli memory store "billing service auth pattern confirmed" \
+  --tags PAR,billing,auth
+
+# Search within PAR context (post-filter by tags)
+vds-cli memory search "billing auth" --limit 10
+```
+
+## Health Check
+
+Before a long agent run, verify the memory service is reachable:
+
+```bash
+vds-cli memory health
+```
+
+Expected output: `{"status": "healthy", ...}`
+
+## Practical Rules
+
+- Store decisions immediately after they are made — do not batch at end of session.
+- Include project key, service name, and date context in the content string.
+- Keep content under 500 characters per memory for searchability.
+- Do not store secrets, credentials, or personal data.
+- Use `--importance high` for irreversible architectural decisions.
+
+---
+
+## Python SDK: `vds_memory_client` (VAMI-003)
+
+Since VAMI-003, a standalone Python package `vds_memory_client` provides
+programmatic access to VDS AI Memory for any Python agent or script — no
+`vds-cli` installation required.
+
+### Installing
+
+```bash
+# From the VDS monorepo (worktree or vds-scripts)
+uv run --project WHO-project/vds-scripts/vds_memory_client python3 -c "import vds_memory_client"
+
+# Or add as a dependency in your pyproject.toml
+[tool.uv.sources]
+vds_memory_client = { path = "../../vds_memory_client" }
+```
+
+### Basic Usage
+
+```python
+import asyncio
+from vds_memory_client import VDSMemoryClient
+
+async def main():
+    import os
+
+    base_url = os.getenv("VDS_MEMORY_API_URL") or f"http://localhost:{os.getenv('API_PORT', '8000')}"
+    client = VDSMemoryClient(base_url=base_url, timeout=10.0)
+
+    # Health check
+    status = await client.health()
+    print(status)  # {"status": "healthy", ...}
+
+    # Store a decision
+    result = await client.store(
+        content="Decided to use Kafka for async event dispatch",
+        category="business-logic",
+        importance="high",
+        tags=["PAR", "architecture"],
+    )
+    print(result["memory_id"])
+
+    # Search
+    results = await client.search(query="kafka event dispatch", limit=5)
+    for m in results["results"]:
+        print(f"[{m['category']}] {m['content'][:80]}")
+
+asyncio.run(main())
+```
+
+### Session State Caching
+
+`VDSMemoryClient` caches the health-check result in `~/.vds/.memory-session.json`
+using an atomic write (`tempfile.mkstemp` + `os.replace`). This file is:
+- **Not** in iCloud (lives in `~/.vds/`, not `~/Library/Mobile Documents/`)
+- Safe for concurrent writes from multiple agent processes
+- Valid for 60 minutes by default before the client re-checks health
+
+### iCloud Path Compatibility
+
+`vds_memory_client` runs correctly from iCloud-backed project paths
+(e.g. `~/Library/Mobile Documents/com~apple~CloudDocs/...`). The key properties
+that make this safe:
+
+| Concern | How it is handled |
+|---------|-------------------|
+| Spaces in path arguments | Wrap variables in double-quotes: `"$CLAUDE_PROJECT_DIR/..."` |
+| Atomic session writes | Written to `~/.vds/` (outside iCloud), using `os.replace()` |
+| `uv run --project <path>` | Path passed as a quoted argument; uv handles spaces correctly |
+
+### Hook Integration (now via Claude Code plugins)
+
+**Status (2026-04-24)**: The `vds_hooks` Python package was retired by
+`vds-hooks-claude-plugin-packaging` Phase 6. Hook integration with VDS AI Memory
+now lives entirely in the **Claude Code plugin format**:
+
+- `WHO-project/vds-skills/plugins/vds-hooks-core/` — generic hooks
+- `WHO-project/vds-skills/plugins/vds-hooks-extras/` — VDS-specific hooks (memory, audit, agent context)
+
+Plugins are installed via `/plugin marketplace add` + `/plugin install` and fire
+automatically on Claude Code events (`SessionStart`, `Stop`, `SessionEnd`,
+`UserPromptSubmit`, etc.) — no manual `vds-cli` invocation required.
+
+For the HTTP proxy endpoints, see
+`WHO-project/vds-scripts/memory_orchestrator/` — those endpoints are
+independent of the Python-package retirement and continue to serve
+`POST /api/v1/hooks/session-context` and `POST /api/v1/hooks/session-persist`.
+
+For SDK-level memory access from your own scripts, use `vds_memory_client`
+(see "Python SDK" section above). For the canonical hook semantics + dual-path
+safety-net design, see the spec at
+`.gpt-5.4/specs/vds-hooks-claude-plugin-packaging/` (Phase 6 archive +
+predecessor `hooks.RETIRED-2026-05-02/`).
+
+### Environment Variables
+
+| Variable | Effect | Default |
+|----------|--------|---------|
+| `VDS_MEMORY_API_URL` | API base URL | If unset: `http://localhost:${API_PORT:-8000}` |
+| `VDS_HOOK_SESSION_MEMORY` | Set to `"0"` to disable session context hook | `"1"` |
+| `VDS_HOOK_MEMORY_PERSIST` | Set to `"0"` to disable persist-stop hook | `"1"` |
+| `VDS_HOOK_MEMORY_DECISIONS` | Set to `"0"` to skip decision extraction | `"1"` |

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/04-using-progress-reports.md

@@ -0,0 +1,242 @@
+<!-- diátaxis: how-to -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# How To: Generate Progress Reports
+
+## Prerequisites
+
+1. **Repos synced**: `vds-cli audit sync repos --bitbucket-project INSURANCE-AI`
+2. **BMAD knowledge graph**: Must exist at `~/.vds/cache/repos/INSURANCE-AI-project/bmad_ntbh/`
+3. **Database** (optional): Set `VDS_PROGRESS_STATE_DSN` in `~/.vds/.env` for persistence
+
+## Quick Start
+
+```bash
+# Structural-only report (fast, ~2s)
+vds-cli progress report -p INSURANCE-AI --dimensions structural --skip-sync
+
+# Check your score
+vds-cli progress db status
+```
+
+## Common Workflows
+
+### Daily Score Check
+
+```bash
+# Generate report and check trend
+vds-cli progress report -p INSURANCE-AI --dimensions structural --skip-sync -q
+vds-cli progress db status
+```
+
+### Deep-Dive a Specific FR
+
+```bash
+# FR8 analysis in JSON
+vds-cli progress report -p INSURANCE-AI --fr FR8 --dimensions structural --format json --skip-sync -q
+```
+
+### Scripted/CI Usage
+
+Use `--quiet` (`-q`) and `--format json` for clean machine-readable output:
+
+```bash
+SCORE=$(vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['overall_score'])")
+echo "Current score: $SCORE"
+```
+
+### Resume an Interrupted Run
+
+If a run fails mid-pipeline, the checkpoint is saved in the DB:
+
+```bash
+# The run_id is printed in the log output
+vds-cli progress report -p INSURANCE-AI --resume-run-id <uuid-from-failed-run>
+```
+
+### Topology Exploration
+
+```bash
+# List all FRs in the knowledge graph
+vds-cli progress topology -p INSURANCE-AI -q | jq '.fr_modules[].fr_id'
+
+# Count services
+vds-cli progress topology -p INSURANCE-AI -q | jq '.service_catalog | length'
+```
+
+## LLM Provider Selection (Phase 3)
+
+Use `--llm-provider` to control which LLM backend scores dimensions 7-8:
+
+```bash
+# Auto-detect from environment (default)
+vds-cli progress report -p INSURANCE-AI --llm-provider auto
+
+# Explicit provider
+vds-cli progress report -p INSURANCE-AI --llm-provider openai    # requires OPENAI_API_KEY
+vds-cli progress report -p INSURANCE-AI --llm-provider anthropic # requires ANTHROPIC_AUTH_TOKEN
+vds-cli progress report -p INSURANCE-AI --llm-provider ollama    # requires Ollama on localhost:11434
+
+# Disable LLM entirely (equivalent to --dimensions structural)
+vds-cli progress report -p INSURANCE-AI --llm-provider none --skip-sync
+```
+
+Auto-detect order: explicit `--profile` → `VDS_AUDIT_LLM_ENABLED=0` hard-disable → `OPENAI_API_KEY` / `ANTHROPIC_AUTH_TOKEN` env → structural-only.
+
+**Ollama is NOT auto-detected** — it must be requested via `--llm-provider ollama` explicitly. This is because Ollama's installed models may be cloud-routed, embedding-only, or reasoning models that need different token budgets, so aggressive auto-detection caused score regressions. When auto mode finds no provider, it leaves dims 7-8 as `None` and scores renormalize across structural dimensions only — **auto-detect is guaranteed to produce the same score as `--llm-provider none`**.
+
+## JSON Report Schema (Phase 3)
+
+Phase 3 reports include three new top-level keys in `--format json` output:
+
+```bash
+vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q \
+  | jq '{heatmap: .heatmap, repo_health: .repo_health, coverage: .dimension_coverage}'
+```
+
+- **`heatmap`**: List of FR × dimension objects — boolean pass/fail and numeric scores per FR
+- **`repo_health`**: Per-repo test ratio and `green`/`yellow`/`red` health indicator
+- **`dimension_coverage`**: Pass-rates and averages across all FRs (e.g. `service_exists: 0.9`)
+
+## Scripted Score + Coverage
+
+```bash
+vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q | \
+  python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print(f'Score: {d[\"overall_score\"]}')
+print(f'Doc chain: {d[\"dimension_coverage\"].get(\"doc_chain_complete\", \"N/A\")}')
+print(f'Recommendations: {sum(len(s[\"recommendations\"]) for s in d[\"sections\"])}')
+"
+```
+
+## Progressive Disclosure Modes (Phase 4)
+
+`--mode` picks a rendering tier. All four modes use the same underlying computation — only the rendered output differs:
+
+```bash
+# Exec: ≤20 lines. Slack pastes, email digests, GitHub status checks.
+vds-cli progress report -p INSURANCE-AI --mode exec --skip-sync -q
+
+# Summary: ≤100 lines. Standup review, code-review context, daily digest.
+vds-cli progress report -p INSURANCE-AI --mode summary --skip-sync -q
+
+# Standard: ~564 lines. Default. Byte-identical to pre-Phase-4 output (heatmap,
+# per-FR detail, trend, risk register). Use when daily development review.
+vds-cli progress report -p INSURANCE-AI --skip-sync -q   # --mode standard is implicit
+
+# Full: ~581 lines. Standard + stratified cluster sub-reports + appendices.
+# Use for quarterly audits, retrospectives, compliance packets.
+vds-cli progress report -p INSURANCE-AI --mode full --skip-sync -q
+```
+
+**Tip**: Start with `--mode exec` when piping into chat notifications and bump up to `summary` or `full` only when someone asks "why did the score move?"
+
+## CI/CD Quality Gates (Phase 4)
+
+Make progress report failures break your pipeline. `vds-cli progress report` exits with:
+
+- `0` — report generated, no gates tripped
+- `1` — runtime error (missing DSN, sync failed, crash)
+- `2` — **quality gate failed** (report file still written)
+
+```bash
+# Fail the build if overall score drops below 60
+vds-cli progress report -p INSURANCE-AI --skip-sync --fail-under 60 -q
+
+# Fail if any FR regressed by more than 15 points vs the previous run
+vds-cli progress report -p INSURANCE-AI --skip-sync --fail-on-regression -q
+
+# Compare against a specific historical run instead of "previous"
+vds-cli progress report -p INSURANCE-AI --skip-sync \
+  --fail-on-regression --baseline <run-id> -q
+
+# Combine gates — any trip exits 2
+vds-cli progress report -p INSURANCE-AI --skip-sync \
+  --fail-under 60 --fail-on-regression -q
+echo $?   # 2 if either gate fails
+```
+
+**Important**: Unlike SonarQube's `sonar-scanner` (which silently exits 0 even on gate failure unless you pass `-Dsonar.qualitygate.wait=true`), `vds-cli progress` honors gate flags immediately when set. The report file is always written before the non-zero exit, so your CI can still upload it as an artifact.
+
+**GitHub Actions example**:
+
+```yaml
+- name: Progress check
+  run: |
+    vds-cli progress report -p INSURANCE-AI --skip-sync \
+      --fail-under 60 --mode exec -q > progress.txt
+  continue-on-error: false   # exit 2 fails the step
+
+- name: Upload report
+  if: always()   # still upload when the step failed
+  uses: actions/upload-artifact@v4
+  with:
+    path: ~/.vds/cache/progress-reports/
+```
+
+## Bimodal Distribution / Stratified Clusters (Phase 4)
+
+When your FR scores split cleanly into "passing FRs" and "failing FRs" with no middle tier, the report emits a `bimodal_warning` block. This is the **valence-gap heuristic** — a UX signal, not statistical bimodality (ADR-Q7).
+
+Detection rules (all must hold):
+
+1. `total_frs ≥ 10`
+2. `medium == 0`
+3. `high_count > 0 AND low_count > 0`
+4. `min(high, low) / total ≥ 0.25` (dominance guard — kills skewed-unimodal false positives like 14/0/1)
+
+When detected, `summary` and `full` modes render **stratified sub-reports**: a high-cluster mini-report (passing FRs, avg score, weakest remaining dim, top remaining action) and a low-cluster mini-report (blocked FRs, dominant blocker, highest-priority fix).
+
+Extract cluster data from JSON:
+
+```bash
+vds-cli progress report -p INSURANCE-AI --format json --skip-sync -q \
+  | jq '.bimodal_warning'
+# {
+#   "detected": true,
+#   "stratification_variable": "service_exists",
+#   "high_cluster": {
+#     "label": "passing",
+#     "fr_ids": ["FR6", "FR7", "FR8", ...],
+#     "avg_score": 83.6,
+#     "dominant_blocker": "test_coverage",
+#     "top_recommendation_fr": "FR8"
+#   },
+#   "low_cluster": { ... }
+# }
+```
+
+**Interpretation**: A bimodal warning usually means *"the services that exist are healthy; the ones that are failing aren't built yet"* — your work is recipe-style scaffolding, not debugging the passing services. Use `dominant_blocker` to pick the next sprint focus and `top_recommendation_fr` as the starting FR.
+
+## Trend Regression Bucketing (Phase 4)
+
+When a previous run exists, the report bucketizes FR deltas vs baseline:
+
+| Δ score | Bucket | Render |
+|---------|--------|--------|
+| `Δ ≤ -15` | **Critical regression** | Loud callout + risk register entry |
+| `-15 < Δ ≤ -5` | Minor regression | Subtle callout |
+| `-5 < Δ < 5` | Noise floor | Ignored |
+| `5 ≤ Δ < 15` | Improvement | Noted |
+| `Δ ≥ 15` | Major improvement | Highlighted |
+
+Thresholds are intentionally simple for Phase 4. Phase 4.1 will upgrade to **Western Electric Rules** (3σ single-point, 2-of-3 at 2σ, 4-of-5 at 1σ) using rolling mean/stddev from `daily_scores`.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "no DSN provided" | Set `VDS_PROGRESS_STATE_DSN` in `~/.vds/.env` |
+| "bmad_ntbh not found" | Run `vds-cli audit sync repos --bitbucket-project INSURANCE-AI` |
+| Structlog lines in output | Use `-q` flag or redirect stderr (`2>/dev/null`) |
+| Score unchanged after code changes | Re-sync repos (remove `--skip-sync`) |
+| LLM not detected | Check `OPENAI_API_KEY` / `ANTHROPIC_AUTH_TOKEN` in `~/.vds/.env`, or use `--llm-provider none` |
+| CI shows exit 0 when score is low | Confirm `--fail-under <score>` flag is set — gates are opt-in |
+| `--fail-on-regression` not tripping | No baseline exists yet (first run) or baseline is outside the noise floor — pass `--baseline <run-id>` explicitly |
+| `bimodal_warning.detected: false` when I expected true | Check `total_frs ≥ 10`, `medium == 0`, dominance `≥ 0.25` — skewed distributions like 14/0/1 are rejected by design |
+| `--mode exec` output missing trend | Exec mode is deliberately ≤20 lines; use `--mode summary` for trend sparklines |
+| Standard mode output looks different | Should be byte-identical to Phase 3. File a bug if it's not — the G-Q11c structural invariants test guards this. |

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/08-semantic-search.md

@@ -0,0 +1,16 @@
+<!-- diátaxis: how-to -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# How To Run Semantic Search
+
+Use the skill entrypoint and local references first:
+
+- [grepai-skill](../../../../vds-skills/skills/grepai-skill/SKILL.md)
+- [Advanced patterns](../../../../vds-skills/skills/grepai-skill/references/advanced-patterns.md)
+- [grepai commands](../../../../vds-skills/skills/grepai-skill/references/grepai-commands.md)
+
+Operational rule:
+
+- Start with semantic search to discover candidates.
+- Narrow with `rg` or `sg` once the search space is known.

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/choose-the-right-command-or-skill.md

@@ -0,0 +1,36 @@
+<!-- diátaxis: how-to -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Choose The Right WHO Command Or Skill
+
+Use this guide when you know the task you want to perform but are not sure whether to start with a CLI command family or a specialist skill.
+
+## Step 1: Is this a platform-routing question?
+
+Use `vds-scripts-skill` when you need to:
+- find the right WHO command family
+- bootstrap the scripts workspace
+- understand which workspace capability owns a task
+- route to the correct specialist skill
+
+## Step 2: Route by task intent
+
+| Intent | Start Here |
+|-------|------------|
+| Run audit workflow, readiness, rerun, upload | `audit-orchestrator-skill` + `vds-cli audit` |
+| Evaluate README/API docs/security docs with LLM support | `llm-analysis-skill` |
+| Create or update specs | `spec-creation-skill` + `vds-cli spec` |
+| Develop a CLI/orchestrator | `cli-development-skill` |
+| Use Jira/Confluence/Bitbucket/Git | `vds-scripts-skill` + `vds-cli` integration family |
+| Validate docs, links, schemas, OpenAPI, diagrams, sheets | `vds-scripts-skill` + validation family |
+| Configure LSP | `lsp-skill` |
+| Analyze dependency cycles | `circular-dependency-skill` |
+| Research across local + external sources | `research-skill` |
+
+## Step 3: Follow canonical sources
+
+- Scripts: `WHO-project/vds-scripts/`
+- Skills: `WHO-project/vds-skills/skills/`
+- Do not edit `.agent/skills/` directly
+- For shared env/config/cache path behavior, use `../reference/portable-paths-and-config.md`

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/decision-tree.md

@@ -0,0 +1,77 @@
+<!-- diátaxis: how-to -->
+<!-- TODO: translate — Vietnamese translation needed -->
+
+# Tôi Đang Viết Loại Tài Liệu Nào?
+
+> **Lưu ý**: Tài liệu này cần được dịch sang tiếng Việt.
+> **Note**: This document needs Vietnamese translation. The English version is canonical.
+> English source: [docs/agents/how-to/decision-tree.md](../how-to/decision-tree.md)
+
+---
+
+## Phương Pháp Một Câu Hỏi
+
+*(English content below — TODO: translate)*
+
+# What Kind of Doc Am I Writing?
+
+Quick decision tree for choosing the correct Diátaxis quadrant.
+
+---
+
+## The One-Question Method
+
+Start at the top and answer each question. The first "YES" tells you the quadrant.
+
+```
+Q1: Is this for someone who has NEVER done this before?
+     → YES → TUTORIAL
+     → NO → Q2
+
+Q2: Is this a step-by-step recipe for a SPECIFIC task?
+     → YES → HOW-TO GUIDE
+     → NO → Q3
+
+Q3: Is this listing exact flags, contracts, or API surfaces?
+     → YES → REFERENCE
+     → NO → Q4
+
+Q4: Is this explaining WHY something works or background concepts?
+     → YES → EXPLANATION
+     → NO → Re-examine your scope. You may be mixing quadrants.
+```
+
+---
+
+## Examples by Quadrant
+
+| Doc Title | Quadrant | Why |
+|-----------|----------|-----|
+| "Day 0: Install the WHO toolchain" | Tutorial | First-time learner |
+| "How to add a new skill to the catalog" | How-to | Specific task |
+| `vds-cli --help` auto-generated docs | Reference | Exact flags |
+| "Why we use Diátaxis for doc architecture" | Explanation | Background concept |
+
+---
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Fix |
+|--------------|-----|
+| Tutorial sneaks in unrelated tasks | Split to a separate How-to |
+| Reference doc tells a story | Delete narrative; keep only facts |
+| How-to explains the "why" | Move "why" to a linked Explanation doc |
+| Explanation gives step-by-step commands | Move commands to a How-to |
+
+---
+
+## Header Convention
+
+Every `.md` in `docs/agents/` should include its quadrant as the very first line:
+
+```markdown
+<!-- diátaxis: tutorial -->
+# Title
+```
+
+Valid values: `tutorial`, `how-to`, `reference`, `explanation`