diff --git a/.claude/commands/deepwork_jobs.define.md b/.claude/commands/deepwork_jobs.define.md index b210991..5a8d8bf 100644 --- a/.claude/commands/deepwork_jobs.define.md +++ b/.claude/commands/deepwork_jobs.define.md @@ -122,6 +122,12 @@ For each major phase they mentioned, ask detailed questions: **Note**: You're gathering this information to understand what instructions will be needed, but you won't create the instruction files yet - that happens in the `implement` step. +### Capability Considerations + +When defining steps, identify any that require specialized tools: + +**Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps. + ### Step 3: Validate the Workflow After gathering information about all steps: @@ -189,68 +195,31 @@ stop_hooks: **Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests). -### Step 5: Create the job.yml Specification +### Step 5: Create the Job Directory and Specification -Only after you have complete understanding, create the `job.yml` file: +Only after you have complete understanding, create the job directory and `job.yml` file: -**File Location**: `.deepwork/jobs/[job_name]/job.yml` +**First, create the directory structure** using the `make_new_job.sh` script: -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `.deepwork/jobs/competitive_research/job.yml`) - -**Format**: -```yaml -name: [job_name] -version: "1.0.0" -summary: "[Brief one-line summary of what this job accomplishes]" -description: | - [Detailed multi-line description of the job's purpose, process, and goals. - - This should explain: - - What problem this workflow solves - - What the overall process looks like - - What the end result will be - - Who the intended users are - - Any important context about the workflow] - -changelog: - - version: "1.0.0" - changes: "Initial job creation" - -steps: - - id: [step_id] - name: "[Step Name]" - description: "[What this step does]" - instructions_file: steps/[step_id].md - inputs: - - name: [param_name] - description: "[What user needs to provide]" - # OR for file inputs from previous steps: - # - file: [filename_or_path] - # from_step: [previous_step_id] - outputs: - - [output_filename_or_path] # e.g., "report.md" or "reports/analysis.md" - dependencies: [] # List of step IDs that must complete first - # Optional: Quality validation hooks - stop_hooks: - - prompt: | - Verify this step's output meets quality criteria: - 1. [Criterion 1] - 2. [Criterion 2] - If ALL criteria are met, include `✓ Quality Criteria Met`. - - - id: [another_step] - name: "[Another Step]" - description: "[What this step does]" - instructions_file: steps/[another_step].md - inputs: - - file: [output_filename_or_path] - from_step: [step_id] - outputs: - - [another_output_path] - dependencies: - - [step_id] # This step requires the previous step +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - For step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts +- `.deepwork/jobs/[job_name]/templates/` - For example file formats +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance + +**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` + +(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) + +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. + +**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. + **Important**: - Use lowercase with underscores for job name and step IDs - Ensure file inputs reference steps in dependencies diff --git a/.claude/commands/deepwork_jobs.implement.md b/.claude/commands/deepwork_jobs.implement.md index 04cf12d..f691cf4 100644 --- a/.claude/commands/deepwork_jobs.implement.md +++ b/.claude/commands/deepwork_jobs.implement.md @@ -18,8 +18,7 @@ hooks: 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. **Summary Created**: Has `implementation_summary.md` been created? - 9. **Policies Considered**: Have you thought about whether policies would benefit this job? + 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. @@ -78,10 +77,31 @@ Generate the DeepWork job directory structure and instruction files for each ste Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available. -### Step 1: Read and Validate the Specification +### Step 1: Create Directory Structure Using Script + +Run the `make_new_job.sh` script to create the standard directory structure: + +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` + +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - Step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep) +- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep) +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance + +**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories: +```bash +mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates +touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep +``` + +### Step 2: Read and Validate the Specification 1. **Locate the job.yml file** - - Read `.deepwork/jobs/[job_name]/job.yml` from the define step (Where `[job_name]` is the name of the new job that was created in the define step) + - Read `.deepwork/jobs/[job_name]/job.yml` from the define step - Parse the YAML content 2. **Validate the specification** @@ -95,83 +115,20 @@ Read the `job.yml` specification file and create all the necessary files to make - List of all steps with their details - Understand the workflow structure -### Step 2: Create Directory Structure - -Create the job directory in `.deepwork/jobs/[job_name]/`: - -```bash -mkdir -p .deepwork/jobs/[job_name]/steps -``` - -Files to create: -- `.deepwork/jobs/[job_name]/job.yml` -- `.deepwork/jobs/[job_name]/steps/[step_id].md` - One for each step - ### Step 3: Generate Step Instruction Files For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`. -Each instruction file should follow this structure: - -```markdown -# [Step Name] - -## Objective - -[Clear statement of what this step accomplishes, derived from the step's description] - -## Task - -[Detailed instructions for completing this step, based on: -- The step's purpose -- Expected inputs and outputs -- The job's overall context -] - -### Process - -[Break down the step into substeps. Use the information gathered during define about: -- What needs to be done -- What makes a good output -- Any quality criteria -] +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. -1. [Substep 1] -2. [Substep 2] -3. [Substep 3] +**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. -[If this step has user inputs, explain how to gather them] -[If this step has file inputs, explain how to use them] - -## Output Format - -### [output_filename_1] - -[Description of what should be in this output file] - -**Structure**: -```[file format] -[Example or template of what the output should look like] -``` - -[Repeat for each output file] - -## Quality Criteria - -[List what makes this step's output high quality: -- Completeness checks -- Format requirements -- Content requirements -] - -- [Quality criterion 1] -- [Quality criterion 2] -- [Quality criterion 3] - -## Context - -[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture] -``` +**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** +- `job.yml.template` - Job specification structure +- `step_instruction.md.template` - Step instruction file structure +- `agents.md.template` - AGENTS.md file structure +- `job.yml.example` - Complete job specification example +- `step_instruction.md.example` - Complete step instruction example **Guidelines for generating instructions:** @@ -214,6 +171,12 @@ If a step in the job.yml has `stop_hooks` defined, the generated instruction fil This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing. +### Using Supplementary Reference Files + +Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. + +See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. + ### Step 4: Verify job.yml Location Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define step should have created it there. If for some reason it's not there, you may need to create or move it. @@ -297,112 +260,9 @@ Would you like me to create this policy? I can run `/deepwork_policy.define` to ## Example Implementation -**Given this job.yml:** -```yaml -name: competitive_research -version: "1.0.0" -summary: "Systematic competitive analysis workflow" -description: | - A comprehensive workflow for analyzing competitors in your market segment. - Helps product teams understand the competitive landscape through systematic - identification, research, comparison, and positioning recommendations. - -steps: - - id: identify_competitors - name: "Identify Competitors" - description: "Identify 5-7 key competitors in the target market" - instructions_file: steps/identify_competitors.md - inputs: - - name: market_segment - description: "The market segment to analyze" - - name: product_category - description: "The product category" - outputs: - - competitors_list.md - dependencies: [] -``` - -**Generate this instruction file** (`.deepwork/jobs/competitive_research/steps/identify_competitors.md`): - -```markdown -# Identify Competitors - -## Objective - -Identify 5-7 key competitors in the target market segment to analyze for competitive positioning. - -## Task - -Research and identify the most relevant competitors in the specified market segment and product category. Focus on companies that directly compete for the same customer base and solve similar problems. - -### Process - -1. **Understand the market context** - - Review the market segment provided by the user - - Understand the product category boundaries - - Consider direct and indirect competitors - -2. **Research competitors** - - Search for companies in this space - - Look for market leaders and emerging players - - Consider different competitive dimensions (features, price, target market) - -3. **Select 5-7 key competitors** - - Prioritize direct competitors - - Include at least one market leader - - Include 1-2 emerging/innovative players - - Ensure diversity in the competitive set - -4. **Document each competitor** - - Company name - - Brief description (2-3 sentences) - - Why they're a relevant competitor - - Primary competitive dimension - -## Output Format - -### competitors_list.md - -A markdown document listing each competitor with context. - -**Structure**: -```markdown -# Competitor Analysis: [Market Segment] - -## Market Context -- **Segment**: [market segment] -- **Category**: [product category] -- **Analysis Date**: [current date] - -## Identified Competitors - -### 1. [Competitor Name] -**Description**: [2-3 sentence description of what they do] - -**Why Relevant**: [Why they're a key competitor in this space] - -**Competitive Dimension**: [What they compete on - e.g., price, features, market segment] - -[Repeat for each competitor, 5-7 total] - -## Selection Rationale - -[Brief paragraph explaining why these specific competitors were chosen and what dimensions of competition they represent] -``` - -## Quality Criteria - -- 5-7 competitors identified (not too few, not too many) -- Mix of established and emerging players -- All competitors are genuinely relevant to the market segment -- Each competitor has clear, specific description -- Selection rationale explains the competitive landscape -- Output is well-formatted and ready for use by next step - -## Context - -This is the foundation step for competitive analysis. The competitors identified here will be deeply researched in subsequent steps, so it's important to choose the right set. Focus on competitors that will provide strategic insights for positioning decisions. -``` +For a complete worked example showing a job.yml and corresponding step instruction file, see: +- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` +- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` ## Important Guidelines @@ -421,63 +281,6 @@ Before running `deepwork sync`, verify: - All step instruction files exist (one per step) - No file system errors -## Output Format - -### implementation_summary.md - -After successful implementation, create a summary: - -```markdown -# Job Implementation Complete: [job_name] - -## Overview - -Successfully implemented the **[job_name]** workflow with [N] steps. - -**Summary**: [job summary] - -**Version**: [version] - -## Files Created - -### Job Definition -- `.deepwork/jobs/[job_name]/job.yml` - -### Step Instructions -- `.deepwork/jobs/[job_name]/steps/[step1_id].md` -- `.deepwork/jobs/[job_name]/steps/[step2_id].md` -[... list all step files ...] - - -## Generated Commands - -After running `deepwork sync`, the following slash-commands are now available: - -- `/[job_name].[step1_id]` - [step description] -- `/[job_name].[step2_id]` - [step description] -[... list all commands ...] - -## Next Steps - -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 - -## Job Structure - -[Show the workflow diagram with step names and dependencies] - -Step 1: [step_name] - ↓ -Step 2: [step_name] - ↓ -Step 3: [step_name] - ↓ -[Final output] - -The job is now ready for use! -``` - ## Completion Checklist Before marking this step complete, ensure: @@ -487,7 +290,6 @@ Before marking this step complete, ensure: - [ ] `deepwork sync` executed successfully - [ ] Commands generated in platform directory - [ ] 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` @@ -530,7 +332,7 @@ All work for this job should be done on a dedicated work branch: ## Output Requirements Create the following output(s): -- `implementation_summary.md` +- `steps/` (directory) Ensure all outputs are: - Well-formatted and complete - Ready for review or use by subsequent steps @@ -549,8 +351,7 @@ Verify the implementation meets ALL quality criteria before completing: 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. **Summary Created**: Has `implementation_summary.md` been created? -9. **Policies Considered**: Have you thought about whether policies would benefit this job? +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. @@ -576,7 +377,7 @@ After completing this step: 2. **Inform the user**: - Step 2 of 3 is complete - - Outputs created: implementation_summary.md + - Outputs created: steps/ - Ready to proceed to next step: `/deepwork_jobs.learn` ## Next Step diff --git a/.claude/commands/deepwork_jobs.learn.md b/.claude/commands/deepwork_jobs.learn.md index 0a1f63b..b3cc251 100644 --- a/.claude/commands/deepwork_jobs.learn.md +++ b/.claude/commands/deepwork_jobs.learn.md @@ -205,42 +205,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 @@ -262,36 +227,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 @@ -322,7 +265,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 @@ -382,7 +324,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 @@ -434,7 +376,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 - Ready for review or use by subsequent steps @@ -479,7 +421,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/.deepwork/jobs/deepwork_jobs/AGENTS.md b/.deepwork/jobs/deepwork_jobs/AGENTS.md new file mode 100644 index 0000000..6d97d0e --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/AGENTS.md @@ -0,0 +1,60 @@ +# Project Context for deepwork_jobs + +This is the source of truth for the `deepwork_jobs` standard job. + +## Codebase Structure + +- Source location: `src/deepwork/standard_jobs/deepwork_jobs/` +- Working copy: `.deepwork/jobs/deepwork_jobs/` +- Templates: `templates/` directory within each location + +## Dual Location Maintenance + +**Important**: This job exists in two locations that must be kept in sync: + +1. **Source of truth**: `src/deepwork/standard_jobs/deepwork_jobs/` + - This is where changes should be made first + - Tracked in version control + +2. **Working copy**: `.deepwork/jobs/deepwork_jobs/` + - Must be updated after changes to source + - Used by `deepwork sync` to generate commands + +After making changes to the source, copy files to the working copy: +```bash +cp src/deepwork/standard_jobs/deepwork_jobs/job.yml .deepwork/jobs/deepwork_jobs/ +cp src/deepwork/standard_jobs/deepwork_jobs/steps/*.md .deepwork/jobs/deepwork_jobs/steps/ +cp -r src/deepwork/standard_jobs/deepwork_jobs/templates/* .deepwork/jobs/deepwork_jobs/templates/ +``` + +## File Organization + +``` +deepwork_jobs/ +├── AGENTS.md # This file +├── job.yml # Job definition +├── make_new_job.sh # Script to create new job structure +├── steps/ +│ ├── define.md # Define step instructions +│ ├── implement.md # Implement step instructions +│ ├── learn.md # Learn step instructions +│ └── supplemental_file_references.md # Reference documentation +└── templates/ + ├── job.yml.template # Job spec structure + ├── step_instruction.md.template # Step instruction structure + ├── agents.md.template # AGENTS.md structure + ├── job.yml.example # Complete job example + └── step_instruction.md.example # Complete step example +``` + +## Version Management + +- Version is tracked in `job.yml` +- Bump patch version (0.0.x) for instruction improvements +- Bump minor version (0.x.0) for new features or structural changes +- Always update changelog when bumping version + +## Last Updated + +- Date: 2026-01-15 +- From conversation about: Adding make_new_job.sh script and templates directory diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml index 4bb8656..ac861a5 100644 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ b/.deepwork/jobs/deepwork_jobs/job.yml @@ -1,5 +1,5 @@ name: deepwork_jobs -version: "0.2.0" +version: "0.4.0" summary: "DeepWork job management commands" description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step @@ -18,6 +18,10 @@ changelog: changes: "Initial version" - version: "0.2.0" changes: "Replaced refine command with learn command for conversation-driven improvement" + - version: "0.3.0" + 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" steps: - id: define @@ -54,7 +58,7 @@ steps: - file: job.yml from_step: define outputs: - - implementation_summary.md + - steps/ dependencies: - define hooks: @@ -69,8 +73,7 @@ steps: 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. **Summary Created**: Has `implementation_summary.md` been created? - 9. **Policies Considered**: Have you thought about whether policies would benefit this job? + 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. @@ -85,7 +88,7 @@ steps: - name: job_name description: "Name of the job that was run (optional - will auto-detect from conversation)" outputs: - - learning_summary.md + - AGENTS.md dependencies: [] hooks: after_agent: diff --git a/.deepwork/jobs/deepwork_jobs/make_new_job.sh b/.deepwork/jobs/deepwork_jobs/make_new_job.sh new file mode 100755 index 0000000..c561d6d --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/make_new_job.sh @@ -0,0 +1,134 @@ +#!/usr/bin/env bash +# +# make_new_job.sh - Create directory structure for a new DeepWork job +# +# Usage: ./make_new_job.sh +# + +set -euo pipefail + +# Color output helpers +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +info() { + echo -e "${GREEN}[INFO]${NC} $1" +} + +warn() { + echo -e "${YELLOW}[WARN]${NC} $1" +} + +error() { + echo -e "${RED}[ERROR]${NC} $1" + exit 1 +} + +# Validate job name format +validate_job_name() { + local name="$1" + if [[ ! "$name" =~ ^[a-z][a-z0-9_]*$ ]]; then + error "Invalid job name '$name'. Must be lowercase, start with a letter, and contain only letters, numbers, and underscores." + fi +} + +# Main script +main() { + if [[ $# -lt 1 ]]; then + echo "Usage: $0 " + echo "" + echo "Creates the directory structure for a new DeepWork job." + echo "" + echo "Arguments:" + echo " job_name Name of the job (lowercase, underscores allowed)" + echo "" + echo "Example:" + echo " $0 competitive_research" + exit 1 + fi + + local job_name="$1" + validate_job_name "$job_name" + + # Determine the base path - look for .deepwork directory + local base_path + if [[ -d ".deepwork/jobs" ]]; then + base_path=".deepwork/jobs" + elif [[ -d "../.deepwork/jobs" ]]; then + base_path="../.deepwork/jobs" + else + # Create from current directory + base_path=".deepwork/jobs" + mkdir -p "$base_path" + fi + + local job_path="${base_path}/${job_name}" + + # Check if job already exists + if [[ -d "$job_path" ]]; then + error "Job '$job_name' already exists at $job_path" + fi + + info "Creating job directory structure for '$job_name'..." + + # Create main job directory and subdirectories + mkdir -p "$job_path" + mkdir -p "$job_path/steps" + mkdir -p "$job_path/hooks" + mkdir -p "$job_path/templates" + + # Add .gitkeep files to empty directories + touch "$job_path/hooks/.gitkeep" + touch "$job_path/templates/.gitkeep" + + # Create AGENTS.md file + cat > "$job_path/AGENTS.md" << 'EOF' +# Job Management + +This folder and its subfolders are managed using the `deepwork_jobs` slash commands. + +## Recommended Commands + +- `/deepwork_jobs.define` - Create or modify the job.yml specification +- `/deepwork_jobs.implement` - Generate step instruction files from the specification +- `/deepwork_jobs.learn` - Improve instructions based on execution learnings + +## Directory Structure + +``` +. +├── AGENTS.md # This file - project context and guidance +├── job.yml # Job specification (created by /deepwork_jobs.define) +├── steps/ # Step instruction files (created by /deepwork_jobs.implement) +│ └── *.md # One file per step +├── hooks/ # Custom validation scripts and prompts +│ └── *.md|*.sh # Hook files referenced in job.yml +└── templates/ # Example file formats and templates + └── *.md|*.yml # Templates referenced in step instructions +``` + +## Editing Guidelines + +1. **Use slash commands** for structural changes (adding steps, modifying job.yml) +2. **Direct edits** are fine for minor instruction tweaks +3. **Run `/deepwork_jobs.learn`** after executing job steps to capture improvements +4. **Run `deepwork sync`** after any changes to regenerate commands +EOF + + info "Created directory structure:" + echo " $job_path/" + echo " ├── AGENTS.md" + echo " ├── steps/" + echo " ├── hooks/.gitkeep" + echo " └── templates/.gitkeep" + + echo "" + info "Next steps:" + echo " 1. Run '/deepwork_jobs.define' to create the job.yml specification" + echo " 2. Run '/deepwork_jobs.implement' to generate step instructions" + echo " 3. Run 'deepwork sync' to create slash commands" +} + +main "$@" diff --git a/.deepwork/jobs/deepwork_jobs/steps/define.md b/.deepwork/jobs/deepwork_jobs/steps/define.md index d961060..0a79561 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/define.md +++ b/.deepwork/jobs/deepwork_jobs/steps/define.md @@ -62,6 +62,12 @@ For each major phase they mentioned, ask detailed questions: **Note**: You're gathering this information to understand what instructions will be needed, but you won't create the instruction files yet - that happens in the `implement` step. +### Capability Considerations + +When defining steps, identify any that require specialized tools: + +**Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps. + ### Step 3: Validate the Workflow After gathering information about all steps: @@ -129,68 +135,31 @@ stop_hooks: **Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests). -### Step 5: Create the job.yml Specification +### Step 5: Create the Job Directory and Specification -Only after you have complete understanding, create the `job.yml` file: +Only after you have complete understanding, create the job directory and `job.yml` file: -**File Location**: `.deepwork/jobs/[job_name]/job.yml` +**First, create the directory structure** using the `make_new_job.sh` script: -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `.deepwork/jobs/competitive_research/job.yml`) - -**Format**: -```yaml -name: [job_name] -version: "1.0.0" -summary: "[Brief one-line summary of what this job accomplishes]" -description: | - [Detailed multi-line description of the job's purpose, process, and goals. - - This should explain: - - What problem this workflow solves - - What the overall process looks like - - What the end result will be - - Who the intended users are - - Any important context about the workflow] - -changelog: - - version: "1.0.0" - changes: "Initial job creation" - -steps: - - id: [step_id] - name: "[Step Name]" - description: "[What this step does]" - instructions_file: steps/[step_id].md - inputs: - - name: [param_name] - description: "[What user needs to provide]" - # OR for file inputs from previous steps: - # - file: [filename_or_path] - # from_step: [previous_step_id] - outputs: - - [output_filename_or_path] # e.g., "report.md" or "reports/analysis.md" - dependencies: [] # List of step IDs that must complete first - # Optional: Quality validation hooks - stop_hooks: - - prompt: | - Verify this step's output meets quality criteria: - 1. [Criterion 1] - 2. [Criterion 2] - If ALL criteria are met, include `✓ Quality Criteria Met`. - - - id: [another_step] - name: "[Another Step]" - description: "[What this step does]" - instructions_file: steps/[another_step].md - inputs: - - file: [output_filename_or_path] - from_step: [step_id] - outputs: - - [another_output_path] - dependencies: - - [step_id] # This step requires the previous step +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - For step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts +- `.deepwork/jobs/[job_name]/templates/` - For example file formats +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance + +**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` + +(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) + +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. + +**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. + **Important**: - Use lowercase with underscores for job name and step IDs - Ensure file inputs reference steps in dependencies diff --git a/.deepwork/jobs/deepwork_jobs/steps/implement.md b/.deepwork/jobs/deepwork_jobs/steps/implement.md index a6ac706..05967b6 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/implement.md +++ b/.deepwork/jobs/deepwork_jobs/steps/implement.md @@ -8,10 +8,31 @@ Generate the DeepWork job directory structure and instruction files for each ste Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available. -### Step 1: Read and Validate the Specification +### Step 1: Create Directory Structure Using Script + +Run the `make_new_job.sh` script to create the standard directory structure: + +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` + +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - Step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep) +- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep) +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance + +**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories: +```bash +mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates +touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep +``` + +### Step 2: Read and Validate the Specification 1. **Locate the job.yml file** - - Read `.deepwork/jobs/[job_name]/job.yml` from the define step (Where `[job_name]` is the name of the new job that was created in the define step) + - Read `.deepwork/jobs/[job_name]/job.yml` from the define step - Parse the YAML content 2. **Validate the specification** @@ -25,83 +46,20 @@ Read the `job.yml` specification file and create all the necessary files to make - List of all steps with their details - Understand the workflow structure -### Step 2: Create Directory Structure - -Create the job directory in `.deepwork/jobs/[job_name]/`: - -```bash -mkdir -p .deepwork/jobs/[job_name]/steps -``` - -Files to create: -- `.deepwork/jobs/[job_name]/job.yml` -- `.deepwork/jobs/[job_name]/steps/[step_id].md` - One for each step - ### Step 3: Generate Step Instruction Files For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`. -Each instruction file should follow this structure: - -```markdown -# [Step Name] - -## Objective - -[Clear statement of what this step accomplishes, derived from the step's description] - -## Task - -[Detailed instructions for completing this step, based on: -- The step's purpose -- Expected inputs and outputs -- The job's overall context -] - -### Process - -[Break down the step into substeps. Use the information gathered during define about: -- What needs to be done -- What makes a good output -- Any quality criteria -] +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. -1. [Substep 1] -2. [Substep 2] -3. [Substep 3] +**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. -[If this step has user inputs, explain how to gather them] -[If this step has file inputs, explain how to use them] - -## Output Format - -### [output_filename_1] - -[Description of what should be in this output file] - -**Structure**: -```[file format] -[Example or template of what the output should look like] -``` - -[Repeat for each output file] - -## Quality Criteria - -[List what makes this step's output high quality: -- Completeness checks -- Format requirements -- Content requirements -] - -- [Quality criterion 1] -- [Quality criterion 2] -- [Quality criterion 3] - -## Context - -[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture] -``` +**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** +- `job.yml.template` - Job specification structure +- `step_instruction.md.template` - Step instruction file structure +- `agents.md.template` - AGENTS.md file structure +- `job.yml.example` - Complete job specification example +- `step_instruction.md.example` - Complete step instruction example **Guidelines for generating instructions:** @@ -144,6 +102,12 @@ If a step in the job.yml has `stop_hooks` defined, the generated instruction fil This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing. +### Using Supplementary Reference Files + +Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. + +See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. + ### Step 4: Verify job.yml Location Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define step should have created it there. If for some reason it's not there, you may need to create or move it. @@ -227,112 +191,9 @@ Would you like me to create this policy? I can run `/deepwork_policy.define` to ## Example Implementation -**Given this job.yml:** -```yaml -name: competitive_research -version: "1.0.0" -summary: "Systematic competitive analysis workflow" -description: | - A comprehensive workflow for analyzing competitors in your market segment. - Helps product teams understand the competitive landscape through systematic - identification, research, comparison, and positioning recommendations. - -steps: - - id: identify_competitors - name: "Identify Competitors" - description: "Identify 5-7 key competitors in the target market" - instructions_file: steps/identify_competitors.md - inputs: - - name: market_segment - description: "The market segment to analyze" - - name: product_category - description: "The product category" - outputs: - - competitors_list.md - dependencies: [] -``` - -**Generate this instruction file** (`.deepwork/jobs/competitive_research/steps/identify_competitors.md`): - -```markdown -# Identify Competitors - -## Objective - -Identify 5-7 key competitors in the target market segment to analyze for competitive positioning. - -## Task - -Research and identify the most relevant competitors in the specified market segment and product category. Focus on companies that directly compete for the same customer base and solve similar problems. - -### Process - -1. **Understand the market context** - - Review the market segment provided by the user - - Understand the product category boundaries - - Consider direct and indirect competitors - -2. **Research competitors** - - Search for companies in this space - - Look for market leaders and emerging players - - Consider different competitive dimensions (features, price, target market) - -3. **Select 5-7 key competitors** - - Prioritize direct competitors - - Include at least one market leader - - Include 1-2 emerging/innovative players - - Ensure diversity in the competitive set - -4. **Document each competitor** - - Company name - - Brief description (2-3 sentences) - - Why they're a relevant competitor - - Primary competitive dimension - -## Output Format - -### competitors_list.md - -A markdown document listing each competitor with context. - -**Structure**: -```markdown -# Competitor Analysis: [Market Segment] - -## Market Context -- **Segment**: [market segment] -- **Category**: [product category] -- **Analysis Date**: [current date] - -## Identified Competitors - -### 1. [Competitor Name] -**Description**: [2-3 sentence description of what they do] - -**Why Relevant**: [Why they're a key competitor in this space] - -**Competitive Dimension**: [What they compete on - e.g., price, features, market segment] - -[Repeat for each competitor, 5-7 total] - -## Selection Rationale - -[Brief paragraph explaining why these specific competitors were chosen and what dimensions of competition they represent] -``` - -## Quality Criteria - -- 5-7 competitors identified (not too few, not too many) -- Mix of established and emerging players -- All competitors are genuinely relevant to the market segment -- Each competitor has clear, specific description -- Selection rationale explains the competitive landscape -- Output is well-formatted and ready for use by next step - -## Context - -This is the foundation step for competitive analysis. The competitors identified here will be deeply researched in subsequent steps, so it's important to choose the right set. Focus on competitors that will provide strategic insights for positioning decisions. -``` +For a complete worked example showing a job.yml and corresponding step instruction file, see: +- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` +- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` ## Important Guidelines @@ -351,63 +212,6 @@ Before running `deepwork sync`, verify: - All step instruction files exist (one per step) - No file system errors -## Output Format - -### implementation_summary.md - -After successful implementation, create a summary: - -```markdown -# Job Implementation Complete: [job_name] - -## Overview - -Successfully implemented the **[job_name]** workflow with [N] steps. - -**Summary**: [job summary] - -**Version**: [version] - -## Files Created - -### Job Definition -- `.deepwork/jobs/[job_name]/job.yml` - -### Step Instructions -- `.deepwork/jobs/[job_name]/steps/[step1_id].md` -- `.deepwork/jobs/[job_name]/steps/[step2_id].md` -[... list all step files ...] - - -## Generated Commands - -After running `deepwork sync`, the following slash-commands are now available: - -- `/[job_name].[step1_id]` - [step description] -- `/[job_name].[step2_id]` - [step description] -[... list all commands ...] - -## Next Steps - -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 - -## Job Structure - -[Show the workflow diagram with step names and dependencies] - -Step 1: [step_name] - ↓ -Step 2: [step_name] - ↓ -Step 3: [step_name] - ↓ -[Final output] - -The job is now ready for use! -``` - ## Completion Checklist Before marking this step complete, ensure: @@ -417,7 +221,6 @@ Before marking this step complete, ensure: - [ ] `deepwork sync` executed successfully - [ ] Commands generated in platform directory - [ ] 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 a1ed623..36bfd8c 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/learn.md +++ b/.deepwork/jobs/deepwork_jobs/steps/learn.md @@ -142,42 +142,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 @@ -199,36 +164,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 @@ -259,7 +202,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 @@ -319,7 +261,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 diff --git a/.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md b/.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md new file mode 100644 index 0000000..81b6494 --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md @@ -0,0 +1,40 @@ +# Supplementary Reference Files + +Step instructions can include additional `.md` files in the `steps/` directory. These supplementary files are useful for: + +- Providing detailed examples or templates that would clutter the main instruction file +- Sharing common reference material across multiple steps +- Including technical specifications, API documentation, or style guides + +## How to Use + +1. Place additional `.md` files in the `steps/` directory alongside the main step instruction files +2. Reference them in your step instructions using the **full path from the project root** + +## Example + +If you have a job called `my_job` and want to include an API specification template: + +1. Create the file at `.deepwork/jobs/my_job/steps/api_spec.md` +2. Reference it in your step instructions like this: + +```markdown +Use the template in `.deepwork/jobs/my_job/steps/api_spec.md` to structure your API endpoints. +``` + +## Path Format + +Always use the full relative path from the project root: + +``` +.deepwork/jobs/[job_name]/steps/[filename].md +``` + +For example: +- `.deepwork/jobs/competitive_research/steps/competitor_template.md` +- `.deepwork/jobs/api_design/steps/endpoint_schema.md` +- `.deepwork/jobs/onboarding/steps/checklist_template.md` + +## Benefits + +Using supplementary files keeps your main step instructions focused and readable while allowing you to provide detailed reference material when needed. The AI agent can read these files during execution to get additional context. diff --git a/.deepwork/jobs/deepwork_jobs/templates/agents.md.template b/.deepwork/jobs/deepwork_jobs/templates/agents.md.template new file mode 100644 index 0000000..c160921 --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/templates/agents.md.template @@ -0,0 +1,32 @@ +# 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] diff --git a/.deepwork/jobs/deepwork_jobs/templates/job.yml.example b/.deepwork/jobs/deepwork_jobs/templates/job.yml.example new file mode 100644 index 0000000..7cc6e3b --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/templates/job.yml.example @@ -0,0 +1,73 @@ +# Example: Competitive Research Job +# +# This is a complete example of a job.yml file for reference. + +name: competitive_research +version: "1.0.0" +summary: "Systematic competitive analysis workflow" +description: | + A comprehensive workflow for analyzing competitors in your market segment. + Helps product teams understand the competitive landscape through systematic + identification, research, comparison, and positioning recommendations. + +changelog: + - version: "1.0.0" + changes: "Initial job creation" + +steps: + - id: identify_competitors + name: "Identify Competitors" + description: "Identify 5-7 key competitors in the target market" + instructions_file: steps/identify_competitors.md + inputs: + - name: market_segment + description: "The market segment to analyze" + - name: product_category + description: "The product category" + outputs: + - competitors_list.md + dependencies: [] + + - id: research_competitors + name: "Research Competitors" + description: "Deep dive research on each identified competitor" + instructions_file: steps/research_competitors.md + inputs: + - file: competitors_list.md + from_step: identify_competitors + outputs: + - research_notes.md + dependencies: + - identify_competitors + hooks: + after_agent: + - prompt: | + Verify the research meets criteria: + 1. Each competitor has at least 3 data points + 2. Sources are cited + 3. Information is current (within last year) + If ALL criteria are met, include `✓ Quality Criteria Met`. + + - id: comparative_analysis + name: "Comparative Analysis" + description: "Create side-by-side comparison matrix" + instructions_file: steps/comparative_analysis.md + inputs: + - file: research_notes.md + from_step: research_competitors + outputs: + - comparison_matrix.md + dependencies: + - research_competitors + + - id: positioning_recommendations + name: "Positioning Recommendations" + description: "Strategic positioning recommendations based on analysis" + instructions_file: steps/positioning_recommendations.md + inputs: + - file: comparison_matrix.md + from_step: comparative_analysis + outputs: + - positioning_report.md + dependencies: + - comparative_analysis diff --git a/.deepwork/jobs/deepwork_jobs/templates/job.yml.template b/.deepwork/jobs/deepwork_jobs/templates/job.yml.template new file mode 100644 index 0000000..9aaf45d --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/templates/job.yml.template @@ -0,0 +1,56 @@ +# DeepWork Job Specification Template +# +# This template shows the structure of a job.yml file. +# Replace placeholders in [brackets] with actual values. + +name: [job_name] +version: "1.0.0" +summary: "[Brief one-line summary of what this job accomplishes - max 200 chars]" +description: | + [Detailed multi-line description of the job's purpose, process, and goals. + + This should explain: + - What problem this workflow solves + - What the overall process looks like + - What the end result will be + - Who the intended users are + - Any important context about the workflow] + +changelog: + - version: "1.0.0" + changes: "Initial job creation" + +steps: + - id: [step_id] + name: "[Step Name]" + description: "[What this step does]" + instructions_file: steps/[step_id].md + inputs: + - name: [param_name] + description: "[What user needs to provide]" + # OR for file inputs from previous steps: + # - file: [filename_or_path] + # from_step: [previous_step_id] + outputs: + - [output_filename_or_path] # e.g., "report.md" or "reports/analysis.md" + dependencies: [] # List of step IDs that must complete first + # Optional: Quality validation hooks + hooks: + after_agent: + - prompt: | + Verify this step's output meets quality criteria: + 1. [Criterion 1] + 2. [Criterion 2] + If ALL criteria are met, include `✓ Quality Criteria Met`. + + - id: [another_step] + name: "[Another Step]" + description: "[What this step does]" + instructions_file: steps/[another_step].md + inputs: + - file: [output_filename_or_path] + from_step: [step_id] + outputs: + - [another_output_path] + dependencies: + - [step_id] # This step requires the previous step diff --git a/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example b/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example new file mode 100644 index 0000000..4f53b78 --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example @@ -0,0 +1,82 @@ +# Example: Identify Competitors Step Instruction +# +# This is a complete example of a step instruction file for reference. + +# Identify Competitors + +## Objective + +Identify 5-7 key competitors in the target market segment to analyze for competitive positioning. + +## Task + +Research and identify the most relevant competitors in the specified market segment and product category. Focus on companies that directly compete for the same customer base and solve similar problems. + +### Process + +1. **Understand the market context** + - Review the market segment provided by the user + - Understand the product category boundaries + - Consider direct and indirect competitors + +2. **Research competitors** + - Search for companies in this space + - Look for market leaders and emerging players + - Consider different competitive dimensions (features, price, target market) + +3. **Select 5-7 key competitors** + - Prioritize direct competitors + - Include at least one market leader + - Include 1-2 emerging/innovative players + - Ensure diversity in the competitive set + +4. **Document each competitor** + - Company name + - Brief description (2-3 sentences) + - Why they're a relevant competitor + - Primary competitive dimension + +## Output Format + +### competitors_list.md + +A markdown document listing each competitor with context. + +**Structure**: +```markdown +# Competitor Analysis: [Market Segment] + +## Market Context +- **Segment**: [market segment] +- **Category**: [product category] +- **Analysis Date**: [current date] + +## Identified Competitors + +### 1. [Competitor Name] +**Description**: [2-3 sentence description of what they do] + +**Why Relevant**: [Why they're a key competitor in this space] + +**Competitive Dimension**: [What they compete on - e.g., price, features, market segment] + +[Repeat for each competitor, 5-7 total] + +## Selection Rationale + +[Brief paragraph explaining why these specific competitors were chosen and what dimensions of competition they represent] +``` + +## Quality Criteria + +- 5-7 competitors identified (not too few, not too many) +- Mix of established and emerging players +- All competitors are genuinely relevant to the market segment +- Each competitor has clear, specific description +- Selection rationale explains the competitive landscape +- Output is well-formatted and ready for use by next step +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This is the foundation step for competitive analysis. The competitors identified here will be deeply researched in subsequent steps, so it's important to choose the right set. Focus on competitors that will provide strategic insights for positioning decisions. diff --git a/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template b/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template new file mode 100644 index 0000000..ddd1921 --- /dev/null +++ b/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template @@ -0,0 +1,58 @@ +# [Step Name] + +## Objective + +[Clear statement of what this step accomplishes, derived from the step's description] + +## Task + +[Detailed instructions for completing this step, based on: +- The step's purpose +- Expected inputs and outputs +- The job's overall context +] + +### Process + +[Break down the step into substeps. Use the information gathered during define about: +- What needs to be done +- What makes a good output +- Any quality criteria +] + +1. [Substep 1] +2. [Substep 2] +3. [Substep 3] + +[If this step has user inputs, explain how to gather them] +[If this step has file inputs, explain how to use them] + +## Output Format + +### [output_filename_1] + +[Description of what should be in this output file] + +**Structure**: +```[file format] +[Example or template of what the output should look like] +``` + +[Repeat for each output file] + +## Quality Criteria + +[List what makes this step's output high quality: +- Completeness checks +- Format requirements +- Content requirements +] + +- [Quality criterion 1] +- [Quality criterion 2] +- [Quality criterion 3] +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture] diff --git a/.gemini/commands/deepwork_jobs/define.toml b/.gemini/commands/deepwork_jobs/define.toml index 563b8c6..3a02872 100644 --- a/.gemini/commands/deepwork_jobs/define.toml +++ b/.gemini/commands/deepwork_jobs/define.toml @@ -94,6 +94,12 @@ For each major phase they mentioned, ask detailed questions: **Note**: You're gathering this information to understand what instructions will be needed, but you won't create the instruction files yet - that happens in the `implement` step. +### Capability Considerations + +When defining steps, identify any that require specialized tools: + +**Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps. + ### Step 3: Validate the Workflow After gathering information about all steps: @@ -161,68 +167,31 @@ stop_hooks: **Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests). -### Step 5: Create the job.yml Specification +### Step 5: Create the Job Directory and Specification -Only after you have complete understanding, create the `job.yml` file: +Only after you have complete understanding, create the job directory and `job.yml` file: -**File Location**: `.deepwork/jobs/[job_name]/job.yml` +**First, create the directory structure** using the `make_new_job.sh` script: -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `.deepwork/jobs/competitive_research/job.yml`) - -**Format**: -```yaml -name: [job_name] -version: "1.0.0" -summary: "[Brief one-line summary of what this job accomplishes]" -description: | - [Detailed multi-line description of the job's purpose, process, and goals. - - This should explain: - - What problem this workflow solves - - What the overall process looks like - - What the end result will be - - Who the intended users are - - Any important context about the workflow] - -changelog: - - version: "1.0.0" - changes: "Initial job creation" - -steps: - - id: [step_id] - name: "[Step Name]" - description: "[What this step does]" - instructions_file: steps/[step_id].md - inputs: - - name: [param_name] - description: "[What user needs to provide]" - # OR for file inputs from previous steps: - # - file: [filename_or_path] - # from_step: [previous_step_id] - outputs: - - [output_filename_or_path] # e.g., "report.md" or "reports/analysis.md" - dependencies: [] # List of step IDs that must complete first - # Optional: Quality validation hooks - stop_hooks: - - prompt: | - Verify this step's output meets quality criteria: - 1. [Criterion 1] - 2. [Criterion 2] - If ALL criteria are met, include `✓ Quality Criteria Met`. - - - id: [another_step] - name: "[Another Step]" - description: "[What this step does]" - instructions_file: steps/[another_step].md - inputs: - - file: [output_filename_or_path] - from_step: [step_id] - outputs: - - [another_output_path] - dependencies: - - [step_id] # This step requires the previous step +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - For step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts +- `.deepwork/jobs/[job_name]/templates/` - For example file formats +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance + +**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` + +(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) + +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. + +**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. + **Important**: - Use lowercase with underscores for job name and step IDs - Ensure file inputs reference steps in dependencies diff --git a/.gemini/commands/deepwork_jobs/implement.toml b/.gemini/commands/deepwork_jobs/implement.toml index baa584d..51422fc 100644 --- a/.gemini/commands/deepwork_jobs/implement.toml +++ b/.gemini/commands/deepwork_jobs/implement.toml @@ -46,10 +46,31 @@ Generate the DeepWork job directory structure and instruction files for each ste Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available. -### Step 1: Read and Validate the Specification +### Step 1: Create Directory Structure Using Script + +Run the `make_new_job.sh` script to create the standard directory structure: + +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` + +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - Step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep) +- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep) +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance + +**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories: +```bash +mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates +touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep +``` + +### Step 2: Read and Validate the Specification 1. **Locate the job.yml file** - - Read `.deepwork/jobs/[job_name]/job.yml` from the define step (Where `[job_name]` is the name of the new job that was created in the define step) + - Read `.deepwork/jobs/[job_name]/job.yml` from the define step - Parse the YAML content 2. **Validate the specification** @@ -63,83 +84,20 @@ Read the `job.yml` specification file and create all the necessary files to make - List of all steps with their details - Understand the workflow structure -### Step 2: Create Directory Structure - -Create the job directory in `.deepwork/jobs/[job_name]/`: - -```bash -mkdir -p .deepwork/jobs/[job_name]/steps -``` - -Files to create: -- `.deepwork/jobs/[job_name]/job.yml` -- `.deepwork/jobs/[job_name]/steps/[step_id].md` - One for each step - ### Step 3: Generate Step Instruction Files For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`. -Each instruction file should follow this structure: - -```markdown -# [Step Name] - -## Objective - -[Clear statement of what this step accomplishes, derived from the step's description] - -## Task - -[Detailed instructions for completing this step, based on: -- The step's purpose -- Expected inputs and outputs -- The job's overall context -] - -### Process - -[Break down the step into substeps. Use the information gathered during define about: -- What needs to be done -- What makes a good output -- Any quality criteria -] +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. -1. [Substep 1] -2. [Substep 2] -3. [Substep 3] +**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. -[If this step has user inputs, explain how to gather them] -[If this step has file inputs, explain how to use them] - -## Output Format - -### [output_filename_1] - -[Description of what should be in this output file] - -**Structure**: -```[file format] -[Example or template of what the output should look like] -``` - -[Repeat for each output file] - -## Quality Criteria - -[List what makes this step's output high quality: -- Completeness checks -- Format requirements -- Content requirements -] - -- [Quality criterion 1] -- [Quality criterion 2] -- [Quality criterion 3] - -## Context - -[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture] -``` +**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** +- `job.yml.template` - Job specification structure +- `step_instruction.md.template` - Step instruction file structure +- `agents.md.template` - AGENTS.md file structure +- `job.yml.example` - Complete job specification example +- `step_instruction.md.example` - Complete step instruction example **Guidelines for generating instructions:** @@ -182,6 +140,12 @@ If a step in the job.yml has `stop_hooks` defined, the generated instruction fil This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing. +### Using Supplementary Reference Files + +Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. + +See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. + ### Step 4: Verify job.yml Location Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define step should have created it there. If for some reason it's not there, you may need to create or move it. @@ -265,112 +229,9 @@ Would you like me to create this policy? I can run `/deepwork_policy.define` to ## Example Implementation -**Given this job.yml:** -```yaml -name: competitive_research -version: "1.0.0" -summary: "Systematic competitive analysis workflow" -description: | - A comprehensive workflow for analyzing competitors in your market segment. - Helps product teams understand the competitive landscape through systematic - identification, research, comparison, and positioning recommendations. - -steps: - - id: identify_competitors - name: "Identify Competitors" - description: "Identify 5-7 key competitors in the target market" - instructions_file: steps/identify_competitors.md - inputs: - - name: market_segment - description: "The market segment to analyze" - - name: product_category - description: "The product category" - outputs: - - competitors_list.md - dependencies: [] -``` - -**Generate this instruction file** (`.deepwork/jobs/competitive_research/steps/identify_competitors.md`): - -```markdown -# Identify Competitors - -## Objective - -Identify 5-7 key competitors in the target market segment to analyze for competitive positioning. - -## Task - -Research and identify the most relevant competitors in the specified market segment and product category. Focus on companies that directly compete for the same customer base and solve similar problems. - -### Process - -1. **Understand the market context** - - Review the market segment provided by the user - - Understand the product category boundaries - - Consider direct and indirect competitors - -2. **Research competitors** - - Search for companies in this space - - Look for market leaders and emerging players - - Consider different competitive dimensions (features, price, target market) - -3. **Select 5-7 key competitors** - - Prioritize direct competitors - - Include at least one market leader - - Include 1-2 emerging/innovative players - - Ensure diversity in the competitive set - -4. **Document each competitor** - - Company name - - Brief description (2-3 sentences) - - Why they're a relevant competitor - - Primary competitive dimension - -## Output Format - -### competitors_list.md - -A markdown document listing each competitor with context. - -**Structure**: -```markdown -# Competitor Analysis: [Market Segment] - -## Market Context -- **Segment**: [market segment] -- **Category**: [product category] -- **Analysis Date**: [current date] - -## Identified Competitors - -### 1. [Competitor Name] -**Description**: [2-3 sentence description of what they do] - -**Why Relevant**: [Why they're a key competitor in this space] - -**Competitive Dimension**: [What they compete on - e.g., price, features, market segment] - -[Repeat for each competitor, 5-7 total] - -## Selection Rationale - -[Brief paragraph explaining why these specific competitors were chosen and what dimensions of competition they represent] -``` - -## Quality Criteria - -- 5-7 competitors identified (not too few, not too many) -- Mix of established and emerging players -- All competitors are genuinely relevant to the market segment -- Each competitor has clear, specific description -- Selection rationale explains the competitive landscape -- Output is well-formatted and ready for use by next step - -## Context - -This is the foundation step for competitive analysis. The competitors identified here will be deeply researched in subsequent steps, so it's important to choose the right set. Focus on competitors that will provide strategic insights for positioning decisions. -``` +For a complete worked example showing a job.yml and corresponding step instruction file, see: +- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` +- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` ## Important Guidelines @@ -389,63 +250,6 @@ Before running `deepwork sync`, verify: - All step instruction files exist (one per step) - No file system errors -## Output Format - -### implementation_summary.md - -After successful implementation, create a summary: - -```markdown -# Job Implementation Complete: [job_name] - -## Overview - -Successfully implemented the **[job_name]** workflow with [N] steps. - -**Summary**: [job summary] - -**Version**: [version] - -## Files Created - -### Job Definition -- `.deepwork/jobs/[job_name]/job.yml` - -### Step Instructions -- `.deepwork/jobs/[job_name]/steps/[step1_id].md` -- `.deepwork/jobs/[job_name]/steps/[step2_id].md` -[... list all step files ...] - - -## Generated Commands - -After running `deepwork sync`, the following slash-commands are now available: - -- `/[job_name].[step1_id]` - [step description] -- `/[job_name].[step2_id]` - [step description] -[... list all commands ...] - -## Next Steps - -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 - -## Job Structure - -[Show the workflow diagram with step names and dependencies] - -Step 1: [step_name] - ↓ -Step 2: [step_name] - ↓ -Step 3: [step_name] - ↓ -[Final output] - -The job is now ready for use! -``` - ## Completion Checklist Before marking this step complete, ensure: @@ -455,7 +259,6 @@ Before marking this step complete, ensure: - [ ] `deepwork sync` executed successfully - [ ] Commands generated in platform directory - [ ] 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` @@ -498,7 +301,7 @@ All work for this job should be done on a dedicated work branch: ## Output Requirements Create the following output(s): -- `implementation_summary.md` +- `steps/` (directory) Ensure all outputs are: - Well-formatted and complete @@ -512,7 +315,7 @@ After completing this step: 2. **Inform the user**: - Step 2 of 3 is complete - - Outputs created: implementation_summary.md + - Outputs created: steps/ - Ready to proceed to next step: `/deepwork_jobs:learn` ## Next Step diff --git a/.gemini/commands/deepwork_jobs/learn.toml b/.gemini/commands/deepwork_jobs/learn.toml index 394c4cd..5330428 100644 --- a/.gemini/commands/deepwork_jobs/learn.toml +++ b/.gemini/commands/deepwork_jobs/learn.toml @@ -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, run '/memory refresh' or restart your session. +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/src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md b/src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md new file mode 100644 index 0000000..6d97d0e --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md @@ -0,0 +1,60 @@ +# Project Context for deepwork_jobs + +This is the source of truth for the `deepwork_jobs` standard job. + +## Codebase Structure + +- Source location: `src/deepwork/standard_jobs/deepwork_jobs/` +- Working copy: `.deepwork/jobs/deepwork_jobs/` +- Templates: `templates/` directory within each location + +## Dual Location Maintenance + +**Important**: This job exists in two locations that must be kept in sync: + +1. **Source of truth**: `src/deepwork/standard_jobs/deepwork_jobs/` + - This is where changes should be made first + - Tracked in version control + +2. **Working copy**: `.deepwork/jobs/deepwork_jobs/` + - Must be updated after changes to source + - Used by `deepwork sync` to generate commands + +After making changes to the source, copy files to the working copy: +```bash +cp src/deepwork/standard_jobs/deepwork_jobs/job.yml .deepwork/jobs/deepwork_jobs/ +cp src/deepwork/standard_jobs/deepwork_jobs/steps/*.md .deepwork/jobs/deepwork_jobs/steps/ +cp -r src/deepwork/standard_jobs/deepwork_jobs/templates/* .deepwork/jobs/deepwork_jobs/templates/ +``` + +## File Organization + +``` +deepwork_jobs/ +├── AGENTS.md # This file +├── job.yml # Job definition +├── make_new_job.sh # Script to create new job structure +├── steps/ +│ ├── define.md # Define step instructions +│ ├── implement.md # Implement step instructions +│ ├── learn.md # Learn step instructions +│ └── supplemental_file_references.md # Reference documentation +└── templates/ + ├── job.yml.template # Job spec structure + ├── step_instruction.md.template # Step instruction structure + ├── agents.md.template # AGENTS.md structure + ├── job.yml.example # Complete job example + └── step_instruction.md.example # Complete step example +``` + +## Version Management + +- Version is tracked in `job.yml` +- Bump patch version (0.0.x) for instruction improvements +- Bump minor version (0.x.0) for new features or structural changes +- Always update changelog when bumping version + +## Last Updated + +- Date: 2026-01-15 +- From conversation about: Adding make_new_job.sh script and templates directory diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 4bb8656..ac861a5 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -1,5 +1,5 @@ name: deepwork_jobs -version: "0.2.0" +version: "0.4.0" summary: "DeepWork job management commands" description: | Core commands for managing DeepWork jobs. These commands help you define new multi-step @@ -18,6 +18,10 @@ changelog: changes: "Initial version" - version: "0.2.0" changes: "Replaced refine command with learn command for conversation-driven improvement" + - version: "0.3.0" + 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" steps: - id: define @@ -54,7 +58,7 @@ steps: - file: job.yml from_step: define outputs: - - implementation_summary.md + - steps/ dependencies: - define hooks: @@ -69,8 +73,7 @@ steps: 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. **Summary Created**: Has `implementation_summary.md` been created? - 9. **Policies Considered**: Have you thought about whether policies would benefit this job? + 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. @@ -85,7 +88,7 @@ steps: - name: job_name description: "Name of the job that was run (optional - will auto-detect from conversation)" outputs: - - learning_summary.md + - AGENTS.md dependencies: [] hooks: after_agent: diff --git a/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh b/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh new file mode 100755 index 0000000..c561d6d --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh @@ -0,0 +1,134 @@ +#!/usr/bin/env bash +# +# make_new_job.sh - Create directory structure for a new DeepWork job +# +# Usage: ./make_new_job.sh +# + +set -euo pipefail + +# Color output helpers +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +info() { + echo -e "${GREEN}[INFO]${NC} $1" +} + +warn() { + echo -e "${YELLOW}[WARN]${NC} $1" +} + +error() { + echo -e "${RED}[ERROR]${NC} $1" + exit 1 +} + +# Validate job name format +validate_job_name() { + local name="$1" + if [[ ! "$name" =~ ^[a-z][a-z0-9_]*$ ]]; then + error "Invalid job name '$name'. Must be lowercase, start with a letter, and contain only letters, numbers, and underscores." + fi +} + +# Main script +main() { + if [[ $# -lt 1 ]]; then + echo "Usage: $0 " + echo "" + echo "Creates the directory structure for a new DeepWork job." + echo "" + echo "Arguments:" + echo " job_name Name of the job (lowercase, underscores allowed)" + echo "" + echo "Example:" + echo " $0 competitive_research" + exit 1 + fi + + local job_name="$1" + validate_job_name "$job_name" + + # Determine the base path - look for .deepwork directory + local base_path + if [[ -d ".deepwork/jobs" ]]; then + base_path=".deepwork/jobs" + elif [[ -d "../.deepwork/jobs" ]]; then + base_path="../.deepwork/jobs" + else + # Create from current directory + base_path=".deepwork/jobs" + mkdir -p "$base_path" + fi + + local job_path="${base_path}/${job_name}" + + # Check if job already exists + if [[ -d "$job_path" ]]; then + error "Job '$job_name' already exists at $job_path" + fi + + info "Creating job directory structure for '$job_name'..." + + # Create main job directory and subdirectories + mkdir -p "$job_path" + mkdir -p "$job_path/steps" + mkdir -p "$job_path/hooks" + mkdir -p "$job_path/templates" + + # Add .gitkeep files to empty directories + touch "$job_path/hooks/.gitkeep" + touch "$job_path/templates/.gitkeep" + + # Create AGENTS.md file + cat > "$job_path/AGENTS.md" << 'EOF' +# Job Management + +This folder and its subfolders are managed using the `deepwork_jobs` slash commands. + +## Recommended Commands + +- `/deepwork_jobs.define` - Create or modify the job.yml specification +- `/deepwork_jobs.implement` - Generate step instruction files from the specification +- `/deepwork_jobs.learn` - Improve instructions based on execution learnings + +## Directory Structure + +``` +. +├── AGENTS.md # This file - project context and guidance +├── job.yml # Job specification (created by /deepwork_jobs.define) +├── steps/ # Step instruction files (created by /deepwork_jobs.implement) +│ └── *.md # One file per step +├── hooks/ # Custom validation scripts and prompts +│ └── *.md|*.sh # Hook files referenced in job.yml +└── templates/ # Example file formats and templates + └── *.md|*.yml # Templates referenced in step instructions +``` + +## Editing Guidelines + +1. **Use slash commands** for structural changes (adding steps, modifying job.yml) +2. **Direct edits** are fine for minor instruction tweaks +3. **Run `/deepwork_jobs.learn`** after executing job steps to capture improvements +4. **Run `deepwork sync`** after any changes to regenerate commands +EOF + + info "Created directory structure:" + echo " $job_path/" + echo " ├── AGENTS.md" + echo " ├── steps/" + echo " ├── hooks/.gitkeep" + echo " └── templates/.gitkeep" + + echo "" + info "Next steps:" + echo " 1. Run '/deepwork_jobs.define' to create the job.yml specification" + echo " 2. Run '/deepwork_jobs.implement' to generate step instructions" + echo " 3. Run 'deepwork sync' to create slash commands" +} + +main "$@" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md index d76ca55..0a79561 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md @@ -135,68 +135,31 @@ stop_hooks: **Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests). -### Step 5: Create the job.yml Specification +### Step 5: Create the Job Directory and Specification -Only after you have complete understanding, create the `job.yml` file: +Only after you have complete understanding, create the job directory and `job.yml` file: -**File Location**: `.deepwork/jobs/[job_name]/job.yml` +**First, create the directory structure** using the `make_new_job.sh` script: -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `.deepwork/jobs/competitive_research/job.yml`) - -**Format**: -```yaml -name: [job_name] -version: "1.0.0" -summary: "[Brief one-line summary of what this job accomplishes]" -description: | - [Detailed multi-line description of the job's purpose, process, and goals. - - This should explain: - - What problem this workflow solves - - What the overall process looks like - - What the end result will be - - Who the intended users are - - Any important context about the workflow] - -changelog: - - version: "1.0.0" - changes: "Initial job creation" - -steps: - - id: [step_id] - name: "[Step Name]" - description: "[What this step does]" - instructions_file: steps/[step_id].md - inputs: - - name: [param_name] - description: "[What user needs to provide]" - # OR for file inputs from previous steps: - # - file: [filename_or_path] - # from_step: [previous_step_id] - outputs: - - [output_filename_or_path] # e.g., "report.md" or "reports/analysis.md" - dependencies: [] # List of step IDs that must complete first - # Optional: Quality validation hooks - stop_hooks: - - prompt: | - Verify this step's output meets quality criteria: - 1. [Criterion 1] - 2. [Criterion 2] - If ALL criteria are met, include `✓ Quality Criteria Met`. - - - id: [another_step] - name: "[Another Step]" - description: "[What this step does]" - instructions_file: steps/[another_step].md - inputs: - - file: [output_filename_or_path] - from_step: [step_id] - outputs: - - [another_output_path] - dependencies: - - [step_id] # This step requires the previous step +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] ``` +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - For step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts +- `.deepwork/jobs/[job_name]/templates/` - For example file formats +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance + +**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` + +(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) + +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. + +**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. + **Important**: - Use lowercase with underscores for job name and step IDs - Ensure file inputs reference steps in dependencies diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md index 60a6882..05967b6 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md @@ -8,10 +8,31 @@ Generate the DeepWork job directory structure and instruction files for each ste Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available. -### Step 1: Read and Validate the Specification +### Step 1: Create Directory Structure Using Script + +Run the `make_new_job.sh` script to create the standard directory structure: + +```bash +.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +``` + +This creates: +- `.deepwork/jobs/[job_name]/` - Main job directory +- `.deepwork/jobs/[job_name]/steps/` - Step instruction files +- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep) +- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep) +- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance + +**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories: +```bash +mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates +touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep +``` + +### Step 2: Read and Validate the Specification 1. **Locate the job.yml file** - - Read `.deepwork/jobs/[job_name]/job.yml` from the define step (Where `[job_name]` is the name of the new job that was created in the define step) + - Read `.deepwork/jobs/[job_name]/job.yml` from the define step - Parse the YAML content 2. **Validate the specification** @@ -25,83 +46,20 @@ Read the `job.yml` specification file and create all the necessary files to make - List of all steps with their details - Understand the workflow structure -### Step 2: Create Directory Structure - -Create the job directory in `.deepwork/jobs/[job_name]/`: - -```bash -mkdir -p .deepwork/jobs/[job_name]/steps -``` - -Files to create: -- `.deepwork/jobs/[job_name]/job.yml` -- `.deepwork/jobs/[job_name]/steps/[step_id].md` - One for each step - ### Step 3: Generate Step Instruction Files For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`. -Each instruction file should follow this structure: - -```markdown -# [Step Name] - -## Objective - -[Clear statement of what this step accomplishes, derived from the step's description] - -## Task - -[Detailed instructions for completing this step, based on: -- The step's purpose -- Expected inputs and outputs -- The job's overall context -] - -### Process - -[Break down the step into substeps. Use the information gathered during define about: -- What needs to be done -- What makes a good output -- Any quality criteria -] +**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. -1. [Substep 1] -2. [Substep 2] -3. [Substep 3] +**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. -[If this step has user inputs, explain how to gather them] -[If this step has file inputs, explain how to use them] - -## Output Format - -### [output_filename_1] - -[Description of what should be in this output file] - -**Structure**: -```[file format] -[Example or template of what the output should look like] -``` - -[Repeat for each output file] - -## Quality Criteria - -[List what makes this step's output high quality: -- Completeness checks -- Format requirements -- Content requirements -] - -- [Quality criterion 1] -- [Quality criterion 2] -- [Quality criterion 3] - -## Context - -[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture] -``` +**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** +- `job.yml.template` - Job specification structure +- `step_instruction.md.template` - Step instruction file structure +- `agents.md.template` - AGENTS.md file structure +- `job.yml.example` - Complete job specification example +- `step_instruction.md.example` - Complete step instruction example **Guidelines for generating instructions:** @@ -233,112 +191,9 @@ Would you like me to create this policy? I can run `/deepwork_policy.define` to ## Example Implementation -**Given this job.yml:** -```yaml -name: competitive_research -version: "1.0.0" -summary: "Systematic competitive analysis workflow" -description: | - A comprehensive workflow for analyzing competitors in your market segment. - Helps product teams understand the competitive landscape through systematic - identification, research, comparison, and positioning recommendations. - -steps: - - id: identify_competitors - name: "Identify Competitors" - description: "Identify 5-7 key competitors in the target market" - instructions_file: steps/identify_competitors.md - inputs: - - name: market_segment - description: "The market segment to analyze" - - name: product_category - description: "The product category" - outputs: - - competitors_list.md - dependencies: [] -``` - -**Generate this instruction file** (`.deepwork/jobs/competitive_research/steps/identify_competitors.md`): - -```markdown -# Identify Competitors - -## Objective - -Identify 5-7 key competitors in the target market segment to analyze for competitive positioning. - -## Task - -Research and identify the most relevant competitors in the specified market segment and product category. Focus on companies that directly compete for the same customer base and solve similar problems. - -### Process - -1. **Understand the market context** - - Review the market segment provided by the user - - Understand the product category boundaries - - Consider direct and indirect competitors - -2. **Research competitors** - - Search for companies in this space - - Look for market leaders and emerging players - - Consider different competitive dimensions (features, price, target market) - -3. **Select 5-7 key competitors** - - Prioritize direct competitors - - Include at least one market leader - - Include 1-2 emerging/innovative players - - Ensure diversity in the competitive set - -4. **Document each competitor** - - Company name - - Brief description (2-3 sentences) - - Why they're a relevant competitor - - Primary competitive dimension - -## Output Format - -### competitors_list.md - -A markdown document listing each competitor with context. - -**Structure**: -```markdown -# Competitor Analysis: [Market Segment] - -## Market Context -- **Segment**: [market segment] -- **Category**: [product category] -- **Analysis Date**: [current date] - -## Identified Competitors - -### 1. [Competitor Name] -**Description**: [2-3 sentence description of what they do] - -**Why Relevant**: [Why they're a key competitor in this space] - -**Competitive Dimension**: [What they compete on - e.g., price, features, market segment] - -[Repeat for each competitor, 5-7 total] - -## Selection Rationale - -[Brief paragraph explaining why these specific competitors were chosen and what dimensions of competition they represent] -``` - -## Quality Criteria - -- 5-7 competitors identified (not too few, not too many) -- Mix of established and emerging players -- All competitors are genuinely relevant to the market segment -- Each competitor has clear, specific description -- Selection rationale explains the competitive landscape -- Output is well-formatted and ready for use by next step - -## Context - -This is the foundation step for competitive analysis. The competitors identified here will be deeply researched in subsequent steps, so it's important to choose the right set. Focus on competitors that will provide strategic insights for positioning decisions. -``` +For a complete worked example showing a job.yml and corresponding step instruction file, see: +- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` +- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` ## Important Guidelines @@ -357,63 +212,6 @@ Before running `deepwork sync`, verify: - All step instruction files exist (one per step) - No file system errors -## Output Format - -### implementation_summary.md - -After successful implementation, create a summary: - -```markdown -# Job Implementation Complete: [job_name] - -## Overview - -Successfully implemented the **[job_name]** workflow with [N] steps. - -**Summary**: [job summary] - -**Version**: [version] - -## Files Created - -### Job Definition -- `.deepwork/jobs/[job_name]/job.yml` - -### Step Instructions -- `.deepwork/jobs/[job_name]/steps/[step1_id].md` -- `.deepwork/jobs/[job_name]/steps/[step2_id].md` -[... list all step files ...] - - -## Generated Commands - -After running `deepwork sync`, the following slash-commands are now available: - -- `/[job_name].[step1_id]` - [step description] -- `/[job_name].[step2_id]` - [step description] -[... list all commands ...] - -## Next Steps - -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 - -## Job Structure - -[Show the workflow diagram with step names and dependencies] - -Step 1: [step_name] - ↓ -Step 2: [step_name] - ↓ -Step 3: [step_name] - ↓ -[Final output] - -The job is now ready for use! -``` - ## Completion Checklist Before marking this step complete, ensure: @@ -423,7 +221,6 @@ Before marking this step complete, ensure: - [ ] `deepwork sync` executed successfully - [ ] Commands generated in platform directory - [ ] 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 a1ed623..36bfd8c 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md @@ -142,42 +142,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 @@ -199,36 +164,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 @@ -259,7 +202,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 @@ -319,7 +261,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 diff --git a/src/deepwork/standard_jobs/deepwork_jobs/templates/agents.md.template b/src/deepwork/standard_jobs/deepwork_jobs/templates/agents.md.template new file mode 100644 index 0000000..c160921 --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/templates/agents.md.template @@ -0,0 +1,32 @@ +# 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] diff --git a/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.example b/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.example new file mode 100644 index 0000000..7cc6e3b --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.example @@ -0,0 +1,73 @@ +# Example: Competitive Research Job +# +# This is a complete example of a job.yml file for reference. + +name: competitive_research +version: "1.0.0" +summary: "Systematic competitive analysis workflow" +description: | + A comprehensive workflow for analyzing competitors in your market segment. + Helps product teams understand the competitive landscape through systematic + identification, research, comparison, and positioning recommendations. + +changelog: + - version: "1.0.0" + changes: "Initial job creation" + +steps: + - id: identify_competitors + name: "Identify Competitors" + description: "Identify 5-7 key competitors in the target market" + instructions_file: steps/identify_competitors.md + inputs: + - name: market_segment + description: "The market segment to analyze" + - name: product_category + description: "The product category" + outputs: + - competitors_list.md + dependencies: [] + + - id: research_competitors + name: "Research Competitors" + description: "Deep dive research on each identified competitor" + instructions_file: steps/research_competitors.md + inputs: + - file: competitors_list.md + from_step: identify_competitors + outputs: + - research_notes.md + dependencies: + - identify_competitors + hooks: + after_agent: + - prompt: | + Verify the research meets criteria: + 1. Each competitor has at least 3 data points + 2. Sources are cited + 3. Information is current (within last year) + If ALL criteria are met, include `✓ Quality Criteria Met`. + + - id: comparative_analysis + name: "Comparative Analysis" + description: "Create side-by-side comparison matrix" + instructions_file: steps/comparative_analysis.md + inputs: + - file: research_notes.md + from_step: research_competitors + outputs: + - comparison_matrix.md + dependencies: + - research_competitors + + - id: positioning_recommendations + name: "Positioning Recommendations" + description: "Strategic positioning recommendations based on analysis" + instructions_file: steps/positioning_recommendations.md + inputs: + - file: comparison_matrix.md + from_step: comparative_analysis + outputs: + - positioning_report.md + dependencies: + - comparative_analysis diff --git a/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.template b/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.template new file mode 100644 index 0000000..9aaf45d --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.template @@ -0,0 +1,56 @@ +# DeepWork Job Specification Template +# +# This template shows the structure of a job.yml file. +# Replace placeholders in [brackets] with actual values. + +name: [job_name] +version: "1.0.0" +summary: "[Brief one-line summary of what this job accomplishes - max 200 chars]" +description: | + [Detailed multi-line description of the job's purpose, process, and goals. + + This should explain: + - What problem this workflow solves + - What the overall process looks like + - What the end result will be + - Who the intended users are + - Any important context about the workflow] + +changelog: + - version: "1.0.0" + changes: "Initial job creation" + +steps: + - id: [step_id] + name: "[Step Name]" + description: "[What this step does]" + instructions_file: steps/[step_id].md + inputs: + - name: [param_name] + description: "[What user needs to provide]" + # OR for file inputs from previous steps: + # - file: [filename_or_path] + # from_step: [previous_step_id] + outputs: + - [output_filename_or_path] # e.g., "report.md" or "reports/analysis.md" + dependencies: [] # List of step IDs that must complete first + # Optional: Quality validation hooks + hooks: + after_agent: + - prompt: | + Verify this step's output meets quality criteria: + 1. [Criterion 1] + 2. [Criterion 2] + If ALL criteria are met, include `✓ Quality Criteria Met`. + + - id: [another_step] + name: "[Another Step]" + description: "[What this step does]" + instructions_file: steps/[another_step].md + inputs: + - file: [output_filename_or_path] + from_step: [step_id] + outputs: + - [another_output_path] + dependencies: + - [step_id] # This step requires the previous step diff --git a/src/deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.example b/src/deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.example new file mode 100644 index 0000000..4f53b78 --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.example @@ -0,0 +1,82 @@ +# Example: Identify Competitors Step Instruction +# +# This is a complete example of a step instruction file for reference. + +# Identify Competitors + +## Objective + +Identify 5-7 key competitors in the target market segment to analyze for competitive positioning. + +## Task + +Research and identify the most relevant competitors in the specified market segment and product category. Focus on companies that directly compete for the same customer base and solve similar problems. + +### Process + +1. **Understand the market context** + - Review the market segment provided by the user + - Understand the product category boundaries + - Consider direct and indirect competitors + +2. **Research competitors** + - Search for companies in this space + - Look for market leaders and emerging players + - Consider different competitive dimensions (features, price, target market) + +3. **Select 5-7 key competitors** + - Prioritize direct competitors + - Include at least one market leader + - Include 1-2 emerging/innovative players + - Ensure diversity in the competitive set + +4. **Document each competitor** + - Company name + - Brief description (2-3 sentences) + - Why they're a relevant competitor + - Primary competitive dimension + +## Output Format + +### competitors_list.md + +A markdown document listing each competitor with context. + +**Structure**: +```markdown +# Competitor Analysis: [Market Segment] + +## Market Context +- **Segment**: [market segment] +- **Category**: [product category] +- **Analysis Date**: [current date] + +## Identified Competitors + +### 1. [Competitor Name] +**Description**: [2-3 sentence description of what they do] + +**Why Relevant**: [Why they're a key competitor in this space] + +**Competitive Dimension**: [What they compete on - e.g., price, features, market segment] + +[Repeat for each competitor, 5-7 total] + +## Selection Rationale + +[Brief paragraph explaining why these specific competitors were chosen and what dimensions of competition they represent] +``` + +## Quality Criteria + +- 5-7 competitors identified (not too few, not too many) +- Mix of established and emerging players +- All competitors are genuinely relevant to the market segment +- Each competitor has clear, specific description +- Selection rationale explains the competitive landscape +- Output is well-formatted and ready for use by next step +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This is the foundation step for competitive analysis. The competitors identified here will be deeply researched in subsequent steps, so it's important to choose the right set. Focus on competitors that will provide strategic insights for positioning decisions. diff --git a/src/deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.template b/src/deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.template new file mode 100644 index 0000000..ddd1921 --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.template @@ -0,0 +1,58 @@ +# [Step Name] + +## Objective + +[Clear statement of what this step accomplishes, derived from the step's description] + +## Task + +[Detailed instructions for completing this step, based on: +- The step's purpose +- Expected inputs and outputs +- The job's overall context +] + +### Process + +[Break down the step into substeps. Use the information gathered during define about: +- What needs to be done +- What makes a good output +- Any quality criteria +] + +1. [Substep 1] +2. [Substep 2] +3. [Substep 3] + +[If this step has user inputs, explain how to gather them] +[If this step has file inputs, explain how to use them] + +## Output Format + +### [output_filename_1] + +[Description of what should be in this output file] + +**Structure**: +```[file format] +[Example or template of what the output should look like] +``` + +[Repeat for each output file] + +## Quality Criteria + +[List what makes this step's output high quality: +- Completeness checks +- Format requirements +- Content requirements +] + +- [Quality criterion 1] +- [Quality criterion 2] +- [Quality criterion 3] +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture]