@bcelep/capint 0.4.2 → 0.6.5

package/skills/nexus-mapper/scripts/query_graph.py

@@ -0,0 +1,556 @@
+#!/usr/bin/env python3
+"""
+query_graph.py — AST on-demand query tool
+
+Reads the ast_nodes.json produced by extract_ast.py and provides multiple query modes,
+outputting concise text easily consumed by agents.
+
+Purpose:
+  - Assist the REASON/OBJECT/EMIT stages of the PROBE workflow in generating cognitive files
+  - Support bug investigation, change impact assessment, and refactoring analysis during development
+
+Usage:
+  python query_graph.py <ast_nodes.json> --file <path>
+  python query_graph.py <ast_nodes.json> --who-imports <module_or_path>
+  python query_graph.py <ast_nodes.json> --impact <path>
+  python query_graph.py <ast_nodes.json> --hub-analysis [--top N]
+  python query_graph.py <ast_nodes.json> --summary
+"""
+
+import sys
+import json
+import argparse
+from pathlib import Path, PurePosixPath
+from collections import defaultdict
+
+
+class GitStats:
+    """Query helper for git_stats.json. Optional loading; does not affect core AST queries."""
+
+    def __init__(self, data: dict):
+        self.period_days: int = data.get('analysis_period_days', 90)
+        self.hotspots: dict[str, dict] = {}  # path → {changes, risk}
+        for h in data.get('hotspots', []):
+            self.hotspots[h['path']] = h
+        self.coupling: dict[str, list[dict]] = defaultdict(list)  # path → [{peer, co_changes, score}]
+        for c in data.get('coupling_pairs', []):
+            self.coupling[c['file_a']].append({
+                'peer': c['file_b'], 'co_changes': c['co_changes'],
+                'score': c['coupling_score'],
+            })
+            self.coupling[c['file_b']].append({
+                'peer': c['file_a'], 'co_changes': c['co_changes'],
+                'score': c['coupling_score'],
+            })
+
+    def file_risk(self, path: str) -> dict | None:
+        return self.hotspots.get(path)
+
+    def file_coupling(self, path: str) -> list[dict]:
+        return sorted(self.coupling.get(path, []), key=lambda x: x['score'], reverse=True)
+
+    RISK_ICON = {'high': '🔴', 'medium': '🟡', 'low': '🟢'}
+
+    def format_risk_block(self, path: str) -> list[str]:
+        """Generate git risk + coupling text lines for a file (empty list means no data)."""
+        lines: list[str] = []
+        risk = self.file_risk(path)
+        if risk:
+            icon = self.RISK_ICON.get(risk['risk'], '⚪')
+            lines.append(f"Git risk: {icon} {risk['risk']} ({risk['changes']} changes in {self.period_days} days)")
+        coupling = self.file_coupling(path)
+        if coupling:
+            lines.append("Coupled files (co-change):")
+            for c in coupling[:5]:
+                lines.append(f"  - {c['peer']} (coupling: {c['score']:.2f}, {c['co_changes']} co-changes)")
+        return lines
+
+
+class ASTGraph:
+    """In-memory AST graph index supporting multiple query modes."""
+
+    SOURCE_ROOT_MARKERS = (
+        ('src',),
+        ('backend', 'src'),
+        ('frontend', 'src'),
+        ('client', 'src'),
+        ('src', 'main', 'python'),
+        ('src', 'test', 'python'),
+        ('src', 'main', 'java'),
+        ('src', 'test', 'java'),
+        ('src', 'main', 'kotlin'),
+        ('src', 'test', 'kotlin'),
+    )
+
+    def __init__(self, data: dict, git_stats: GitStats | None = None):
+        self.data = data
+        self.nodes: list[dict] = data.get('nodes', [])
+        self.edges: list[dict] = data.get('edges', [])
+        self.stats: dict = data.get('stats', {})
+        self.languages: list[str] = data.get('languages', [])
+        self.git: GitStats | None = git_stats
+
+        # Indexes
+        self.nodes_by_id: dict[str, dict] = {}
+        self.nodes_by_path: dict[str, list[dict]] = defaultdict(list)
+        self.modules_by_path: dict[str, dict] = {}
+        self.imports_forward: dict[str, set[str]] = defaultdict(set)
+        self.imports_reverse: dict[str, set[str]] = defaultdict(set)
+        self.internal_imports_forward: dict[str, set[str]] = defaultdict(set)
+        self.internal_imports_reverse: dict[str, set[str]] = defaultdict(set)
+        self.contains_children: dict[str, list[dict]] = defaultdict(list)
+        self.path_to_module_id: dict[str, str] = {}
+        self.alias_to_module_ids: dict[str, set[str]] = defaultdict(set)
+
+        self._build_index()
+
+    def _build_index(self) -> None:
+        for node in self.nodes:
+            nid = node['id']
+            self.nodes_by_id[nid] = node
+            path = node.get('path', '')
+            if path:
+                self.nodes_by_path[path].append(node)
+            if node['type'] == 'Module' and path:
+                self.modules_by_path[path] = node
+                self.path_to_module_id[path] = nid
+                for alias in self._module_aliases(nid, path):
+                    self.alias_to_module_ids[alias].add(nid)
+
+        for edge in self.edges:
+            src, tgt, etype = edge['source'], edge['target'], edge['type']
+            if etype == 'imports':
+                self.imports_forward[src].add(tgt)
+                self.imports_reverse[tgt].add(src)
+            elif etype == 'contains':
+                child = self.nodes_by_id.get(tgt)
+                if child:
+                    self.contains_children[src].append(child)
+
+        module_ids = {n['id'] for n in self.nodes if n['type'] == 'Module'}
+        for source, targets in self.imports_forward.items():
+            if source not in module_ids:
+                continue
+            for target in targets:
+                resolved = self.resolve_import_target(target)
+                if resolved and resolved in module_ids and resolved != source:
+                    self.internal_imports_forward[source].add(resolved)
+                    self.internal_imports_reverse[resolved].add(source)
+
+    def _module_aliases(self, module_id: str, path: str) -> set[str]:
+        aliases = {module_id}
+        parts = list(PurePosixPath(path.replace('\\', '/')).parts)
+        if not parts:
+            return aliases
+
+        stem = PurePosixPath(parts[-1]).stem
+        normalized_parts = parts[:-1] if stem == '__init__' else parts[:-1] + [stem]
+
+        for marker in self.SOURCE_ROOT_MARKERS:
+            if tuple(normalized_parts[:len(marker)]) == marker and len(normalized_parts) > len(marker):
+                aliases.add('.'.join(normalized_parts[len(marker):]))
+
+        for idx, part in enumerate(normalized_parts):
+            if part == 'src' and idx + 1 < len(normalized_parts):
+                aliases.add('.'.join(normalized_parts[idx + 1:]))
+
+        return {alias for alias in aliases if alias}
+
+    def resolve_import_target(self, target: str) -> str | None:
+        if target in self.nodes_by_id and self.nodes_by_id[target]['type'] == 'Module':
+            return target
+
+        direct = self.alias_to_module_ids.get(target)
+        if direct and len(direct) == 1:
+            return next(iter(direct))
+
+        parts = target.split('.')
+        while len(parts) > 1:
+            parts = parts[:-1]
+            candidate = '.'.join(parts)
+            matches = self.alias_to_module_ids.get(candidate)
+            if matches and len(matches) == 1:
+                return next(iter(matches))
+
+        return None
+
+    def _classify_imports(self, imports: set[str]) -> tuple[list[tuple[str, str]], list[str]]:
+        internal: list[tuple[str, str]] = []
+        external: list[str] = []
+        for imp in sorted(imports):
+            resolved = self.resolve_import_target(imp)
+            if resolved:
+                internal.append((imp, resolved))
+            else:
+                external.append(imp)
+        return internal, external
+
+    def resolve_to_module_id(self, query: str) -> str | None:
+        """Resolve a file path or module id uniformly to a module id."""
+        # Try directly as a module id
+        if query in self.nodes_by_id and self.nodes_by_id[query]['type'] == 'Module':
+            return query
+        # Try as a file path (compatible with \\ and /)
+        normalized = query.replace('\\', '/')
+        if normalized in self.path_to_module_id:
+            return self.path_to_module_id[normalized]
+        # Fuzzy match: strip leading repo-relative path prefix
+        for path, mid in self.path_to_module_id.items():
+            if path.endswith(normalized) or normalized.endswith(path):
+                return mid
+        return None
+
+    def resolve_to_path(self, module_id: str) -> str | None:
+        """Resolve a module id to a file path."""
+        node = self.nodes_by_id.get(module_id)
+        if node:
+            return node.get('path')
+        return None
+
+    # ── Query mode implementations ──────────────────────────────────
+
+    def query_file(self, file_query: str) -> str:
+        """--file: View the complete structure and import list for a file."""
+        mid = self.resolve_to_module_id(file_query)
+        if not mid:
+            return f"[NOT FOUND] No module matching '{file_query}'"
+
+        module_node = self.nodes_by_id[mid]
+        path = module_node.get('path', mid)
+        lines = module_node.get('lines', '?')
+        lang = module_node.get('lang', '?')
+
+        out = [f"=== {path} ==="]
+        out.append(f"Module: {mid} ({lines} lines, {lang})")
+        out.append("")
+
+        # Classes and functions
+        classes = [n for n in self.contains_children.get(mid, []) if n['type'] == 'Class']
+        top_funcs = [n for n in self.contains_children.get(mid, []) if n['type'] == 'Function']
+
+        if classes:
+            out.append("Classes:")
+            for cls in classes:
+                sl = cls.get('start_line', '?')
+                el = cls.get('end_line', '?')
+                out.append(f"  {cls['label']} (L{sl}-L{el})")
+                methods = [n for n in self.contains_children.get(cls['id'], []) if n['type'] == 'Function']
+                for i, m in enumerate(methods):
+                    prefix = "└─" if i == len(methods) - 1 else "├─"
+                    ml = m.get('start_line', '?')
+                    me = m.get('end_line', '?')
+                    out.append(f"    {prefix} {m['label']} (L{ml}-L{me})")
+            out.append("")
+
+        if top_funcs:
+            out.append("Top-level Functions:")
+            for f in top_funcs:
+                sl = f.get('start_line', '?')
+                el = f.get('end_line', '?')
+                out.append(f"  {f['label']} (L{sl}-L{el})")
+            out.append("")
+
+        # Imports
+        imports = sorted(self.imports_forward.get(mid, set()))
+        if imports:
+            internal, external = self._classify_imports(set(imports))
+            out.append("Imports:")
+            for raw_imp, resolved_imp in internal:
+                imp_path = self.resolve_to_path(resolved_imp)
+                suffix = f" ({imp_path})" if imp_path else ""
+                if raw_imp == resolved_imp:
+                    out.append(f"  → {raw_imp}{suffix}")
+                else:
+                    out.append(f"  → {raw_imp}  [resolved: {resolved_imp}{suffix}]")
+            for imp in external:
+                out.append(f"  → {imp} (external)")
+            out.append("")
+
+        if not classes and not top_funcs and not imports:
+            out.append("(no classes, functions, or imports detected)")
+
+        # Git stats (optional)
+        if self.git:
+            git_lines = self.git.format_risk_block(path)
+            if git_lines:
+                out.append("Git:")
+                out.extend(f"  {l}" for l in git_lines)
+                out.append("")
+
+        return "\n".join(out)
+
+    def query_who_imports(self, module_query: str) -> str:
+        """--who-imports: Reverse dependency query."""
+        mid = self.resolve_to_module_id(module_query)
+
+        # Also try looking up directly in imports_reverse (handles external package names, etc.)
+        if not mid:
+            # Might be a partial match (e.g. 'flask' in imports target)
+            matches = set()
+            normalized = module_query.replace('\\', '/')
+            for target, sources in self.imports_reverse.items():
+                if target == normalized or target == module_query:
+                    matches.update(sources)
+            if matches:
+                return self._format_who_imports(module_query, matches)
+            return f"[NOT FOUND] No module matching '{module_query}'"
+
+        importers: set[str] = set(self.internal_imports_reverse.get(mid, set()))
+
+        return self._format_who_imports(mid, importers)
+
+    def _format_who_imports(self, query: str, importers: set[str]) -> str:
+        out = [f"=== Who imports {query}? ==="]
+        if not importers:
+            out.append("Not imported by any module in the project.")
+            return "\n".join(out)
+
+        out.append(f"Imported by {len(importers)} module(s):")
+        for imp in sorted(importers):
+            imp_path = self.resolve_to_path(imp)
+            suffix = f" ({imp_path})" if imp_path else ""
+            out.append(f"  ← {imp}{suffix}")
+        return "\n".join(out)
+
+    def query_impact(self, file_query: str) -> str:
+        """--impact: Impact radius analysis (upstream and downstream dependency overview)."""
+        mid = self.resolve_to_module_id(file_query)
+        if not mid:
+            return f"[NOT FOUND] No module matching '{file_query}'"
+
+        module_node = self.nodes_by_id[mid]
+        path = module_node.get('path', mid)
+
+        out = [f"=== Impact radius: {path} ===", ""]
+
+        # Upstream: what this file imports
+        forward = sorted(self.imports_forward.get(mid, set()))
+        internal_forward, external_forward = self._classify_imports(set(forward))
+
+        out.append("Depends on (this file imports):")
+        if internal_forward:
+            for raw_dep, resolved_dep in internal_forward:
+                dep_path = self.resolve_to_path(resolved_dep)
+                suffix = f" ({dep_path})" if dep_path else ""
+                if raw_dep == resolved_dep:
+                    out.append(f"  → {raw_dep}{suffix}")
+                else:
+                    out.append(f"  → {raw_dep}  [resolved: {resolved_dep}{suffix}]")
+        if external_forward:
+            for dep in external_forward:
+                out.append(f"  → {dep} (external)")
+        if not forward:
+            out.append("  (none)")
+        out.append("")
+
+        # Downstream: who imports this file
+        importers: set[str] = set(self.internal_imports_reverse.get(mid, set()))
+
+        out.append("Depended by (other files import this):")
+        if importers:
+            for imp in sorted(importers):
+                imp_path = self.resolve_to_path(imp)
+                suffix = f" ({imp_path})" if imp_path else ""
+                out.append(f"  ← {imp}{suffix}")
+        else:
+            out.append("  (none)")
+        out.append("")
+
+        downstream_count = len(importers)
+        upstream_count = len({resolved for _raw, resolved in internal_forward})
+        out.append(
+            f"Impact summary: {upstream_count} upstream dependencies, "
+            f"{downstream_count} downstream dependents"
+        )
+
+        # Git stats (optional)
+        if self.git:
+            out.append("")
+            git_lines = self.git.format_risk_block(path)
+            if git_lines:
+                out.extend(git_lines)
+
+        return "\n".join(out)
+
+    def query_hub_analysis(self, top_n: int = 10) -> str:
+        """--hub-analysis: Identify high fan-in / high fan-out core nodes."""
+        fan_in = {target: len(sources) for target, sources in self.internal_imports_reverse.items()}
+        fan_out = {source: len(targets) for source, targets in self.internal_imports_forward.items()}
+
+        out = ["=== Hub Analysis ===", ""]
+
+        # Top fan-in
+        top_fan_in = sorted(fan_in.items(), key=lambda x: x[1], reverse=True)[:top_n]
+        out.append("Top fan-in (most imported by others):")
+        if top_fan_in:
+            for i, (mid, count) in enumerate(top_fan_in, 1):
+                path = self.resolve_to_path(mid) or ""
+                out.append(f"  {i}. {mid} — imported by {count} module(s)  [{path}]")
+        else:
+            out.append("  (no internal import relationships found)")
+        out.append("")
+
+        # Top fan-out
+        top_fan_out = sorted(fan_out.items(), key=lambda x: x[1], reverse=True)[:top_n]
+        out.append("Top fan-out (imports most others):")
+        if top_fan_out:
+            for i, (mid, count) in enumerate(top_fan_out, 1):
+                path = self.resolve_to_path(mid) or ""
+                out.append(f"  {i}. {mid} — imports {count} internal module(s)  [{path}]")
+        else:
+            out.append("  (no internal import relationships found)")
+
+        return "\n".join(out)
+
+    def query_summary(self) -> str:
+        """--summary: Structural summary aggregated by top-level directory."""
+        # Aggregate by first or second level directory
+        dir_stats: dict[str, dict] = defaultdict(
+            lambda: {'modules': 0, 'classes': 0, 'functions': 0, 'lines': 0,
+                     'class_names': [], 'import_dirs': set()}
+        )
+
+        # Determine aggregation granularity: use the first 2 levels of the path
+        def _dir_key(path: str) -> str:
+            parts = path.split('/')
+            if len(parts) <= 2:
+                return parts[0] + '/'
+            return '/'.join(parts[:2]) + '/'
+
+        for node in self.nodes:
+            path = node.get('path', '')
+            if not path:
+                continue
+            dk = _dir_key(path)
+            ntype = node['type']
+            if ntype == 'Module':
+                dir_stats[dk]['modules'] += 1
+                dir_stats[dk]['lines'] += node.get('lines', 0)
+            elif ntype == 'Class':
+                dir_stats[dk]['classes'] += 1
+                dir_stats[dk]['class_names'].append(node['label'])
+            elif ntype == 'Function':
+                dir_stats[dk]['functions'] += 1
+
+        # Collect import source directories for each directory
+        for mid, targets in self.imports_forward.items():
+            src_node = self.nodes_by_id.get(mid)
+            if not src_node or src_node['type'] != 'Module':
+                continue
+            src_path = src_node.get('path', '')
+            if not src_path:
+                continue
+            src_dk = _dir_key(src_path)
+            for t in targets:
+                t_node = self.nodes_by_id.get(t)
+                if t_node and t_node.get('path'):
+                    t_dk = _dir_key(t_node['path'])
+                    if t_dk != src_dk:
+                        dir_stats[src_dk]['import_dirs'].add(t_dk.rstrip('/'))
+
+        out = ["=== Directory Summary ===", ""]
+
+        for dk in sorted(dir_stats.keys()):
+            s = dir_stats[dk]
+            out.append(
+                f"{dk} ({s['modules']} modules, {s['classes']} classes, "
+                f"{s['functions']} functions, {s['lines']} lines)"
+            )
+            if s['class_names']:
+                # Show at most 8
+                names = s['class_names'][:8]
+                suffix = f" ... +{len(s['class_names']) - 8}" if len(s['class_names']) > 8 else ""
+                out.append(f"  Key classes: {', '.join(names)}{suffix}")
+            import_dirs = sorted(s['import_dirs'])
+            if import_dirs:
+                out.append(f"  Key imports from: {', '.join(import_dirs)}")
+            else:
+                out.append(f"  Key imports from: (none / external only)")
+            out.append("")
+
+        if not dir_stats:
+            out.append("(no modules found in ast_nodes.json)")
+
+        return "\n".join(out)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description='Query AST graph from ast_nodes.json',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s ast_nodes.json --file src/server/handler.py
+  %(prog)s ast_nodes.json --who-imports src.server.handler
+  %(prog)s ast_nodes.json --impact src/server/handler.py
+  %(prog)s ast_nodes.json --hub-analysis --top 10
+  %(prog)s ast_nodes.json --summary
+""",
+    )
+    parser.add_argument('ast_json', help='Path to ast_nodes.json')
+    parser.add_argument('--file', dest='file_query', help='Show structure and imports of a file')
+    parser.add_argument('--who-imports', dest='who_imports', help='Find modules that import the given module')
+    parser.add_argument('--impact', dest='impact_query', help='Show impact radius (deps + dependents)')
+    parser.add_argument('--hub-analysis', action='store_true', help='Show top fan-in/fan-out modules')
+    parser.add_argument('--summary', action='store_true', help='Show per-directory structural summary')
+    parser.add_argument('--top', type=int, default=10, help='Number of results for hub-analysis (default: 10)')
+    parser.add_argument('--git-stats', dest='git_stats_path', metavar='GIT_STATS_JSON',
+                        help='Optional git_stats.json to enrich --file and --impact with risk/coupling data')
+
+    args = parser.parse_args()
+
+    # Check that at least one query mode is specified
+    has_query = any([args.file_query, args.who_imports, args.impact_query,
+                     args.hub_analysis, args.summary])
+    if not has_query:
+        parser.print_help()
+        sys.exit(1)
+
+    # Load JSON
+    ast_path = Path(args.ast_json)
+    if not ast_path.exists():
+        sys.stderr.write(f"[ERROR] File not found: {ast_path}\n")
+        sys.exit(1)
+
+    try:
+        raw_text = ast_path.read_text(encoding='utf-8')
+        # Skip possible stderr lines mixed in (e.g. [WARNING]), locate the first '{' to start parsing
+        json_start = raw_text.find('{')
+        if json_start < 0:
+            sys.stderr.write(f"[ERROR] No JSON object found in {ast_path}\n")
+            sys.exit(1)
+        data = json.loads(raw_text[json_start:])
+    except json.JSONDecodeError as e:
+        sys.stderr.write(f"[ERROR] Invalid JSON: {e}\n")
+        sys.exit(1)
+
+    # Optionally load git stats
+    git_stats: GitStats | None = None
+    if args.git_stats_path:
+        gs_path = Path(args.git_stats_path)
+        if not gs_path.exists():
+            sys.stderr.write(f"[WARNING] git_stats file not found: {gs_path}, ignoring\n")
+        else:
+            try:
+                gs_data = json.loads(gs_path.read_text(encoding='utf-8'))
+                git_stats = GitStats(gs_data)
+            except (json.JSONDecodeError, KeyError) as e:
+                sys.stderr.write(f"[WARNING] git_stats parse error: {e}, ignoring\n")
+
+    graph = ASTGraph(data, git_stats=git_stats)
+
+    # Execute query
+    if args.file_query:
+        print(graph.query_file(args.file_query))
+    elif args.who_imports:
+        print(graph.query_who_imports(args.who_imports))
+    elif args.impact_query:
+        print(graph.query_impact(args.impact_query))
+    elif args.hub_analysis:
+        print(graph.query_hub_analysis(args.top))
+    elif args.summary:
+        print(graph.query_summary())
+
+
+if __name__ == '__main__':
+    main()

package/skills/nexus-mapper/scripts/requirements.txt

@@ -0,0 +1,6 @@
+# nexus-mapper scripts dependencies
+# For standalone use or distribution installation
+# When used within the Nexus project, dependencies are already covered by the poetry environment (tree-sitter ^0.25.2 + tree-sitter-language-pack)
+
+tree-sitter>=0.22.0
+tree-sitter-language-pack

package/skills/notion-spec-to-implementation/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2025 Notion Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/skills/notion-spec-to-implementation/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: notion-spec-to-implementation
+description: Turn Notion specs into implementation plans, tasks, and progress tracking; use when implementing PRDs/feature specs and creating Notion plans + tasks from them.
+metadata:
+  version: 1.0.1
+  short-description: Turn Notion specs into implementation plans, tasks, and progress tracking
+origin: verdent
+prismx_bundle: verdent
+prismx_imported_at: 2026-05-27
+---
+
+# Spec to Implementation
+
+Convert a Notion spec into linked implementation plans, tasks, and ongoing status updates.
+
+## Quick start
+
+1. Locate the spec with `Notion:notion-search`, then fetch it with `Notion:notion-fetch`.
+2. Parse requirements and ambiguities using `reference/spec-parsing.md`.
+3. Create a plan page with `Notion:notion-create-pages` (pick a template: quick vs. full).
+4. Find the task database, confirm schema, then create tasks with `Notion:notion-create-pages`.
+5. Link spec ↔ plan ↔ tasks; keep status current with `Notion:notion-update-page`.
+
+## Workflow
+
+### 0) If any MCP call fails because Notion MCP is not connected, pause and set it up:
+
+1. Open Verdent Settings → MCP Servers
+2. Add the Notion MCP server with URL: `https://mcp.notion.com/mcp`
+3. Follow the OAuth authentication flow when prompted
+
+After successful setup, the MCP tools will be available for use.
+
+### 1) Locate and read the spec
+
+- Search first (`Notion:notion-search`); if multiple hits, ask the user which to use.
+- Fetch the page (`Notion:notion-fetch`) and scan for requirements, acceptance criteria, constraints, and priorities. See `reference/spec-parsing.md` for extraction patterns.
+- Capture gaps/assumptions in a clarifications block before proceeding.
+
+### 2) Choose plan depth
+
+- Simple change → use `reference/quick-implementation-plan.md`.
+- Multi-phase feature/migration → use `reference/standard-implementation-plan.md`.
+- Create the plan via `Notion:notion-create-pages`, include: overview, linked spec, requirements summary, phases, dependencies/risks, and success criteria. Link back to the spec.
+
+### 3) Create tasks
+
+- Find the task database (`Notion:notion-search` → `Notion:notion-fetch` to confirm the data source and required properties). Patterns in `reference/task-creation.md`.
+- Size tasks to 1–2 days. Use `reference/task-creation-template.md` for content (context, objective, acceptance criteria, dependencies, resources).
+- Set properties: title/action verb, status, priority, relations to spec + plan, due date/story points/assignee if provided.
+- Create pages with `Notion:notion-create-pages` using the database’s `data_source_id`.
+
+### 4) Link artifacts
+
+- Plan links to spec; tasks link to both plan and spec.
+- Optionally update the spec with a short “Implementation” section pointing to the plan and tasks using `Notion:notion-update-page`.
+
+### 5) Track progress
+
+- Use the cadence in `reference/progress-tracking.md`.
+- Post updates with `reference/progress-update-template.md`; close phases with `reference/milestone-summary-template.md`.
+- Keep checklists and status fields in plan/tasks in sync; note blockers and decisions.
+
+## References and examples
+
+- `reference/` — parsing patterns, plan/task templates, progress cadence (e.g., `spec-parsing.md`, `standard-implementation-plan.md`, `task-creation.md`, `progress-tracking.md`).
+- `examples/` — end-to-end walkthroughs (e.g., `ui-component.md`, `api-feature.md`, `database-migration.md`).

package/skills/notion-spec-to-implementation/agents/verdent.yaml

@@ -0,0 +1,7 @@
+category: Documentation
+interface:
+  display_name: 'Notion Spec to Implementation'
+  short_description: 'Turn Notion specs into implementation plans, tasks, and progress tracking'
+  icon_dark: './assets/icon-dark.png'
+  icon_light: './assets/icon-light.png'
+  default_prompt: 'Turn this Notion spec into an implementation plan with tasks.'