From 91cbe74af2dc89571b799bd7c1d1cb44a29c4619 Mon Sep 17 00:00:00 2001 From: Tyler Willis Date: Wed, 14 Jan 2026 23:39:34 -0800 Subject: [PATCH 1/3] Fix reload instructions to be platform-specific and actionable Previously, instruction files told users to run `/reload` which doesn't exist in Claude Code. Users were confused and didn't know how to pick up newly created commands. Changes: - Add `reload_instructions` property to adapters with platform-specific text - Update `deepwork sync` to display reload instructions after syncing - Update instruction files to tell agent to relay sync output to user - Remove all `/reload` references from instruction files Now when an agent runs `deepwork sync`, it sees the reload instructions in the output and tells the user exactly what to do: - Claude Code: "Type 'exit' then run 'claude --resume'" - Gemini CLI: "Run '/memory refresh'" Co-Authored-By: Claude Opus 4.5 --- .claude/commands/deepwork_jobs.implement.md | 10 ++++------ .claude/commands/deepwork_jobs.learn.md | 4 ++-- .deepwork/jobs/deepwork_jobs/steps/implement.md | 10 ++++------ .deepwork/jobs/deepwork_jobs/steps/learn.md | 4 ++-- .gemini/commands/deepwork_jobs/implement.toml | 10 ++++------ .gemini/commands/deepwork_jobs/learn.toml | 4 ++-- .gemini/commands/deepwork_jobs/refine.toml | 4 ++-- src/deepwork/cli/sync.py | 9 +++++++++ src/deepwork/core/adapters.py | 15 +++++++++++++++ .../deepwork_jobs/steps/implement.md | 10 ++++------ .../standard_jobs/deepwork_jobs/steps/learn.md | 4 ++-- 11 files changed, 50 insertions(+), 34 deletions(-) diff --git a/.claude/commands/deepwork_jobs.implement.md b/.claude/commands/deepwork_jobs.implement.md index 98d5c7d1..04cf12d3 100644 --- a/.claude/commands/deepwork_jobs.implement.md +++ b/.claude/commands/deepwork_jobs.implement.md @@ -231,11 +231,9 @@ This will: - Generate slash-commands for each step - Make the commands available in `.claude/commands/` (or appropriate platform directory) -### Step 6: Reload Commands +### Step 6: Relay Reload Instructions -Instruct the user to reload commands in their current session: -- Run `/reload` command (if available) -- Or restart the Claude session +After running `deepwork sync`, look at the "To use the new commands" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new commands. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI). ### Step 7: Consider Policies for the New Job @@ -461,7 +459,7 @@ After running `deepwork sync`, the following slash-commands are now available: ## Next Steps -1. **Reload commands**: Run `/reload` or restart your Claude session +1. **Reload commands**: [Include the specific reload instructions from the `deepwork sync` output here] 2. **Start the workflow**: Run `/[job_name].[first_step_id]` to begin 3. **Test the job**: Try executing the first step to ensure everything works @@ -488,7 +486,7 @@ Before marking this step complete, ensure: - [ ] Each instruction file is complete and actionable - [ ] `deepwork sync` executed successfully - [ ] Commands generated in platform directory -- [ ] User informed of next steps (reload commands) +- [ ] User informed to follow reload instructions from `deepwork sync` - [ ] implementation_summary.md created - [ ] Considered whether policies would benefit this job (Step 7) - [ ] If policies suggested, offered to run `/deepwork_policy.define` diff --git a/.claude/commands/deepwork_jobs.learn.md b/.claude/commands/deepwork_jobs.learn.md index 9453f52f..81ba47fb 100644 --- a/.claude/commands/deepwork_jobs.learn.md +++ b/.claude/commands/deepwork_jobs.learn.md @@ -291,7 +291,7 @@ If instruction files were modified: - [Any additional suggestions] ``` -3. **Instruct user to reload** if commands were regenerated +3. **If commands were regenerated**, look at the "To use the new commands" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code) ## File Reference Patterns @@ -382,7 +382,7 @@ I found the following job executions: **Summary** -Created `learning_summary.md` documenting all changes. Please run `/reload` to get the updated commands. +Created `learning_summary.md` documenting all changes. To get the updated commands, type 'exit' then run 'claude --resume'. ``` ## Handling Edge Cases diff --git a/.deepwork/jobs/deepwork_jobs/steps/implement.md b/.deepwork/jobs/deepwork_jobs/steps/implement.md index de77741d..a6ac706d 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/implement.md +++ b/.deepwork/jobs/deepwork_jobs/steps/implement.md @@ -161,11 +161,9 @@ This will: - Generate slash-commands for each step - Make the commands available in `.claude/commands/` (or appropriate platform directory) -### Step 6: Reload Commands +### Step 6: Relay Reload Instructions -Instruct the user to reload commands in their current session: -- Run `/reload` command (if available) -- Or restart the Claude session +After running `deepwork sync`, look at the "To use the new commands" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new commands. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI). ### Step 7: Consider Policies for the New Job @@ -391,7 +389,7 @@ After running `deepwork sync`, the following slash-commands are now available: ## Next Steps -1. **Reload commands**: Run `/reload` or restart your Claude session +1. **Reload commands**: [Include the specific reload instructions from the `deepwork sync` output here] 2. **Start the workflow**: Run `/[job_name].[first_step_id]` to begin 3. **Test the job**: Try executing the first step to ensure everything works @@ -418,7 +416,7 @@ Before marking this step complete, ensure: - [ ] Each instruction file is complete and actionable - [ ] `deepwork sync` executed successfully - [ ] Commands generated in platform directory -- [ ] User informed of next steps (reload commands) +- [ ] User informed to follow reload instructions from `deepwork sync` - [ ] implementation_summary.md created - [ ] Considered whether policies would benefit this job (Step 7) - [ ] If policies suggested, offered to run `/deepwork_policy.define` diff --git a/.deepwork/jobs/deepwork_jobs/steps/learn.md b/.deepwork/jobs/deepwork_jobs/steps/learn.md index 5a74ed78..f50727c3 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/learn.md +++ b/.deepwork/jobs/deepwork_jobs/steps/learn.md @@ -228,7 +228,7 @@ If instruction files were modified: - [Any additional suggestions] ``` -3. **Instruct user to reload** if commands were regenerated +3. **If commands were regenerated**, look at the "To use the new commands" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code) ## File Reference Patterns @@ -319,7 +319,7 @@ I found the following job executions: **Summary** -Created `learning_summary.md` documenting all changes. Please run `/reload` to get the updated commands. +Created `learning_summary.md` documenting all changes. To get the updated commands, type 'exit' then run 'claude --resume'. ``` ## Handling Edge Cases diff --git a/.gemini/commands/deepwork_jobs/implement.toml b/.gemini/commands/deepwork_jobs/implement.toml index 6eae959e..baa584d2 100644 --- a/.gemini/commands/deepwork_jobs/implement.toml +++ b/.gemini/commands/deepwork_jobs/implement.toml @@ -199,11 +199,9 @@ This will: - Generate slash-commands for each step - Make the commands available in `.claude/commands/` (or appropriate platform directory) -### Step 6: Reload Commands +### Step 6: Relay Reload Instructions -Instruct the user to reload commands in their current session: -- Run `/reload` command (if available) -- Or restart the Claude session +After running `deepwork sync`, look at the "To use the new commands" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new commands. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI). ### Step 7: Consider Policies for the New Job @@ -429,7 +427,7 @@ After running `deepwork sync`, the following slash-commands are now available: ## Next Steps -1. **Reload commands**: Run `/reload` or restart your Claude session +1. **Reload commands**: [Include the specific reload instructions from the `deepwork sync` output here] 2. **Start the workflow**: Run `/[job_name].[first_step_id]` to begin 3. **Test the job**: Try executing the first step to ensure everything works @@ -456,7 +454,7 @@ Before marking this step complete, ensure: - [ ] Each instruction file is complete and actionable - [ ] `deepwork sync` executed successfully - [ ] Commands generated in platform directory -- [ ] User informed of next steps (reload commands) +- [ ] User informed to follow reload instructions from `deepwork sync` - [ ] implementation_summary.md created - [ ] Considered whether policies would benefit this job (Step 7) - [ ] If policies suggested, offered to run `/deepwork_policy.define` diff --git a/.gemini/commands/deepwork_jobs/learn.toml b/.gemini/commands/deepwork_jobs/learn.toml index 39e90537..8300911a 100644 --- a/.gemini/commands/deepwork_jobs/learn.toml +++ b/.gemini/commands/deepwork_jobs/learn.toml @@ -260,7 +260,7 @@ If instruction files were modified: - [Any additional suggestions] ``` -3. **Instruct user to reload** if commands were regenerated +3. **If commands were regenerated**, look at the "To use the new commands" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code) ## File Reference Patterns @@ -351,7 +351,7 @@ I found the following job executions: **Summary** -Created `learning_summary.md` documenting all changes. Please run `/reload` to get the updated commands. +Created `learning_summary.md` documenting all changes. To get the updated commands, run '/memory refresh' or restart your session. ``` ## Handling Edge Cases diff --git a/.gemini/commands/deepwork_jobs/refine.toml b/.gemini/commands/deepwork_jobs/refine.toml index 5a29751b..19523289 100644 --- a/.gemini/commands/deepwork_jobs/refine.toml +++ b/.gemini/commands/deepwork_jobs/refine.toml @@ -292,7 +292,7 @@ After updating the changelog: ``` 2. **Reload commands** - - Instruct user to run `/reload` or restart session + - Instruct user to follow the reload instructions shown by `deepwork sync` 3. **Provide summary** - Show what changed @@ -410,7 +410,7 @@ Now run: deepwork sync ``` -Then reload your session and you'll have: +Then follow the reload instructions shown by `deepwork sync` and you'll have: - /competitive_research.validate_positioning (new!) - All other commands updated ``` diff --git a/src/deepwork/cli/sync.py b/src/deepwork/cli/sync.py index e127e49b..b533eb58 100644 --- a/src/deepwork/cli/sync.py +++ b/src/deepwork/cli/sync.py @@ -117,6 +117,7 @@ def sync_commands(project_path: Path) -> None: # Sync each platform generator = CommandGenerator() stats = {"platforms": 0, "commands": 0, "hooks": 0} + synced_adapters: list[AgentAdapter] = [] for platform_name in platforms: try: @@ -157,6 +158,7 @@ def sync_commands(project_path: Path) -> None: console.print(f" [red]✗[/red] Failed to sync hooks: {e}") stats["platforms"] += 1 + synced_adapters.append(adapter) # Summary console.print() @@ -174,3 +176,10 @@ def sync_commands(project_path: Path) -> None: console.print(table) console.print() + + # Show reload instructions for each synced platform + if synced_adapters and stats["commands"] > 0: + console.print("[bold]To use the new commands:[/bold]") + for adapter in synced_adapters: + console.print(f" [cyan]{adapter.display_name}:[/cyan] {adapter.reload_instructions}") + console.print() diff --git a/src/deepwork/core/adapters.py b/src/deepwork/core/adapters.py index 1ddcb537..1fa0a836 100644 --- a/src/deepwork/core/adapters.py +++ b/src/deepwork/core/adapters.py @@ -57,6 +57,10 @@ class AgentAdapter(ABC): commands_dir: ClassVar[str] = "commands" command_template: ClassVar[str] = "command-job-step.md.jinja" + # Instructions for reloading commands after sync (shown to users) + # Subclasses should override with platform-specific instructions. + reload_instructions: ClassVar[str] = "Restart your AI assistant session to use the new commands." + # Mapping from generic CommandLifecycleHook to platform-specific event names. # Subclasses should override this to provide platform-specific mappings. hook_name_mapping: ClassVar[dict[CommandLifecycleHook, str]] = {} @@ -253,6 +257,12 @@ class ClaudeAdapter(AgentAdapter): display_name = "Claude Code" config_dir = ".claude" + # Claude Code doesn't have a reload command - must restart session + reload_instructions: ClassVar[str] = ( + "Type 'exit' to leave your current session, then run 'claude' " + "(fresh start) or 'claude --resume' (keep conversation history)." + ) + # Claude Code uses PascalCase event names hook_name_mapping: ClassVar[dict[CommandLifecycleHook, str]] = { CommandLifecycleHook.AFTER_AGENT: "Stop", @@ -333,6 +343,11 @@ class GeminiAdapter(AgentAdapter): config_dir = ".gemini" command_template = "command-job-step.toml.jinja" + # Gemini CLI can reload with /memory refresh + reload_instructions: ClassVar[str] = ( + "Run '/memory refresh' to reload commands, or restart your Gemini CLI session." + ) + # Gemini CLI does NOT support command-level hooks # Hooks are global/project-level in settings.json, not per-command hook_name_mapping: ClassVar[dict[CommandLifecycleHook, str]] = {} diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md index c5f55ae6..60a68827 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md @@ -167,11 +167,9 @@ This will: - Generate slash-commands for each step - Make the commands available in `.claude/commands/` (or appropriate platform directory) -### Step 6: Reload Commands +### Step 6: Relay Reload Instructions -Instruct the user to reload commands in their current session: -- Run `/reload` command (if available) -- Or restart the Claude session +After running `deepwork sync`, look at the "To use the new commands" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new commands. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI). ### Step 7: Consider Policies for the New Job @@ -397,7 +395,7 @@ After running `deepwork sync`, the following slash-commands are now available: ## Next Steps -1. **Reload commands**: Run `/reload` or restart your Claude session +1. **Reload commands**: [Include the specific reload instructions from the `deepwork sync` output here] 2. **Start the workflow**: Run `/[job_name].[first_step_id]` to begin 3. **Test the job**: Try executing the first step to ensure everything works @@ -424,7 +422,7 @@ Before marking this step complete, ensure: - [ ] Each instruction file is complete and actionable - [ ] `deepwork sync` executed successfully - [ ] Commands generated in platform directory -- [ ] User informed of next steps (reload commands) +- [ ] User informed to follow reload instructions from `deepwork sync` - [ ] implementation_summary.md created - [ ] Considered whether policies would benefit this job (Step 7) - [ ] If policies suggested, offered to run `/deepwork_policy.define` diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md index 5a74ed78..f50727c3 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md @@ -228,7 +228,7 @@ If instruction files were modified: - [Any additional suggestions] ``` -3. **Instruct user to reload** if commands were regenerated +3. **If commands were regenerated**, look at the "To use the new commands" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code) ## File Reference Patterns @@ -319,7 +319,7 @@ I found the following job executions: **Summary** -Created `learning_summary.md` documenting all changes. Please run `/reload` to get the updated commands. +Created `learning_summary.md` documenting all changes. To get the updated commands, type 'exit' then run 'claude --resume'. ``` ## Handling Edge Cases From 4fd9cbe236edd75a89790539ecc59842a9379389 Mon Sep 17 00:00:00 2001 From: Tyler Willis Date: Thu, 15 Jan 2026 01:56:08 -0800 Subject: [PATCH 2/3] Fix ruff formatting in adapters.py Co-Authored-By: Claude Opus 4.5 --- src/deepwork/core/adapters.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/deepwork/core/adapters.py b/src/deepwork/core/adapters.py index 1fa0a836..17d16c5f 100644 --- a/src/deepwork/core/adapters.py +++ b/src/deepwork/core/adapters.py @@ -59,7 +59,9 @@ class AgentAdapter(ABC): # Instructions for reloading commands after sync (shown to users) # Subclasses should override with platform-specific instructions. - reload_instructions: ClassVar[str] = "Restart your AI assistant session to use the new commands." + reload_instructions: ClassVar[str] = ( + "Restart your AI assistant session to use the new commands." + ) # Mapping from generic CommandLifecycleHook to platform-specific event names. # Subclasses should override this to provide platform-specific mappings. From 75f8861f0e27802449473dc60a213e6d0967c368 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Thu, 15 Jan 2026 08:29:48 -0700 Subject: [PATCH 3/3] Apply suggestion from @nhorton --- src/deepwork/core/adapters.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/deepwork/core/adapters.py b/src/deepwork/core/adapters.py index 17d16c5f..82afa868 100644 --- a/src/deepwork/core/adapters.py +++ b/src/deepwork/core/adapters.py @@ -261,8 +261,8 @@ class ClaudeAdapter(AgentAdapter): # Claude Code doesn't have a reload command - must restart session reload_instructions: ClassVar[str] = ( - "Type 'exit' to leave your current session, then run 'claude' " - "(fresh start) or 'claude --resume' (keep conversation history)." + "Type 'exit' to leave your current session, then run " + "'claude --resume' (your history will be maintained)." ) # Claude Code uses PascalCase event names