@abarcenas/ai-workflow-template 1.23.0 → 1.26.0

package/.agents/skills/graphify-framework-aware/scripts/fw-exclude.py

@@ -0,0 +1,425 @@
+#!/usr/bin/env python3
+"""graphify-framework-aware: detect project frameworks and generate .graphifyignore patterns.
+
+Commands:
+    detect <path>        Print JSON of detected frameworks and their markers.
+    apply  <path>        Idempotently write/update .graphifyignore with FW patterns.
+    show   <path>        Print FW patterns only (dry-run, no files written).
+
+Exit codes: 0 = success, 1 = error (bad path, invalid args), 2 = nothing to apply.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+# ── Framework Registry ────────────────────────────────────────────────────────
+# Adding a new framework:
+#   1. Add detection marker(s) to FRAMEWORK_MARKERS.
+#   2. Add exclude patterns to FRAMEWORK_EXCLUDES.
+# Complex detection (Hugo theme) goes in _post_process_excludes().
+
+FRAMEWORK_MARKERS: dict[str, list[str]] = {
+    "angular":     ["angular.json"],
+    "nextjs":      ["next.config.js", "next.config.ts", "next.config.mjs"],
+    "svelte":      ["svelte.config.js"],
+    "hugo":        ["hugo.toml", "hugo.yaml", "hugo.json"],
+    "jekyll":      ["_config.yml"],
+    "docusaurus":  ["docusaurus.config.js", "docusaurus.config.ts"],
+    "flutter":     ["pubspec.yaml"],
+    "wordpress":   ["wp-config.php"],
+}
+
+FRAMEWORK_EXCLUDES: dict[str, list[str]] = {
+    "angular": [
+        "**/*.spec.ts",
+        "**/*.harness.ts",
+        "e2e/",
+        "src/environments/",
+        "karma.conf.js",
+        "src/test.ts",
+    ],
+    "nextjs": [
+        "next-env.d.ts",
+        "out/",
+    ],
+    "svelte": [
+        "build/",
+        "**/*.test.ts",
+    ],
+    "hugo": [],
+    "jekyll": [
+        "_site/",
+        ".jekyll-cache/",
+        ".jekyll-metadata",
+    ],
+    "docusaurus": [
+        ".docusaurus/",
+        "build/",
+    ],
+    "flutter": [
+        ".dart_tool/",
+        "build/",
+        ".flutter-plugins",
+        ".flutter-plugins-dependencies",
+    ],
+    "wordpress": [
+        "wp-admin/",
+        "wp-includes/",
+        "wp-content/languages/",
+        "wp-content/upgrade/",
+    ],
+}
+
+# Marker section boundaries in .graphifyignore
+_MARKER_START = "# ===== graphify-framework-aware (auto-generated) ====="
+_MARKER_END   = "# ===== end graphify-framework-aware ====="
+
+# Directories graphify already skips natively — don't duplicate them.
+_GRAPHIFY_BUILTIN_SKIP = frozenset({
+    "node_modules", "__pycache__", ".git", "dist", "build", "target", "out",
+    "site-packages", "lib64", ".pytest_cache", ".mypy_cache", ".ruff_cache",
+    ".tox", ".eggs", "*.egg-info", "graphify-out",
+    "coverage", "lcov-report", "visual-tests", "visual-test",
+    "__snapshots__", "snapshots", "storybook-static", "dist-protected",
+    ".next", ".nuxt", ".turbo", ".angular",
+    ".idea", ".cache", ".parcel-cache", ".svelte-kit", ".terraform",
+    ".serverless", ".graphify", ".worktrees",
+    "venv", ".venv", "env", ".env",
+})
+
+# Lock files graphify already skips.
+_GRAPHIFY_BUILTIN_SKIP_FILES = frozenset({
+    "package-lock.json", "yarn.lock", "pnpm-lock.yaml",
+    "Cargo.lock", "poetry.lock", "Gemfile.lock",
+    "composer.lock", "go.sum", "go.work.sum",
+})
+
+
+# ── Detection ─────────────────────────────────────────────────────────────────
+
+def _glob_marker(root: Path, pattern: str) -> bool:
+    """Check if a glob pattern matches any file in root (non-recursive by default)."""
+    matches = list(root.glob(pattern))
+    if matches:
+        return any(m.is_file() for m in matches)
+    return False
+
+
+def detect_frameworks(root: Path) -> dict:
+    """Scan project root for framework marker files.
+
+    Returns:
+        {"frameworks": ["angular", "nextjs"], "markers": {"angular": ["angular.json"], ...}}
+    """
+    root = root.resolve()
+    if not root.is_dir():
+        print(f"error: not a directory: {root}", file=sys.stderr)
+        sys.exit(1)
+
+    found: dict[str, list[str]] = {}
+    for fw_name, markers in FRAMEWORK_MARKERS.items():
+        matched = [m for m in markers if _glob_marker(root, m)]
+        if matched:
+            found[fw_name] = matched
+
+    # Flutter: pubspec.yaml is generic — verify it's a Flutter project
+    if "flutter" in found:
+        pubspec = root / "pubspec.yaml"
+        try:
+            content = pubspec.read_text(encoding="utf-8")
+            if "flutter" not in content.lower():
+                del found["flutter"]
+        except OSError:
+            del found["flutter"]
+
+    # Hugo: config.toml needs content check if not hugo.toml
+    # (config.toml is too generic — many non-Hugo projects use it)
+    if "hugo" in found:
+        hugo_specific = any("hugo" in m.lower() for m in found["hugo"])
+        if not hugo_specific:
+            # Only matched generic config.toml — verify it's actually Hugo
+            config_file = next((root / m for m in found["hugo"] if (root / m).exists()), None)
+            if config_file:
+                try:
+                    content = config_file.read_text(encoding="utf-8")
+                    if "baseURL" not in content and "title" not in content:
+                        del found["hugo"]
+                except OSError:
+                    del found["hugo"]
+            else:
+                del found["hugo"]
+
+    return {
+        "frameworks": sorted(found.keys()),
+        "markers": found,
+    }
+
+
+# ── Exclude pattern generation ────────────────────────────────────────────────
+
+def _hugo_theme_is_vendored(root: Path) -> bool:
+    """Check if Hugo themes/ directory contains git submodules or cloned themes."""
+    themes_dir = root / "themes"
+    if not themes_dir.is_dir():
+        return False
+
+    # Check for .gitmodules referencing themes
+    gitmodules = root / ".gitmodules"
+    if gitmodules.exists():
+        try:
+            content = gitmodules.read_text(encoding="utf-8")
+            if "themes/" in content:
+                return True
+        except OSError:
+            pass
+
+    # Check if individual themes are git repos (submodules)
+    for theme in themes_dir.iterdir():
+        if theme.is_dir() and (theme / ".git").exists():
+            return True
+
+    return False
+
+
+def _hugo_user_has_custom_layouts(root: Path) -> bool:
+    """Check if the user has custom layouts at project root (outside themes/)."""
+    layouts = root / "layouts"
+    if not layouts.is_dir():
+        return False
+    # Has custom layouts if more than just _default/ and partials/ exist
+    entries = list(layouts.iterdir())
+    custom_entries = [e for e in entries
+                      if e.name not in ("_default", "partials", "shortcodes")]
+    return len(custom_entries) > 0
+
+
+def _post_process_excludes(frameworks: dict, root: Path) -> dict[str, list[str]]:
+    """Apply framework-specific heuristics to refine exclude patterns.
+
+    Args:
+        frameworks: Raw detection result {"frameworks": [...], "markers": {...}}.
+        root: Project root path.
+
+    Returns:
+        Per-framework final exclude lists (may add/remove patterns).
+    """
+    excludes: dict[str, list[str]] = {}
+    for fw in frameworks["frameworks"]:
+        patterns = list(FRAMEWORK_EXCLUDES.get(fw, []))
+        excludes[fw] = patterns
+
+    # Hugo: refine based on theme/layout detection
+    if "hugo" in excludes:
+        patterns = excludes["hugo"]
+        patterns.append("public/")
+        patterns.append("resources/")
+
+        if _hugo_theme_is_vendored(root):
+            patterns.append("archetypes/")
+            patterns.append("themes/**/archetypes/")
+            patterns.append("themes/**/layouts/")
+        else:
+            patterns.append("archetypes/")
+
+        # If user has custom layouts, only exclude defaults
+        if not _hugo_user_has_custom_layouts(root):
+            patterns.append("layouts/")
+        else:
+            patterns.append("layouts/_default/")
+            patterns.append("layouts/partials/")
+            patterns.append("layouts/shortcodes/")
+
+    return excludes
+
+
+# ── .graphifyignore management ────────────────────────────────────────────────
+
+def _read_graphifyignore(root: Path) -> tuple[str, list[str]]:
+    """Read .graphifyignore and split into preamble / our-section / postscript.
+
+    Returns: (full_raw_content, lines_matching_our_section)
+    """
+    gf = root / ".graphifyignore"
+    if not gf.exists():
+        return ("", [])
+    try:
+        content = gf.read_text(encoding="utf-8")
+    except OSError:
+        return ("", [])
+    return (content, _extract_marker_lines(content))
+
+
+def _extract_marker_lines(content: str) -> list[str]:
+    """Extract lines between our start/end markers (exclusive)."""
+    lines = content.splitlines()
+    in_block = False
+    block_lines: list[str] = []
+    for line in lines:
+        if line.strip() == _MARKER_START:
+            in_block = True
+            continue
+        if line.strip() == _MARKER_END:
+            in_block = False
+            continue
+        if in_block:
+            block_lines.append(line)
+    return block_lines
+
+
+def _normalize_ignore_line(line: str) -> str:
+    """Strip comments and whitespace from a single .graphifyignore line."""
+    stripped = line.strip()
+    if not stripped or stripped.startswith("#"):
+        return ""
+    return stripped
+
+
+def _build_marker_block(excludes: dict[str, list[str]]) -> list[str]:
+    """Build the marker-delimited block of FW patterns."""
+    lines: list[str] = [_MARKER_START]
+    seen: set[str] = set()
+
+    for fw_name, patterns in excludes.items():
+        lines.append(f"# auto-detected framework: {fw_name}")
+        for pat in patterns:
+            normalized = _normalize_ignore_line(pat)
+            if not normalized or normalized in seen:
+                continue
+            # Skip patterns graphify already skips natively
+            if normalized.rstrip("/") in _GRAPHIFY_BUILTIN_SKIP:
+                continue
+            if normalized in _GRAPHIFY_BUILTIN_SKIP_FILES:
+                continue
+            seen.add(normalized)
+            lines.append(pat)
+
+    lines.append(_MARKER_END)
+    return lines
+
+
+def _write_graphifyignore(root: Path, excludes: dict[str, list[str]]) -> str:
+    """Write or update .graphifyignore, replacing our marker section.
+
+    Returns the summary string describing what was written.
+    """
+    gf = root / ".graphifyignore"
+    existing_content, existing_block = _read_graphifyignore(root)
+
+    new_block = _build_marker_block(excludes)
+    new_block_text = "\n".join(new_block)
+
+    # Compare ignoring comments (our own section header comments are stable)
+    old_effective = [_normalize_ignore_line(l) for l in existing_block if _normalize_ignore_line(l)]
+    new_effective = []
+    for l in new_block:
+        n = _normalize_ignore_line(l)
+        if n and not n.startswith("#"):
+            new_effective.append(n)
+
+    if sorted(old_effective) == sorted(new_effective) and _MARKER_START in existing_content:
+        return "unchanged"
+
+    # Rebuild the file: remove old marker block, insert new one
+    if _MARKER_START in existing_content:
+        lines = existing_content.splitlines()
+        out_lines: list[str] = []
+        in_block = False
+        for line in lines:
+            if line.strip() == _MARKER_START:
+                in_block = True
+                continue
+            if line.strip() == _MARKER_END:
+                in_block = False
+                continue
+            if not in_block:
+                out_lines.append(line)
+        # Remove trailing blank lines before appending
+        while out_lines and out_lines[-1].strip() == "":
+            out_lines.pop()
+        out_lines.append("")
+        out_lines.append(new_block_text)
+        result = "\n".join(out_lines)
+        if not result.endswith("\n"):
+            result += "\n"
+    else:
+        # No existing block — append
+        if existing_content.strip():
+            result = existing_content.rstrip() + "\n\n" + new_block_text + "\n"
+        else:
+            result = new_block_text + "\n"
+
+    gf.write_text(result, encoding="utf-8")
+
+    # Build summary
+    fw_names = list(excludes.keys())
+    pattern_count = len(new_effective)
+    if pattern_count == 0:
+        return f"frameworks detected ({', '.join(fw_names)}) but no additional patterns needed"
+    return (
+        f"detected {', '.join(fw_names)} — wrote {pattern_count} "
+        f"exclusion pattern{'s' if pattern_count != 1 else ''} to .graphifyignore"
+    )
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+def _cmd_detect(root: Path) -> None:
+    result = detect_frameworks(root)
+    print(json.dumps(result, indent=2))
+
+
+def _cmd_show(root: Path) -> None:
+    result = detect_frameworks(root)
+    if not result["frameworks"]:
+        print("No supported frameworks detected.", file=sys.stderr)
+        sys.exit(2)
+    excludes = _post_process_excludes(result, root)
+    for fw, patterns in excludes.items():
+        print(f"# {fw}")
+        for pat in patterns:
+            n = _normalize_ignore_line(pat)
+            if n and n not in _GRAPHIFY_BUILTIN_SKIP and n not in _GRAPHIFY_BUILTIN_SKIP_FILES:
+                print(pat)
+        print()
+
+
+def _cmd_apply(root: Path) -> None:
+    result = detect_frameworks(root)
+    if not result["frameworks"]:
+        print("No supported frameworks detected.", file=sys.stderr)
+        sys.exit(2)
+    excludes = _post_process_excludes(result, root)
+    summary = _write_graphifyignore(root, excludes)
+    print(f"graphify-framework-aware: {summary}")
+
+
+_CMD_TABLE: dict[str, callable] = {
+    "detect": _cmd_detect,
+    "show":   _cmd_show,
+    "apply":  _cmd_apply,
+}
+
+
+def main() -> None:
+    if len(sys.argv) < 3:
+        print(f"usage: {sys.argv[0]} <detect|show|apply> <project-path>", file=sys.stderr)
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+    path = Path(sys.argv[2])
+
+    if cmd not in _CMD_TABLE:
+        print(f"error: unknown command '{cmd}' (expected: detect, show, apply)", file=sys.stderr)
+        sys.exit(1)
+
+    _CMD_TABLE[cmd](path)
+
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/memory-search/SKILL.md

@@ -0,0 +1,69 @@
+---
+description: "Search project memory bank using semantic vector search"
+name: "memory-search"
+---
+
+# Memory Search Skill
+
+Use this skill to retrieve project context from the memory bank without loading all files into context.
+
+## When to Use
+
+- At the start of a session: search for current project focus and recent changes
+- Before making a decision: search for related past decisions
+- When stuck: search for architectural patterns or known issues
+- After writing to memory-bank: run `memory_rebuild` to update the index
+
+## Available MCP Tools
+
+This skill uses the `memory-bank` MCP server, configured in `opencode.json`:
+
+| Tool | Purpose |
+|---|---|
+| `memory_search` | Semantic search across all memory-bank and docs files |
+| `memory_update` | Incremental sync — only changed files (~2 seconds). Use daily. |
+| `memory_rebuild` | Full rebuild (rare — fresh clone, corrupted index) |
+| `memory_get` | Read a specific memory file by name |
+| `memory_stats` | Get index statistics (vector count, file count, DB size) |
+
+## Workflow
+
+### Session Start
+
+1. Run `memory_stats` to check if the index is populated
+2. If empty, run `memory_rebuild`; otherwise, run `memory_update`
+3. Search for current context: `memory_search({ query: "current focus recent changes next steps" })`
+
+### During Tasks
+
+- Before implementing: `memory_search({ query: "<topic>", topK: 5 })` for related decisions
+- When writing to memory-bank: update files, then run `memory_update`
+- For full file content: `memory_get({ file: "activeContext" })`
+
+### After Git Pull
+
+The `post-merge` hook runs `memory:update` automatically if memory-bank files changed.
+
+### Search Tips
+
+- **Be specific**: "TDD orchestrator bootstrap prerequisites" gets better results than "project"
+- **Use contextual terms**: Include entity names (vitest, playwright, graphify) from the vocabulary
+- **Filter by file**: `memory_search({ query: "...", sourceFile: "systemPatterns" })` to narrow scope
+- **Top-K tuning**: Use `topK: 3` for focused queries, `topK: 10` for broad exploration
+
+## Vocabulary Reference
+
+See `memory-bank/.vocabulary.json` for the full controlled vocabulary. Key tags:
+
+- **Agent roles**: orchestrator, coder, reviewer, tracker, architect, researcher
+- **Workflow**: tdd, feature-pipeline, bootstrap, configuration, refactor, migration
+- **Memory ops**: decision, discovery, status-update, task-plan, retrospective
+- **Technologies**: typescript, vitest, playwright, graphify, mcp, sqlite-vec
+
+## Manual CLI (for debugging)
+
+```bash
+node scripts/memory-cli.js search "tdd orchestrator"
+node scripts/memory-cli.js rebuild
+node scripts/memory-cli.js stats
+```

package/.agents/skills/microsoft-docs/SKILL.md

@@ -64,7 +64,7 @@ GitHub docs live on **docs.github.com** and **cli.github.com**.
 
 | Library ID             | Use for                                       |
 | ---------------------- | --------------------------------------------- |
-| `/websites/github_en`  | Actions, API, repos, security, admin, Copilot |
+| `/websites/github_en`  | Actions, API, repos, security, admin |
 | `/websites/cli_github` | GitHub CLI (`gh`) commands and flags          |
 
 ### Agent Framework — Use Learn MCP + Context7

package/.agents/skills/polygot-test-agent/SKILL.md

@@ -154,7 +154,6 @@ Add tests for the authentication module with focus on edge cases
 
 - Project must have a build/test system configured
 - Testing framework should be installed (or installable)
-- VS Code with GitHub Copilot extension
 
 ## Troubleshooting
 

package/.agents/skills/prompt-builder/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: prompt-builder
-description: "Guide users through creating high-quality GitHub Copilot prompts with proper structure, tools, and best practices."
+description: "Guide users through creating high-quality opencode prompts with proper structure, tools, and best practices."
 ---
 
 # Professional Prompt Builder
 
-You are an expert prompt engineer specializing in GitHub Copilot prompt development with deep knowledge of:
+You are an expert prompt engineer specializing in opencode prompt development with deep knowledge of:
 
 - Prompt engineering best practices and patterns
-- VS Code Copilot customization capabilities
+- opencode customization capabilities
 - Effective persona design and task specification
 - Tool integration and front matter configuration
 - Output format optimization for AI consumption
@@ -27,7 +27,7 @@ I will ask you targeted questions to gather all necessary information. After col
 
 ### 2. **Persona Definition**
 
-- What role/expertise should Copilot embody? Be specific about:
+- What role/expertise should the AI assistant embody? Be specific about:
   - Technical expertise level (junior, senior, expert, specialist)
   - Domain knowledge (languages, frameworks, tools)
   - Years of experience or specific qualifications
@@ -42,15 +42,15 @@ I will ask you targeted questions to gather all necessary information. After col
 
 ### 4. **Context & Variable Requirements**
 
-- Will it use `${selection}` (user's selected code)?
-- Will it use `${file}` (current file) or other file references?
-- Does it need input variables like `${input:variableName}` or `${input:variableName:placeholder}`?
-- Will it reference workspace variables (`${workspaceFolder}`, etc.)?
+- Will it use selected text from the editor?
+- Will it use the current file path or other file references?
+- Does it need custom input parameters or variable references?
+- Will it reference the workspace root path or other project-level variables?
 - Does it need to access other files or prompt files as dependencies?
 
 ### 5. **Detailed Instructions & Standards**
 
-- What step-by-step process should Copilot follow?
+- What step-by-step process should the AI follow?
 - Are there specific coding standards, frameworks, or libraries to use?
 - What patterns or best practices should be enforced?
 - Are there things to avoid or constraints to respect?
@@ -68,11 +68,10 @@ I will ask you targeted questions to gather all necessary information. After col
 
 Which tools does this prompt need? Common options include:
 
-- **File Operations**: `codebase`, `editFiles`, `search`, `problems`
-- **Execution**: `runCommands`, `runTasks`, `runTests`, `terminalLastCommand`
-- **External**: `fetch`, `githubRepo`, `openSimpleBrowser`
-- **Specialized**: `playwright`, `usages`, `vscodeAPI`, `extensions`
-- **Analysis**: `changes`, `findTestFiles`, `testFailure`, `searchResults`
+- **File Operations**: `Read`, `Write`, `Edit`, `Grep`, `Glob`
+- **Execution**: `Bash`
+- **External**: `WebFetch`, `WebSearch`
+- **Specialized**: `playwright` (Playwright MCP)
 
 ### 8. **Technical Configuration**
 
@@ -111,9 +110,11 @@ After gathering all requirements, I will generate a complete `.prompt.md` file f
 ```markdown
 ---
 description: "[Clear, concise description from requirements]"
+name: "[prompt-name]"
 agent: "[agent|ask|edit based on task type]"
 tools: ["[appropriate tools based on functionality]"]
 model: "[only if specific model required]"
+argument-hint: "[hint text shown in chat input]"
 ---
 
 # [Prompt Title]

package/.husky/post-merge

@@ -0,0 +1,10 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+# After git pull/merge, check if memory-bank files changed
+# and update the vector index incrementally
+
+if git diff HEAD@{1} --name-only 2>/dev/null | grep -q "^memory-bank\|^docs/"; then
+  echo "[memory-bank] Memory bank files changed. Updating vector index..."
+  node scripts/memory-cli.js update 2>/dev/null || echo "[memory-bank] Index update skipped (service not installed)"
+fi

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+node scripts/bump-version.js
+node scripts/validate-memory-schema.js

package/AGENTS.md

@@ -141,9 +141,63 @@ The agent file is at `.opencode/agents/orchestrator/feature-pipeline.agent.md`.
 
 **When to use:** You want a predictable, four-step feature pipeline without dynamic agent selection. The orchestrator agent is more flexible; this is more opinionated.
 
+### TDD Orchestrator — Test-Driven Development Pipeline
+
+Use this when you want strict Test-Driven Development: **tests first, code second**. The pipeline enforces the RED → GREEN → REFACTOR/VERIFY cycle:
+
+```
+implementer (PLAN) → unit-tester∥ (RED) → coder∥ (GREEN) → unit-tester (VERIFY ≥90%) → reviewer → tracker
+```
+
+| Step | Phase | Agent | Role |
+|------|-------|-------|------|
+| 1 | PLAN | implementer | Creates plan with parallel test/code batch tables |
+| 2 | RED | unit-tester∥ | Writes failing tests before any implementation exists |
+| 3 | GREEN | coder∥ | Writes minimal code to pass tests — no extra features |
+| 4 | VERIFY | unit-tester | Runs all tests, checks coverage ≥ 90% |
+| 5 | REVIEW | reviewer | Audits tests + code for quality, security, patterns |
+| 6 | DOCUMENT | tracker | Records results to `docs/tracker-log.md` |
+
+The agent file is at `.opencode/agents/orchestrator/tdd-orchestrator.agent.md`.
+
+**When to use:** Any feature, bug fix, or refactor where tests should be written first. The orchestrator automatically selects this pipeline when testable code changes are requested.
+
+**Coverage gate:** If coverage < 90%, the pipeline loops back to RED phase (up to 3 iterations).
+
+### Memory Bank
+
+The memory bank at `memory-bank/` preserves project context across AI sessions. Core files:
+
+| File | Purpose |
+|------|---------|
+| `projectbrief.md` | Core requirements, goals, scope |
+| `productContext.md` | Problem solved, UX goals |
+| `systemPatterns.md` | Architecture, design patterns |
+| `techContext.md` | Technologies, setup, constraints |
+| `activeContext.md` | Current focus, recent changes, next steps |
+| `progress.md` | What works, what's left, known issues |
+| `tasks/` | Per-task tracking with `_index.md` |
+
+**Always read `activeContext.md` and `progress.md` at the start of every task.** Update them after completing work. See `.agents/instructions/memory-bank.instructions.md` for full details.
+
 ## Additional Resources
 
 ### Playwright MCP Configuration
 
 For details on how Playwright MCP integrates with the headed mode debugging configuration, see:
 - **Docs**: `docs/playwright-mcp-configuration.md`
+
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+When the user types `/graphify`, invoke these skills in order before doing anything else:
+1. `skill: "graphify-framework-aware"` — detects project frameworks and configures `.graphifyignore` to exclude boilerplate
+2. `skill: "graphify"` — runs the knowledge graph pipeline
+
+Rules:
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).