From c3704ea236cd1bc659d46033d8a7fc58946ad9b1 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Jan 2026 00:01:02 +0000 Subject: [PATCH] Standardize on 'ask structured questions' phrasing Update all job definitions and step instructions to explicitly use the phrase "ask structured questions" when referring to gathering user input. This ensures consistency across all DeepWork jobs. Changes: - deepwork_jobs v0.5.0: Updated description, define.md, implement.md, and quality criteria hooks to use "ask structured questions" - deepwork_policy v0.2.0: Updated define.md to use phrase - Added quality criteria hooks to verify phrase usage - implement.md now instructs agents to use phrase in generated instructions --- .claude/commands/deepwork_jobs.define.md | 47 ++++++------ .claude/commands/deepwork_jobs.implement.md | 18 +++-- .claude/commands/deepwork_jobs.learn.md | 2 +- .claude/commands/deepwork_policy.define.md | 7 +- .deepwork/jobs/deepwork_jobs/job.yml | 28 ++++---- .deepwork/jobs/deepwork_jobs/steps/define.md | 15 ++-- .../jobs/deepwork_jobs/steps/implement.md | 2 + .deepwork/jobs/deepwork_policy/job.yml | 4 +- .../jobs/deepwork_policy/steps/define.md | 7 +- .gemini/commands/deepwork_jobs/define.toml | 17 +++-- .gemini/commands/deepwork_jobs/implement.toml | 4 +- .gemini/commands/deepwork_jobs/learn.toml | 72 ++----------------- .gemini/commands/deepwork_policy/define.toml | 7 +- uv.lock | 2 +- 14 files changed, 104 insertions(+), 128 deletions(-) diff --git a/.claude/commands/deepwork_jobs.define.md b/.claude/commands/deepwork_jobs.define.md index 5a8d8bf1..4de4eaf0 100644 --- a/.claude/commands/deepwork_jobs.define.md +++ b/.claude/commands/deepwork_jobs.define.md @@ -11,13 +11,14 @@ hooks: 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`? + 1. **User Understanding**: Did you fully understand the user's workflow by asking structured questions? + 2. **Structured Questions Used**: Did you ask structured questions (using the AskUserQuestion tool) to gather user input? + 3. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs? + 4. **Logical Dependencies**: Do step dependencies make sense and avoid circular references? + 5. **Concise Summary**: Is the summary under 200 characters and descriptive? + 6. **Rich Description**: Does the description provide enough context for future refinement? + 7. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)? + 8. **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 `✓ Quality Criteria Met` in your response. @@ -47,7 +48,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul 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 @@ -66,13 +67,15 @@ Create a `job.yml` specification file that defines the structure of a new DeepWo ## Task -Guide the user through defining a job specification by asking clarifying questions. **Do not attempt to create the specification without first fully understanding the user's needs.** +Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** + +**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`). ### Step 1: Understand the Job Purpose -Start by asking questions to understand what the user wants to accomplish: +Start by asking structured questions to understand what the user wants to accomplish: 1. **What is the overall goal of this workflow?** - What complex task are they trying to accomplish? @@ -91,7 +94,7 @@ Start by asking questions to understand what the user wants to accomplish: ### Step 2: Define Each Step -For each major phase they mentioned, ask detailed questions: +For each major phase they mentioned, ask structured questions to gather details: 1. **Step Purpose** - What exactly does this step accomplish? @@ -152,7 +155,7 @@ After gathering information about all steps: For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met. -**Ask the user about quality validation:** +**Ask structured questions about quality validation:** - "Are there specific quality criteria that must be met for this step?" - "Would you like the agent to validate its work before completing?" - "What would make you send the work back for revision?" @@ -341,11 +344,11 @@ Run `/deepwork_jobs.implement` to generate the instruction files for each step b ## Important Guidelines 1. **Focus on specification only** - Don't create instruction files yet -2. **Ask clarifying questions** - Never skip the discovery phase +2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool 3. **Rich context in description** - This helps with future refinement 4. **Validate understanding** - Summarize and confirm before creating 5. **Use examples** - Help users understand what good specifications look like -6. **Understand file organization** - Always ask where outputs should be saved and if subdirectories are needed +6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed ## Validation Rules @@ -379,6 +382,7 @@ After creating the file: ## Quality Criteria +- Asked structured questions to fully understand user requirements - User fully understands what job they're creating - All steps have clear inputs and outputs - Dependencies make logical sense @@ -425,13 +429,14 @@ This step uses an iterative quality validation loop. After completing your work, ### Quality Criteria 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`? +1. **User Understanding**: Did you fully understand the user's workflow by asking structured questions? +2. **Structured Questions Used**: Did you ask structured questions (using the AskUserQuestion tool) to gather user input? +3. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs? +4. **Logical Dependencies**: Do step dependencies make sense and avoid circular references? +5. **Concise Summary**: Is the summary under 200 characters and descriptive? +6. **Rich Description**: Does the description provide enough context for future refinement? +7. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)? +8. **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 `✓ Quality Criteria Met` in your response. diff --git a/.claude/commands/deepwork_jobs.implement.md b/.claude/commands/deepwork_jobs.implement.md index f691cf46..132330f1 100644 --- a/.claude/commands/deepwork_jobs.implement.md +++ b/.claude/commands/deepwork_jobs.implement.md @@ -16,9 +16,10 @@ hooks: 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? + 6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"? + 7. **Sync Complete**: Has `deepwork sync` been run successfully? + 8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`? + 9. **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. @@ -50,7 +51,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul 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 @@ -138,6 +139,7 @@ For each step in the job.yml, create a comprehensive instruction file at `.deepw 4. **Explain the "why"** - Help the user understand the step's role in the workflow 5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones 6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks +7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions" ### Handling Stop Hooks @@ -300,6 +302,7 @@ Before marking this step complete, ensure: - Instructions are specific and actionable - Output examples are provided in each instruction file - Quality criteria defined for each step +- Steps with user inputs explicitly use "ask structured questions" phrasing - Sync completed successfully - Commands available for use - Thoughtfully considered relevant policies for the job domain @@ -349,9 +352,10 @@ Verify the implementation meets ALL quality criteria before completing: 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? +6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"? +7. **Sync Complete**: Has `deepwork sync` been run successfully? +8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`? +9. **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. diff --git a/.claude/commands/deepwork_jobs.learn.md b/.claude/commands/deepwork_jobs.learn.md index b3cc2513..b1eb339c 100644 --- a/.claude/commands/deepwork_jobs.learn.md +++ b/.claude/commands/deepwork_jobs.learn.md @@ -50,7 +50,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul 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 diff --git a/.claude/commands/deepwork_policy.define.md b/.claude/commands/deepwork_policy.define.md index 3b6fb96d..9e7d1c20 100644 --- a/.claude/commands/deepwork_policy.define.md +++ b/.claude/commands/deepwork_policy.define.md @@ -38,11 +38,13 @@ Create or update policy entries in the `.deepwork.policy.yml` file to enforce te ## Task -Guide the user through defining a new policy by asking clarifying questions. **Do not create the policy without first understanding what they want to enforce.** +Guide the user through defining a new policy by asking structured questions. **Do not create the policy without first understanding what they want to enforce.** + +**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. ### Step 1: Understand the Policy Purpose -Start by asking questions to understand what the user wants to enforce: +Start by asking structured questions to understand what the user wants to enforce: 1. **What guideline or constraint should this policy enforce?** - What situation triggers the need for action? @@ -207,6 +209,7 @@ Create or update this file at the project root with the new policy entry. ## Quality Criteria +- Asked structured questions to understand user requirements - Policy name is clear and descriptive - Trigger patterns accurately match the intended files - Safety patterns prevent unnecessary triggering diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index ac861a5b..e1afa5ee 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/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 @@ -39,13 +41,14 @@ steps: - 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`? + 1. **User Understanding**: Did you fully understand the user's workflow by asking structured questions? + 2. **Structured Questions Used**: Did you ask structured questions (using the AskUserQuestion tool) to gather user input? + 3. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs? + 4. **Logical Dependencies**: Do step dependencies make sense and avoid circular references? + 5. **Concise Summary**: Is the summary under 200 characters and descriptive? + 6. **Rich Description**: Does the description provide enough context for future refinement? + 7. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)? + 8. **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 `✓ Quality Criteria Met` in your response. @@ -71,9 +74,10 @@ steps: 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? + 6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"? + 7. **Sync Complete**: Has `deepwork sync` been run successfully? + 8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`? + 9. **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. diff --git a/.deepwork/jobs/deepwork_jobs/steps/define.md b/.deepwork/jobs/deepwork_jobs/steps/define.md index 0a79561d..2b0b19f1 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/define.md +++ b/.deepwork/jobs/deepwork_jobs/steps/define.md @@ -6,13 +6,15 @@ Create a `job.yml` specification file that defines the structure of a new DeepWo ## Task -Guide the user through defining a job specification by asking clarifying questions. **Do not attempt to create the specification without first fully understanding the user's needs.** +Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** + +**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`). ### Step 1: Understand the Job Purpose -Start by asking questions to understand what the user wants to accomplish: +Start by asking structured questions to understand what the user wants to accomplish: 1. **What is the overall goal of this workflow?** - What complex task are they trying to accomplish? @@ -31,7 +33,7 @@ Start by asking questions to understand what the user wants to accomplish: ### Step 2: Define Each Step -For each major phase they mentioned, ask detailed questions: +For each major phase they mentioned, ask structured questions to gather details: 1. **Step Purpose** - What exactly does this step accomplish? @@ -92,7 +94,7 @@ After gathering information about all steps: For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met. -**Ask the user about quality validation:** +**Ask structured questions about quality validation:** - "Are there specific quality criteria that must be met for this step?" - "Would you like the agent to validate its work before completing?" - "What would make you send the work back for revision?" @@ -281,11 +283,11 @@ Run `/deepwork_jobs.implement` to generate the instruction files for each step b ## Important Guidelines 1. **Focus on specification only** - Don't create instruction files yet -2. **Ask clarifying questions** - Never skip the discovery phase +2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool 3. **Rich context in description** - This helps with future refinement 4. **Validate understanding** - Summarize and confirm before creating 5. **Use examples** - Help users understand what good specifications look like -6. **Understand file organization** - Always ask where outputs should be saved and if subdirectories are needed +6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed ## Validation Rules @@ -319,6 +321,7 @@ After creating the file: ## Quality Criteria +- Asked structured questions to fully understand user requirements - User fully understands what job they're creating - All steps have clear inputs and outputs - Dependencies make logical sense diff --git a/.deepwork/jobs/deepwork_jobs/steps/implement.md b/.deepwork/jobs/deepwork_jobs/steps/implement.md index 05967b66..a3a790f6 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/implement.md +++ b/.deepwork/jobs/deepwork_jobs/steps/implement.md @@ -69,6 +69,7 @@ For each step in the job.yml, create a comprehensive instruction file at `.deepw 4. **Explain the "why"** - Help the user understand the step's role in the workflow 5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones 6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks +7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions" ### Handling Stop Hooks @@ -231,6 +232,7 @@ Before marking this step complete, ensure: - Instructions are specific and actionable - Output examples are provided in each instruction file - Quality criteria defined for each step +- Steps with user inputs explicitly use "ask structured questions" phrasing - Sync completed successfully - Commands available for use - Thoughtfully considered relevant policies for the job domain diff --git a/.deepwork/jobs/deepwork_policy/job.yml b/.deepwork/jobs/deepwork_policy/job.yml index 0aacc872..777894ed 100644 --- a/.deepwork/jobs/deepwork_policy/job.yml +++ b/.deepwork/jobs/deepwork_policy/job.yml @@ -1,5 +1,5 @@ name: deepwork_policy -version: "0.1.0" +version: "0.2.0" summary: "Policy enforcement for AI agent sessions" description: | Manages policies that automatically trigger when certain files change during an AI agent session. @@ -21,6 +21,8 @@ description: | changelog: - version: "0.1.0" changes: "Initial version" + - version: "0.2.0" + changes: "Standardized on 'ask structured questions' phrasing for user input" steps: - id: define diff --git a/.deepwork/jobs/deepwork_policy/steps/define.md b/.deepwork/jobs/deepwork_policy/steps/define.md index 85c2b631..302eda7f 100644 --- a/.deepwork/jobs/deepwork_policy/steps/define.md +++ b/.deepwork/jobs/deepwork_policy/steps/define.md @@ -6,11 +6,13 @@ Create or update policy entries in the `.deepwork.policy.yml` file to enforce te ## Task -Guide the user through defining a new policy by asking clarifying questions. **Do not create the policy without first understanding what they want to enforce.** +Guide the user through defining a new policy by asking structured questions. **Do not create the policy without first understanding what they want to enforce.** + +**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. ### Step 1: Understand the Policy Purpose -Start by asking questions to understand what the user wants to enforce: +Start by asking structured questions to understand what the user wants to enforce: 1. **What guideline or constraint should this policy enforce?** - What situation triggers the need for action? @@ -175,6 +177,7 @@ Create or update this file at the project root with the new policy entry. ## Quality Criteria +- Asked structured questions to understand user requirements - Policy name is clear and descriptive - Trigger patterns accurately match the intended files - Safety patterns prevent unnecessary triggering diff --git a/.gemini/commands/deepwork_jobs/define.toml b/.gemini/commands/deepwork_jobs/define.toml index 3a02872d..d59b3e15 100644 --- a/.gemini/commands/deepwork_jobs/define.toml +++ b/.gemini/commands/deepwork_jobs/define.toml @@ -19,7 +19,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul 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 @@ -38,13 +38,15 @@ Create a `job.yml` specification file that defines the structure of a new DeepWo ## Task -Guide the user through defining a job specification by asking clarifying questions. **Do not attempt to create the specification without first fully understanding the user's needs.** +Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.** + +**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`). ### Step 1: Understand the Job Purpose -Start by asking questions to understand what the user wants to accomplish: +Start by asking structured questions to understand what the user wants to accomplish: 1. **What is the overall goal of this workflow?** - What complex task are they trying to accomplish? @@ -63,7 +65,7 @@ Start by asking questions to understand what the user wants to accomplish: ### Step 2: Define Each Step -For each major phase they mentioned, ask detailed questions: +For each major phase they mentioned, ask structured questions to gather details: 1. **Step Purpose** - What exactly does this step accomplish? @@ -124,7 +126,7 @@ After gathering information about all steps: For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met. -**Ask the user about quality validation:** +**Ask structured questions about quality validation:** - "Are there specific quality criteria that must be met for this step?" - "Would you like the agent to validate its work before completing?" - "What would make you send the work back for revision?" @@ -313,11 +315,11 @@ Run `/deepwork_jobs.implement` to generate the instruction files for each step b ## Important Guidelines 1. **Focus on specification only** - Don't create instruction files yet -2. **Ask clarifying questions** - Never skip the discovery phase +2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool 3. **Rich context in description** - This helps with future refinement 4. **Validate understanding** - Summarize and confirm before creating 5. **Use examples** - Help users understand what good specifications look like -6. **Understand file organization** - Always ask where outputs should be saved and if subdirectories are needed +6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed ## Validation Rules @@ -351,6 +353,7 @@ After creating the file: ## Quality Criteria +- Asked structured questions to fully understand user requirements - User fully understands what job they're creating - All steps have clear inputs and outputs - Dependencies make logical sense diff --git a/.gemini/commands/deepwork_jobs/implement.toml b/.gemini/commands/deepwork_jobs/implement.toml index 51422fc8..3e922243 100644 --- a/.gemini/commands/deepwork_jobs/implement.toml +++ b/.gemini/commands/deepwork_jobs/implement.toml @@ -19,7 +19,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul 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 @@ -107,6 +107,7 @@ For each step in the job.yml, create a comprehensive instruction file at `.deepw 4. **Explain the "why"** - Help the user understand the step's role in the workflow 5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones 6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks +7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions" ### Handling Stop Hooks @@ -269,6 +270,7 @@ Before marking this step complete, ensure: - Instructions are specific and actionable - Output examples are provided in each instruction file - Quality criteria defined for each step +- Steps with user inputs explicitly use "ask structured questions" phrasing - Sync completed successfully - Commands available for use - Thoughtfully considered relevant policies for the job domain diff --git a/.gemini/commands/deepwork_jobs/learn.toml b/.gemini/commands/deepwork_jobs/learn.toml index f901e960..eb33d6df 100644 --- a/.gemini/commands/deepwork_jobs/learn.toml +++ b/.gemini/commands/deepwork_jobs/learn.toml @@ -19,7 +19,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul 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 @@ -174,42 +174,7 @@ The AGENTS.md file captures project-specific knowledge that helps future agent r - This keeps AGENTS.md in sync as the codebase evolves - Pattern: "See `path/to/file.ext` for [description]" -3. **AGENTS.md structure**: - -```markdown -# Project Context for [Job Name] - -## Codebase Structure - - -- Project structure: See `README.md` for overview -- API documentation: See `docs/api.md` -- Configuration: See `config/README.md` - -## Conventions - -### Naming Conventions -- [Convention]: See example in `path/to/example.ext:LINE` - -### File Organization -- [Pattern]: Reference `path/to/pattern/` - -## Job-Specific Context - -### [Job Name] - -#### [Step Name] -- [Learning]: Reference `relevant/file.ext` -- [Context]: [Brief explanation with file reference] - -## Known Issues and Workarounds - -- [Issue]: [Workaround with file reference if applicable] - -## Last Updated -- Date: [YYYY-MM-DD] -- From conversation about: [Brief description] -``` +3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format. 4. **Writing entries** - Be concise but specific @@ -231,36 +196,14 @@ If instruction files were modified: changes: "Improved [step] instructions based on execution learnings: [brief description]" ``` -### Step 7: Sync and Summarize +### Step 7: Sync and Relay Instructions 1. **Run deepwork sync** (if instructions were modified) ```bash deepwork sync ``` -2. **Create learning_summary.md** in the working folder: - ```markdown - # Learning Summary - - ## Job Analyzed - - Job: [job_name] - - Steps executed: [list of steps] - - ## Generalizable Improvements Made - - [Step]: [What was improved] - - ## Bespoke Learnings Captured - - Location: [path to AGENTS.md] - - Entries added: [list of entries] - - ## Files Modified - - [List of files changed] - - ## Recommendations - - [Any additional suggestions] - ``` - -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) +2. **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 @@ -291,7 +234,6 @@ When adding entries to AGENTS.md, prefer these patterns: - AGENTS.md created/updated with bespoke learnings - File references used instead of duplicating content - AGENTS.md is in the correct working folder -- learning_summary.md documents all changes - When all criteria are met, include `✓ Quality Criteria Met` ## Example Dialog @@ -351,7 +293,7 @@ I found the following job executions: **Summary** -Created `learning_summary.md` documenting all changes. To get the updated commands, type 'exit' then run 'claude --resume'. +Updated job instructions and created AGENTS.md with bespoke learnings. To get the updated commands, type 'exit' then run 'claude --resume'. ``` ## Handling Edge Cases @@ -403,7 +345,7 @@ All work for this job should be done on a dedicated work branch: ## Output Requirements Create the following output(s): -- `learning_summary.md` +- `AGENTS.md` Ensure all outputs are: - Well-formatted and complete @@ -417,7 +359,7 @@ After completing this step: 2. **Inform the user**: - The learn command is complete - - Outputs created: learning_summary.md + - Outputs created: AGENTS.md - This command can be run again anytime to make further changes ## Command Complete diff --git a/.gemini/commands/deepwork_policy/define.toml b/.gemini/commands/deepwork_policy/define.toml index 7deb844e..ca45a47f 100644 --- a/.gemini/commands/deepwork_policy/define.toml +++ b/.gemini/commands/deepwork_policy/define.toml @@ -43,11 +43,13 @@ Create or update policy entries in the `.deepwork.policy.yml` file to enforce te ## Task -Guide the user through defining a new policy by asking clarifying questions. **Do not create the policy without first understanding what they want to enforce.** +Guide the user through defining a new policy by asking structured questions. **Do not create the policy without first understanding what they want to enforce.** + +**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. ### Step 1: Understand the Policy Purpose -Start by asking questions to understand what the user wants to enforce: +Start by asking structured questions to understand what the user wants to enforce: 1. **What guideline or constraint should this policy enforce?** - What situation triggers the need for action? @@ -212,6 +214,7 @@ Create or update this file at the project root with the new policy entry. ## Quality Criteria +- Asked structured questions to understand user requirements - Policy name is clear and descriptive - Trigger patterns accurately match the intended files - Safety patterns prevent unnecessary triggering diff --git a/uv.lock b/uv.lock index ccd8b049..3706d2f5 100644 --- a/uv.lock +++ b/uv.lock @@ -126,7 +126,7 @@ toml = [ [[package]] name = "deepwork" -version = "0.1.1" +version = "0.1.2" source = { editable = "." } dependencies = [ { name = "click" },