deepwork 0.2.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

deepwork/hooks/wrapper.py

@@ -0,0 +1,363 @@
+"""
+Hook wrapper module for cross-platform hook compatibility.
+
+This module provides utilities for normalizing hook input/output between
+different AI CLI platforms (Claude Code, Gemini CLI, etc.).
+
+The wrapper system allows writing hooks once in Python and running them
+on any supported platform. Platform-specific shell scripts handle the
+input/output translation, while Python hooks work with a normalized format.
+
+Normalized Format:
+    Input:
+        - session_id: str
+        - transcript_path: str
+        - cwd: str
+        - event: str (normalized: 'after_agent', 'before_tool', 'before_prompt')
+        - tool_name: str (normalized: 'write_file', 'shell', etc.)
+        - tool_input: dict
+        - prompt: str (for agent events)
+        - raw_input: dict (original platform-specific input)
+
+    Output:
+        - decision: str ('block', 'allow', 'deny')
+        - reason: str (explanation for blocking)
+        - context: str (additional context to add)
+        - raw_output: dict (will be merged into final output)
+
+Usage:
+    # In a Python hook:
+    from deepwork.hooks.wrapper import HookInput, HookOutput, normalize_input, denormalize_output
+
+    def my_hook(input_data: HookInput) -> HookOutput:
+        if should_block:
+            return HookOutput(decision='block', reason='Must do X first')
+        return HookOutput()  # Allow
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Platform(str, Enum):
+    """Supported AI CLI platforms."""
+
+    CLAUDE = "claude"
+    GEMINI = "gemini"
+
+
+class NormalizedEvent(str, Enum):
+    """Normalized hook event names."""
+
+    AFTER_AGENT = "after_agent"
+    BEFORE_TOOL = "before_tool"
+    BEFORE_PROMPT = "before_prompt"
+    SESSION_START = "session_start"
+    SESSION_END = "session_end"
+    AFTER_TOOL = "after_tool"
+    BEFORE_MODEL = "before_model"
+    AFTER_MODEL = "after_model"
+
+
+# Event name mappings from platform-specific to normalized
+EVENT_TO_NORMALIZED: dict[Platform, dict[str, NormalizedEvent]] = {
+    Platform.CLAUDE: {
+        "Stop": NormalizedEvent.AFTER_AGENT,
+        "SubagentStop": NormalizedEvent.AFTER_AGENT,
+        "PreToolUse": NormalizedEvent.BEFORE_TOOL,
+        "PostToolUse": NormalizedEvent.AFTER_TOOL,
+        "UserPromptSubmit": NormalizedEvent.BEFORE_PROMPT,
+        "SessionStart": NormalizedEvent.SESSION_START,
+        "SessionEnd": NormalizedEvent.SESSION_END,
+    },
+    Platform.GEMINI: {
+        "AfterAgent": NormalizedEvent.AFTER_AGENT,
+        "BeforeTool": NormalizedEvent.BEFORE_TOOL,
+        "AfterTool": NormalizedEvent.AFTER_TOOL,
+        "BeforeAgent": NormalizedEvent.BEFORE_PROMPT,
+        "SessionStart": NormalizedEvent.SESSION_START,
+        "SessionEnd": NormalizedEvent.SESSION_END,
+        "BeforeModel": NormalizedEvent.BEFORE_MODEL,
+        "AfterModel": NormalizedEvent.AFTER_MODEL,
+    },
+}
+
+# Normalized event to platform-specific event name
+NORMALIZED_TO_EVENT: dict[Platform, dict[NormalizedEvent, str]] = {
+    Platform.CLAUDE: {
+        NormalizedEvent.AFTER_AGENT: "Stop",
+        NormalizedEvent.BEFORE_TOOL: "PreToolUse",
+        NormalizedEvent.AFTER_TOOL: "PostToolUse",
+        NormalizedEvent.BEFORE_PROMPT: "UserPromptSubmit",
+        NormalizedEvent.SESSION_START: "SessionStart",
+        NormalizedEvent.SESSION_END: "SessionEnd",
+    },
+    Platform.GEMINI: {
+        NormalizedEvent.AFTER_AGENT: "AfterAgent",
+        NormalizedEvent.BEFORE_TOOL: "BeforeTool",
+        NormalizedEvent.AFTER_TOOL: "AfterTool",
+        NormalizedEvent.BEFORE_PROMPT: "BeforeAgent",
+        NormalizedEvent.SESSION_START: "SessionStart",
+        NormalizedEvent.SESSION_END: "SessionEnd",
+        NormalizedEvent.BEFORE_MODEL: "BeforeModel",
+        NormalizedEvent.AFTER_MODEL: "AfterModel",
+    },
+}
+
+# Tool name mappings from platform-specific to normalized (snake_case)
+TOOL_TO_NORMALIZED: dict[Platform, dict[str, str]] = {
+    Platform.CLAUDE: {
+        "Write": "write_file",
+        "Edit": "edit_file",
+        "Read": "read_file",
+        "Bash": "shell",
+        "Glob": "glob",
+        "Grep": "grep",
+        "WebFetch": "web_fetch",
+        "WebSearch": "web_search",
+        "Task": "task",
+    },
+    Platform.GEMINI: {
+        # Gemini already uses snake_case
+        "write_file": "write_file",
+        "edit_file": "edit_file",
+        "read_file": "read_file",
+        "shell": "shell",
+        "glob": "glob",
+        "grep": "grep",
+        "web_fetch": "web_fetch",
+        "web_search": "web_search",
+    },
+}
+
+# Normalized tool names to platform-specific
+NORMALIZED_TO_TOOL: dict[Platform, dict[str, str]] = {
+    Platform.CLAUDE: {
+        "write_file": "Write",
+        "edit_file": "Edit",
+        "read_file": "Read",
+        "shell": "Bash",
+        "glob": "Glob",
+        "grep": "Grep",
+        "web_fetch": "WebFetch",
+        "web_search": "WebSearch",
+        "task": "Task",
+    },
+    Platform.GEMINI: {
+        # Gemini already uses snake_case
+        "write_file": "write_file",
+        "edit_file": "edit_file",
+        "read_file": "read_file",
+        "shell": "shell",
+        "glob": "glob",
+        "grep": "grep",
+        "web_fetch": "web_fetch",
+        "web_search": "web_search",
+    },
+}
+
+
+@dataclass
+class HookInput:
+    """Normalized hook input data."""
+
+    platform: Platform
+    event: NormalizedEvent
+    session_id: str = ""
+    transcript_path: str = ""
+    cwd: str = ""
+    tool_name: str = ""
+    tool_input: dict[str, Any] = field(default_factory=dict)
+    tool_response: str = ""
+    prompt: str = ""
+    raw_input: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], platform: Platform) -> HookInput:
+        """Create HookInput from raw platform-specific input."""
+        # Get event name and normalize
+        raw_event = data.get("hook_event_name", "")
+        event_map = EVENT_TO_NORMALIZED.get(platform, {})
+        event = event_map.get(raw_event, NormalizedEvent.AFTER_AGENT)
+
+        # Get tool name and normalize
+        raw_tool = data.get("tool_name", "")
+        tool_map = TOOL_TO_NORMALIZED.get(platform, {})
+        tool_name = tool_map.get(raw_tool, raw_tool.lower())
+
+        return cls(
+            platform=platform,
+            event=event,
+            session_id=data.get("session_id", ""),
+            transcript_path=data.get("transcript_path", ""),
+            cwd=data.get("cwd", ""),
+            tool_name=tool_name,
+            tool_input=data.get("tool_input", {}),
+            tool_response=data.get("tool_response", ""),
+            prompt=data.get("prompt", ""),
+            raw_input=data,
+        )
+
+
+@dataclass
+class HookOutput:
+    """Normalized hook output data."""
+
+    decision: str = ""  # 'block', 'allow', 'deny', '' (empty = allow)
+    reason: str = ""  # Explanation for blocking
+    context: str = ""  # Additional context to add
+    continue_loop: bool = True  # False to terminate agent loop
+    stop_reason: str = ""  # Message when stopping
+    suppress_output: bool = False  # Hide from transcript
+    raw_output: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self, platform: Platform, event: NormalizedEvent) -> dict[str, Any]:
+        """Convert to platform-specific output format."""
+        result: dict[str, Any] = {}
+
+        # Handle decision
+        if self.decision:
+            if platform == Platform.GEMINI and self.decision == "block":
+                # Gemini prefers 'deny'
+                result["decision"] = "deny"
+            else:
+                result["decision"] = self.decision
+
+        # Handle reason
+        if self.reason:
+            result["reason"] = self.reason
+
+        # Handle continue_loop
+        if not self.continue_loop:
+            result["continue"] = False
+            if self.stop_reason:
+                result["stopReason"] = self.stop_reason
+
+        # Handle suppress_output
+        if self.suppress_output:
+            result["suppressOutput"] = True
+
+        # Handle context (platform-specific)
+        if self.context:
+            if platform == Platform.CLAUDE:
+                # Claude uses different fields depending on event
+                if event == NormalizedEvent.SESSION_START:
+                    result.setdefault("hookSpecificOutput", {})
+                    result["hookSpecificOutput"]["hookEventName"] = NORMALIZED_TO_EVENT[platform][
+                        event
+                    ]
+                    result["hookSpecificOutput"]["additionalContext"] = self.context
+                else:
+                    result["systemMessage"] = self.context
+            else:
+                # Gemini
+                result.setdefault("hookSpecificOutput", {})
+                result["hookSpecificOutput"]["hookEventName"] = NORMALIZED_TO_EVENT[platform].get(
+                    event, str(event)
+                )
+                result["hookSpecificOutput"]["additionalContext"] = self.context
+
+        # Merge any raw output
+        for key, value in self.raw_output.items():
+            if key not in result:
+                result[key] = value
+
+        return result
+
+
+def normalize_input(raw_json: str, platform: Platform) -> HookInput:
+    """
+    Parse raw JSON input and normalize it.
+
+    Args:
+        raw_json: JSON string from stdin
+        platform: Source platform
+
+    Returns:
+        Normalized HookInput
+    """
+    try:
+        data = json.loads(raw_json) if raw_json.strip() else {}
+    except json.JSONDecodeError:
+        data = {}
+
+    return HookInput.from_dict(data, platform)
+
+
+def denormalize_output(output: HookOutput, platform: Platform, event: NormalizedEvent) -> str:
+    """
+    Convert normalized output to platform-specific JSON.
+
+    Args:
+        output: Normalized HookOutput
+        platform: Target platform
+        event: The event being processed
+
+    Returns:
+        JSON string for stdout
+    """
+    result = output.to_dict(platform, event)
+    return json.dumps(result) if result else "{}"
+
+
+def read_stdin() -> str:
+    """Read all input from stdin."""
+    if sys.stdin.isatty():
+        return ""
+    try:
+        return sys.stdin.read()
+    except Exception:
+        return ""
+
+
+def write_stdout(data: str) -> None:
+    """Write output to stdout."""
+    print(data)
+
+
+def run_hook(
+    hook_fn: Callable[[HookInput], HookOutput],
+    platform: Platform,
+) -> int:
+    """
+    Run a hook function with normalized input/output.
+
+    This is the main entry point for Python hooks. It:
+    1. Reads raw input from stdin
+    2. Normalizes the input
+    3. Calls the hook function
+    4. Denormalizes the output
+    5. Writes to stdout
+
+    Args:
+        hook_fn: Function that takes HookInput and returns HookOutput
+        platform: The platform calling this hook
+
+    Returns:
+        Exit code (0 for success, 2 for blocking)
+    """
+    # Read and normalize input
+    raw_input = read_stdin()
+    hook_input = normalize_input(raw_input, platform)
+
+    # Call the hook
+    try:
+        hook_output = hook_fn(hook_input)
+    except Exception as e:
+        # On error, allow the action but log
+        print(f"Hook error: {e}", file=sys.stderr)
+        hook_output = HookOutput()
+
+    # Denormalize and write output
+    output_json = denormalize_output(hook_output, platform, hook_input.event)
+    write_stdout(output_json)
+
+    # Always return 0 when using JSON output format
+    # The decision field in the JSON controls blocking behavior
+    return 0

deepwork/schemas/job_schema.py

@@ -3,7 +3,7 @@
 from typing import Any
 
 # Supported lifecycle hook events (generic names, mapped to platform-specific by adapters)
-# These values must match CommandLifecycleHook enum in adapters.py
+# These values must match SkillLifecycleHook enum in adapters.py
 LIFECYCLE_HOOK_EVENTS = ["after_agent", "before_tool", "before_prompt"]
 
 # Schema definition for a single hook action (prompt, prompt_file, or script)
@@ -203,6 +203,19 @@ JOB_SCHEMA: dict[str, Any] = {
                         "description": "DEPRECATED: Use hooks.after_agent instead. Stop hooks for quality validation loops.",
                         "items": HOOK_ACTION_SCHEMA,
                     },
+                    "exposed": {
+                        "type": "boolean",
+                        "description": "If true, skill is user-invocable in menus. Default: false (hidden from menus).",
+                        "default": False,
+                    },
+                    "quality_criteria": {
+                        "type": "array",
+                        "description": "Declarative quality criteria. Rendered with standard evaluation framing.",
+                        "items": {
+                            "type": "string",
+                            "minLength": 1,
+                        },
+                    },
                 },
                 "additionalProperties": False,
             },

deepwork/schemas/rules_schema.py

@@ -0,0 +1,135 @@
+"""JSON Schema definition for rule definitions (v2 - frontmatter format)."""
+
+from typing import Any
+
+# Pattern for string or array of strings
+STRING_OR_ARRAY: dict[str, Any] = {
+    "oneOf": [
+        {"type": "string", "minLength": 1},
+        {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1},
+    ]
+}
+
+# JSON Schema for rule frontmatter (YAML between --- delimiters)
+# Rules are stored as individual .md files in .deepwork/rules/
+RULES_FRONTMATTER_SCHEMA: dict[str, Any] = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["name", "compare_to"],
+    "properties": {
+        "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Human-friendly name for the rule (displayed in promise tags)",
+        },
+        # Detection mode: trigger/safety (mutually exclusive with set/pair)
+        "trigger": {
+            **STRING_OR_ARRAY,
+            "description": "Glob pattern(s) for files that trigger this rule",
+        },
+        "safety": {
+            **STRING_OR_ARRAY,
+            "description": "Glob pattern(s) that suppress the rule if changed",
+        },
+        # Detection mode: set (bidirectional correspondence)
+        "set": {
+            "type": "array",
+            "items": {"type": "string", "minLength": 1},
+            "minItems": 2,
+            "description": "Patterns defining bidirectional file correspondence",
+        },
+        # Detection mode: pair (directional correspondence)
+        "pair": {
+            "type": "object",
+            "required": ["trigger", "expects"],
+            "properties": {
+                "trigger": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Pattern that triggers the rule",
+                },
+                "expects": {
+                    **STRING_OR_ARRAY,
+                    "description": "Pattern(s) for expected corresponding files",
+                },
+            },
+            "additionalProperties": False,
+            "description": "Directional file correspondence (trigger -> expects)",
+        },
+        # Detection mode: created (fire when files are created matching patterns)
+        "created": {
+            **STRING_OR_ARRAY,
+            "description": "Glob pattern(s) for newly created files that trigger this rule",
+        },
+        # Action type: command (default is prompt using markdown body)
+        "action": {
+            "type": "object",
+            "required": ["command"],
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Command to run (supports {file}, {files}, {repo_root})",
+                },
+                "run_for": {
+                    "type": "string",
+                    "enum": ["each_match", "all_matches"],
+                    "default": "each_match",
+                    "description": "Run command for each file or all files at once",
+                },
+            },
+            "additionalProperties": False,
+            "description": "Command action to run instead of prompting",
+        },
+        # Common options
+        "compare_to": {
+            "type": "string",
+            "enum": ["base", "default_tip", "prompt"],
+            "description": "Baseline for detecting file changes",
+        },
+    },
+    "additionalProperties": False,
+    # Detection mode must be exactly one of: trigger, set, pair, or created
+    "oneOf": [
+        {
+            "required": ["trigger"],
+            "not": {
+                "anyOf": [
+                    {"required": ["set"]},
+                    {"required": ["pair"]},
+                    {"required": ["created"]},
+                ]
+            },
+        },
+        {
+            "required": ["set"],
+            "not": {
+                "anyOf": [
+                    {"required": ["trigger"]},
+                    {"required": ["pair"]},
+                    {"required": ["created"]},
+                ]
+            },
+        },
+        {
+            "required": ["pair"],
+            "not": {
+                "anyOf": [
+                    {"required": ["trigger"]},
+                    {"required": ["set"]},
+                    {"required": ["created"]},
+                ]
+            },
+        },
+        {
+            "required": ["created"],
+            "not": {
+                "anyOf": [
+                    {"required": ["trigger"]},
+                    {"required": ["set"]},
+                    {"required": ["pair"]},
+                ]
+            },
+        },
+    ],
+}

deepwork/standard_jobs/deepwork_jobs/job.yml

@@ -1,12 +1,12 @@
 name: deepwork_jobs
-version: "0.4.0"
+version: "0.5.0"
 summary: "DeepWork job management commands"
 description: |
   Core commands for managing DeepWork jobs. These commands help you define new multi-step
   workflows and learn from running them.
 
   The `define` command guides you through an interactive process to create a new job by
-  asking detailed questions about your workflow, understanding each step's inputs and outputs,
+  asking structured questions about your workflow, understanding each step's inputs and outputs,
   and generating all necessary files.
 
   The `learn` command reflects on conversations where DeepWork jobs were run, identifies
@@ -22,6 +22,8 @@ changelog:
     changes: "Added make_new_job.sh script and templates directory; updated instructions to reference templates instead of inline examples"
   - version: "0.4.0"
     changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs"
+  - version: "0.5.0"
+    changes: "Standardized on 'ask structured questions' phrasing for user input; Updated quality criteria hooks to verify phrase usage; Added guidance in implement.md to use phrase in generated instructions"
 
 steps:
   - id: define
@@ -34,21 +36,15 @@ steps:
     outputs:
       - job.yml
     dependencies: []
-    hooks:
-      after_agent:
-        - prompt: |
-            Verify the job.yml output meets ALL quality criteria before completing:
-
-            1. **User Understanding**: Did you fully understand the user's workflow through interactive Q&A?
-            2. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
-            3. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
-            4. **Concise Summary**: Is the summary under 200 characters and descriptive?
-            5. **Rich Description**: Does the description provide enough context for future refinement?
-            6. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
-            7. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
-
-            If ANY criterion is not met, continue working to address it.
-            If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
+    quality_criteria:
+      - "**User Understanding**: Did the agent fully understand the user's workflow by asking structured questions?"
+      - "**Structured Questions Used**: Did the agent ask structured questions (using the AskUserQuestion tool) to gather user input?"
+      - "**Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?"
+      - "**Logical Dependencies**: Do step dependencies make sense and avoid circular references?"
+      - "**Concise Summary**: Is the summary under 200 characters and descriptive?"
+      - "**Rich Description**: Does the description provide enough context for future refinement?"
+      - "**Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?"
+      - "**File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?"
 
   - id: implement
     name: "Implement Job Steps"
@@ -61,50 +57,36 @@ steps:
       - steps/
     dependencies:
       - define
-    hooks:
-      after_agent:
-        - prompt: |
-            Verify the implementation meets ALL quality criteria before completing:
-
-            1. **Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?
-            2. **Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?
-            3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?
-            4. **Output Examples**: Does each instruction file show what good output looks like?
-            5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
-            6. **Sync Complete**: Has `deepwork sync` been run successfully?
-            7. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
-            8. **Policies Considered**: Have you thought about whether policies would benefit this job?
-               - If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
-               - Not every job needs policies - only suggest when genuinely helpful.
-
-            If ANY criterion is not met, continue working to address it.
-            If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
+    quality_criteria:
+      - "**Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?"
+      - "**Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?"
+      - "**Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?"
+      - "**Output Examples**: Does each instruction file show what good output looks like?"
+      - "**Quality Criteria**: Does each instruction file define quality criteria for its outputs?"
+      - "**Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase \"ask structured questions\"?"
+      - "**Sync Complete**: Has `deepwork sync` been run successfully?"
+      - "**Commands Available**: Are the slash-commands generated in `.claude/commands/`?"
+      - "**Rules Considered**: Has the agent thought about whether rules would benefit this job? If relevant rules were identified, did they explain them and offer to run `/deepwork_rules.define`? Not every job needs rules - only suggest when genuinely helpful."
 
   - id: learn
     name: "Learn from Job Execution"
     description: "Reflect on conversation to improve job instructions and capture learnings"
     instructions_file: steps/learn.md
+    exposed: true
     inputs:
       - name: job_name
         description: "Name of the job that was run (optional - will auto-detect from conversation)"
     outputs:
       - AGENTS.md
     dependencies: []
-    hooks:
-      after_agent:
-        - prompt: |
-            Verify the learning process meets ALL quality criteria before completing:
-
-            1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions?
-            2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies?
-            3. **Instructions Improved**: Were job instructions updated to address identified issues?
-            4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?
-            5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?
-            6. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?
-            7. **File References Used**: Do AGENTS.md entries reference other files where appropriate?
-            8. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?
-            9. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?
-            10. **Sync Complete**: Has `deepwork sync` been run if instructions were modified?
-
-            If ANY criterion is not met, continue working to address it.
-            If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
+    quality_criteria:
+      - "**Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions?"
+      - "**Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies?"
+      - "**Instructions Improved**: Were job instructions updated to address identified issues?"
+      - "**Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?"
+      - "**Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?"
+      - "**Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?"
+      - "**File References Used**: Do AGENTS.md entries reference other files where appropriate?"
+      - "**Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?"
+      - "**Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?"
+      - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?"