From f5bebfd2383ea9707ffea436aae77332e9a4e55a Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Sun, 11 Jan 2026 18:57:36 -0700 Subject: [PATCH 1/3] flow cleaned to use itself for the job definition process and docs up to date --- .claude/commands/deepwork.define_job.md | 197 -------- .claude/commands/deepwork.refine_job.md | 236 --------- .claude/commands/deepwork_jobs.define.md | 393 +++++++++++++++ .claude/commands/deepwork_jobs.implement.md | 465 ++++++++++++++++++ .claude/commands/deepwork_jobs.refine.md | 453 +++++++++++++++++ readme.md => README.md | 0 src/deepwork/__init__.py | 3 - src/deepwork/cli/install.py | 58 ++- src/deepwork/cli/sync.py | 24 +- src/deepwork/core/generator.py | 56 +-- src/deepwork/core/parser.py | 6 +- src/deepwork/core/registry.py | 221 --------- src/deepwork/schemas/job_schema.py | 10 +- .../standard_jobs/deepwork_jobs/job.yml | 48 ++ .../deepwork_jobs/steps/define.md | 300 +++++++++++ .../deepwork_jobs/steps/implement.md | 363 ++++++++++++++ .../deepwork_jobs/steps/refine.md | 358 ++++++++++++++ .../templates/claude/command-define.md.jinja | 197 -------- .../claude/command-job-step.md.jinja | 24 +- .../templates/claude/command-refine.md.jinja | 236 --------- .../claude/skill-deepwork.define.md.jinja | 191 ------- tests/conftest.py | 2 +- tests/integration/test_full_workflow.py | 72 +-- tests/integration/test_install_flow.py | 25 - tests/unit/test_detector.py | 1 - tests/unit/test_registry.py | 252 ---------- 26 files changed, 2462 insertions(+), 1729 deletions(-) delete mode 100644 .claude/commands/deepwork.define_job.md delete mode 100644 .claude/commands/deepwork.refine_job.md create mode 100644 .claude/commands/deepwork_jobs.define.md create mode 100644 .claude/commands/deepwork_jobs.implement.md create mode 100644 .claude/commands/deepwork_jobs.refine.md rename readme.md => README.md (100%) delete mode 100644 src/deepwork/core/registry.py create mode 100644 src/deepwork/standard_jobs/deepwork_jobs/job.yml create mode 100644 src/deepwork/standard_jobs/deepwork_jobs/steps/define.md create mode 100644 src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md create mode 100644 src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md delete mode 100644 src/deepwork/templates/claude/command-define.md.jinja delete mode 100644 src/deepwork/templates/claude/command-refine.md.jinja delete mode 100644 src/deepwork/templates/claude/skill-deepwork.define.md.jinja delete mode 100644 tests/unit/test_registry.py diff --git a/.claude/commands/deepwork.define_job.md b/.claude/commands/deepwork.define_job.md deleted file mode 100644 index a54b6851..00000000 --- a/.claude/commands/deepwork.define_job.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -description: Create a new DeepWork job definition ---- - -# Define a New DeepWork Job - -This command helps you create a new multi-step workflow (job) for DeepWork. - -## What is a Job? - -A job is a reusable, multi-step workflow that guides you through complex tasks. Examples: -- Competitive research -- Feature development -- Monthly reporting -- Ad campaign creation -- Research paper writing - -## Job Structure - -Each job consists of: -- **Job metadata**: Name, version, description -- **Steps**: Individual tasks with clear inputs and outputs -- **Dependencies**: Which steps must complete before others - -## Creating a Job - -### Step 1: Plan Your Workflow - -Think through the major phases of your work: -1. What are the distinct stages? -2. What outputs does each stage produce? -3. What dependencies exist between stages? - -### Step 2: Create Job Directory - -```bash -mkdir -p .deepwork/jobs/[job_name]/steps -``` - -### Step 3: Create job.yml - -Create `.deepwork/jobs/[job_name]/job.yml`: - -```yaml -name: [job_name] -version: "1.0.0" -description: "[Brief description of what this workflow accomplishes]" - -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] - # from_step: [previous_step_id] - outputs: - - [output_filename] - dependencies: [] # List of step IDs that must complete first - - - id: [another_step] - name: "[Another Step]" - description: "[What this step does]" - instructions_file: steps/[another_step].md - inputs: - - file: [output_filename] - from_step: [step_id] - outputs: - - [another_output] - dependencies: - - [step_id] # This step requires the previous step -``` - -### Step 4: Create Step Instructions - -For each step, create `.deepwork/jobs/[job_name]/steps/[step_id].md`: - -```markdown -# [Step Name] - -## Objective -[Clear statement of what this step accomplishes] - -## Task -[Detailed instructions for completing this step] - -### Process -1. [Substep 1] -2. [Substep 2] -3. [Substep 3] - -## Output Format - -### [output_filename] -[Description of the expected output] - -```markdown -[Example or template of the output] -``` - -## Quality Criteria -- [Quality check 1] -- [Quality check 2] -``` - -### Step 5: Validate and Sync - -```bash -# Sync to generate slash-commands -deepwork sync - -# Your commands will be available as: -# /[job_name].[step_id] -``` - -## Example - -Here's a simple two-step job: - -```yaml -name: blog_post -version: "1.0.0" -description: "Create a blog post from outline to final draft" - -steps: - - id: outline - name: "Create Outline" - description: "Create a structured outline for the blog post" - instructions_file: steps/outline.md - inputs: - - name: topic - description: "The blog post topic" - - name: target_audience - description: "Who is the target audience" - outputs: - - outline.md - dependencies: [] - - - id: draft - name: "Write Draft" - description: "Write the full blog post draft from the outline" - instructions_file: steps/draft.md - inputs: - - file: outline.md - from_step: outline - outputs: - - draft.md - dependencies: - - outline -``` - -## Tips - -- **Keep steps atomic**: Each step should do one thing well -- **Clear outputs**: Every step should produce reviewable artifacts -- **Logical dependencies**: Steps should build on each other -- **User parameters**: Use when you need information from the user -- **File inputs**: Use when you need outputs from previous steps - -## Validation Rules - -- Job name: lowercase, underscores allowed (e.g., `my_job`) -- Version: semantic versioning (e.g., `1.0.0`) -- Step IDs: unique within the job -- Dependencies: must reference existing step IDs -- File inputs: `from_step` must be in dependencies -- At least one output per step -- No circular dependencies - -## After Creating Your Job - -**IMPORTANT**: You MUST run `deepwork sync` to generate the slash-commands for this job. - -```bash -deepwork sync -``` - -This will: -- Parse the job definition -- Generate slash-commands for each step -- Make the commands available in your AI tool - -**After sync completes successfully**, reload the commands in the current Claude session: -- Type `/reload` to reload commands (if available), OR -- Restart the Claude session to pick up the new commands - -The job is then ready to use: -``` -/[job_name].[first_step_id] -``` - ---- - -Need help? Check `.deepwork/jobs/` for example jobs or see the DeepWork documentation. \ No newline at end of file diff --git a/.claude/commands/deepwork.refine_job.md b/.claude/commands/deepwork.refine_job.md deleted file mode 100644 index 20f38166..00000000 --- a/.claude/commands/deepwork.refine_job.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -description: Refine and update existing job definitions ---- - -# Refine Existing DeepWork Job - -This command helps you modify existing DeepWork jobs. You can: -- Add new steps to a workflow -- Modify step instructions -- Update inputs/outputs -- Adjust dependencies -- Change job metadata (description, version) - -## Instructions - -You will help the user refine an existing job definition. Follow this process: - -### Step 1: Select Job to Refine - -1. **List available jobs**: - Read `.deepwork/registry.yml` to show installed jobs: - ``` - Available jobs: - 1. competitive_research v1.0.0 - Systematic competitive analysis workflow - 2. ad_campaign v1.0.0 - Marketing campaign planning - ``` - -2. **Ask user which job to refine** - -3. **Load job definition**: - Read `.deepwork/jobs/[job_name]/job.yml` - -4. **Show current structure**: - ``` - Job: [name] v[version] - Description: [description] - - Steps: - 1. [step1] - [description] - 2. [step2] - [description] - ... - ``` - -### Step 2: Determine Changes - -Ask the user what they'd like to change: - -**Options**: -1. **Add a new step** - Insert or append a step to the workflow -2. **Modify step instructions** - Update the .md file for a step -3. **Change step inputs/outputs** - Modify what a step consumes or produces -4. **Update dependencies** - Adjust the dependency graph -5. **Update job metadata** - Change description or version -6. **Remove a step** - Delete a step (with validation) - -### Step 3: Make Changes - -Based on the user's selection: - -#### Adding a Step - -1. Ask for step details (same as define wizard) -2. Ask where to insert: "Before which step?" or "At the end?" -3. Validate dependencies (can't depend on later steps if inserted early) -4. Update job.yml -5. Create new step instructions file - -#### Modifying Step Instructions - -1. Ask which step to modify -2. Read current `.deepwork/jobs/[job_name]/steps/[step_id].md` -3. Ask user how to modify (or read their changes) -4. Update the markdown file - -#### Changing Inputs/Outputs - -1. Ask which step to modify -2. Show current inputs and outputs -3. Ask what changes to make -4. Validate: - - File inputs must reference existing dependencies - - If removing an output, check if other steps depend on it -5. Update job.yml - -#### Updating Dependencies - -1. Ask which step to modify -2. Show current dependencies -3. Ask what changes to make -4. Validate: - - No circular dependencies - - All file inputs match dependencies -5. Update job.yml - -#### Updating Metadata - -1. Ask what to change (description and/or version) -2. If version changes, follow semantic versioning: - - Major: Breaking changes - - Minor: New features, backwards compatible - - Patch: Bug fixes -3. Update job.yml -4. Update registry entry - -#### Removing a Step - -1. Ask which step to remove -2. **Validate safety**: - - Check if other steps depend on this step - - Check if other steps use outputs from this step - - If dependencies exist, warn user and suggest updating dependents first -3. If safe, remove: - - Remove from job.yml - - Delete step instructions file - -### Step 4: Sync and Reload Commands - -**IMPORTANT**: After making any changes, you MUST run sync to regenerate the slash-commands: - -```bash -deepwork sync -``` - -This will: -- Parse the updated job definition -- Regenerate all slash-commands for this job -- Update commands in `.claude/commands/` - -**After sync completes successfully**, reload the commands in the current Claude session: -- Type `/reload` to reload commands (if available), OR -- Restart the Claude session to pick up the new commands - -### Step 5: Confirm Changes - -Show summary of changes: -``` -✓ Job "[job_name]" has been updated! - -Changes made: -- Added new step: [step_id] -- Modified step: [step_id] -- Updated version: [old] → [new] - -Files updated: -- .deepwork/jobs/[job_name]/job.yml -- .deepwork/jobs/[job_name]/steps/[step_id].md - -Commands regenerated via sync. Reload your Claude session to use the updated commands. - -To test the changes, run: -/[job_name].[first_step_id] -``` - -## Validation Rules - -Enforce all the same rules as the define wizard, plus: - -1. **Version updates**: Follow semantic versioning conventions -2. **Dependency safety**: When removing/modifying steps, check impact on dependent steps -3. **Output safety**: Warn if removing outputs that other steps consume -4. **Step ordering**: If inserting steps, validate dependency order - -## Safe Modification Patterns - -Guide users toward safe changes: - -### Safe Changes (Always OK) -- Adding steps at the end with new outputs -- Updating step instructions (content) -- Changing job description -- Adding user inputs to a step -- Adding outputs (not removing) - -### Potentially Breaking Changes (Warn User) -- Removing steps -- Removing outputs -- Changing dependencies -- Renaming outputs (other steps may reference them) -- Major version bumps - -### Always Validate -- Circular dependencies after any dependency change -- File inputs match dependencies after any change -- Step IDs remain unique - -## Error Handling - -If issues arise: -- **Dependency conflict**: "Step X depends on step Y which you're trying to remove. Update X first." -- **Circular dependency**: "Adding this dependency would create a cycle: A → B → C → A" -- **Missing file input**: "Step X requires file.md from step Y, but Y is not in its dependencies" - -## Example Usage - -``` -User: /deepwork.refine_job - -Claude: I'll help you refine an existing job. Here are your installed jobs: - -1. competitive_research v1.0.0 - Systematic competitive analysis workflow -2. product_launch v1.0.0 - End-to-end product launch planning - -Which job would you like to refine? - -User: 1 - -Claude: Loading competitive_research... - -Current structure: -- Step 1: identify_competitors -- Step 2: primary_research -- Step 3: secondary_research -- Step 4: comparative_report - -What would you like to do? -1. Add a new step -2. Modify step instructions -3. Change inputs/outputs -4. Update dependencies -5. Update job metadata -6. Remove a step - -User: 1 - -Claude: Great! Let's add a new step. Where would you like to insert it? -[continues interactive dialog] -``` - ---- - -## Context Files - -- Job schema: `src/deepwork/schemas/job_schema.py` -- Job parser: `src/deepwork/core/parser.py` -- Registry: `.deepwork/registry.yml` -- Template: `src/deepwork/templates/claude/command-job-step.md.jinja` \ No newline at end of file diff --git a/.claude/commands/deepwork_jobs.define.md b/.claude/commands/deepwork_jobs.define.md new file mode 100644 index 00000000..4fd3b0b2 --- /dev/null +++ b/.claude/commands/deepwork_jobs.define.md @@ -0,0 +1,393 @@ +--- +description: Create the job.yml specification file by understanding workflow requirements +--- + +# deepwork_jobs.define + +**Step 1 of 3** in the **deepwork_jobs** workflow + +**Summary**: DeepWork job management commands + +## Job Overview + +Core commands for managing DeepWork jobs. These commands help you define new multi-step +workflows and refine existing ones. + +The `define` command guides you through an interactive process to create a new job by +asking detailed questions about your workflow, understanding each step's inputs and outputs, +and generating all necessary files. + +The `refine` command helps you modify existing jobs safely by understanding what you want +to change, validating the impact, and ensuring consistency across your workflow. + + + +## Instructions + +# Define Job Specification + +## Objective + +Create a `job.yml` specification file that defines the structure of a new DeepWork job by thoroughly understanding the user's workflow requirements through an interactive question-and-answer process. + +## Task + +Guide the user through defining a job specification by asking clarifying questions. **Do not attempt to create the specification without first fully understanding the user's needs.** + +The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`). + +### Step 1: Understand the Job Purpose + +Start by asking questions to understand what the user wants to accomplish: + +1. **What is the overall goal of this workflow?** + - What complex task are they trying to accomplish? + - What domain is this in? (e.g., research, marketing, development, reporting) + - How often will they run this workflow? + +2. **What does success look like?** + - What's the final deliverable or outcome? + - Who is the audience for the output? + - What quality criteria matter most? + +3. **What are the major phases?** + - Ask them to describe the workflow at a high level + - What are the distinct stages from start to finish? + - Are there any dependencies between phases? + +### Step 2: Define Each Step + +For each major phase they mentioned, ask detailed questions: + +1. **Step Purpose** + - What exactly does this step accomplish? + - What is the input to this step? + - What is the output from this step? + +2. **Step Inputs** + - What information is needed to start this step? + - Does it need user-provided parameters? (e.g., topic, target audience) + - Does it need files from previous steps? + - What format should inputs be in? + +3. **Step Outputs** + - What files or artifacts does this step produce? + - What format should the output be in? (markdown, YAML, JSON, etc.) + - Where should each output be saved? (filename/path) + - Should outputs be organized in subdirectories? (e.g., `reports/`, `data/`, `drafts/`) + - Will other steps need this output? + +4. **Step Dependencies** + - Which previous steps must complete before this one? + - Are there any ordering constraints? + +5. **Step Process** (high-level understanding) + - What are the key activities in this step? + - Are there any quality checks or validation needed? + - What makes a good vs. bad output for this step? + +**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. + +### Step 3: Validate the Workflow + +After gathering information about all steps: + +1. **Review the flow** + - Summarize the complete workflow + - Show how outputs from one step feed into the next + - Ask if anything is missing + +2. **Check for gaps** + - Are there any steps where the input isn't clearly defined? + - Are there any outputs that aren't used by later steps? + - Are there circular dependencies? + +3. **Confirm details** + - Job name (lowercase, underscores, descriptive) + - Job summary (one clear sentence, max 200 chars) + - Job description (detailed multi-line explanation) + - Version number (start with 1.0.0) + +### Step 4: Create the job.yml Specification + +Only after you have complete understanding, create the `job.yml` file: + +**File Location**: `deepwork/[job_name]/job.yml` + +(Where `[job_name]` is the name of the NEW job you're creating, e.g., `deepwork/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] + +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 + + - 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 +``` + +**Important**: +- Use lowercase with underscores for job name and step IDs +- Ensure file inputs reference steps in dependencies +- No circular dependencies +- At least one output per step +- The `summary` should be concise (max 200 chars) +- The `description` should provide rich context for future refinement + +## Example Dialog + +``` +Claude: I'll help you define a new DeepWork job. Let's start by understanding what you're trying to accomplish. + +What complex task or workflow are you trying to create? What's the overall goal? + +User: I want to create competitive research reports for my company + +Claude: Great! Let's dig into that. A few questions: + +1. What's the final deliverable? Is it a written report, a presentation, or something else? +2. Who is the audience? Your team, executives, clients? +3. How comprehensive should these reports be? + +User: It's a written report for our product team. Should be comprehensive - analyzing 3-5 competitors. + +Claude: Perfect. Now let's think about the major phases of creating this report. What are the main stages you go through? For example: +- Identifying which competitors to analyze? +- Gathering information about them? +- Analyzing the data? +- Writing the report? + +Or is your process different? + +User: Yes, that's close. I would say: +1. Identify competitors +2. Research each one +3. Create comparison analysis +4. Write positioning recommendations + +Claude: Excellent! Now let's define each step in detail. Starting with "Identify competitors": + +1. What inputs do you need to start? Do you already have a market segment in mind, or do you need to specify that? +2. What should the output look like? A list of competitor names? More detailed? +3. How many competitors should be identified? + +User: I need to specify the market segment and product category as inputs. The output should be a markdown file with 5-7 competitors and brief descriptions of each. + +Claude: Perfect. A few more questions about that output: +1. What should the file be called? Something like `competitors_list.md`? +2. Should it go directly in the deepwork/competitive_research/ folder, or in a subdirectory like `research/` or `data/`? + +User: Just call it `competitors_list.md` in the main folder. + +Claude: Great. Now for the "Research each one" step: +1. Does it use the competitor list from the first step as input? +2. What kind of research - product features, pricing, marketing, all of the above? +3. What format should the research output be in? +4. Where should that research be saved? + +[continues for each step...] + +[After gathering all information:] + +Claude: Let me summarize the workflow I've designed based on our conversation: + +**Job: competitive_research** +Summary: Systematic competitive analysis workflow for product positioning + +Description: +A comprehensive workflow for analyzing competitors in your market segment. This job helps product teams understand the competitive landscape by systematically identifying competitors, researching their offerings, creating comparison matrices, and developing strategic positioning recommendations. + +The workflow produces: +- A vetted list of key competitors +- Detailed research notes on each competitor +- A comparison matrix highlighting key differentiators +- Strategic positioning recommendations + +Designed for product teams conducting quarterly competitive analysis. + +**Steps:** + +Step 1: identify_competitors +- Input: market_segment (user), product_category (user) +- Output: competitors_list.md (5-7 competitors with descriptions) + +Step 2: research_competitors +- Input: competitors_list.md (from step 1) +- Output: research_notes.md (detailed findings for each competitor) +- Depends on: identify_competitors + +Step 3: comparative_analysis +- Input: research_notes.md (from step 2) +- Output: comparison_matrix.md (side-by-side analysis) +- Depends on: research_competitors + +Step 4: positioning_recommendations +- Input: comparison_matrix.md (from step 3) +- Output: positioning_report.md (strategic recommendations) +- Depends on: comparative_analysis + +Does this accurately capture your workflow? Any changes needed? + +User: Yes, that's perfect! + +Claude: Great! Creating the job.yml specification now... + +[Creates deepwork/competitive_research/job.yml with the complete spec] + +✓ Job specification created! + +**File created:** +- deepwork/competitive_research/job.yml + +**Next step:** +Run `/deepwork_jobs.implement` to generate the instruction files for each step based on this specification. +``` + +## Important Guidelines + +1. **Focus on specification only** - Don't create instruction files yet +2. **Ask clarifying questions** - Never skip the discovery phase +3. **Rich context in description** - This helps with future refinement +4. **Validate understanding** - Summarize and confirm before creating +5. **Use examples** - Help users understand what good specifications look like +6. **Understand file organization** - Always ask where outputs should be saved and if subdirectories are needed + +## Validation Rules + +Before creating the job.yml, ensure: +- Job name: lowercase, underscores, no spaces +- Version: semantic versioning (1.0.0) +- Summary: concise, under 200 characters +- Description: detailed, provides context +- Step IDs: unique, descriptive, lowercase with underscores +- Dependencies: must reference existing step IDs +- File inputs: `from_step` must be in dependencies +- At least one output per step +- Outputs can be filenames (e.g., `report.md`) or paths (e.g., `reports/analysis.md`) +- File paths in outputs should match where files will actually be created +- No circular dependencies + +## Output Format + +### job.yml + +The complete YAML specification file (example shown in Step 4 above). + +**Location**: `deepwork/[job_name]/job.yml` + +(Where `[job_name]` is the name of the new job being created) + +After creating the file: +1. Commit it to the work branch +2. Inform the user that the specification is complete +3. Tell them to run `/deepwork_jobs.implement` next + +## Quality Criteria + +- User fully understands what job they're creating +- All steps have clear inputs and outputs +- Dependencies make logical sense +- Summary is concise and descriptive +- Description provides rich context for future refinement +- Specification is valid YAML and follows the schema +- Ready for implementation step + + +## Inputs + +### User Parameters + +Please gather the following information from the user: +- **job_purpose**: What complex task or workflow are you trying to accomplish? + + +## Work Branch Management + +All work for this job should be done on a dedicated work branch: + +1. **Check current branch**: + - If already on a work branch for this job (format: `deepwork/deepwork_jobs-[instance]-[date]`), continue using it + - If on main/master, create a new work branch + +2. **Create work branch** (if needed): + ```bash + git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d) + ``` + Replace `[instance]` with a descriptive identifier (e.g., `acme`, `q1-launch`, etc.) + +3. **All outputs go in the work directory**: + - Create files in: `deepwork/deepwork_jobs/` + - This keeps work products organized by job + +## Output Requirements + +Create the following output(s) in the work directory: +- `deepwork/deepwork_jobs/job.yml` +Ensure all outputs are: +- Well-formatted and complete +- Committed to the work branch +- Ready for review or use by subsequent steps + +## Completion + +After completing this step: + +1. **Commit your work**: + ```bash + git add deepwork/deepwork_jobs/ + git commit -m "deepwork_jobs: Complete define step" + ``` + +2. **Verify outputs**: Confirm all required files have been created + +3. **Inform the user**: + - Step 1 of 3 is complete + - Outputs created: job.yml + - Ready to proceed to next step: `/deepwork_jobs.implement` + +## Next Step + +To continue the workflow, run: +``` +/deepwork_jobs.implement +``` + +--- + +## Context Files + +- Job definition: `.deepwork/jobs/deepwork_jobs/job.yml` +- Step instructions: `.deepwork/jobs/deepwork_jobs/steps/define.md` \ No newline at end of file diff --git a/.claude/commands/deepwork_jobs.implement.md b/.claude/commands/deepwork_jobs.implement.md new file mode 100644 index 00000000..dc3be9ef --- /dev/null +++ b/.claude/commands/deepwork_jobs.implement.md @@ -0,0 +1,465 @@ +--- +description: Generate instruction files for each step based on the job.yml specification +--- + +# deepwork_jobs.implement + +**Step 2 of 3** in the **deepwork_jobs** workflow + +**Summary**: DeepWork job management commands + +## Job Overview + +Core commands for managing DeepWork jobs. These commands help you define new multi-step +workflows and refine existing ones. + +The `define` command guides you through an interactive process to create a new job by +asking detailed questions about your workflow, understanding each step's inputs and outputs, +and generating all necessary files. + +The `refine` command helps you modify existing jobs safely by understanding what you want +to change, validating the impact, and ensuring consistency across your workflow. + + +## Prerequisites + +This step requires completion of the following step(s): +- `/deepwork_jobs.define` + +Please ensure these steps have been completed before proceeding. + +## Instructions + +# Implement Job Steps + +## Objective + +Generate the DeepWork job directory structure and instruction files for each step based on the `job.yml` specification created in the previous step. + +## Task + +Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure, step instruction files, and registry entry. Then sync the commands to make them available. + +### Step 1: Read and Validate the Specification + +1. **Locate the job.yml file** + - Read `deepwork/[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) + - Parse the YAML content + +2. **Validate the specification** + - Ensure it follows the schema (name, version, summary, description, steps) + - Check that all dependencies reference existing steps + - Verify no circular dependencies + - Confirm file inputs match dependencies + +3. **Extract key information** + - Job name, version, summary, description + - 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` - Copy from work directory +- `.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 +] + +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] + +## Context + +[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture] +``` + +**Guidelines for generating instructions:** + +1. **Use the job description** - The detailed description from job.yml provides crucial context +2. **Be specific** - Don't write generic instructions; tailor them to the step's purpose +3. **Provide examples** - Show what good output looks like +4. **Explain the "why"** - Help the user understand the step's role in the workflow +5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones + +### Step 4: Copy job.yml to Job Directory + +Copy the validated `job.yml` from the work directory to `.deepwork/jobs/[job_name]/job.yml`: + +```bash +cp deepwork/[job_name]/job.yml .deepwork/jobs/[job_name]/job.yml +``` + +### Step 5: Register the Job + +Update `.deepwork/registry.yml` to register the new job: + +```yaml +jobs: + [job_name]: + version: "[version]" + summary: "[summary]" + path: "[job_name]" +``` + +**Important**: Don't overwrite existing jobs in the registry - add to it. + +### Step 6: Sync Commands + +Run `deepwork sync` to generate the slash-commands for this job: + +```bash +deepwork sync +``` + +This will: +- Parse the job definition +- Generate slash-commands for each step +- Make the commands available in `.claude/commands/` (or appropriate platform directory) + +### Step 7: Reload Commands + +Instruct the user to reload commands in their current session: +- Run `/reload` command (if available) +- Or restart the Claude session + +## 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. +``` + +## Important Guidelines + +1. **Read the spec carefully** - Understand the job's intent from the description +2. **Generate complete instructions** - Don't create placeholder or stub files +3. **Maintain consistency** - Use the same structure for all step instruction files +4. **Provide examples** - Show what good output looks like +5. **Use context** - The job description provides valuable context for each step +6. **Be specific** - Tailor instructions to the specific step, not generic advice + +## Validation Before Sync + +Before running `deepwork sync`, verify: +- All directories exist +- `job.yml` is in place +- All step instruction files exist (one per step) +- Registry is updated +- 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 ...] + +### Registry +- Updated `.deepwork/registry.yml` with job registration + +## 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**: Run `/reload` or restart your Claude session +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: +- [ ] job.yml validated and copied to job directory +- [ ] All step instruction files created +- [ ] Each instruction file is complete and actionable +- [ ] Registry updated with new job +- [ ] `deepwork sync` executed successfully +- [ ] Commands generated in platform directory +- [ ] User informed of next steps (reload commands) +- [ ] implementation_summary.md created + +## Quality Criteria + +- Job directory structure is correct +- All instruction files are complete (not stubs) +- Instructions are specific and actionable +- Output examples are provided in each instruction file +- Quality criteria defined for each step +- Registry properly updated +- Sync completed successfully +- Commands available for use + + +## Inputs + + +### Required Files + +This step requires the following files from previous steps: +- `job.yml` (from step `define`) + Location: `deepwork/deepwork_jobs/job.yml` + +Make sure to read and use these files as context for this step. + +## Work Branch Management + +All work for this job should be done on a dedicated work branch: + +1. **Check current branch**: + - If already on a work branch for this job (format: `deepwork/deepwork_jobs-[instance]-[date]`), continue using it + - If on main/master, create a new work branch + +2. **Create work branch** (if needed): + ```bash + git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d) + ``` + Replace `[instance]` with a descriptive identifier (e.g., `acme`, `q1-launch`, etc.) + +3. **All outputs go in the work directory**: + - Create files in: `deepwork/deepwork_jobs/` + - This keeps work products organized by job + +## Output Requirements + +Create the following output(s) in the work directory: +- `deepwork/deepwork_jobs/implementation_summary.md` +Ensure all outputs are: +- Well-formatted and complete +- Committed to the work branch +- Ready for review or use by subsequent steps + +## Completion + +After completing this step: + +1. **Commit your work**: + ```bash + git add deepwork/deepwork_jobs/ + git commit -m "deepwork_jobs: Complete implement step" + ``` + +2. **Verify outputs**: Confirm all required files have been created + +3. **Inform the user**: + - Step 2 of 3 is complete + - Outputs created: implementation_summary.md + - Ready to proceed to next step: `/deepwork_jobs.refine` + +## Next Step + +To continue the workflow, run: +``` +/deepwork_jobs.refine +``` + +--- + +## Context Files + +- Job definition: `.deepwork/jobs/deepwork_jobs/job.yml` +- Step instructions: `.deepwork/jobs/deepwork_jobs/steps/implement.md` \ No newline at end of file diff --git a/.claude/commands/deepwork_jobs.refine.md b/.claude/commands/deepwork_jobs.refine.md new file mode 100644 index 00000000..c982cbb1 --- /dev/null +++ b/.claude/commands/deepwork_jobs.refine.md @@ -0,0 +1,453 @@ +--- +description: Modify an existing job definition +--- + +# deepwork_jobs.refine + +**Step 3 of 3** in the **deepwork_jobs** workflow + +**Summary**: DeepWork job management commands + +## Job Overview + +Core commands for managing DeepWork jobs. These commands help you define new multi-step +workflows and refine existing ones. + +The `define` command guides you through an interactive process to create a new job by +asking detailed questions about your workflow, understanding each step's inputs and outputs, +and generating all necessary files. + +The `refine` command helps you modify existing jobs safely by understanding what you want +to change, validating the impact, and ensuring consistency across your workflow. + + + +## Instructions + +# Refine Existing DeepWork Job + +## Objective + +Help the user modify an existing DeepWork job definition by understanding what they want to change and ensuring the modifications maintain consistency and validity. + +## Task + +Guide the user through refining a job by first understanding their existing job, then what they want to change, and finally implementing those changes safely. + +### Step 1: Select and Load Job + +1. **List available jobs** + - Read `.deepwork/registry.yml` + - Display installed jobs with versions and descriptions + - Ask which job to refine + +2. **Load job definition** + - Read `.deepwork/jobs/[job_name]/job.yml` + - Parse and understand the current structure + +3. **Show current structure** + - Display all steps with their names and descriptions + - Show the dependency flow + - Highlight key inputs and outputs + +### Step 2: Understand Desired Changes + +Ask the user what they want to change: + +**Change Options:** +1. Add a new step to the workflow +2. Modify step instructions +3. Change step inputs/outputs +4. Update dependencies between steps +5. Update job metadata (description, version) +6. Remove a step + +**For each change, ask clarifying questions:** +- Why do they want to make this change? +- How will it improve the workflow? +- Are there dependencies or side effects to consider? + +### Step 3: Make Changes Safely + +Based on the user's selection: + +#### Adding a Step + +1. **Gather step details** (same as define command) + - What does this step accomplish? + - What are the inputs? User parameters or file inputs? + - What outputs does it produce? + - What are the dependencies? + +2. **Determine placement** + - Where should it go in the workflow? + - Before which existing step? + - Or at the end? + +3. **Validate placement** + - Can't depend on later steps if inserted early + - File inputs must come from dependencies + - Check for circular dependencies + +4. **Create files** + - Update `job.yml` with new step + - Create step instructions file in `steps/[step_id].md` + +#### Modifying Step Instructions + +1. **Select step to modify** + - Show list of steps + - Ask which one to modify + +2. **Understand the change** + - What's not working with current instructions? + - What should be different? + - Show current instructions + +3. **Update instructions** + - Modify `.deepwork/jobs/[job_name]/steps/[step_id].md` + - Keep the same structure (Objective, Task, Process, Output Format, Quality Criteria) + +#### Changing Inputs/Outputs + +1. **Select step to modify** +2. **Show current inputs and outputs** +3. **Understand the change** + - Adding or removing? + - Why is this needed? + +4. **Validate impact** + - If removing output: check if other steps depend on it (BREAKING CHANGE) + - If adding file input: ensure from_step is in dependencies + - If removing input: ensure it's not critical + +5. **Update job.yml** + +#### Updating Dependencies + +1. **Select step to modify** +2. **Show current dependency graph** +3. **Understand the change** + - Adding or removing dependency? + - Why? + +4. **Validate** + - Check for circular dependencies + - Ensure all file inputs have matching dependencies + - Ensure dependency chain makes logical sense + +5. **Update job.yml** + +#### Updating Metadata + +1. **Ask what to change** + - Description? + - Version? + +2. **If version change, explain semantic versioning** + - Major (x.0.0): Breaking changes (removing steps, removing outputs) + - Minor (0.x.0): New features, backwards compatible (adding steps) + - Patch (0.0.x): Bug fixes, improvements + +3. **Update job.yml and registry.yml** + +#### Removing a Step + +1. **Select step to remove** + +2. **CRITICAL: Validate safety** + - Check if other steps depend on this step + - Check if other steps use outputs from this step + - If dependencies exist: **WARN** and suggest updating dependents first + - This is a BREAKING CHANGE - requires major version bump + +3. **If safe to remove** + - Remove from `job.yml` + - Delete step instructions file + - Suggest version bump + +### Step 4: Validate Changes + +After making changes: + +1. **Review the updated structure** + - Show the complete updated workflow + - Highlight what changed + - Check for consistency + +2. **Validate job definition** + - No circular dependencies + - All file inputs match dependencies + - All step IDs unique + - All outputs defined + +3. **Suggest version update** if not already done + - Breaking changes? Major version + - New features? Minor version + - Improvements? Patch version + +### Step 5: Sync and Reload + +1. **Run sync** + ```bash + deepwork sync + ``` + +2. **Reload commands** + - Instruct user to run `/reload` or restart session + +3. **Provide summary** + - Show what changed + - List updated files + - Explain next steps + +## Safe Modification Patterns + +Guide users toward safe changes: + +### Safe Changes (Always OK) +- Adding steps at the end with new outputs +- Updating step instructions (content only) +- Changing job description +- Adding user inputs to a step +- Adding outputs (not removing) +- Patch version bumps + +### Potentially Breaking Changes (Warn User) +- Removing steps +- Removing outputs +- Removing inputs +- Changing dependencies +- Renaming outputs (other steps may reference them) +- Requires major or minor version bump + +### Always Validate +- Circular dependencies after any dependency change +- File inputs match dependencies after any change +- Step IDs remain unique +- At least one output per step + +## Example Dialog + +``` +Claude: I'll help you refine an existing job. Here are your installed jobs: + +1. competitive_research v1.0.0 - Systematic competitive analysis workflow +2. blog_post v1.0.0 - Blog post creation workflow + +Which job would you like to refine? + +User: 1 + +Claude: Loading competitive_research v1.0.0... + +Current structure: +- Step 1: identify_competitors - Identify 5-7 competitors in target market +- Step 2: research_competitors - Deep research on each competitor +- Step 3: comparative_analysis - Side-by-side comparison matrix +- Step 4: positioning_recommendations - Strategic positioning report + +What would you like to change? +1. Add a new step +2. Modify step instructions +3. Change inputs/outputs +4. Update dependencies +5. Update job metadata +6. Remove a step + +User: 1 + +Claude: Great! Let's add a new step. First, help me understand: + +1. What should this new step accomplish? +2. Where should it fit in the workflow? + - Should it go between existing steps or at the end? + +User: I want to add a step that validates our product positioning before the final recommendations. It should go between step 3 and step 4. + +Claude: Excellent idea. So this would be: +- Step 4: validate_positioning +- Step 5: positioning_recommendations (renumbered) + +For this validation step: +1. What inputs does it need? I assume it needs the comparison_matrix.md from step 3? +2. What should it output? +3. What exactly should this validation check for? + +User: Yes, it needs the comparison matrix. It should output a validation_report.md that identifies gaps in our positioning. + +Claude: Perfect. Let me confirm the details: + +**New Step: validate_positioning** +- Name: "Validate Product Positioning" +- Description: "Identify gaps and opportunities in current positioning" +- Inputs: comparison_matrix.md (from comparative_analysis step) +- Outputs: validation_report.md +- Dependencies: comparative_analysis +- Position: Between step 3 and 4 + +Should the positioning_recommendations step also use the validation_report.md as input? + +User: Yes, definitely + +Claude: Great! So I'll also update the positioning_recommendations step to include validation_report.md as an input and add validate_positioning as a dependency. + +This is a new feature, so I'll bump the version to 1.1.0 (minor version). + +Creating the new step... ✓ + +Updated files: +- .deepwork/jobs/competitive_research/job.yml (added step, updated dependencies, version → 1.1.0) +- .deepwork/jobs/competitive_research/steps/validate_positioning.md (created) +- .deepwork/registry.yml (updated version) + +Now run: +```bash +deepwork sync +``` + +Then reload your session and you'll have: +- /competitive_research.validate_positioning (new!) +- All other commands updated +``` + +## Validation Rules + +Enforce the same rules as job definition: +- Job name: lowercase, underscores +- Version: semantic versioning +- Step IDs: unique within job +- Dependencies: must reference existing step IDs +- File inputs: `from_step` must be in dependencies +- At least one output per step +- No circular dependencies + +## Error Handling + +If issues arise, provide clear guidance: +- **Dependency conflict**: "Step X depends on step Y which you're trying to remove. You must update step X first, or remove both steps." +- **Circular dependency**: "Adding this dependency would create a cycle: A → B → C → A. Please choose a different dependency structure." +- **Missing file input**: "Step X requires file.md from step Y, but Y is not in its dependencies. I'll add Y to the dependencies." +- **Breaking change**: "Removing this output is a breaking change. Other steps depend on it. I recommend against this change unless you update the dependent steps first." + +## Output Format + +### refinement_summary.md + +```markdown +# Job Refinement: [job_name] + +## Changes Made + +### Version +[old_version] → [new_version] + +### Added Steps +- **[step_name]** (`[step_id]`) + - Purpose: [what it does] + - Inputs: [list] + - Outputs: [list] + - Position: After [previous_step] + +### Modified Steps +- **[step_name]** (`[step_id]`) + - Changed: [what changed] + - Reason: [why] + +### Updated Dependencies +- **[step_name]**: Added dependency on [other_step] + +### Removed +- [Anything removed] + +## Files Updated +- `.deepwork/jobs/[job_name]/job.yml` +- `.deepwork/jobs/[job_name]/steps/[step_id].md` +- `.deepwork/registry.yml` + +## Next Steps +1. Run `deepwork sync` to regenerate commands +2. Reload your Claude session (`/reload` or restart) +3. Test the updated workflow: `/[job_name].[first_step]` + +## Updated Command Reference +[List all commands with brief descriptions] +``` + +## Quality Criteria + +- Changes maintain job consistency +- Dependencies are logically valid +- Version bump follows semantic versioning +- No circular dependencies introduced +- User understands impact of changes +- Breaking changes are clearly communicated + + +## Inputs + +### User Parameters + +Please gather the following information from the user: +- **job_name**: Name of the job to refine + + +## Work Branch Management + +All work for this job should be done on a dedicated work branch: + +1. **Check current branch**: + - If already on a work branch for this job (format: `deepwork/deepwork_jobs-[instance]-[date]`), continue using it + - If on main/master, create a new work branch + +2. **Create work branch** (if needed): + ```bash + git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d) + ``` + Replace `[instance]` with a descriptive identifier (e.g., `acme`, `q1-launch`, etc.) + +3. **All outputs go in the work directory**: + - Create files in: `deepwork/deepwork_jobs/` + - This keeps work products organized by job + +## Output Requirements + +Create the following output(s) in the work directory: +- `deepwork/deepwork_jobs/refinement_summary.md` +Ensure all outputs are: +- Well-formatted and complete +- Committed to the work branch +- Ready for review or use by subsequent steps + +## Completion + +After completing this step: + +1. **Commit your work**: + ```bash + git add deepwork/deepwork_jobs/ + git commit -m "deepwork_jobs: Complete refine step" + ``` + +2. **Verify outputs**: Confirm all required files have been created + +3. **Inform the user**: + - Step 3 of 3 is complete + - Outputs created: refinement_summary.md + - This is the final step - the job is complete! + +## Workflow Complete + +This is the final step in the deepwork_jobs workflow. All outputs should now be complete and ready for review. + +Consider: +- Reviewing all work products in `deepwork/deepwork_jobs/` +- Creating a pull request to merge the work branch +- Documenting any insights or learnings + +--- + +## Context Files + +- Job definition: `.deepwork/jobs/deepwork_jobs/job.yml` +- Step instructions: `.deepwork/jobs/deepwork_jobs/steps/refine.md` \ No newline at end of file diff --git a/readme.md b/README.md similarity index 100% rename from readme.md rename to README.md diff --git a/src/deepwork/__init__.py b/src/deepwork/__init__.py index 9130faf7..9e3fc9c1 100644 --- a/src/deepwork/__init__.py +++ b/src/deepwork/__init__.py @@ -20,7 +20,4 @@ def __getattr__(name: str) -> object: parse_job_definition, ) return locals()[name] - elif name in ("JobRegistry", "JobRegistryEntry", "RegistryError"): - from deepwork.core.registry import JobRegistry, JobRegistryEntry, RegistryError - return locals()[name] raise AttributeError(f"module {__name__!r} has no attribute {name!r}") diff --git a/src/deepwork/cli/install.py b/src/deepwork/cli/install.py index 9a3e5ca6..6005d4f9 100644 --- a/src/deepwork/cli/install.py +++ b/src/deepwork/cli/install.py @@ -1,5 +1,6 @@ """Install command for DeepWork CLI.""" +import shutil from pathlib import Path import click @@ -19,6 +20,44 @@ class InstallError(Exception): pass +def _inject_deepwork_jobs(jobs_dir: Path, project_path: Path) -> None: + """ + Inject the deepwork_jobs job definition into the project. + + Args: + jobs_dir: Path to .deepwork/jobs directory + project_path: Path to project root (for relative path display) + + Raises: + InstallError: If injection fails + """ + # Find the standard jobs directory + standard_jobs_dir = Path(__file__).parent.parent / "standard_jobs" / "deepwork_jobs" + + if not standard_jobs_dir.exists(): + raise InstallError( + f"Core job definition not found at {standard_jobs_dir}. " + "DeepWork installation may be corrupted." + ) + + # Target directory + target_dir = jobs_dir / "deepwork_jobs" + + # Copy the entire directory + try: + if target_dir.exists(): + # Remove existing if present (for reinstall/upgrade) + shutil.rmtree(target_dir) + + shutil.copytree(standard_jobs_dir, target_dir) + console.print( + f" [green]✓[/green] Installed deepwork_jobs " + f"({target_dir.relative_to(project_path)})" + ) + except Exception as e: + raise InstallError(f"Failed to install core jobs: {e}") from e + + @click.command() @click.option( "--platform", @@ -124,6 +163,10 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None: ensure_dir(jobs_dir) console.print(f" [green]✓[/green] Created {deepwork_dir.relative_to(project_path)}/") + # Step 3b: Inject deepwork_jobs (core job definitions) + console.print("[yellow]→[/yellow] Installing core job definitions...") + _inject_deepwork_jobs(jobs_dir, project_path) + # Step 4: Load or create config.yml console.print("[yellow]→[/yellow] Updating configuration...") config_file = deepwork_dir / "config.yml" @@ -154,18 +197,7 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None: save_yaml(config_file, config_data) console.print(f" [green]✓[/green] Updated {config_file.relative_to(project_path)}") - # Step 5: Create registry.yml - console.print("[yellow]→[/yellow] Initializing job registry...") - registry_file = deepwork_dir / "registry.yml" - if not registry_file.exists(): - save_yaml(registry_file, {"jobs": {}}) - console.print(f" [green]✓[/green] Created {registry_file.relative_to(project_path)}") - else: - console.print( - f" [dim]•[/dim] {registry_file.relative_to(project_path)} already exists" - ) - - # Step 6: Run sync to generate commands + # Step 5: Run sync to generate commands console.print() console.print("[yellow]→[/yellow] Running sync to generate commands...") console.print() @@ -185,5 +217,5 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None: console.print() console.print("[bold]Next steps:[/bold]") console.print(" 1. Start your agent CLI (ex. [cyan]claude[/cyan] or [cyan]gemini[/cyan])") - console.print(" 2. Define your first job using the command [cyan]/deepwork.define_job[/cyan]") + console.print(" 2. Define your first job using the command [cyan]/deepwork_jobs.define[/cyan]") console.print() diff --git a/src/deepwork/cli/sync.py b/src/deepwork/cli/sync.py index b7bea690..864ea2f7 100644 --- a/src/deepwork/cli/sync.py +++ b/src/deepwork/cli/sync.py @@ -100,7 +100,7 @@ def sync_commands(project_path: Path) -> None: # Sync each platform generator = CommandGenerator() - stats = {"platforms": 0, "core_commands": 0, "job_commands": 0} + stats = {"platforms": 0, "commands": 0} for platform_name in platforms: if platform_name not in PLATFORMS: @@ -116,25 +116,13 @@ def sync_commands(project_path: Path) -> None: # Create commands directory ensure_dir(commands_dir) - # Generate core commands - console.print(f" [dim]•[/dim] Generating core commands...") - try: - core_paths = generator.generate_core_commands(platform_config, platform_dir) - stats["core_commands"] += len(core_paths) - for path in core_paths: - rel_path = path.relative_to(project_path) - console.print(f" [green]✓[/green] {rel_path}") - except Exception as e: - console.print(f" [red]✗[/red] Failed to generate core commands: {e}") - continue - - # Generate job commands + # Generate commands for all jobs if jobs: - console.print(f" [dim]•[/dim] Generating job commands...") + console.print(" [dim]•[/dim] Generating commands...") for job in jobs: try: job_paths = generator.generate_all_commands(job, platform_config, platform_dir) - stats["job_commands"] += len(job_paths) + stats["commands"] += len(job_paths) console.print(f" [green]✓[/green] {job.name} ({len(job_paths)} commands)") except Exception as e: console.print(f" [red]✗[/red] Failed for {job.name}: {e}") @@ -151,9 +139,7 @@ def sync_commands(project_path: Path) -> None: table.add_column("Count", style="green") table.add_row("Platforms synced", str(stats["platforms"])) - table.add_row("Core commands", str(stats["core_commands"])) - table.add_row("Job commands", str(stats["job_commands"])) - table.add_row("Total commands", str(stats["core_commands"] + stats["job_commands"])) + table.add_row("Total commands", str(stats["commands"])) console.print(table) console.print() diff --git a/src/deepwork/core/generator.py b/src/deepwork/core/generator.py index 2b905a4e..0956f2fa 100644 --- a/src/deepwork/core/generator.py +++ b/src/deepwork/core/generator.py @@ -103,6 +103,7 @@ def _build_step_context( return { "job_name": job.name, "job_version": job.version, + "job_summary": job.summary, "job_description": job.description, "step_id": step.id, "step_name": step.name, @@ -209,58 +210,3 @@ def generate_all_commands( return command_paths - def generate_core_commands( - self, platform: PlatformConfig, output_dir: Path | str - ) -> list[Path]: - """ - Generate core DeepWork commands (like define). - - Args: - platform: Platform configuration - output_dir: Base directory to write commands to (e.g., .claude/) - - Returns: - List of paths to generated command files - - Raises: - GeneratorError: If generation fails - """ - output_dir = Path(output_dir) - commands_dir = output_dir / platform.commands_dir - commands_dir.mkdir(parents=True, exist_ok=True) - - command_paths = [] - - # Core templates to generate - core_templates = [ - ("command-define.md.jinja", "deepwork.define_job.md"), - ("command-refine.md.jinja", "deepwork.refine_job.md"), - ] - - env = self._get_jinja_env(platform) - - for template_name, command_filename in core_templates: - try: - template = env.get_template(template_name) - except TemplateNotFound: - # Skip if template doesn't exist yet - continue - - try: - rendered = template.render() - except Exception as e: - raise GeneratorError( - f"Core template rendering failed for {template_name}: {e}" - ) from e - - command_path = commands_dir / command_filename - - try: - safe_write(command_path, rendered) - except Exception as e: - raise GeneratorError(f"Failed to write core command file: {e}") from e - - command_paths.append(command_path) - - return command_paths - diff --git a/src/deepwork/core/parser.py b/src/deepwork/core/parser.py index 27966ac4..21d29235 100644 --- a/src/deepwork/core/parser.py +++ b/src/deepwork/core/parser.py @@ -78,7 +78,8 @@ class JobDefinition: name: str version: str - description: str + summary: str + description: str | None steps: list[Step] job_dir: Path @@ -179,7 +180,8 @@ def from_dict(cls, data: dict[str, Any], job_dir: Path) -> "JobDefinition": return cls( name=data["name"], version=data["version"], - description=data["description"], + summary=data["summary"], + description=data.get("description"), steps=[Step.from_dict(step_data) for step_data in data["steps"]], job_dir=job_dir, ) diff --git a/src/deepwork/core/registry.py b/src/deepwork/core/registry.py deleted file mode 100644 index 42af5d88..00000000 --- a/src/deepwork/core/registry.py +++ /dev/null @@ -1,221 +0,0 @@ -"""Job registry for tracking installed jobs.""" - -from dataclasses import dataclass -from datetime import datetime -from pathlib import Path -from typing import Any - -from deepwork.utils.fs import ensure_dir -from deepwork.utils.yaml_utils import YAMLError, load_yaml, save_yaml - - -class RegistryError(Exception): - """Exception raised for registry errors.""" - - pass - - -@dataclass -class JobRegistryEntry: - """Represents an entry in the job registry.""" - - name: str - version: str - description: str - job_dir: str # Relative path to job directory - installed_at: str # ISO format timestamp - - def to_dict(self) -> dict[str, Any]: - """Convert to dictionary.""" - return { - "name": self.name, - "version": self.version, - "description": self.description, - "job_dir": self.job_dir, - "installed_at": self.installed_at, - } - - @classmethod - def from_dict(cls, data: dict[str, Any]) -> "JobRegistryEntry": - """Create entry from dictionary.""" - return cls( - name=data["name"], - version=data["version"], - description=data["description"], - job_dir=data["job_dir"], - installed_at=data["installed_at"], - ) - - -class JobRegistry: - """Manages the job registry.""" - - def __init__(self, deepwork_dir: Path | str): - """ - Initialize registry. - - Args: - deepwork_dir: Path to .deepwork directory - """ - self.deepwork_dir = Path(deepwork_dir) - self.registry_file = self.deepwork_dir / "registry.yml" - - def _load_registry(self) -> dict[str, dict[str, Any]]: - """ - Load registry from file. - - Returns: - Dictionary mapping job names to entry data - """ - if not self.registry_file.exists(): - return {} - - try: - data = load_yaml(self.registry_file) - if data is None: - return {} - return data.get("jobs", {}) - except YAMLError as e: - raise RegistryError(f"Failed to load registry: {e}") from e - - def _save_registry(self, registry_data: dict[str, dict[str, Any]]) -> None: - """ - Save registry to file. - - Args: - registry_data: Dictionary mapping job names to entry data - """ - ensure_dir(self.deepwork_dir) - - try: - save_yaml(self.registry_file, {"jobs": registry_data}) - except YAMLError as e: - raise RegistryError(f"Failed to save registry: {e}") from e - - def register_job( - self, name: str, version: str, description: str, job_dir: str - ) -> JobRegistryEntry: - """ - Register a job. - - Args: - name: Job name - version: Job version - description: Job description - job_dir: Relative path to job directory - - Returns: - Created registry entry - - Raises: - RegistryError: If job is already registered - """ - registry = self._load_registry() - - if name in registry: - raise RegistryError(f"Job '{name}' is already registered") - - entry = JobRegistryEntry( - name=name, - version=version, - description=description, - job_dir=job_dir, - installed_at=datetime.utcnow().isoformat(), - ) - - registry[name] = entry.to_dict() - self._save_registry(registry) - - return entry - - def unregister_job(self, name: str) -> None: - """ - Unregister a job. - - Args: - name: Job name to unregister - - Raises: - RegistryError: If job is not registered - """ - registry = self._load_registry() - - if name not in registry: - raise RegistryError(f"Job '{name}' is not registered") - - del registry[name] - self._save_registry(registry) - - def get_job(self, name: str) -> JobRegistryEntry | None: - """ - Get registry entry for a job. - - Args: - name: Job name - - Returns: - Registry entry if found, None otherwise - """ - registry = self._load_registry() - - if name not in registry: - return None - - return JobRegistryEntry.from_dict(registry[name]) - - def list_jobs(self) -> list[JobRegistryEntry]: - """ - List all registered jobs. - - Returns: - List of registry entries (sorted by name) - """ - registry = self._load_registry() - entries = [JobRegistryEntry.from_dict(data) for data in registry.values()] - return sorted(entries, key=lambda e: e.name) - - def is_registered(self, name: str) -> bool: - """ - Check if a job is registered. - - Args: - name: Job name - - Returns: - True if job is registered, False otherwise - """ - registry = self._load_registry() - return name in registry - - def update_job( - self, name: str, version: str | None = None, description: str | None = None - ) -> JobRegistryEntry: - """ - Update a registered job's metadata. - - Args: - name: Job name - version: New version (optional) - description: New description (optional) - - Returns: - Updated registry entry - - Raises: - RegistryError: If job is not registered - """ - registry = self._load_registry() - - if name not in registry: - raise RegistryError(f"Job '{name}' is not registered") - - entry_data = registry[name] - if version is not None: - entry_data["version"] = version - if description is not None: - entry_data["description"] = description - - registry[name] = entry_data - self._save_registry(registry) - - return JobRegistryEntry.from_dict(entry_data) diff --git a/src/deepwork/schemas/job_schema.py b/src/deepwork/schemas/job_schema.py index 91683c6a..09be6912 100644 --- a/src/deepwork/schemas/job_schema.py +++ b/src/deepwork/schemas/job_schema.py @@ -6,7 +6,7 @@ JOB_SCHEMA: dict[str, Any] = { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", - "required": ["name", "version", "description", "steps"], + "required": ["name", "version", "summary", "steps"], "properties": { "name": { "type": "string", @@ -18,10 +18,16 @@ "pattern": r"^\d+\.\d+\.\d+$", "description": "Semantic version (e.g., 1.0.0)", }, + "summary": { + "type": "string", + "minLength": 1, + "maxLength": 200, + "description": "Brief one-line summary of what this job accomplishes", + }, "description": { "type": "string", "minLength": 1, - "description": "Human-readable description of the job", + "description": "Detailed multi-line description of the job's purpose, process, and goals", }, "steps": { "type": "array", diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml new file mode 100644 index 00000000..f9003b73 --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -0,0 +1,48 @@ +name: deepwork_jobs +version: "1.0.0" +summary: "DeepWork job management commands" +description: | + Core commands for managing DeepWork jobs. These commands help you define new multi-step + workflows and refine existing ones. + + The `define` command guides you through an interactive process to create a new job by + asking detailed questions about your workflow, understanding each step's inputs and outputs, + and generating all necessary files. + + The `refine` command helps you modify existing jobs safely by understanding what you want + to change, validating the impact, and ensuring consistency across your workflow. + +steps: + - id: define + name: "Define Job Specification" + description: "Create the job.yml specification file by understanding workflow requirements" + instructions_file: steps/define.md + inputs: + - name: job_purpose + description: "What complex task or workflow are you trying to accomplish?" + outputs: + - job.yml + dependencies: [] + + - id: implement + name: "Implement Job Steps" + description: "Generate instruction files for each step based on the job.yml specification" + instructions_file: steps/implement.md + inputs: + - file: job.yml + from_step: define + outputs: + - implementation_summary.md + dependencies: + - define + + - id: refine + name: "Refine Existing Job" + description: "Modify an existing job definition" + instructions_file: steps/refine.md + inputs: + - name: job_name + description: "Name of the job to refine" + outputs: + - refinement_summary.md + dependencies: [] diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md new file mode 100644 index 00000000..6e50b8f5 --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md @@ -0,0 +1,300 @@ +# Define Job Specification + +## Objective + +Create a `job.yml` specification file that defines the structure of a new DeepWork job by thoroughly understanding the user's workflow requirements through an interactive question-and-answer process. + +## Task + +Guide the user through defining a job specification by asking clarifying questions. **Do not attempt to create the specification without first fully understanding the user's needs.** + +The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`). + +### Step 1: Understand the Job Purpose + +Start by asking questions to understand what the user wants to accomplish: + +1. **What is the overall goal of this workflow?** + - What complex task are they trying to accomplish? + - What domain is this in? (e.g., research, marketing, development, reporting) + - How often will they run this workflow? + +2. **What does success look like?** + - What's the final deliverable or outcome? + - Who is the audience for the output? + - What quality criteria matter most? + +3. **What are the major phases?** + - Ask them to describe the workflow at a high level + - What are the distinct stages from start to finish? + - Are there any dependencies between phases? + +### Step 2: Define Each Step + +For each major phase they mentioned, ask detailed questions: + +1. **Step Purpose** + - What exactly does this step accomplish? + - What is the input to this step? + - What is the output from this step? + +2. **Step Inputs** + - What information is needed to start this step? + - Does it need user-provided parameters? (e.g., topic, target audience) + - Does it need files from previous steps? + - What format should inputs be in? + +3. **Step Outputs** + - What files or artifacts does this step produce? + - What format should the output be in? (markdown, YAML, JSON, etc.) + - Where should each output be saved? (filename/path) + - Should outputs be organized in subdirectories? (e.g., `reports/`, `data/`, `drafts/`) + - Will other steps need this output? + +4. **Step Dependencies** + - Which previous steps must complete before this one? + - Are there any ordering constraints? + +5. **Step Process** (high-level understanding) + - What are the key activities in this step? + - Are there any quality checks or validation needed? + - What makes a good vs. bad output for this step? + +**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. + +### Step 3: Validate the Workflow + +After gathering information about all steps: + +1. **Review the flow** + - Summarize the complete workflow + - Show how outputs from one step feed into the next + - Ask if anything is missing + +2. **Check for gaps** + - Are there any steps where the input isn't clearly defined? + - Are there any outputs that aren't used by later steps? + - Are there circular dependencies? + +3. **Confirm details** + - Job name (lowercase, underscores, descriptive) + - Job summary (one clear sentence, max 200 chars) + - Job description (detailed multi-line explanation) + - Version number (start with 1.0.0) + +### Step 4: Create the job.yml Specification + +Only after you have complete understanding, create the `job.yml` file: + +**File Location**: `deepwork/[job_name]/job.yml` + +(Where `[job_name]` is the name of the NEW job you're creating, e.g., `deepwork/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] + +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 + + - 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 +``` + +**Important**: +- Use lowercase with underscores for job name and step IDs +- Ensure file inputs reference steps in dependencies +- No circular dependencies +- At least one output per step +- The `summary` should be concise (max 200 chars) +- The `description` should provide rich context for future refinement + +## Example Dialog + +``` +Claude: I'll help you define a new DeepWork job. Let's start by understanding what you're trying to accomplish. + +What complex task or workflow are you trying to create? What's the overall goal? + +User: I want to create competitive research reports for my company + +Claude: Great! Let's dig into that. A few questions: + +1. What's the final deliverable? Is it a written report, a presentation, or something else? +2. Who is the audience? Your team, executives, clients? +3. How comprehensive should these reports be? + +User: It's a written report for our product team. Should be comprehensive - analyzing 3-5 competitors. + +Claude: Perfect. Now let's think about the major phases of creating this report. What are the main stages you go through? For example: +- Identifying which competitors to analyze? +- Gathering information about them? +- Analyzing the data? +- Writing the report? + +Or is your process different? + +User: Yes, that's close. I would say: +1. Identify competitors +2. Research each one +3. Create comparison analysis +4. Write positioning recommendations + +Claude: Excellent! Now let's define each step in detail. Starting with "Identify competitors": + +1. What inputs do you need to start? Do you already have a market segment in mind, or do you need to specify that? +2. What should the output look like? A list of competitor names? More detailed? +3. How many competitors should be identified? + +User: I need to specify the market segment and product category as inputs. The output should be a markdown file with 5-7 competitors and brief descriptions of each. + +Claude: Perfect. A few more questions about that output: +1. What should the file be called? Something like `competitors_list.md`? +2. Should it go directly in the deepwork/competitive_research/ folder, or in a subdirectory like `research/` or `data/`? + +User: Just call it `competitors_list.md` in the main folder. + +Claude: Great. Now for the "Research each one" step: +1. Does it use the competitor list from the first step as input? +2. What kind of research - product features, pricing, marketing, all of the above? +3. What format should the research output be in? +4. Where should that research be saved? + +[continues for each step...] + +[After gathering all information:] + +Claude: Let me summarize the workflow I've designed based on our conversation: + +**Job: competitive_research** +Summary: Systematic competitive analysis workflow for product positioning + +Description: +A comprehensive workflow for analyzing competitors in your market segment. This job helps product teams understand the competitive landscape by systematically identifying competitors, researching their offerings, creating comparison matrices, and developing strategic positioning recommendations. + +The workflow produces: +- A vetted list of key competitors +- Detailed research notes on each competitor +- A comparison matrix highlighting key differentiators +- Strategic positioning recommendations + +Designed for product teams conducting quarterly competitive analysis. + +**Steps:** + +Step 1: identify_competitors +- Input: market_segment (user), product_category (user) +- Output: competitors_list.md (5-7 competitors with descriptions) + +Step 2: research_competitors +- Input: competitors_list.md (from step 1) +- Output: research_notes.md (detailed findings for each competitor) +- Depends on: identify_competitors + +Step 3: comparative_analysis +- Input: research_notes.md (from step 2) +- Output: comparison_matrix.md (side-by-side analysis) +- Depends on: research_competitors + +Step 4: positioning_recommendations +- Input: comparison_matrix.md (from step 3) +- Output: positioning_report.md (strategic recommendations) +- Depends on: comparative_analysis + +Does this accurately capture your workflow? Any changes needed? + +User: Yes, that's perfect! + +Claude: Great! Creating the job.yml specification now... + +[Creates deepwork/competitive_research/job.yml with the complete spec] + +✓ Job specification created! + +**File created:** +- deepwork/competitive_research/job.yml + +**Next step:** +Run `/deepwork_jobs.implement` to generate the instruction files for each step based on this specification. +``` + +## Important Guidelines + +1. **Focus on specification only** - Don't create instruction files yet +2. **Ask clarifying questions** - Never skip the discovery phase +3. **Rich context in description** - This helps with future refinement +4. **Validate understanding** - Summarize and confirm before creating +5. **Use examples** - Help users understand what good specifications look like +6. **Understand file organization** - Always ask where outputs should be saved and if subdirectories are needed + +## Validation Rules + +Before creating the job.yml, ensure: +- Job name: lowercase, underscores, no spaces +- Version: semantic versioning (1.0.0) +- Summary: concise, under 200 characters +- Description: detailed, provides context +- Step IDs: unique, descriptive, lowercase with underscores +- Dependencies: must reference existing step IDs +- File inputs: `from_step` must be in dependencies +- At least one output per step +- Outputs can be filenames (e.g., `report.md`) or paths (e.g., `reports/analysis.md`) +- File paths in outputs should match where files will actually be created +- No circular dependencies + +## Output Format + +### job.yml + +The complete YAML specification file (example shown in Step 4 above). + +**Location**: `deepwork/[job_name]/job.yml` + +(Where `[job_name]` is the name of the new job being created) + +After creating the file: +1. Commit it to the work branch +2. Inform the user that the specification is complete +3. Tell them to run `/deepwork_jobs.implement` next + +## Quality Criteria + +- User fully understands what job they're creating +- All steps have clear inputs and outputs +- Dependencies make logical sense +- Summary is concise and descriptive +- Description provides rich context for future refinement +- Specification is valid YAML and follows the schema +- Ready for implementation step diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md new file mode 100644 index 00000000..dd3f247a --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md @@ -0,0 +1,363 @@ +# Implement Job Steps + +## Objective + +Generate the DeepWork job directory structure and instruction files for each step based on the `job.yml` specification created in the previous step. + +## Task + +Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure, step instruction files, and registry entry. Then sync the commands to make them available. + +### Step 1: Read and Validate the Specification + +1. **Locate the job.yml file** + - Read `deepwork/[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) + - Parse the YAML content + +2. **Validate the specification** + - Ensure it follows the schema (name, version, summary, description, steps) + - Check that all dependencies reference existing steps + - Verify no circular dependencies + - Confirm file inputs match dependencies + +3. **Extract key information** + - Job name, version, summary, description + - 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` - Copy from work directory +- `.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 +] + +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] + +## Context + +[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture] +``` + +**Guidelines for generating instructions:** + +1. **Use the job description** - The detailed description from job.yml provides crucial context +2. **Be specific** - Don't write generic instructions; tailor them to the step's purpose +3. **Provide examples** - Show what good output looks like +4. **Explain the "why"** - Help the user understand the step's role in the workflow +5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones + +### Step 4: Copy job.yml to Job Directory + +Copy the validated `job.yml` from the work directory to `.deepwork/jobs/[job_name]/job.yml`: + +```bash +cp deepwork/[job_name]/job.yml .deepwork/jobs/[job_name]/job.yml +``` + +### Step 5: Register the Job + +Update `.deepwork/registry.yml` to register the new job: + +```yaml +jobs: + [job_name]: + version: "[version]" + summary: "[summary]" + path: "[job_name]" +``` + +**Important**: Don't overwrite existing jobs in the registry - add to it. + +### Step 6: Sync Commands + +Run `deepwork sync` to generate the slash-commands for this job: + +```bash +deepwork sync +``` + +This will: +- Parse the job definition +- Generate slash-commands for each step +- Make the commands available in `.claude/commands/` (or appropriate platform directory) + +### Step 7: Reload Commands + +Instruct the user to reload commands in their current session: +- Run `/reload` command (if available) +- Or restart the Claude session + +## 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. +``` + +## Important Guidelines + +1. **Read the spec carefully** - Understand the job's intent from the description +2. **Generate complete instructions** - Don't create placeholder or stub files +3. **Maintain consistency** - Use the same structure for all step instruction files +4. **Provide examples** - Show what good output looks like +5. **Use context** - The job description provides valuable context for each step +6. **Be specific** - Tailor instructions to the specific step, not generic advice + +## Validation Before Sync + +Before running `deepwork sync`, verify: +- All directories exist +- `job.yml` is in place +- All step instruction files exist (one per step) +- Registry is updated +- 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 ...] + +### Registry +- Updated `.deepwork/registry.yml` with job registration + +## 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**: Run `/reload` or restart your Claude session +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: +- [ ] job.yml validated and copied to job directory +- [ ] All step instruction files created +- [ ] Each instruction file is complete and actionable +- [ ] Registry updated with new job +- [ ] `deepwork sync` executed successfully +- [ ] Commands generated in platform directory +- [ ] User informed of next steps (reload commands) +- [ ] implementation_summary.md created + +## Quality Criteria + +- Job directory structure is correct +- All instruction files are complete (not stubs) +- Instructions are specific and actionable +- Output examples are provided in each instruction file +- Quality criteria defined for each step +- Registry properly updated +- Sync completed successfully +- Commands available for use diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md new file mode 100644 index 00000000..97b9d63e --- /dev/null +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md @@ -0,0 +1,358 @@ +# Refine Existing DeepWork Job + +## Objective + +Help the user modify an existing DeepWork job definition by understanding what they want to change and ensuring the modifications maintain consistency and validity. + +## Task + +Guide the user through refining a job by first understanding their existing job, then what they want to change, and finally implementing those changes safely. + +### Step 1: Select and Load Job + +1. **List available jobs** + - Read `.deepwork/registry.yml` + - Display installed jobs with versions and descriptions + - Ask which job to refine + +2. **Load job definition** + - Read `.deepwork/jobs/[job_name]/job.yml` + - Parse and understand the current structure + +3. **Show current structure** + - Display all steps with their names and descriptions + - Show the dependency flow + - Highlight key inputs and outputs + +### Step 2: Understand Desired Changes + +Ask the user what they want to change: + +**Change Options:** +1. Add a new step to the workflow +2. Modify step instructions +3. Change step inputs/outputs +4. Update dependencies between steps +5. Update job metadata (description, version) +6. Remove a step + +**For each change, ask clarifying questions:** +- Why do they want to make this change? +- How will it improve the workflow? +- Are there dependencies or side effects to consider? + +### Step 3: Make Changes Safely + +Based on the user's selection: + +#### Adding a Step + +1. **Gather step details** (same as define command) + - What does this step accomplish? + - What are the inputs? User parameters or file inputs? + - What outputs does it produce? + - What are the dependencies? + +2. **Determine placement** + - Where should it go in the workflow? + - Before which existing step? + - Or at the end? + +3. **Validate placement** + - Can't depend on later steps if inserted early + - File inputs must come from dependencies + - Check for circular dependencies + +4. **Create files** + - Update `job.yml` with new step + - Create step instructions file in `steps/[step_id].md` + +#### Modifying Step Instructions + +1. **Select step to modify** + - Show list of steps + - Ask which one to modify + +2. **Understand the change** + - What's not working with current instructions? + - What should be different? + - Show current instructions + +3. **Update instructions** + - Modify `.deepwork/jobs/[job_name]/steps/[step_id].md` + - Keep the same structure (Objective, Task, Process, Output Format, Quality Criteria) + +#### Changing Inputs/Outputs + +1. **Select step to modify** +2. **Show current inputs and outputs** +3. **Understand the change** + - Adding or removing? + - Why is this needed? + +4. **Validate impact** + - If removing output: check if other steps depend on it (BREAKING CHANGE) + - If adding file input: ensure from_step is in dependencies + - If removing input: ensure it's not critical + +5. **Update job.yml** + +#### Updating Dependencies + +1. **Select step to modify** +2. **Show current dependency graph** +3. **Understand the change** + - Adding or removing dependency? + - Why? + +4. **Validate** + - Check for circular dependencies + - Ensure all file inputs have matching dependencies + - Ensure dependency chain makes logical sense + +5. **Update job.yml** + +#### Updating Metadata + +1. **Ask what to change** + - Description? + - Version? + +2. **If version change, explain semantic versioning** + - Major (x.0.0): Breaking changes (removing steps, removing outputs) + - Minor (0.x.0): New features, backwards compatible (adding steps) + - Patch (0.0.x): Bug fixes, improvements + +3. **Update job.yml and registry.yml** + +#### Removing a Step + +1. **Select step to remove** + +2. **CRITICAL: Validate safety** + - Check if other steps depend on this step + - Check if other steps use outputs from this step + - If dependencies exist: **WARN** and suggest updating dependents first + - This is a BREAKING CHANGE - requires major version bump + +3. **If safe to remove** + - Remove from `job.yml` + - Delete step instructions file + - Suggest version bump + +### Step 4: Validate Changes + +After making changes: + +1. **Review the updated structure** + - Show the complete updated workflow + - Highlight what changed + - Check for consistency + +2. **Validate job definition** + - No circular dependencies + - All file inputs match dependencies + - All step IDs unique + - All outputs defined + +3. **Suggest version update** if not already done + - Breaking changes? Major version + - New features? Minor version + - Improvements? Patch version + +### Step 5: Sync and Reload + +1. **Run sync** + ```bash + deepwork sync + ``` + +2. **Reload commands** + - Instruct user to run `/reload` or restart session + +3. **Provide summary** + - Show what changed + - List updated files + - Explain next steps + +## Safe Modification Patterns + +Guide users toward safe changes: + +### Safe Changes (Always OK) +- Adding steps at the end with new outputs +- Updating step instructions (content only) +- Changing job description +- Adding user inputs to a step +- Adding outputs (not removing) +- Patch version bumps + +### Potentially Breaking Changes (Warn User) +- Removing steps +- Removing outputs +- Removing inputs +- Changing dependencies +- Renaming outputs (other steps may reference them) +- Requires major or minor version bump + +### Always Validate +- Circular dependencies after any dependency change +- File inputs match dependencies after any change +- Step IDs remain unique +- At least one output per step + +## Example Dialog + +``` +Claude: I'll help you refine an existing job. Here are your installed jobs: + +1. competitive_research v1.0.0 - Systematic competitive analysis workflow +2. blog_post v1.0.0 - Blog post creation workflow + +Which job would you like to refine? + +User: 1 + +Claude: Loading competitive_research v1.0.0... + +Current structure: +- Step 1: identify_competitors - Identify 5-7 competitors in target market +- Step 2: research_competitors - Deep research on each competitor +- Step 3: comparative_analysis - Side-by-side comparison matrix +- Step 4: positioning_recommendations - Strategic positioning report + +What would you like to change? +1. Add a new step +2. Modify step instructions +3. Change inputs/outputs +4. Update dependencies +5. Update job metadata +6. Remove a step + +User: 1 + +Claude: Great! Let's add a new step. First, help me understand: + +1. What should this new step accomplish? +2. Where should it fit in the workflow? + - Should it go between existing steps or at the end? + +User: I want to add a step that validates our product positioning before the final recommendations. It should go between step 3 and step 4. + +Claude: Excellent idea. So this would be: +- Step 4: validate_positioning +- Step 5: positioning_recommendations (renumbered) + +For this validation step: +1. What inputs does it need? I assume it needs the comparison_matrix.md from step 3? +2. What should it output? +3. What exactly should this validation check for? + +User: Yes, it needs the comparison matrix. It should output a validation_report.md that identifies gaps in our positioning. + +Claude: Perfect. Let me confirm the details: + +**New Step: validate_positioning** +- Name: "Validate Product Positioning" +- Description: "Identify gaps and opportunities in current positioning" +- Inputs: comparison_matrix.md (from comparative_analysis step) +- Outputs: validation_report.md +- Dependencies: comparative_analysis +- Position: Between step 3 and 4 + +Should the positioning_recommendations step also use the validation_report.md as input? + +User: Yes, definitely + +Claude: Great! So I'll also update the positioning_recommendations step to include validation_report.md as an input and add validate_positioning as a dependency. + +This is a new feature, so I'll bump the version to 1.1.0 (minor version). + +Creating the new step... ✓ + +Updated files: +- .deepwork/jobs/competitive_research/job.yml (added step, updated dependencies, version → 1.1.0) +- .deepwork/jobs/competitive_research/steps/validate_positioning.md (created) +- .deepwork/registry.yml (updated version) + +Now run: +```bash +deepwork sync +``` + +Then reload your session and you'll have: +- /competitive_research.validate_positioning (new!) +- All other commands updated +``` + +## Validation Rules + +Enforce the same rules as job definition: +- Job name: lowercase, underscores +- Version: semantic versioning +- Step IDs: unique within job +- Dependencies: must reference existing step IDs +- File inputs: `from_step` must be in dependencies +- At least one output per step +- No circular dependencies + +## Error Handling + +If issues arise, provide clear guidance: +- **Dependency conflict**: "Step X depends on step Y which you're trying to remove. You must update step X first, or remove both steps." +- **Circular dependency**: "Adding this dependency would create a cycle: A → B → C → A. Please choose a different dependency structure." +- **Missing file input**: "Step X requires file.md from step Y, but Y is not in its dependencies. I'll add Y to the dependencies." +- **Breaking change**: "Removing this output is a breaking change. Other steps depend on it. I recommend against this change unless you update the dependent steps first." + +## Output Format + +### refinement_summary.md + +```markdown +# Job Refinement: [job_name] + +## Changes Made + +### Version +[old_version] → [new_version] + +### Added Steps +- **[step_name]** (`[step_id]`) + - Purpose: [what it does] + - Inputs: [list] + - Outputs: [list] + - Position: After [previous_step] + +### Modified Steps +- **[step_name]** (`[step_id]`) + - Changed: [what changed] + - Reason: [why] + +### Updated Dependencies +- **[step_name]**: Added dependency on [other_step] + +### Removed +- [Anything removed] + +## Files Updated +- `.deepwork/jobs/[job_name]/job.yml` +- `.deepwork/jobs/[job_name]/steps/[step_id].md` +- `.deepwork/registry.yml` + +## Next Steps +1. Run `deepwork sync` to regenerate commands +2. Reload your Claude session (`/reload` or restart) +3. Test the updated workflow: `/[job_name].[first_step]` + +## Updated Command Reference +[List all commands with brief descriptions] +``` + +## Quality Criteria + +- Changes maintain job consistency +- Dependencies are logically valid +- Version bump follows semantic versioning +- No circular dependencies introduced +- User understands impact of changes +- Breaking changes are clearly communicated diff --git a/src/deepwork/templates/claude/command-define.md.jinja b/src/deepwork/templates/claude/command-define.md.jinja deleted file mode 100644 index 3a3494f2..00000000 --- a/src/deepwork/templates/claude/command-define.md.jinja +++ /dev/null @@ -1,197 +0,0 @@ ---- -description: Create a new DeepWork job definition ---- - -# Define a New DeepWork Job - -This command helps you create a new multi-step workflow (job) for DeepWork. - -## What is a Job? - -A job is a reusable, multi-step workflow that guides you through complex tasks. Examples: -- Competitive research -- Feature development -- Monthly reporting -- Ad campaign creation -- Research paper writing - -## Job Structure - -Each job consists of: -- **Job metadata**: Name, version, description -- **Steps**: Individual tasks with clear inputs and outputs -- **Dependencies**: Which steps must complete before others - -## Creating a Job - -### Step 1: Plan Your Workflow - -Think through the major phases of your work: -1. What are the distinct stages? -2. What outputs does each stage produce? -3. What dependencies exist between stages? - -### Step 2: Create Job Directory - -```bash -mkdir -p .deepwork/jobs/[job_name]/steps -``` - -### Step 3: Create job.yml - -Create `.deepwork/jobs/[job_name]/job.yml`: - -```yaml -name: [job_name] -version: "1.0.0" -description: "[Brief description of what this workflow accomplishes]" - -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] - # from_step: [previous_step_id] - outputs: - - [output_filename] - dependencies: [] # List of step IDs that must complete first - - - id: [another_step] - name: "[Another Step]" - description: "[What this step does]" - instructions_file: steps/[another_step].md - inputs: - - file: [output_filename] - from_step: [step_id] - outputs: - - [another_output] - dependencies: - - [step_id] # This step requires the previous step -``` - -### Step 4: Create Step Instructions - -For each step, create `.deepwork/jobs/[job_name]/steps/[step_id].md`: - -```markdown -# [Step Name] - -## Objective -[Clear statement of what this step accomplishes] - -## Task -[Detailed instructions for completing this step] - -### Process -1. [Substep 1] -2. [Substep 2] -3. [Substep 3] - -## Output Format - -### [output_filename] -[Description of the expected output] - -```markdown -[Example or template of the output] -``` - -## Quality Criteria -- [Quality check 1] -- [Quality check 2] -``` - -### Step 5: Validate and Sync - -```bash -# Sync to generate slash-commands -deepwork sync - -# Your commands will be available as: -# /[job_name].[step_id] -``` - -## Example - -Here's a simple two-step job: - -```yaml -name: blog_post -version: "1.0.0" -description: "Create a blog post from outline to final draft" - -steps: - - id: outline - name: "Create Outline" - description: "Create a structured outline for the blog post" - instructions_file: steps/outline.md - inputs: - - name: topic - description: "The blog post topic" - - name: target_audience - description: "Who is the target audience" - outputs: - - outline.md - dependencies: [] - - - id: draft - name: "Write Draft" - description: "Write the full blog post draft from the outline" - instructions_file: steps/draft.md - inputs: - - file: outline.md - from_step: outline - outputs: - - draft.md - dependencies: - - outline -``` - -## Tips - -- **Keep steps atomic**: Each step should do one thing well -- **Clear outputs**: Every step should produce reviewable artifacts -- **Logical dependencies**: Steps should build on each other -- **User parameters**: Use when you need information from the user -- **File inputs**: Use when you need outputs from previous steps - -## Validation Rules - -- Job name: lowercase, underscores allowed (e.g., `my_job`) -- Version: semantic versioning (e.g., `1.0.0`) -- Step IDs: unique within the job -- Dependencies: must reference existing step IDs -- File inputs: `from_step` must be in dependencies -- At least one output per step -- No circular dependencies - -## After Creating Your Job - -**IMPORTANT**: You MUST run `deepwork sync` to generate the slash-commands for this job. - -```bash -deepwork sync -``` - -This will: -- Parse the job definition -- Generate slash-commands for each step -- Make the commands available in your AI tool - -**After sync completes successfully**, reload the commands in the current Claude session: -- Type `/reload` to reload commands (if available), OR -- Restart the Claude session to pick up the new commands - -The job is then ready to use: -``` -/[job_name].[first_step_id] -``` - ---- - -Need help? Check `.deepwork/jobs/` for example jobs or see the DeepWork documentation. diff --git a/src/deepwork/templates/claude/command-job-step.md.jinja b/src/deepwork/templates/claude/command-job-step.md.jinja index 7b239bfe..fe371b90 100644 --- a/src/deepwork/templates/claude/command-job-step.md.jinja +++ b/src/deepwork/templates/claude/command-job-step.md.jinja @@ -6,7 +6,13 @@ description: {{ step_description }} **Step {{ step_number }} of {{ total_steps }}** in the **{{ job_name }}** workflow -**Job**: {{ job_description }} +**Summary**: {{ job_summary }} + +{% if job_description %} +## Job Overview + +{{ job_description }} +{% endif %} {% if dependencies %} ## Prerequisites @@ -41,7 +47,7 @@ Please gather the following information from the user: This step requires the following files from previous steps: {% for input in file_inputs %} - `{{ input.file }}` (from step `{{ input.from_step }}`) - Location: `work/[branch-name]/{{ input.file }}` + Location: `deepwork/{{ job_name }}/{{ input.file }}` {% endfor %} Make sure to read and use these files as context for this step. @@ -53,24 +59,24 @@ Make sure to read and use these files as context for this step. All work for this job should be done on a dedicated work branch: 1. **Check current branch**: - - If already on a work branch for this job (format: `work/{{ job_name }}-[instance]-[date]`), continue using it + - If already on a work branch for this job (format: `deepwork/{{ job_name }}-[instance]-[date]`), continue using it - If on main/master, create a new work branch 2. **Create work branch** (if needed): ```bash - git checkout -b work/{{ job_name }}-[instance]-$(date +%Y%m%d) + git checkout -b deepwork/{{ job_name }}-[instance]-$(date +%Y%m%d) ``` Replace `[instance]` with a descriptive identifier (e.g., `acme`, `q1-launch`, etc.) 3. **All outputs go in the work directory**: - - Create files in: `work/[branch-name]/` - - This keeps work products organized and reviewable + - Create files in: `deepwork/{{ job_name }}/` + - This keeps work products organized by job ## Output Requirements Create the following output(s) in the work directory: {% for output in outputs %} -- `work/[branch-name]/{{ output }}`{% if output.endswith('/') %} (directory){% endif %} +- `deepwork/{{ job_name }}/{{ output }}`{% if output.endswith('/') %} (directory){% endif %} {% endfor %} Ensure all outputs are: @@ -84,7 +90,7 @@ After completing this step: 1. **Commit your work**: ```bash - git add work/[branch-name]/ + git add deepwork/{{ job_name }}/ git commit -m "{{ job_name }}: Complete {{ step_id }} step" ``` @@ -112,7 +118,7 @@ To continue the workflow, run: This is the final step in the {{ job_name }} workflow. All outputs should now be complete and ready for review. Consider: -- Reviewing all work products in `work/[branch-name]/` +- Reviewing all work products in `deepwork/{{ job_name }}/` - Creating a pull request to merge the work branch - Documenting any insights or learnings {% endif %} diff --git a/src/deepwork/templates/claude/command-refine.md.jinja b/src/deepwork/templates/claude/command-refine.md.jinja deleted file mode 100644 index 1a2f15fb..00000000 --- a/src/deepwork/templates/claude/command-refine.md.jinja +++ /dev/null @@ -1,236 +0,0 @@ ---- -description: Refine and update existing job definitions ---- - -# Refine Existing DeepWork Job - -This command helps you modify existing DeepWork jobs. You can: -- Add new steps to a workflow -- Modify step instructions -- Update inputs/outputs -- Adjust dependencies -- Change job metadata (description, version) - -## Instructions - -You will help the user refine an existing job definition. Follow this process: - -### Step 1: Select Job to Refine - -1. **List available jobs**: - Read `.deepwork/registry.yml` to show installed jobs: - ``` - Available jobs: - 1. competitive_research v1.0.0 - Systematic competitive analysis workflow - 2. ad_campaign v1.0.0 - Marketing campaign planning - ``` - -2. **Ask user which job to refine** - -3. **Load job definition**: - Read `.deepwork/jobs/[job_name]/job.yml` - -4. **Show current structure**: - ``` - Job: [name] v[version] - Description: [description] - - Steps: - 1. [step1] - [description] - 2. [step2] - [description] - ... - ``` - -### Step 2: Determine Changes - -Ask the user what they'd like to change: - -**Options**: -1. **Add a new step** - Insert or append a step to the workflow -2. **Modify step instructions** - Update the .md file for a step -3. **Change step inputs/outputs** - Modify what a step consumes or produces -4. **Update dependencies** - Adjust the dependency graph -5. **Update job metadata** - Change description or version -6. **Remove a step** - Delete a step (with validation) - -### Step 3: Make Changes - -Based on the user's selection: - -#### Adding a Step - -1. Ask for step details (same as define wizard) -2. Ask where to insert: "Before which step?" or "At the end?" -3. Validate dependencies (can't depend on later steps if inserted early) -4. Update job.yml -5. Create new step instructions file - -#### Modifying Step Instructions - -1. Ask which step to modify -2. Read current `.deepwork/jobs/[job_name]/steps/[step_id].md` -3. Ask user how to modify (or read their changes) -4. Update the markdown file - -#### Changing Inputs/Outputs - -1. Ask which step to modify -2. Show current inputs and outputs -3. Ask what changes to make -4. Validate: - - File inputs must reference existing dependencies - - If removing an output, check if other steps depend on it -5. Update job.yml - -#### Updating Dependencies - -1. Ask which step to modify -2. Show current dependencies -3. Ask what changes to make -4. Validate: - - No circular dependencies - - All file inputs match dependencies -5. Update job.yml - -#### Updating Metadata - -1. Ask what to change (description and/or version) -2. If version changes, follow semantic versioning: - - Major: Breaking changes - - Minor: New features, backwards compatible - - Patch: Bug fixes -3. Update job.yml -4. Update registry entry - -#### Removing a Step - -1. Ask which step to remove -2. **Validate safety**: - - Check if other steps depend on this step - - Check if other steps use outputs from this step - - If dependencies exist, warn user and suggest updating dependents first -3. If safe, remove: - - Remove from job.yml - - Delete step instructions file - -### Step 4: Sync and Reload Commands - -**IMPORTANT**: After making any changes, you MUST run sync to regenerate the slash-commands: - -```bash -deepwork sync -``` - -This will: -- Parse the updated job definition -- Regenerate all slash-commands for this job -- Update commands in `.claude/commands/` - -**After sync completes successfully**, reload the commands in the current Claude session: -- Type `/reload` to reload commands (if available), OR -- Restart the Claude session to pick up the new commands - -### Step 5: Confirm Changes - -Show summary of changes: -``` -✓ Job "[job_name]" has been updated! - -Changes made: -- Added new step: [step_id] -- Modified step: [step_id] -- Updated version: [old] → [new] - -Files updated: -- .deepwork/jobs/[job_name]/job.yml -- .deepwork/jobs/[job_name]/steps/[step_id].md - -Commands regenerated via sync. Reload your Claude session to use the updated commands. - -To test the changes, run: -/[job_name].[first_step_id] -``` - -## Validation Rules - -Enforce all the same rules as the define wizard, plus: - -1. **Version updates**: Follow semantic versioning conventions -2. **Dependency safety**: When removing/modifying steps, check impact on dependent steps -3. **Output safety**: Warn if removing outputs that other steps consume -4. **Step ordering**: If inserting steps, validate dependency order - -## Safe Modification Patterns - -Guide users toward safe changes: - -### Safe Changes (Always OK) -- Adding steps at the end with new outputs -- Updating step instructions (content) -- Changing job description -- Adding user inputs to a step -- Adding outputs (not removing) - -### Potentially Breaking Changes (Warn User) -- Removing steps -- Removing outputs -- Changing dependencies -- Renaming outputs (other steps may reference them) -- Major version bumps - -### Always Validate -- Circular dependencies after any dependency change -- File inputs match dependencies after any change -- Step IDs remain unique - -## Error Handling - -If issues arise: -- **Dependency conflict**: "Step X depends on step Y which you're trying to remove. Update X first." -- **Circular dependency**: "Adding this dependency would create a cycle: A → B → C → A" -- **Missing file input**: "Step X requires file.md from step Y, but Y is not in its dependencies" - -## Example Usage - -``` -User: /deepwork.refine_job - -Claude: I'll help you refine an existing job. Here are your installed jobs: - -1. competitive_research v1.0.0 - Systematic competitive analysis workflow -2. product_launch v1.0.0 - End-to-end product launch planning - -Which job would you like to refine? - -User: 1 - -Claude: Loading competitive_research... - -Current structure: -- Step 1: identify_competitors -- Step 2: primary_research -- Step 3: secondary_research -- Step 4: comparative_report - -What would you like to do? -1. Add a new step -2. Modify step instructions -3. Change inputs/outputs -4. Update dependencies -5. Update job metadata -6. Remove a step - -User: 1 - -Claude: Great! Let's add a new step. Where would you like to insert it? -[continues interactive dialog] -``` - ---- - -## Context Files - -- Job schema: `src/deepwork/schemas/job_schema.py` -- Job parser: `src/deepwork/core/parser.py` -- Registry: `.deepwork/registry.yml` -- Template: `src/deepwork/templates/claude/command-job-step.md.jinja` diff --git a/src/deepwork/templates/claude/skill-deepwork.define.md.jinja b/src/deepwork/templates/claude/skill-deepwork.define.md.jinja deleted file mode 100644 index bd89b460..00000000 --- a/src/deepwork/templates/claude/skill-deepwork.define.md.jinja +++ /dev/null @@ -1,191 +0,0 @@ -Name: deepwork.define -Description: Interactive job definition wizard - -## Overview - -This skill helps you define a new DeepWork job by guiding you through an interactive process to specify: -- Job metadata (name, description, version) -- Workflow steps -- Step inputs (user parameters and file dependencies) -- Step outputs -- Dependencies between steps - -The result is a complete job definition stored in `.deepwork/jobs/[job_name]/` with generated skill files. - -## Instructions - -You will guide the user through defining a new multi-step workflow. Follow this process: - -### Step 1: Job Metadata - -Ask the user for: -1. **Job name**: A descriptive name (lowercase, underscores allowed, e.g., `competitive_research`, `ad_campaign`) -2. **Job description**: Brief description of what this workflow accomplishes -3. **Initial version**: Semantic version (default: `1.0.0`) - -Validate: -- Job name matches pattern: `^[a-z][a-z0-9_]*$` -- Description is clear and concise -- Version follows semantic versioning (X.Y.Z) - -### Step 2: Define Steps - -For each step in the workflow, ask: - -1. **Step ID**: Unique identifier (e.g., `identify_competitors`) -2. **Step name**: Human-readable name (e.g., `Identify Competitors`) -3. **Step description**: What this step accomplishes -4. **Inputs**: - - User parameters: Information the user needs to provide (name + description) - - File inputs: Files from previous steps (filename + source step ID) -5. **Outputs**: Files or directories this step produces -6. **Dependencies**: Which previous steps must be completed first - -Continue asking "Would you like to add another step?" until the user is done. - -### Step 3: Review and Confirm - -Present a summary of the job definition: - -``` -Job: [name] v[version] -Description: [description] - -Steps: -1. [step_name] (id: [step_id]) - - Inputs: [list inputs] - - Outputs: [list outputs] - - Dependencies: [list deps or "None"] - -2. [step_name] (id: [step_id]) - ... -``` - -Ask the user to confirm or make changes. - -### Step 4: Create Job Definition - -1. **Create directory structure**: - ``` - .deepwork/jobs/[job_name]/ - ├── job.yml - └── steps/ - ├── [step1_id].md - ├── [step2_id].md - └── ... - ``` - -2. **Generate job.yml**: - ```yaml - name: [job_name] - version: "[version]" - description: "[description]" - - steps: - - id: [step_id] - name: "[step_name]" - description: "[step_description]" - instructions_file: steps/[step_id].md - inputs: - - name: [param_name] - description: "[param_description]" - # or - - file: [filename] - from_step: [step_id] - outputs: - - [output_file] - dependencies: - - [dep_step_id] - ``` - -3. **Create step instruction files**: - For each step, create `.deepwork/jobs/[job_name]/steps/[step_id].md`: - ```markdown - # [Step Name] - - ## Objective - [Brief objective - ask user or generate from description] - - ## Task - [Detailed instructions - ask user to provide or help them write] - - ## Output Format - [Expected format of outputs] - ``` - -4. **Generate skill files**: - For each step, generate `.claude/skill-[job_name].[step_id].md` using the job-step template. - -### Step 5: Installation Complete - -Inform the user: -``` -✓ Job "[job_name]" v[version] has been defined! - -Files created: -- .deepwork/jobs/[job_name]/job.yml -- .deepwork/jobs/[job_name]/steps/[step1].md -- .deepwork/jobs/[job_name]/steps/[step2].md -- ... -- .claude/skill-[job_name].[step1].md -- .claude/skill-[job_name].[step2].md -- ... - -To start using this job, run: -/[job_name].[first_step_id] -``` - -## Validation Rules - -Enforce these rules during the definition process: - -1. **Job name**: `^[a-z][a-z0-9_]*$` (lowercase, start with letter) -2. **Version**: `^\\d+\\.\\d+\\.\\d+$` (semantic versioning) -3. **Step IDs**: Must be unique within the job -4. **Dependencies**: Must reference existing step IDs -5. **File inputs**: Must reference `from_step` that exists in dependencies -6. **Outputs**: At least one output per step -7. **No circular dependencies**: Validate dependency graph is acyclic - -## Tips for Users - -Provide helpful guidance: -- "Start by identifying the major phases of your workflow" -- "Each step should produce concrete, reviewable outputs" -- "User parameters are for information you don't know yet (market segment, dates, etc.)" -- "File inputs are for using outputs from previous steps" -- "Dependencies ensure steps run in the right order" - -## Error Handling - -If validation fails: -- Explain the specific issue clearly -- Suggest a fix -- Allow the user to retry or modify their input - -## Example Usage - -``` -User: /deepwork.define - -Claude: I'll help you define a new DeepWork job! This will create a multi-step workflow you can use repeatedly. - -Let's start with the basics: -1. What would you like to call this job? (e.g., competitive_research, ad_campaign) - -User: product_launch - -Claude: Great! Now, what does this workflow accomplish? Provide a brief description. - -User: End-to-end product launch planning and execution - -Claude: Perfect! I'll use version 1.0.0. Now let's define the steps... -[continues interactive dialog] -``` - ---- - -## Context Files - -- Job schema: `src/deepwork/schemas/job_schema.py` -- Template: `src/deepwork/templates/claude/skill-job-step.md.jinja` diff --git a/tests/conftest.py b/tests/conftest.py index e3ca0f2b..ffb6554a 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -1,8 +1,8 @@ """Pytest configuration and shared fixtures.""" import tempfile +from collections.abc import Iterator from pathlib import Path -from typing import Iterator import pytest from git import Repo diff --git a/tests/integration/test_full_workflow.py b/tests/integration/test_full_workflow.py index 39d4e084..d01af079 100644 --- a/tests/integration/test_full_workflow.py +++ b/tests/integration/test_full_workflow.py @@ -2,21 +2,18 @@ from pathlib import Path -import pytest - from deepwork.core.detector import PLATFORMS from deepwork.core.generator import SkillGenerator from deepwork.core.parser import parse_job_definition -from deepwork.core.registry import JobRegistry class TestJobWorkflow: """Integration tests for complete job workflow.""" - def test_parse_register_generate_workflow( + def test_parse_and_generate_workflow( self, fixtures_dir: Path, temp_dir: Path ) -> None: - """Test complete workflow: parse job → register → generate skills.""" + """Test complete workflow: parse job → generate skills.""" # Step 1: Parse job definition job_dir = fixtures_dir / "jobs" / "complex_job" job = parse_job_definition(job_dir) @@ -24,18 +21,7 @@ def test_parse_register_generate_workflow( assert job.name == "competitive_research" assert len(job.steps) == 4 - # Step 2: Register job - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - entry = registry.register_job( - job.name, job.version, job.description, str(job_dir) - ) - - assert entry.name == job.name - assert registry.is_registered(job.name) - - # Step 3: Generate skills + # Step 2: Generate skills generator = SkillGenerator() platform = PLATFORMS["claude"] skills_dir = temp_dir / ".claude" @@ -56,11 +42,6 @@ def test_parse_register_generate_workflow( # Check step numbers assert f"step {i+1} of 4" in content - # Step 4: Verify can read registry - loaded_entry = registry.get_job(job.name) - assert loaded_entry is not None - assert loaded_entry.version == job.version - def test_simple_job_workflow(self, fixtures_dir: Path, temp_dir: Path) -> None: """Test workflow with simple single-step job.""" # Parse @@ -69,11 +50,6 @@ def test_simple_job_workflow(self, fixtures_dir: Path, temp_dir: Path) -> None: assert len(job.steps) == 1 - # Register - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - registry.register_job(job.name, job.version, job.description, str(job_dir)) - # Generate generator = SkillGenerator() platform = PLATFORMS["claude"] @@ -91,48 +67,6 @@ def test_simple_job_workflow(self, fixtures_dir: Path, temp_dir: Path) -> None: assert "input_param" in content assert "Workflow Complete" in content # Final step message - def test_multiple_jobs_registration(self, fixtures_dir: Path, temp_dir: Path) -> None: - """Test registering multiple jobs.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - # Parse and register first job - job1_dir = fixtures_dir / "jobs" / "simple_job" - job1 = parse_job_definition(job1_dir) - registry.register_job(job1.name, job1.version, job1.description, str(job1_dir)) - - # Parse and register second job - job2_dir = fixtures_dir / "jobs" / "complex_job" - job2 = parse_job_definition(job2_dir) - registry.register_job(job2.name, job2.version, job2.description, str(job2_dir)) - - # List all jobs - jobs = registry.list_jobs() - assert len(jobs) == 2 - - # Jobs should be sorted by name - assert jobs[0].name == "competitive_research" - assert jobs[1].name == "simple_job" - - def test_job_update_workflow(self, fixtures_dir: Path, temp_dir: Path) -> None: - """Test updating a registered job.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - # Register job - job_dir = fixtures_dir / "jobs" / "simple_job" - job = parse_job_definition(job_dir) - registry.register_job(job.name, job.version, job.description, str(job_dir)) - - # Update version - updated = registry.update_job(job.name, version="2.0.0") - assert updated.version == "2.0.0" - - # Verify update persisted - loaded = registry.get_job(job.name) - assert loaded is not None - assert loaded.version == "2.0.0" - def test_skill_generation_with_dependencies( self, fixtures_dir: Path, temp_dir: Path ) -> None: diff --git a/tests/integration/test_install_flow.py b/tests/integration/test_install_flow.py index 51874da8..26bc9b80 100644 --- a/tests/integration/test_install_flow.py +++ b/tests/integration/test_install_flow.py @@ -2,11 +2,9 @@ from pathlib import Path -import pytest from click.testing import CliRunner from deepwork.cli.main import cli -from deepwork.core.registry import JobRegistry from deepwork.utils.yaml_utils import load_yaml @@ -42,10 +40,6 @@ def test_install_with_claude(self, mock_claude_project: Path) -> None: assert config["version"] == "1.0.0" assert "installed" in config - # Verify registry.yml - registry_file = deepwork_dir / "registry.yml" - assert registry_file.exists() - # Verify core skills were created claude_dir = mock_claude_project / ".claude" assert (claude_dir / "skill-deepwork.define.md").exists() @@ -122,24 +116,6 @@ def test_install_with_specified_platform_when_missing( assert "Claude Code not detected" in result.output assert ".claude/" in result.output - def test_install_creates_empty_registry(self, mock_claude_project: Path) -> None: - """Test that install creates an empty job registry.""" - runner = CliRunner() - - result = runner.invoke( - cli, ["install", "--platform", "claude", "--path", str(mock_claude_project)], - catch_exceptions=False - ) - - assert result.exit_code == 0 - - # Check registry is created and empty - deepwork_dir = mock_claude_project / ".deepwork" - registry = JobRegistry(deepwork_dir) - jobs = registry.list_jobs() - - assert jobs == [] - def test_install_is_idempotent(self, mock_claude_project: Path) -> None: """Test that running install multiple times is safe.""" runner = CliRunner() @@ -161,7 +137,6 @@ def test_install_is_idempotent(self, mock_claude_project: Path) -> None: # Verify files still exist and are valid deepwork_dir = mock_claude_project / ".deepwork" assert (deepwork_dir / "config.yml").exists() - assert (deepwork_dir / "registry.yml").exists() claude_dir = mock_claude_project / ".claude" assert (claude_dir / "skill-deepwork.define.md").exists() diff --git a/tests/unit/test_detector.py b/tests/unit/test_detector.py index 927edab0..0264c4b3 100644 --- a/tests/unit/test_detector.py +++ b/tests/unit/test_detector.py @@ -7,7 +7,6 @@ from deepwork.core.detector import ( PLATFORMS, DetectorError, - PlatformConfig, PlatformDetector, ) diff --git a/tests/unit/test_registry.py b/tests/unit/test_registry.py deleted file mode 100644 index a88a2df5..00000000 --- a/tests/unit/test_registry.py +++ /dev/null @@ -1,252 +0,0 @@ -"""Tests for job registry.""" - -from pathlib import Path - -import pytest - -from deepwork.core.registry import JobRegistry, JobRegistryEntry, RegistryError - - -class TestJobRegistryEntry: - """Tests for JobRegistryEntry dataclass.""" - - def test_to_dict(self) -> None: - """Test converting entry to dictionary.""" - entry = JobRegistryEntry( - name="test_job", - version="1.0.0", - description="Test job", - job_dir="jobs/test_job", - installed_at="2026-01-09T10:00:00", - ) - - result = entry.to_dict() - - assert result["name"] == "test_job" - assert result["version"] == "1.0.0" - assert result["description"] == "Test job" - assert result["job_dir"] == "jobs/test_job" - assert result["installed_at"] == "2026-01-09T10:00:00" - - def test_from_dict(self) -> None: - """Test creating entry from dictionary.""" - data = { - "name": "test_job", - "version": "1.0.0", - "description": "Test job", - "job_dir": "jobs/test_job", - "installed_at": "2026-01-09T10:00:00", - } - - entry = JobRegistryEntry.from_dict(data) - - assert entry.name == "test_job" - assert entry.version == "1.0.0" - assert entry.description == "Test job" - assert entry.job_dir == "jobs/test_job" - assert entry.installed_at == "2026-01-09T10:00:00" - - -class TestJobRegistry: - """Tests for JobRegistry class.""" - - def test_register_job(self, temp_dir: Path) -> None: - """Test registering a new job.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - entry = registry.register_job( - name="test_job", - version="1.0.0", - description="A test job", - job_dir="jobs/test_job", - ) - - assert entry.name == "test_job" - assert entry.version == "1.0.0" - assert entry.description == "A test job" - assert entry.job_dir == "jobs/test_job" - assert entry.installed_at is not None - - def test_register_creates_deepwork_dir(self, temp_dir: Path) -> None: - """Test that register_job creates .deepwork directory.""" - deepwork_dir = temp_dir / ".deepwork" - assert not deepwork_dir.exists() - - registry = JobRegistry(deepwork_dir) - registry.register_job("test_job", "1.0.0", "Test", "jobs/test_job") - - assert deepwork_dir.exists() - assert (deepwork_dir / "registry.yml").exists() - - def test_register_raises_for_duplicate(self, temp_dir: Path) -> None: - """Test that registering duplicate job raises error.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - registry.register_job("test_job", "1.0.0", "Test", "jobs/test_job") - - with pytest.raises(RegistryError, match="already registered"): - registry.register_job("test_job", "2.0.0", "Test again", "jobs/test_job") - - def test_unregister_job(self, temp_dir: Path) -> None: - """Test unregistering a job.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - registry.register_job("test_job", "1.0.0", "Test", "jobs/test_job") - assert registry.is_registered("test_job") - - registry.unregister_job("test_job") - - assert not registry.is_registered("test_job") - - def test_unregister_raises_for_nonexistent(self, temp_dir: Path) -> None: - """Test that unregistering nonexistent job raises error.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - with pytest.raises(RegistryError, match="not registered"): - registry.unregister_job("nonexistent") - - def test_get_job(self, temp_dir: Path) -> None: - """Test getting a registered job.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - registry.register_job("test_job", "1.0.0", "Test", "jobs/test_job") - - entry = registry.get_job("test_job") - - assert entry is not None - assert entry.name == "test_job" - assert entry.version == "1.0.0" - - def test_get_job_returns_none_for_nonexistent(self, temp_dir: Path) -> None: - """Test that get_job returns None for nonexistent job.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - entry = registry.get_job("nonexistent") - - assert entry is None - - def test_list_jobs_empty(self, temp_dir: Path) -> None: - """Test listing jobs when registry is empty.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - jobs = registry.list_jobs() - - assert jobs == [] - - def test_list_jobs_multiple(self, temp_dir: Path) -> None: - """Test listing multiple registered jobs.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - registry.register_job("job_c", "1.0.0", "Job C", "jobs/job_c") - registry.register_job("job_a", "1.0.0", "Job A", "jobs/job_a") - registry.register_job("job_b", "1.0.0", "Job B", "jobs/job_b") - - jobs = registry.list_jobs() - - assert len(jobs) == 3 - # Should be sorted by name - assert jobs[0].name == "job_a" - assert jobs[1].name == "job_b" - assert jobs[2].name == "job_c" - - def test_is_registered(self, temp_dir: Path) -> None: - """Test checking if job is registered.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - assert not registry.is_registered("test_job") - - registry.register_job("test_job", "1.0.0", "Test", "jobs/test_job") - - assert registry.is_registered("test_job") - - def test_update_job_version(self, temp_dir: Path) -> None: - """Test updating job version.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - registry.register_job("test_job", "1.0.0", "Test", "jobs/test_job") - - updated = registry.update_job("test_job", version="2.0.0") - - assert updated.version == "2.0.0" - assert registry.get_job("test_job").version == "2.0.0" # type: ignore - - def test_update_job_description(self, temp_dir: Path) -> None: - """Test updating job description.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - registry.register_job("test_job", "1.0.0", "Old description", "jobs/test_job") - - updated = registry.update_job("test_job", description="New description") - - assert updated.description == "New description" - assert registry.get_job("test_job").description == "New description" # type: ignore - - def test_update_job_both(self, temp_dir: Path) -> None: - """Test updating both version and description.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - registry.register_job("test_job", "1.0.0", "Old", "jobs/test_job") - - updated = registry.update_job( - "test_job", version="2.0.0", description="New description" - ) - - assert updated.version == "2.0.0" - assert updated.description == "New description" - - def test_update_job_raises_for_nonexistent(self, temp_dir: Path) -> None: - """Test that updating nonexistent job raises error.""" - deepwork_dir = temp_dir / ".deepwork" - registry = JobRegistry(deepwork_dir) - - with pytest.raises(RegistryError, match="not registered"): - registry.update_job("nonexistent", version="2.0.0") - - def test_persistence_across_instances(self, temp_dir: Path) -> None: - """Test that registry persists across instances.""" - deepwork_dir = temp_dir / ".deepwork" - - # First instance - registry1 = JobRegistry(deepwork_dir) - registry1.register_job("test_job", "1.0.0", "Test", "jobs/test_job") - - # Second instance - registry2 = JobRegistry(deepwork_dir) - jobs = registry2.list_jobs() - - assert len(jobs) == 1 - assert jobs[0].name == "test_job" - - def test_handles_empty_registry_file(self, temp_dir: Path) -> None: - """Test that registry handles empty registry file.""" - deepwork_dir = temp_dir / ".deepwork" - deepwork_dir.mkdir() - (deepwork_dir / "registry.yml").write_text("") - - registry = JobRegistry(deepwork_dir) - jobs = registry.list_jobs() - - assert jobs == [] - - def test_handles_missing_jobs_key(self, temp_dir: Path) -> None: - """Test that registry handles missing 'jobs' key in file.""" - deepwork_dir = temp_dir / ".deepwork" - deepwork_dir.mkdir() - (deepwork_dir / "registry.yml").write_text("other_key: value\n") - - registry = JobRegistry(deepwork_dir) - jobs = registry.list_jobs() - - assert jobs == [] From c6b6340937790d129713bf5e61f6815fb3993cc7 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Sun, 11 Jan 2026 18:57:47 -0700 Subject: [PATCH 2/3] doc updates --- claude.md | 88 +++---- doc/architecture.md | 545 ++++++++++++++++++++++++-------------------- 2 files changed, 333 insertions(+), 300 deletions(-) diff --git a/claude.md b/claude.md index 7bdab5e6..7c5b1228 100644 --- a/claude.md +++ b/claude.md @@ -36,16 +36,18 @@ Each job consists of reviewable steps with clear inputs and outputs. For example ``` deepwork/ ├── src/deepwork/ -│ ├── cli/ # CLI commands (install, etc.) -│ ├── core/ # Core logic (project init, detection, generation) -│ ├── templates/ # Skill templates per AI platform +│ ├── cli/ # CLI commands (install, sync) +│ ├── core/ # Core logic (detection, generation, parsing) +│ ├── templates/ # Command templates per AI platform │ │ ├── claude/ │ │ ├── gemini/ │ │ └── copilot/ +│ ├── standard_jobs/ # Built-in job definitions +│ │ └── deepwork_jobs/ │ ├── schemas/ # Job definition schemas -│ └── utils/ # Utilities (git, yaml, validation) +│ └── utils/ # Utilities (fs, git, yaml, validation) ├── tests/ # Test suite -├── docs/ # Documentation +├── doc/ # Documentation └── doc/architecture.md # Detailed architecture document ``` @@ -80,21 +82,28 @@ cd my-project/ deepwork install --claude ``` -This installs core skills into `.claude/`: -- `deepwork.define` - Interactive job definition wizard -- `deepwork.refine` - Refine existing job definitions +This installs core commands into `.claude/commands/`: +- `deepwork_jobs.define` - Interactive job definition wizard +- `deepwork_jobs.implement` - Generates step files and syncs commands +- `deepwork_jobs.refine` - Refine existing job definitions ### 2. Job Definition Users define jobs via Claude Code: ``` -/deepwork.define +/deepwork_jobs.define ``` The agent guides you through defining: - Job name and description - Steps with inputs/outputs - Dependencies between steps -- Instructions for each step + +This creates the `job.yml` file. Then run: +``` +/deepwork_jobs.implement +``` + +This generates step instruction files and syncs commands to `.claude/commands/`. Job definitions are stored in `.deepwork/jobs/[job-name]/` and tracked in Git. @@ -105,13 +114,13 @@ Execute jobs via slash commands in Claude Code: ``` Each step: -- Creates/uses a work branch (`work/[job-name]-[instance]`) +- Creates/uses a work branch (`deepwork/[job-name]-[instance]-[date]`) - Reads inputs from previous steps - Generates outputs for review - Suggests next step ### 4. Work Completion -- Review outputs in `work/[branch-name]/` +- Review outputs in `deepwork/[branch-name]/` - Commit artifacts as you progress - Create PR for team review - Merge to preserve work products for future context @@ -121,53 +130,27 @@ Each step: ``` my-project/ ├── .git/ -├── .claude/ # Claude Code skills -│ ├── skill-deepwork.define.md -│ ├── skill-deepwork.refine.md -│ └── skill-[job].[step].md +├── .claude/ # Claude Code directory +│ └── commands/ # Command files +│ ├── deepwork_jobs.define.md +│ ├── deepwork_jobs.implement.md +│ ├── deepwork_jobs.refine.md +│ └── [job].[step].md ├── .deepwork/ # DeepWork configuration -│ ├── config.yml +│ ├── config.yml # version, platforms[] │ └── jobs/ +│ ├── deepwork_jobs/ # Built-in job +│ │ ├── job.yml +│ │ └── steps/ │ └── [job-name]/ │ ├── job.yml │ └── steps/ │ └── [step].md -└── work/ # Work products (on branches) - └── [job-name]-[instance]/ +└── deepwork/ # Work products (on branches) + └── [job-name]-[instance]-[date]/ └── [outputs].md ``` -## Implementation Phases - -### Phase 1: Core Runtime (Current) -- [ ] Project structure and build system -- [ ] Job definition parser -- [ ] Registry implementation -- [ ] Basic Git integration -- [ ] Template renderer -- [ ] Unit tests for core components - -### Phase 2: CLI and Installation -- [ ] CLI command framework -- [ ] `install` command with platform detection -- [ ] `define` command with interactive wizard -- [ ] Integration tests - -### Phase 3: Runtime Engine -- [ ] Step execution engine -- [ ] Context preparation and injection -- [ ] Output validation system -- [ ] State management - -### Phase 4: AI Platform Integration -- [ ] Claude Code skill generation -- [ ] Gemini command generation -- [ ] Platform-specific templates - -### Phase 5: Job Ecosystem -- [ ] Reference job definitions -- [ ] Job validation tools -- [ ] Documentation and examples ## Key Files to Reference @@ -183,10 +166,7 @@ my-project/ 4. **Testing**: Write tests for new functionality 5. **Type Safety**: Use type hints for better code quality 6. **No Auto-Commit**: DO NOT automatically commit changes to git. Let the user review and commit changes themselves. - -## Current Status - -The project is in early development (Phase 1). The architecture is defined, and we're building the core runtime components. +7. **Documentation Sync**: CRITICAL - When making implementation changes, always update `doc/architecture.md` and `README.md` to reflect those changes. The architecture document must stay in sync with the actual codebase (terminology, file paths, structure, behavior, etc.). ## Success Metrics diff --git a/doc/architecture.md b/doc/architecture.md index 62c8ab29..865e0fc8 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -38,43 +38,48 @@ deepwork/ # DeepWork tool repository │ └── deepwork/ │ ├── cli/ │ │ ├── __init__.py -│ │ ├── install.py # Main install command -│ │ └── commands.py # Other CLI commands +│ │ ├── main.py # CLI entry point +│ │ ├── install.py # Install command +│ │ └── sync.py # Sync command │ ├── core/ -│ │ ├── project.py # Project initialization │ │ ├── detector.py # AI platform detection -│ │ └── generator.py # Skill file generation -│ ├── templates/ # Skill templates for each platform +│ │ ├── generator.py # Command file generation +│ │ └── parser.py # Job definition parsing +│ ├── templates/ # Command templates for each platform │ │ ├── claude/ -│ │ │ ├── skill-deepwork.define.md -│ │ │ ├── skill-deepwork.refine.md -│ │ │ └── skill-job-step.md.jinja +│ │ │ └── command-job-step.md.jinja │ │ ├── gemini/ │ │ └── copilot/ +│ ├── standard_jobs/ # Built-in job definitions +│ │ └── deepwork_jobs/ +│ │ ├── job.yml +│ │ └── steps/ │ ├── schemas/ # Job definition schemas -│ │ └── job.schema.json +│ │ └── job_schema.py │ └── utils/ +│ ├── fs.py │ ├── git.py -│ ├── yaml.py -│ └── validation.py +│ ├── validation.py +│ └── yaml_utils.py ├── tests/ # DeepWork tool tests -├── docs/ # Documentation +├── doc/ # Documentation ├── pyproject.toml -└── README.md +└── readme.md ``` ## DeepWork CLI Components ### 1. Installation Command (`install.py`) -The only command that runs regularly. When user executes `deepwork install --claude`: +The primary installation command. When user executes `deepwork install --claude`: **Responsibilities**: 1. Detect if current directory is a Git repository 2. Detect if specified AI platform is available (check for `.claude/`, `.gemini/`, etc.) 3. Create `.deepwork/` directory structure in the project -4. Copy core skill templates to appropriate AI platform directory -5. Create initial configuration files +4. Inject standard job definitions (deepwork_jobs) +5. Update or create configuration file +6. Run sync to generate commands for all platforms **Pseudocode**: ```python @@ -92,26 +97,24 @@ def install(platform: str): create_directory(".deepwork/") create_directory(".deepwork/jobs/") - # Install core skills - skills_to_install = [ - "deepwork.define", # Interactive job definition - "deepwork.refine", # Refine existing job - ] - - for skill in skills_to_install: - template = load_template(f"templates/{platform}/skill-{skill}.md") - write_file(f"{platform_config.skill_dir}/skill-{skill}.md", template) - - # Create config - config = { - "platform": platform, - "version": DEEPWORK_VERSION, - "installed": datetime.now() - } + # Inject core job definitions + inject_deepwork_jobs(".deepwork/jobs/") + + # Update config (supports multiple platforms) + config = load_yaml(".deepwork/config.yml") or {} + config["version"] = "1.0.0" + config["platforms"] = config.get("platforms", []) + + if platform not in config["platforms"]: + config["platforms"].append(platform) + write_yaml(".deepwork/config.yml", config) + # Run sync to generate commands + sync_commands() + print(f"✓ DeepWork installed for {platform}") - print(f" Run /{skills_to_install[0]} to create your first job") + print(f" Run /deepwork_jobs.define to create your first job") ``` ### 2. Platform Detector (`detector.py`) @@ -120,70 +123,92 @@ Identifies which AI platforms are available in the project. **Detection Logic**: ```python -PLATFORM_SIGNATURES = { - "claude": { - "check": lambda: Path(".claude").exists(), - "skill_dir": ".claude", - "skill_extension": ".md", - "skill_prefix": "skill-" - }, - "gemini": { - "check": lambda: Path(".gemini").exists(), # Hypothetical - "skill_dir": ".gemini", - "skill_extension": ".md", - "skill_prefix": "skill-" - }, - "copilot": { - "check": lambda: Path(".github/copilot-instructions.md").exists(), - "skill_dir": ".github", - "skill_extension": ".md", - "skill_prefix": "copilot-" - } +@dataclass +class PlatformConfig: + """Configuration for an AI platform.""" + name: str # "claude", "gemini", "copilot" + display_name: str # "Claude Code", "Google Gemini", "GitHub Copilot" + config_dir: str # ".claude", ".gemini", ".github" + commands_dir: str # "commands", "commands", "commands" + +PLATFORMS = { + "claude": PlatformConfig( + name="claude", + display_name="Claude Code", + config_dir=".claude", + commands_dir="commands" + ), + "gemini": PlatformConfig( + name="gemini", + display_name="Google Gemini", + config_dir=".gemini", + commands_dir="commands" + ), + "copilot": PlatformConfig( + name="copilot", + display_name="GitHub Copilot", + config_dir=".github", + commands_dir="commands" + ) } + +class PlatformDetector: + def detect_platform(self, platform_name: str) -> PlatformConfig | None: + """Check if a specific platform is available.""" + platform = PLATFORMS[platform_name] + config_dir = self.project_root / platform.config_dir + if config_dir.exists() and config_dir.is_dir(): + return platform + return None ``` -### 3. Skill Generator (`generator.py`) +### 3. Command Generator (`generator.py`) -Generates AI-platform-specific skill files from job definitions. +Generates AI-platform-specific command files from job definitions. -When a user defines a job via `/deepwork.define`, this component: +This component is called by the `sync` command to regenerate all commands: 1. Reads the job definition from `.deepwork/jobs/[job-name]/job.yml` 2. Loads platform-specific templates -3. Generates skill files for each step in the job -4. Writes skills to the AI platform's directory +3. Generates command files for each step in the job +4. Writes commands to the AI platform's commands directory **Example Generation Flow**: ```python -def generate_skills_for_job(job_name: str, platform: str): - # Load job definition - job = load_yaml(f".deepwork/jobs/{job_name}/job.yml") - - # Get platform config - platform_config = PLATFORM_SIGNATURES[platform] - - # Generate skill for each step - for step in job['steps']: - skill_name = f"{job_name}.{step['id']}" - - # Load template - template = load_jinja_template( - f"templates/{platform}/skill-job-step.md.jinja" - ) - - # Render with step data - skill_content = template.render( - job_name=job_name, - step_id=step['id'], - step_name=step['name'], - description=step['description'], - inputs=step['inputs'], - outputs=step['outputs'], - instructions=load_file(step['instructions_file']) - ) - - # Write to platform directory - skill_path = f"{platform_config['skill_dir']}/skill-{skill_name}.md" - write_file(skill_path, skill_content) +class CommandGenerator: + def generate_all_commands(self, job: JobDefinition, + platform: PlatformConfig, + output_dir: Path) -> list[Path]: + """Generate command files for all steps in a job.""" + command_paths = [] + + for step_index, step in enumerate(job.steps): + # Load step instructions + instructions = read_file(job.job_dir / step.instructions_file) + + # Build template context + context = { + "job_name": job.name, + "step_id": step.id, + "step_name": step.name, + "step_number": step_index + 1, + "total_steps": len(job.steps), + "instructions_content": instructions, + "user_inputs": [inp for inp in step.inputs if inp.is_user_input()], + "file_inputs": [inp for inp in step.inputs if inp.is_file_input()], + "outputs": step.outputs, + "dependencies": step.dependencies, + } + + # Render template + template = env.get_template("command-job-step.md.jinja") + rendered = template.render(**context) + + # Write to platform's commands directory + command_path = output_dir / platform.config_dir / platform.commands_dir / f"{job.name}.{step.id}.md" + write_file(command_path, rendered) + command_paths.append(command_path) + + return command_paths ``` --- @@ -198,36 +223,42 @@ This section describes what a project looks like AFTER `deepwork install --claud my-project/ # User's project (target) ├── .git/ ├── .claude/ # Claude Code directory -│ ├── skill-deepwork.define.md # Core DeepWork skill -│ ├── skill-deepwork.refine.md # Refine existing jobs -│ ├── skill-competitive_research.identify_competitors.md -│ ├── skill-competitive_research.primary_research.md -│ ├── skill-competitive_research.secondary_research.md -│ ├── skill-competitive_research.comparative_report.md -│ └── skill-competitive_research.positioning.md +│ └── commands/ # Command files +│ ├── deepwork_jobs.define.md # Core DeepWork commands +│ ├── deepwork_jobs.implement.md +│ ├── deepwork_jobs.refine.md +│ ├── competitive_research.identify_competitors.md +│ ├── competitive_research.primary_research.md +│ ├── competitive_research.secondary_research.md +│ ├── competitive_research.comparative_report.md +│ └── competitive_research.positioning.md ├── .deepwork/ # DeepWork configuration │ ├── config.yml # Platform config │ └── jobs/ # Job definitions +│ ├── deepwork_jobs/ # Core job for managing jobs +│ │ ├── job.yml +│ │ └── steps/ +│ │ ├── define.md +│ │ ├── implement.md +│ │ └── refine.md │ ├── competitive_research/ │ │ ├── job.yml # Job metadata -│ │ ├── steps/ -│ │ │ ├── identify_competitors.md -│ │ │ ├── primary_research.md -│ │ │ ├── secondary_research.md -│ │ │ ├── comparative_report.md -│ │ │ └── positioning.md -│ │ ├── templates/ # Output templates -│ │ └── examples/ # Example outputs +│ │ └── steps/ +│ │ ├── identify_competitors.md +│ │ ├── primary_research.md +│ │ ├── secondary_research.md +│ │ ├── comparative_report.md +│ │ └── positioning.md │ └── ad_campaign/ │ └── ... -├── work/ # Work products (Git branches) -│ ├── competitive-research-acme-2026-01/ +├── deepwork/ # Work products (Git branches) +│ ├── competitive_research-acme-2026-01-11/ │ │ ├── competitors.md │ │ ├── primary_research.md │ │ ├── secondary_research.md │ │ ├── comparison_matrix.md │ │ └── positioning_strategy.md -│ └── ad-campaign-q1-2026/ +│ └── ad_campaign-q1-2026-01-11/ │ └── ... ├── (rest of user's project files) └── README.md @@ -238,11 +269,13 @@ my-project/ # User's project (target) ### `.deepwork/config.yml` ```yaml -platform: claude -version: "1.0.0" -installed: "2026-01-09T10:30:00Z" +version: 1.0.0 +platforms: + - claude ``` +**Note**: The config supports multiple platforms. You can add additional platforms by running `deepwork install --platform gemini` etc. + ### Job Definition Example `.deepwork/jobs/competitive_research/job.yml`: @@ -387,24 +420,34 @@ Create `competitors.md` with this structure: - [ ] No duplicate entries ``` -## Generated Skill Files +## Generated Command Files -When the job is defined, DeepWork generates skill files. Example for Claude Code: +When the job is defined and `sync` is run, DeepWork generates command files. Example for Claude Code: -`.claude/skill-competitive_research.identify_competitors.md`: +`.claude/commands/competitive_research.identify_competitors.md`: ```markdown -Name: competitive_research.identify_competitors -Description: Research and identify direct and indirect competitors +--- +description: Research and identify direct and indirect competitors +--- -## Overview -This is step 1 of 5 in the Competitive Research job. +# competitive_research.identify_competitors + +**Step 1 of 5** in the **competitive_research** workflow + +**Summary**: Systematic competitive analysis workflow + +## Job Overview + +[Job description and context...] ## Instructions You are performing the "Identify Competitors" step of competitive research. ### Prerequisites +This step has no dependencies (it's the first step). + Before starting, ensure you have: - Market segment defined - Product category specified @@ -420,12 +463,12 @@ Ask the user for the following if not already provided: ### Work Branch Management 1. Check if we're on a work branch for this job -2. If not, create a new branch: `work/competitive-research-[timestamp]` -3. All outputs should be created in the `work/[branch-name]/` directory +2. If not, create a new branch: `deepwork/competitive_research-[instance]-[date]` +3. All outputs should be created in the `deepwork/[branch-name]/` directory ### Output Requirements Create the following file in the work directory: -- `work/[branch-name]/competitors.md` +- `deepwork/[branch-name]/competitors.md` ### After Completion 1. Inform the user that step 1 is complete @@ -459,7 +502,7 @@ This section describes how AI agents (like Claude Code) actually execute jobs us 2. **Define a Job** (once per job type): ``` # In Claude Code - User: /deepwork.define + User: /deepwork_jobs.define Claude: I'll help you define a new job. What type of work do you want to define? @@ -468,7 +511,14 @@ This section describes how AI agents (like Claude Code) actually execute jobs us [Interactive dialog to define all the steps] Claude: ✓ Job 'competitive_research' created with 5 steps - Skills installed to .claude/ + Run /deepwork_jobs.implement to generate command files + Then run 'deepwork sync' to install commands + + User: /deepwork_jobs.implement + + Claude: [Generates step instruction files] + [Runs deepwork sync] + ✓ Commands installed to .claude/commands/ Run /competitive_research.identify_competitors to start ``` @@ -478,7 +528,7 @@ This section describes how AI agents (like Claude Code) actually execute jobs us User: /competitive_research.identify_competitors Claude: Starting competitive research job... - Created branch: work/competitive-research-20260109-143022 + Created branch: deepwork/competitive_research-acme-2026-01-11 Please provide: - Market segment: ? @@ -488,7 +538,7 @@ This section describes how AI agents (like Claude Code) actually execute jobs us Product category: Project Management Claude: [Performs research using web tools, analysis, etc.] - ✓ Created work/competitive-research-20260109-143022/competitors.md + ✓ Created deepwork/competitive_research-acme-2026-01-11/competitors.md Found 8 direct competitors and 4 indirect competitors. Review the file and run /competitive_research.primary_research when ready. @@ -510,26 +560,26 @@ This section describes how AI agents (like Claude Code) actually execute jobs us ``` User: Looks great! Create a PR for this work - Claude: [Creates PR from work/competitive-research-20260109-143022 to main] + Claude: [Creates PR from deepwork/competitive_research-acme-2026-01-11 to main] PR created: https://github.com/user/project/pull/123 ``` -## How Claude Code Executes Skills +## How Claude Code Executes Commands When user types `/competitive_research.identify_competitors`: -1. **Skill Discovery**: - - Claude Code scans `.claude/` directory - - Finds `skill-competitive_research.identify_competitors.md` - - Loads the skill definition +1. **Command Discovery**: + - Claude Code scans `.claude/commands/` directory + - Finds `competitive_research.identify_competitors.md` + - Loads the command definition 2. **Context Loading**: - - Skill file contains embedded instructions + - Command file contains embedded instructions - References to job definition and step files - Claude reads these files to understand the full context 3. **Execution**: - - Claude follows the instructions in the skill + - Claude follows the instructions in the command - Uses its tools (Read, Write, WebSearch, WebFetch, etc.) - Creates outputs in the specified format @@ -541,7 +591,7 @@ When user types `/competitive_research.identify_competitors`: 5. **No DeepWork Runtime**: - DeepWork CLI is NOT running during execution - Everything happens through Claude Code's native execution - - Skills are just markdown instruction files that Claude interprets + - Commands are just markdown instruction files that Claude interprets ## Context Passing Between Steps @@ -550,7 +600,7 @@ Since there's no DeepWork runtime process, context is passed through: ### 1. Filesystem (Primary Mechanism) ``` -work/competitive-research-20260109-143022/ +deepwork/competitive_research-acme-2026-01-11/ ├── competitors.md ← Step 1 output ├── primary_research.md ← Step 2 output ├── competitor_profiles/ ← Step 2 output @@ -562,14 +612,14 @@ work/competitive-research-20260109-143022/ └── positioning_strategy.md ← Step 5 output ``` -Each skill instructs Claude to: +Each command instructs Claude to: - Read specific input files from previous steps - Write specific output files for this step - All within the same work directory -### 2. Skill Instructions +### 2. Command Instructions -Each skill file explicitly states its dependencies: +Each command file explicitly states its dependencies: ```markdown ### Prerequisites @@ -578,17 +628,17 @@ This step requires outputs from: - Step 2 (primary_research): primary_research.md ### Your Task -1. Read `work/[branch]/competitors.md` -2. Read `work/[branch]/primary_research.md` +1. Read `deepwork/[branch]/competitors.md` +2. Read `deepwork/[branch]/primary_research.md` 3. [Perform analysis] -4. Write `work/[branch]/secondary_research.md` +4. Write `deepwork/[branch]/secondary_research.md` ``` ### 3. Git History When working on similar jobs: - User: "Do competitive research for Acme Corp, similar to our Widget Corp analysis" -- Claude can read `work/competitive-research-widget-corp/` from git history +- Claude can read `deepwork/competitive_research-widget-corp-2026-01-05/` from git history - Uses it as a template for style, depth, format ### 4. No Environment Variables Needed @@ -605,28 +655,30 @@ Unlike the original architecture, we don't need special environment variables be Each job execution creates a new work branch: ```bash -work/competitive-research-20260109-143022 # Timestamp-based -work/ad-campaign-q1-2026 # Name-based (user can specify) -work/monthly-report-2026-01 # Date-based +deepwork/competitive_research-acme-2026-01-11 # Name-based with date +deepwork/ad_campaign-q1-2026-01-11 # Quarter-based with date +deepwork/monthly_report-2026-01-11 # Date-based ``` **Branch Naming Convention**: ``` -work/[job-name]-[instance-identifier] +deepwork/[job_name]-[instance-identifier]-[date] ``` Where `instance-identifier` can be: -- Timestamp (default): `20260109-143022` -- User-specified: `acme-corp`, `q1-2026`, etc. +- User-specified: `acme`, `q1`, etc. +- Auto-generated from timestamp if not specified - Logical: "ford" when doing competitive research on Ford Motor Company -### Skill Behavior +**Date format**: `YYYY-MM-DD` -Skills should: +### Command Behavior + +Commands should: 1. Check if we're already on a work branch for this job 2. If not, ask user for instance name or auto-generate from timestamp -3. Create branch: `git checkout -b work/[job-name]-[instance]` -4. Create work directory: `mkdir -p work/[job-name]-[instance]` +3. Create branch: `git checkout -b deepwork/[job_name]-[instance]-[date]` +4. Create work directory: `mkdir -p deepwork/[job_name]-[instance]-[date]` 5. Perform work in that directory ### Completion and Merge @@ -640,11 +692,21 @@ When all steps are done: --- -## Job Definition and Skill Generation +## Job Definition and Command Generation + +### Standard Job: `deepwork_jobs` + +DeepWork includes a built-in job called `deepwork_jobs` with three commands for managing jobs: -### The `/deepwork.define` Skill +1. **`/deepwork_jobs.define`** - Interactive job definition wizard +2. **`/deepwork_jobs.implement`** - Generates step instruction files from job.yml +3. **`/deepwork_jobs.refine`** - Modifies existing job definitions -When a user runs `/deepwork.define` in Claude Code: +These commands are installed automatically when you run `deepwork install`. + +### The `/deepwork_jobs.define` Command + +When a user runs `/deepwork_jobs.define` in Claude Code: **What Happens**: 1. Claude engages in interactive dialog to gather: @@ -653,65 +715,44 @@ When a user runs `/deepwork.define` in Claude Code: - List of steps (name, description, inputs, outputs) - Dependencies between steps -2. Claude creates the job definition files: +2. Claude creates the job definition file: ``` .deepwork/jobs/[job-name]/ - ├── job.yml # Job metadata - └── steps/ - ├── step1.md # Instructions for each step - ├── step2.md - └── ... + └── job.yml # Job metadata only ``` -3. Claude generates skill files using the DeepWork skill template: +3. User then runs `/deepwork_jobs.implement` to: + - Generate step instruction files (steps/*.md) + - Run `deepwork sync` to generate command files + - Install commands to `.claude/commands/` + +4. The workflow is now: ``` - For each step in job.yml: - - Load template from embedded knowledge - - Substitute job/step metadata - - Write to .claude/skill-[job].[step].md + /deepwork_jobs.define → Creates job.yml + /deepwork_jobs.implement → Creates steps/*.md and syncs commands ``` -4. The `/deepwork.define` skill contains: +5. The `/deepwork_jobs.define` command contains: - The job definition YAML schema - - The skill file template (Jinja2-like) - - Logic for generation + - Interactive question flow + - Job.yml creation logic -**How Templates are Embedded**: +**Command File Structure**: -The `skill-deepwork.define.md` file contains the template AS DATA: +The actual command file `.claude/commands/deepwork_jobs.define.md` contains: ```markdown -Name: deepwork.define -Description: Interactive job definition wizard - -## Instructions - -[Instructions for Claude on how to run the wizard...] - -## Template for Generated Skills - -When you generate skills, use this template: +--- +description: Create the job.yml specification file by understanding workflow requirements +--- -````markdown -Name: {{job_name}}.{{step_id}} -Description: {{step_description}} +# deepwork_jobs.define -## Overview -This is step {{step_number}} of {{total_steps}} in the {{job_name}} job. +**Step 1 of 3** in the **deepwork_jobs** workflow ## Instructions -{{instructions_content}} - -## Work Branch Management -[Branch creation instructions...] - -## Output Requirements -Create these files: -{{#outputs}} -- `work/[branch]/{{this}}` -{{/outputs}} -```` +[Detailed instructions for Claude on how to run the interactive wizard...] ## Job Definition Schema @@ -719,12 +760,45 @@ When creating job.yml, use this structure: [YAML schema embedded here...] ``` -### The `/deepwork.refine` Skill +### The `/deepwork_jobs.implement` Command + +Generates step instruction files from job.yml and syncs commands: + +``` +User: /deepwork_jobs.implement + +Claude: Reading job definition from .deepwork/jobs/competitive_research/job.yml... + Generating step instruction files... + ✓ Created steps/identify_competitors.md + ✓ Created steps/primary_research.md + ✓ Created steps/secondary_research.md + ✓ Created steps/comparative_report.md + ✓ Created steps/positioning.md + + Running deepwork sync... + ✓ Generated 5 command files in .claude/commands/ + + New commands available: + - /competitive_research.identify_competitors + - /competitive_research.primary_research + - /competitive_research.secondary_research + - /competitive_research.comparative_report + - /competitive_research.positioning +``` + +### The `/deepwork_jobs.refine` Command Allows updating existing job definitions: ``` -User: /deepwork.refine competitive_research +User: /deepwork_jobs.refine + +Claude: Which job would you like to refine? + Available jobs: + - competitive_research + - deepwork_jobs + +User: competitive_research Claude: Loading competitive_research job definition... What would you like to update? @@ -737,9 +811,8 @@ User: Add a new step between primary_research and secondary_research Claude: [Interactive dialog...] ✓ Added step 'social_media_analysis' - ✓ Updated dependencies - ✓ Regenerated skill files - New command available: /competitive_research.social_media_analysis + ✓ Updated dependencies in job.yml + ✓ Please run /deepwork_jobs.implement to generate the new step file ``` ### Template System @@ -1115,53 +1188,33 @@ jobs: --- -## Implementation Phases - -### Phase 1: Core Runtime -- [ ] Project structure and build system -- [ ] Job definition parser -- [ ] Registry implementation -- [ ] Basic Git integration -- [ ] Template renderer -- [ ] Unit tests for core components - -### Phase 2: CLI and Installation -- [ ] CLI command framework -- [ ] `install` command with platform detection -- [ ] `import` command with Git clone -- [ ] `define` command with interactive wizard -- [ ] `list` and `status` commands -- [ ] Integration tests - -### Phase 3: Runtime Engine -- [ ] Step execution engine -- [ ] Context preparation and injection -- [ ] Output validation system -- [ ] State management and resumption -- [ ] Environment variable handling -- [ ] Integration tests for workflows - -### Phase 4: AI Platform Integration -- [ ] Claude Code skill generation -- [ ] Gemini command generation -- [ ] Copilot instruction generation -- [ ] Platform-specific template variations -- [ ] Multi-platform testing - -### Phase 5: Job Ecosystem -- [ ] Create reference jobs (competitive research, campaign design, etc.) -- [ ] Job validation tools -- [ ] Job sharing infrastructure -- [ ] Documentation and examples -- [ ] E2E tests with real job definitions -- [ ] Benchmarks - -### Phase 6: Polish and Release -- [ ] Performance optimization -- [ ] Error handling improvements -- [ ] User documentation -- [ ] Tutorial videos -- [ ] Beta release +## Implementation Status + +**Completed**: Phases 1 & 2 are complete. The core runtime, CLI, installation, and command generation systems are fully functional. + +### Current Focus: Phase 5 - Job Ecosystem +- ✅ Standard job `deepwork_jobs` with define, implement, refine commands +- 📋 Reference job library (competitive research, ad campaigns, etc.) +- 📋 Job sharing via Git repositories + +### Future Work + +**Phase 3: Runtime Engine** (Optional enhancements) +- Step execution tracking and monitoring +- Output validation system +- Advanced state management + +**Phase 4: Multi-Platform Support** +- Gemini command generation +- GitHub Copilot integration +- Multi-platform testing + +**Phase 6: Polish and Release** +- Performance optimization +- Enhanced error handling +- Comprehensive user documentation +- Tutorial content +- Beta and public release --- From f89c6f0d0553c03d968c0f390ce8e7718479bb59 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Sun, 11 Jan 2026 19:32:11 -0700 Subject: [PATCH 3/3] fixed refine largely --- .claude/commands/deepwork_jobs.define.md | 24 +-- .claude/commands/deepwork_jobs.implement.md | 20 +-- .claude/commands/deepwork_jobs.refine.md | 138 ++++++++++-------- .claude/settings.json | 2 +- README.md | 10 +- doc/architecture.md | 20 ++- src/deepwork/schemas/job_schema.py | 21 +++ .../standard_jobs/deepwork_jobs/job.yml | 6 +- .../deepwork_jobs/steps/define.md | 9 +- .../deepwork_jobs/steps/refine.md | 115 +++++++++------ tests/fixtures/jobs/complex_job/job.yml | 19 ++- tests/fixtures/jobs/simple_job/job.yml | 11 +- 12 files changed, 259 insertions(+), 136 deletions(-) diff --git a/.claude/commands/deepwork_jobs.define.md b/.claude/commands/deepwork_jobs.define.md index 4fd3b0b2..e600d63b 100644 --- a/.claude/commands/deepwork_jobs.define.md +++ b/.claude/commands/deepwork_jobs.define.md @@ -131,6 +131,10 @@ description: | - 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]" @@ -166,6 +170,7 @@ steps: - At least one output per step - The `summary` should be concise (max 200 chars) - The `description` should provide rich context for future refinement +- Include a `changelog` section with an initial entry for version 1.0.0 ## Example Dialog @@ -311,8 +316,8 @@ The complete YAML specification file (example shown in Step 4 above). (Where `[job_name]` is the name of the new job being created) After creating the file: -1. Commit it to the work branch -2. Inform the user that the specification is complete +1. Inform the user that the specification is complete +2. Recommend that they review the job.yml file 3. Tell them to run `/deepwork_jobs.implement` next ## Quality Criteria @@ -324,6 +329,7 @@ After creating the file: - Description provides rich context for future refinement - Specification is valid YAML and follows the schema - Ready for implementation step +- Output artifacts have quality criteria defined ## Inputs @@ -358,24 +364,18 @@ Create the following output(s) in the work directory: - `deepwork/deepwork_jobs/job.yml` Ensure all outputs are: - Well-formatted and complete -- Committed to the work branch - Ready for review or use by subsequent steps ## Completion After completing this step: -1. **Commit your work**: - ```bash - git add deepwork/deepwork_jobs/ - git commit -m "deepwork_jobs: Complete define step" - ``` - -2. **Verify outputs**: Confirm all required files have been created +1. **Verify outputs**: Confirm all required files have been created -3. **Inform the user**: - - Step 1 of 3 is complete +2. **Inform the user**: + - Step 1 of 2 is complete - Outputs created: job.yml + - They should review the job.yml file before proceeding - Ready to proceed to next step: `/deepwork_jobs.implement` ## Next Step diff --git a/.claude/commands/deepwork_jobs.implement.md b/.claude/commands/deepwork_jobs.implement.md index dc3be9ef..cc3de87c 100644 --- a/.claude/commands/deepwork_jobs.implement.md +++ b/.claude/commands/deepwork_jobs.implement.md @@ -380,8 +380,8 @@ Before marking this step complete, ensure: - [ ] Registry updated with new job - [ ] `deepwork sync` executed successfully - [ ] Commands generated in platform directory +- [ ] Reload the slash commmands so the user can use them immediately if the current CLI requires it - [ ] User informed of next steps (reload commands) -- [ ] implementation_summary.md created ## Quality Criteria @@ -430,25 +430,19 @@ Create the following output(s) in the work directory: - `deepwork/deepwork_jobs/implementation_summary.md` Ensure all outputs are: - Well-formatted and complete -- Committed to the work branch - Ready for review or use by subsequent steps ## Completion After completing this step: -1. **Commit your work**: - ```bash - git add deepwork/deepwork_jobs/ - git commit -m "deepwork_jobs: Complete implement step" - ``` - -2. **Verify outputs**: Confirm all required files have been created +1. **Verify outputs**: Confirm all required files have been created -3. **Inform the user**: - - Step 2 of 3 is complete - - Outputs created: implementation_summary.md - - Ready to proceed to next step: `/deepwork_jobs.refine` +2. **Inform the user**: + - All steps are complete + - They should review the generated files before proceeding + - Suggest that before they try the job, they should commit the changes so far. + - Remind them what the first command for their new job will be to run it ## Next Step diff --git a/.claude/commands/deepwork_jobs.refine.md b/.claude/commands/deepwork_jobs.refine.md index c982cbb1..bc4bb496 100644 --- a/.claude/commands/deepwork_jobs.refine.md +++ b/.claude/commands/deepwork_jobs.refine.md @@ -89,9 +89,10 @@ Based on the user's selection: - File inputs must come from dependencies - Check for circular dependencies -4. **Create files** +4. **Update files** - Update `job.yml` with new step - Create step instructions file in `steps/[step_id].md` + - Prepare changelog entry describing the addition #### Modifying Step Instructions @@ -107,6 +108,7 @@ Based on the user's selection: 3. **Update instructions** - Modify `.deepwork/jobs/[job_name]/steps/[step_id].md` - Keep the same structure (Objective, Task, Process, Output Format, Quality Criteria) + - Prepare changelog entry describing the modification #### Changing Inputs/Outputs @@ -122,6 +124,7 @@ Based on the user's selection: - If removing input: ensure it's not critical 5. **Update job.yml** + - Prepare changelog entry describing the input/output changes #### Updating Dependencies @@ -137,6 +140,7 @@ Based on the user's selection: - Ensure dependency chain makes logical sense 5. **Update job.yml** + - Prepare changelog entry describing the dependency changes #### Updating Metadata @@ -150,6 +154,7 @@ Based on the user's selection: - Patch (0.0.x): Bug fixes, improvements 3. **Update job.yml and registry.yml** + - Prepare changelog entry describing the metadata changes #### Removing a Step @@ -165,10 +170,34 @@ Based on the user's selection: - Remove from `job.yml` - Delete step instructions file - Suggest version bump + - Prepare changelog entry describing the removal -### Step 4: Validate Changes +### Step 4: Update Changelog -After making changes: +After making changes to the job.yml: + +1. **Add a changelog entry** + - Add a new entry to the `changelog` array in the job.yml + - Use the new version number + - List all changes made in this refinement + +2. **Changelog entry format**: + ```yaml + - version: "[new_version]" + changes: "[Description of all changes in this version]" + ``` + +3. **Example changelog entries**: + - "Added step: validate_positioning" + - "Modified step instructions for research_competitors to improve clarity and add quality criteria" + - "Removed step: duplicate_analysis (consolidated into comparative_analysis)" + - "Updated dependencies: positioning_recommendations now depends on validate_positioning" + - "Changed output filename: comparison_matrix.md → comparison_table.md" + - "Added step: validate_positioning; Updated dependencies for positioning_recommendations" + +### Step 5: Validate Changes + +After updating the changelog: 1. **Review the updated structure** - Show the complete updated workflow @@ -181,12 +210,13 @@ After making changes: - All step IDs unique - All outputs defined -3. **Suggest version update** if not already done +3. **Confirm version update** + - Ensure version was bumped appropriately - Breaking changes? Major version - New features? Minor version - Improvements? Patch version -### Step 5: Sync and Reload +### Step 6: Sync and Reload 1. **Run sync** ```bash @@ -199,6 +229,7 @@ After making changes: 3. **Provide summary** - Show what changed - List updated files + - Display the changelog entry - Explain next steps ## Safe Modification Patterns @@ -297,10 +328,16 @@ This is a new feature, so I'll bump the version to 1.1.0 (minor version). Creating the new step... ✓ Updated files: -- .deepwork/jobs/competitive_research/job.yml (added step, updated dependencies, version → 1.1.0) +- .deepwork/jobs/competitive_research/job.yml (added step, updated dependencies, version → 1.1.0, updated changelog) - .deepwork/jobs/competitive_research/steps/validate_positioning.md (created) - .deepwork/registry.yml (updated version) +Changelog entry added: +```yaml +- version: "1.1.0" + changes: "Added step: validate_positioning between comparative_analysis and positioning_recommendations; Updated dependencies for positioning_recommendations" +``` + Now run: ```bash deepwork sync @@ -330,50 +367,40 @@ If issues arise, provide clear guidance: - **Missing file input**: "Step X requires file.md from step Y, but Y is not in its dependencies. I'll add Y to the dependencies." - **Breaking change**: "Removing this output is a breaking change. Other steps depend on it. I recommend against this change unless you update the dependent steps first." -## Output Format - -### refinement_summary.md - -```markdown -# Job Refinement: [job_name] +## Changelog Entry Format -## Changes Made +Instead of creating a separate refinement_summary.md file, add the changes directly to the job.yml changelog section. This creates a permanent version history within the job definition itself. -### Version -[old_version] → [new_version] +**Location**: `.deepwork/jobs/[job_name]/job.yml` -### Added Steps -- **[step_name]** (`[step_id]`) - - Purpose: [what it does] - - Inputs: [list] - - Outputs: [list] - - Position: After [previous_step] +**Add to the `changelog` array**: -### Modified Steps -- **[step_name]** (`[step_id]`) - - Changed: [what changed] - - Reason: [why] - -### Updated Dependencies -- **[step_name]**: Added dependency on [other_step] - -### Removed -- [Anything removed] - -## Files Updated -- `.deepwork/jobs/[job_name]/job.yml` -- `.deepwork/jobs/[job_name]/steps/[step_id].md` -- `.deepwork/registry.yml` - -## Next Steps -1. Run `deepwork sync` to regenerate commands -2. Reload your Claude session (`/reload` or restart) -3. Test the updated workflow: `/[job_name].[first_step]` - -## Updated Command Reference -[List all commands with brief descriptions] +```yaml +changelog: + - version: "1.0.0" + changes: "Initial job creation" + - version: "[new_version]" + changes: "[Concise description of all changes in this version]" ``` +**Guidelines for changelog entries**: +- Be concise but descriptive +- Use action verbs (Added, Modified, Removed, Updated, Changed, Fixed) +- Reference specific step names when relevant +- For breaking changes, prefix with "BREAKING:" +- If multiple changes, separate with semicolons or use clear phrasing + +**Examples**: +- "Added step: validate_positioning between comparative_analysis and positioning_recommendations" +- "Modified step instructions for research_competitors to improve clarity and add quality criteria" +- "Removed step: duplicate_analysis (consolidated into comparative_analysis)" +- "Updated dependencies: positioning_recommendations now depends on validate_positioning" +- "Changed output filename: comparison_matrix.md → comparison_table.md" +- "BREAKING: Removed output file shared_data.json from identify_competitors step" +- "Fixed circular dependency between steps A and B" +- "Updated job description to reflect new validation phase" +- "Added validate_positioning step; Updated dependencies for positioning_recommendations" + ## Quality Criteria - Changes maintain job consistency @@ -412,28 +439,21 @@ All work for this job should be done on a dedicated work branch: ## Output Requirements -Create the following output(s) in the work directory: -- `deepwork/deepwork_jobs/refinement_summary.md` -Ensure all outputs are: -- Well-formatted and complete -- Committed to the work branch -- Ready for review or use by subsequent steps +**No separate output file is created**. All changes are made directly to: +- `.deepwork/jobs/[job_name]/job.yml` (updated with new version and changelog entry) +- `.deepwork/jobs/[job_name]/steps/[step_id].md` (if step instructions are modified) +- Any new step instruction files created ## Completion After completing this step: -1. **Commit your work**: - ```bash - git add deepwork/deepwork_jobs/ - git commit -m "deepwork_jobs: Complete refine step" - ``` - -2. **Verify outputs**: Confirm all required files have been created +1. **Verify outputs**: Confirm all required files have been created -3. **Inform the user**: +2. **Inform the user**: - Step 3 of 3 is complete - - Outputs created: refinement_summary.md + - Changes made to job.yml with updated version and changelog + - They should review the updated job.yml file before proceeding - This is the final step - the job is complete! ## Workflow Complete diff --git a/.claude/settings.json b/.claude/settings.json index 5822d7eb..fec38f8f 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -87,7 +87,7 @@ "Bash(node:*)", "Bash(npm:*)", "Bash(npx:*)", - "Edit(/Users/noah/deep-work/**)" + "Edit(./**)" ] } } \ No newline at end of file diff --git a/README.md b/README.md index a3cd80fb..9add31f6 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,15 @@ Here's a sample 4-step workflow for competitive analysis: ```yaml name: competitive_research version: "1.0.0" -description: "Systematic competitive analysis workflow" +summary: "Systematic competitive analysis workflow" +description: | + A comprehensive workflow for analyzing competitors in your market segment. + Helps product teams understand the competitive landscape by identifying + competitors, researching their offerings, and developing positioning strategies. + +changelog: + - version: "1.0.0" + changes: "Initial job creation" steps: - id: identify_competitors diff --git a/doc/architecture.md b/doc/architecture.md index 865e0fc8..ff04a00b 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -283,7 +283,24 @@ platforms: ```yaml name: competitive_research version: "1.0.0" -description: "Systematic competitive analysis workflow" +summary: "Systematic competitive analysis workflow" +description: | + A comprehensive workflow for analyzing competitors in your market segment. This job + helps product teams understand the competitive landscape by systematically identifying + competitors, researching their offerings, creating comparison matrices, and developing + strategic positioning recommendations. + + The workflow produces: + - A vetted list of key competitors + - Detailed research notes on each competitor (primary and secondary sources) + - A comparison matrix highlighting key differentiators + - Strategic positioning recommendations + + Designed for product teams conducting quarterly competitive analysis. + +changelog: + - version: "1.0.0" + changes: "Initial job creation" steps: - id: identify_competitors @@ -812,6 +829,7 @@ User: Add a new step between primary_research and secondary_research Claude: [Interactive dialog...] ✓ Added step 'social_media_analysis' ✓ Updated dependencies in job.yml + ✓ Updated changelog with version 1.1.0 ✓ Please run /deepwork_jobs.implement to generate the new step file ``` diff --git a/src/deepwork/schemas/job_schema.py b/src/deepwork/schemas/job_schema.py index 09be6912..439c3686 100644 --- a/src/deepwork/schemas/job_schema.py +++ b/src/deepwork/schemas/job_schema.py @@ -29,6 +29,27 @@ "minLength": 1, "description": "Detailed multi-line description of the job's purpose, process, and goals", }, + "changelog": { + "type": "array", + "description": "Version history and changes to the job", + "items": { + "type": "object", + "required": ["version", "changes"], + "properties": { + "version": { + "type": "string", + "pattern": r"^\d+\.\d+\.\d+$", + "description": "Version number for this change", + }, + "changes": { + "type": "string", + "minLength": 1, + "description": "Description of changes made in this version", + }, + }, + "additionalProperties": False, + }, + }, "steps": { "type": "array", "minItems": 1, diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index f9003b73..b87f5973 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -12,6 +12,10 @@ description: | The `refine` command helps you modify existing jobs safely by understanding what you want to change, validating the impact, and ensuring consistency across your workflow. +changelog: + - version: "1.0.0" + changes: "Initial job creation" + steps: - id: define name: "Define Job Specification" @@ -44,5 +48,5 @@ steps: - name: job_name description: "Name of the job to refine" outputs: - - refinement_summary.md + - job.yml dependencies: [] diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md index 6e50b8f5..af808acd 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md @@ -105,6 +105,10 @@ description: | - 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]" @@ -140,6 +144,7 @@ steps: - At least one output per step - The `summary` should be concise (max 200 chars) - The `description` should provide rich context for future refinement +- Include a `changelog` section with an initial entry for version 1.0.0 ## Example Dialog @@ -285,8 +290,8 @@ The complete YAML specification file (example shown in Step 4 above). (Where `[job_name]` is the name of the new job being created) After creating the file: -1. Commit it to the work branch -2. Inform the user that the specification is complete +1. Inform the user that the specification is complete +2. Recommend that they review the job.yml file 3. Tell them to run `/deepwork_jobs.implement` next ## Quality Criteria diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md index 97b9d63e..fd6abe26 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/refine.md @@ -63,9 +63,10 @@ Based on the user's selection: - File inputs must come from dependencies - Check for circular dependencies -4. **Create files** +4. **Update files** - Update `job.yml` with new step - Create step instructions file in `steps/[step_id].md` + - Prepare changelog entry describing the addition #### Modifying Step Instructions @@ -81,6 +82,7 @@ Based on the user's selection: 3. **Update instructions** - Modify `.deepwork/jobs/[job_name]/steps/[step_id].md` - Keep the same structure (Objective, Task, Process, Output Format, Quality Criteria) + - Prepare changelog entry describing the modification #### Changing Inputs/Outputs @@ -96,6 +98,7 @@ Based on the user's selection: - If removing input: ensure it's not critical 5. **Update job.yml** + - Prepare changelog entry describing the input/output changes #### Updating Dependencies @@ -111,6 +114,7 @@ Based on the user's selection: - Ensure dependency chain makes logical sense 5. **Update job.yml** + - Prepare changelog entry describing the dependency changes #### Updating Metadata @@ -124,6 +128,7 @@ Based on the user's selection: - Patch (0.0.x): Bug fixes, improvements 3. **Update job.yml and registry.yml** + - Prepare changelog entry describing the metadata changes #### Removing a Step @@ -139,10 +144,34 @@ Based on the user's selection: - Remove from `job.yml` - Delete step instructions file - Suggest version bump + - Prepare changelog entry describing the removal -### Step 4: Validate Changes +### Step 4: Update Changelog -After making changes: +After making changes to the job.yml: + +1. **Add a changelog entry** + - Add a new entry to the `changelog` array in the job.yml + - Use the new version number + - List all changes made in this refinement + +2. **Changelog entry format**: + ```yaml + - version: "[new_version]" + changes: "[Description of all changes in this version]" + ``` + +3. **Example changelog entries**: + - "Added step: validate_positioning" + - "Modified step instructions for research_competitors to improve clarity and add quality criteria" + - "Removed step: duplicate_analysis (consolidated into comparative_analysis)" + - "Updated dependencies: positioning_recommendations now depends on validate_positioning" + - "Changed output filename: comparison_matrix.md → comparison_table.md" + - "Added step: validate_positioning; Updated dependencies for positioning_recommendations" + +### Step 5: Validate Changes + +After updating the changelog: 1. **Review the updated structure** - Show the complete updated workflow @@ -155,12 +184,13 @@ After making changes: - All step IDs unique - All outputs defined -3. **Suggest version update** if not already done +3. **Confirm version update** + - Ensure version was bumped appropriately - Breaking changes? Major version - New features? Minor version - Improvements? Patch version -### Step 5: Sync and Reload +### Step 6: Sync and Reload 1. **Run sync** ```bash @@ -173,6 +203,7 @@ After making changes: 3. **Provide summary** - Show what changed - List updated files + - Display the changelog entry - Explain next steps ## Safe Modification Patterns @@ -271,10 +302,16 @@ This is a new feature, so I'll bump the version to 1.1.0 (minor version). Creating the new step... ✓ Updated files: -- .deepwork/jobs/competitive_research/job.yml (added step, updated dependencies, version → 1.1.0) +- .deepwork/jobs/competitive_research/job.yml (added step, updated dependencies, version → 1.1.0, updated changelog) - .deepwork/jobs/competitive_research/steps/validate_positioning.md (created) - .deepwork/registry.yml (updated version) +Changelog entry added: +```yaml +- version: "1.1.0" + changes: "Added step: validate_positioning between comparative_analysis and positioning_recommendations; Updated dependencies for positioning_recommendations" +``` + Now run: ```bash deepwork sync @@ -304,50 +341,40 @@ If issues arise, provide clear guidance: - **Missing file input**: "Step X requires file.md from step Y, but Y is not in its dependencies. I'll add Y to the dependencies." - **Breaking change**: "Removing this output is a breaking change. Other steps depend on it. I recommend against this change unless you update the dependent steps first." -## Output Format +## Changelog Entry Format -### refinement_summary.md +Instead of creating a separate refinement_summary.md file, add the changes directly to the job.yml changelog section. This creates a permanent version history within the job definition itself. -```markdown -# Job Refinement: [job_name] +**Location**: `.deepwork/jobs/[job_name]/job.yml` -## Changes Made +**Add to the `changelog` array**: -### Version -[old_version] → [new_version] - -### Added Steps -- **[step_name]** (`[step_id]`) - - Purpose: [what it does] - - Inputs: [list] - - Outputs: [list] - - Position: After [previous_step] - -### Modified Steps -- **[step_name]** (`[step_id]`) - - Changed: [what changed] - - Reason: [why] - -### Updated Dependencies -- **[step_name]**: Added dependency on [other_step] - -### Removed -- [Anything removed] - -## Files Updated -- `.deepwork/jobs/[job_name]/job.yml` -- `.deepwork/jobs/[job_name]/steps/[step_id].md` -- `.deepwork/registry.yml` - -## Next Steps -1. Run `deepwork sync` to regenerate commands -2. Reload your Claude session (`/reload` or restart) -3. Test the updated workflow: `/[job_name].[first_step]` - -## Updated Command Reference -[List all commands with brief descriptions] +```yaml +changelog: + - version: "1.0.0" + changes: "Initial job creation" + - version: "[new_version]" + changes: "[Concise description of all changes in this version]" ``` +**Guidelines for changelog entries**: +- Be concise but descriptive +- Use action verbs (Added, Modified, Removed, Updated, Changed, Fixed) +- Reference specific step names when relevant +- For breaking changes, prefix with "BREAKING:" +- If multiple changes, separate with semicolons or use clear phrasing + +**Examples**: +- "Added step: validate_positioning between comparative_analysis and positioning_recommendations" +- "Modified step instructions for research_competitors to improve clarity and add quality criteria" +- "Removed step: duplicate_analysis (consolidated into comparative_analysis)" +- "Updated dependencies: positioning_recommendations now depends on validate_positioning" +- "Changed output filename: comparison_matrix.md → comparison_table.md" +- "BREAKING: Removed output file shared_data.json from identify_competitors step" +- "Fixed circular dependency between steps A and B" +- "Updated job description to reflect new validation phase" +- "Added validate_positioning step; Updated dependencies for positioning_recommendations" + ## Quality Criteria - Changes maintain job consistency diff --git a/tests/fixtures/jobs/complex_job/job.yml b/tests/fixtures/jobs/complex_job/job.yml index c09d25c6..bdf4412a 100644 --- a/tests/fixtures/jobs/complex_job/job.yml +++ b/tests/fixtures/jobs/complex_job/job.yml @@ -1,6 +1,23 @@ name: competitive_research version: "1.0.0" -description: "Systematic competitive analysis workflow" +summary: "Systematic competitive analysis workflow" +description: | + A comprehensive workflow for analyzing competitors in your market segment. This job + helps product teams understand the competitive landscape by systematically identifying + competitors, researching their offerings, creating comparison matrices, and developing + strategic positioning recommendations. + + The workflow produces: + - A vetted list of key competitors + - Detailed research notes on each competitor (primary and secondary sources) + - A comparison matrix highlighting key differentiators + - Strategic positioning recommendations + + Designed for product teams conducting quarterly competitive analysis. + +changelog: + - version: "1.0.0" + changes: "Initial job creation" steps: - id: identify_competitors diff --git a/tests/fixtures/jobs/simple_job/job.yml b/tests/fixtures/jobs/simple_job/job.yml index 00edf564..b440dd9d 100644 --- a/tests/fixtures/jobs/simple_job/job.yml +++ b/tests/fixtures/jobs/simple_job/job.yml @@ -1,6 +1,15 @@ name: simple_job version: "1.0.0" -description: "A simple single-step job for testing" +summary: "A simple single-step job for testing" +description: | + A simple single-step job for testing the DeepWork framework. + + This job demonstrates the minimal structure required for a valid job definition, + including a single step with user input and file output. + +changelog: + - version: "1.0.0" + changes: "Initial job creation" steps: - id: single_step